TINE server engine and registration API routines. More...
Functions | |
| int | AcquireAndRegisterBitfield (const char *devName, char *tag) |
| Acquires the bitfield specified by the bitfield tag from the specified device server. More... | |
| int | AddFieldToBitField (char *srv, char *tag, UINT32 mask, char *field) |
| Adds a field definition to a registered bitfield. More... | |
| int | AddFieldToStruct (char *tag, int addr, int size, int fmt, char *field) |
| Adds a field description to a tagged structure. More... | |
| int | AppendRegisteredBCastNetsList (NAME64 *ipaddr, int addsiz) |
| appends the current network broadcast list with the name list given More... | |
| int | AppendRegisteredNetsList (const char *eqm, NAME64 *ipaddr, int addsiz) |
| appends the current network access list with the name list given More... | |
| int | AppendRegisteredUsers (const char *eqm, NAME16 *userlist, int listsize) |
| appends the current users access list with the name list given More... | |
| int | AssertIsAdministrator (const char *usr) |
| returns TRUE if the given user is a registered administrator More... | |
| int | AssignDataStampsToGlobal (char *keyword, int dataStamp, int sysStamp) |
| Assigns additional data stamps to the registered global keyword. More... | |
| int | AssignDeviceAccessList (const char *eqm, const char *dev, NAME16 *users, int nusers) |
| Assigns an access list for the device given. More... | |
| int | AssignDeviceListToProperty (char *eqm, char *prp, NAME64 *devlst, int lstlen) |
| Assigns the given device list to the given registered property. More... | |
| int | AssignDeviceNetsList (const char *eqm, const char *dev, NAME64 *ipnets, int nipnets) |
| Assigns an ip nets access list for the device given. More... | |
| int | AssignNumDevices (char *eqm, int num) |
| Fixes the number of modules (devices) attached to the specified equipment module. More... | |
| int | AssignPropertyAccessList (const char *eqm, const char *prp, NAME16 *users, int nusers) |
| Assigns an access list for the property given. More... | |
| int | AssignPropertyList (char *eqm, char *devname, char *listname, int listsize, NAME64 *list) |
| Assigns the given property list to the given device to be used in device-oriented queries. More... | |
| int | AssignPropertyNetsList (const char *eqm, const char *prp, NAME64 *ipnets, int nipnets) |
| Assigns an ip nets access list for the property given. More... | |
| int | ExecLocalLink (const char *devName, const char *devProperty, DTYPE *dout, DTYPE *din, short access) |
| Executes a synchronous link within the local process. More... | |
| int | FindNameServerOnNetwork () |
| Issues a multicast (or broadcast) to which the TINE equipment name server responds. More... | |
| int | FindServerOnNetwork (char *context, char *eqmName, char *exportName, FecAddrStruct *fec, ExpDataStruct *srv) |
| Issues a multicast (or broadcast) to which configured TINE central servers respond. More... | |
| void | FlushContractTable (void) |
| Flushes the current contract and client entry tables. More... | |
| int | GetAllowBackgroundTaskReentrancy (void) |
| Returns whether equipment module background tasks may be re-entered (boolean). More... | |
| int | GetAllowedRemoteManagement (void) |
| Returns whether remote management via stock properties is possible. More... | |
| int | GetAllowNetworkAddressResolution (void) |
| returns whether NETWORK address resolution is allowed More... | |
| int | GetBitfieldAsString (char *srv, char *tag, UINT32 value, char *strbuf, int buflen) |
| Retrieves the requested field value from a bit field as a string value. More... | |
| char * | GetCaller (char *eqm) |
| Gives the user name of the current caller. More... | |
| int | GetCallerInfo (char *eqm, NAME16 *un, BYTE *ipx, UINT32 *ip, short *prot, int *num) |
| Returns the user name(s) and network address(es) of all callers interested in the current contract. More... | |
| int | GetCallerInformation (char *eqm, ClnInfo *clnInfoList, int *num) |
| Returns the user name, network address and other information of all callers interested in the current contract. More... | |
| int | GetClientListCapacity (void) |
| Gets the maximum number of clients a server will service. More... | |
| int | GetConfigurationCoded (void) |
| Returns whether TINE configuration files will be scanned. More... | |
| void ** | GetContractDataReference (ExportListStruct *el) |
| returns a pointer to a useable reference pointer associated with the contract currently being accessed. More... | |
| void ** | GetContractDataReferenceByEqmName (char *eqm) |
| returns a pointer to a useable reference pointer associated with the contract currently being accessed. More... | |
| int | GetContractListCapacity (void) |
| Gets the maximum number of contracts a server will service. More... | |
| int | GetCurrentFailoverState (void) |
| Returns current master slave state of server. More... | |
| int | GetDefaultDeviceRegion (char *eqmName) |
| Returns the default device region. More... | |
| char * | GetDeviceDescription (char *eqm, int devnr) |
| Gives the registered device description (if known) for the device number. More... | |
| int | GetDeviceGroups (char *eqm, NAME64 *groups, int *len) |
| Gets a NAME64 list of registered device groups. More... | |
| char * | GetDeviceLocation (char *eqm, int devnr) |
| Gives the registered device location (if known) for the device number. More... | |
| int | GetDeviceMask (char *eqm, int devnr) |
| Gives the registered device mask for the device number. More... | |
| char * | GetDeviceName (char *eqm, int devnr) |
| Gives the registered device name for the specified equipment module and device number. More... | |
| int | GetDeviceNumber (char *eqm, char *devname) |
| Gives the registered device number for the specified device name. More... | |
| int | GetDeviceNumberEx (char *eqm, char *devname, char *prpname) |
| Gives the registered device number for the specified device name and property name. More... | |
| int | GetDeviceOfflineStatus (char *eqm, int devnr) |
| Gives the current off line status for the device in question. More... | |
| float | GetDeviceZPosition (char *eqm, int devnr) |
| Gives the registered device Z (or longitudinal) position for the device number. More... | |
| int | GetEnforceMcaAcquisition (void) |
| returns the setting for multi-channel array handshaking enforcement. More... | |
| char * | GetExportedContext (char *eqmName) |
| Returns the exported context associated with the equipment function name given. More... | |
| NAME64 * | GetExportedDeviceList (char *eqm) |
| Returns the list of exported device names explicitly associated with the equipment module passed as the input parameter. More... | |
| char * | GetExportedFecName (void) |
| Returns the FEC name exported at the time of server initialization. More... | |
| char * | GetExportedName (char *eqm) |
| Returns the exported name associated with the equipment function name given. More... | |
| char * | GetExportedSubSystem (char *eqmName) |
| Returns the exported subsystem associated with the equipment function name given. More... | |
| ExportListStruct * | GetExportListItem (char *eqm) |
| Returns a reference to the Export List Structure of the given equipment module. More... | |
| int | GetFieldFromBitfield (char *srv, char *tag, char *field, UINT32 value) |
| Retrieves the requested field value from a bit field. More... | |
| int | GetGCastTableCapacity (void) |
| gets the globals multicast table capacity (server-side) More... | |
| int | GetGroupDeviceMembers (char *eqm, char *grpname, NAME64 *members, int *len) |
| Gets the NAME64 list of member devices associated with the given group. More... | |
| int | GetIgnoreCommonFiles (void) |
| returns the current setting (default = FALSE) More... | |
| char * | GetLocalName (char *exportName) |
| Returns the local equipment module name associated with the export name given. More... | |
| int | GetMinimumAllowedPollingInterval (void) |
| returns the minimum polling rate in milliseconds a server will allow. More... | |
| int | GetNumberRegisteredDevices (char *eqm) |
| Gives the number of registered devices explicitly associated with the equiment module name given. More... | |
| int | GetNumCallers (char *eqm) |
| Returns the current number of callers associated with the equipment module given. More... | |
| int | GetNumCalls (char *eqm) |
| Returns the current number of calls to the given equipment module since startup. More... | |
| int | GetNumConsumers (char *eqm) |
| Returns the current number of consumers associated with the equipment module given. More... | |
| int | GetNumContracts (char *eqm) |
| Returns the current number of contracts associated with the equipment module given. More... | |
| int | GetPortOffset (const char *fecName) |
| Obtains the FEC port offset appropriate for the give FEC name. More... | |
| BYTE * | GetPropertyBuffer (char *eqmName, char *prpName) |
| Returns the address of the buffer previously assigned to the property given. More... | |
| int | GetPropertyId (char *eqm, char *prpName) |
| Gives the associated property identifier for the given property name. More... | |
| ExportPropertyListStruct * | GetPropertyListStruct (char *eqm, char *prpName, char *devName) |
| int | GetPropertySubscriptionRenewalLength (char *eqm, char *prpName, int *value) |
| Gets the current subscription renewal length for the property specified. More... | |
| char * | GetRegisteredContext (char *eqm) |
| Gives the registered context. More... | |
| char * | GetRegisteredExportName (char *eqm) |
| Gives the registered exported equipment module name. More... | |
| int | GetRegisteredNetworks (const char *eqm, NAME64 *list, int *listsize) |
| retrieves network list of ip addresses and subnets for which WRITE access is allowed More... | |
| int | GetRegisteredPropertyList (char *eqm, NAME64 *prpNames, int *nprps) |
| Returns the list of registered properties explicitly associated with the equipment module passed as the first argument input parameter. More... | |
| int | GetRegisteredPropertyListStruct (char *eqm, char *prpName, ExportPropertyListStruct *prpLstStruct) |
| Returns the ExportPropertyListStruct structure for the registered property specified by the first two arguments. More... | |
| int | GetRegisteredUsers (const char *eqm, NAME16 *userlist, int *listsize) |
| retrieves the currently assigned users with WRITE permissions on the equipment module in question. More... | |
| int | GetRejectOverloadedMetaProperties (void) |
| returns the current setting More... | |
| int | GetRetardSingleContractRemoval (void) |
| returns the current setting of this feature. More... | |
| int | GetSchedulerInterval (void) |
| Gets the system scheduler interval. More... | |
| int | GetSizeDeviceCapacity (char *eqm) |
| Gives the maximum size of the device table associated with the equiment module name given. More... | |
| char * | GetSystemAlias (char *name) |
| Gets the alias for either a registered property or registered device. More... | |
| int | GetSystemCycleDeadband (void) |
| Gets the system cycle deadband. More... | |
| int | GetSystemSubscriptionRenewalLength (void) |
| Gets the current contract subscription renewal length. More... | |
| int | GetSystemSynchronizeContracts (void) |
| Returns the setting for general contract synchronization at the server. More... | |
| char * | GetSystemVersionString (void) |
| Returns the system version appended with the library build id as a character string. More... | |
| int | GetValidDeviceNumber (char *eqm, char *devname, char *prpname, int ceiling) |
| Gives the valid registered device number for the specified device name and property name. More... | |
| int | IsStandAlone (void) |
| Determines whether a client or server process is running in stand-alone mode. More... | |
| int | JoinEquipmentGroup (char *eqmName, char *groupname, int groupindex) |
| Instructs the equipment module to join the specified equipment group. More... | |
| int | JoinEquipmentGroupEx (char *eqmName, char *groupname, int groupindex, char *devPrefix, char *devPostfix) |
| Instructs the equipment module to join the specified equipment group. More... | |
| int | OpenBitField (char *srv, char *tag, int fmt) |
| Declares a bit field type and registers with the bitfield registry. More... | |
| int | RedirectDeviceName (char *eqm, char *devname, char *rdr) |
| Applies the redirection string to the given device for all properties. More... | |
| int | RedirectProperty (char *eqm, char *property, char *rdr) |
| Applies the redirection string to the given property. More... | |
| int | RegisterDeviceName (char *eqm, char *devname, int devnr) |
| Assigns a device name to the specified device number. More... | |
| int | RegisteredPropertyIsWritable (char *eqm, char *prpName) |
| Returns TRUE if the given property is registered with the CA_WRITE access bit (in at least one overload). Otherwise the functionr returns FALSE. More... | |
| int | RegisterEquipmentModule (char *expName, char *eqmName, int numdevices, int(*fcn)(char *, char *, DTYPE *, DTYPE *, short), void(*ini)(void), void(*tsk)(void), int rate, void(*exi)(void)) |
| Registers an equipment module with the TINE server engine. More... | |
| int | RegisterEquipmentModuleEx (char *expName, char *eqmName, int numdevices, int(*fcn)(char *, char *, DTYPE *, DTYPE *, short, void *), void(*ini)(void *), void(*tsk)(void *), int rate, void(*exi)(void *), void *reference) |
| Registers an equipment module with the TINE server engine (extended call) More... | |
| int | RegisterFecInformation (char *name, char *sub, char *cntxt, char *dsc, char *loc, char *hdw, char *resp, UINT16 poff) |
| Assigns a FEC Name and descriptive information to the server process. More... | |
| int | RegisterFecName (char *name, char *desc, char *os, char *loc, char *hdw, char *resp, UINT16 poff) |
| Assigns a FEC Name to the server process. More... | |
| int | RegisterFecNameEx (char *name, char *desc, char *os, char *loc, char *hdw, char *resp, UINT16 poff, char *context) |
| Assigns a FEC Name to the server process. Extended call. More... | |
| int | RegisterMultiChannelGroupDevice (char *eqm, char *grpname, char *devname, int grpindex, int grpsize) |
| Assigns a device name to the specified multi-channel group device. More... | |
| int | RegisterProperty (char *eqm, char *property, int siz, short fmt, short acc, char *dsc) |
| Assigns pertinent information for the specified property. More... | |
| int | RegisterPropertyAccessDeadband (char *eqm, char *property, int access, int deadbandInMilliSeconds) |
| Assigns a minimum access deadband to the designated property. More... | |
| int | RegisterPropertyAlias (char *eqm, char *property, char *alias) |
| Assigns an alias to the specified property. More... | |
| int | RegisterPropertyAndHandler (char *eqm, EQMFCNP hndlr, char *prp, DTYPE *dout, DTYPE *din, short acc, short atype, UINT16 rowlen, char *dsc, PrpEgu *egu, PrpEgu *xegu, int pid) |
| Registers a device property and a property handler with the TINE server engine. If no equipment module name is given, an internal equipment module is provided by the TINE server engine, see API call RegisterServer. If not an internal equipment module but a specifically for this server created equipment module should be used, this can be indicated by the parameter eqmName, see below. More... | |
| int | RegisterPropertyAndHandlerEx (char *eqm, XEQMFCNP hndlr, char *prp, DTYPE *dout, DTYPE *din, short acc, short atype, UINT16 rowlen, char *dsc, PrpEgu *egu, PrpEgu *xegu, int pid, void *ref) |
| Registers a device property and a property handler with the TINE server engine (extended call). If no equipment module name is given, an internal equipment module is provided by the TINE server engine, see API call RegisterServer. If not an internal equipment module but a specifically for this server created equipment module should be used, this can be indicated by the parameter eqmName, see below. More... | |
| int | RegisterPropertyEx (char *eqm, char *property, int siz, short fmt, short acc, char *dsc, int pid) |
| Assigns pertinent information for the specified property. More... | |
| int | RegisterPropertyInformation (char *eqm, char *prp, DTYPE *dout, DTYPE *din, short acc, short atype, UINT16 rowlen, char *dsc, int pid, char *rdr) |
| Assigns pertinent information for the specified property. More... | |
| int | RegisterPropertyInformationEx (char *eqm, char *prp, DTYPE *dout, DTYPE *din, short acc, short atype, UINT16 rowlen, char *dsc, PrpEgu *egu, PrpEgu *xegu, int pid, char *rdr) |
| Assigns pertinent information for the specified property (extended version). More... | |
| short | RegisterPropertyQueryFunction (char *eqm, int(*fcn)(char *devName, PrpQueryStruct **prpqs), int numprops) |
| Registers a property query function. More... | |
| int | RegisterPropertySignalFunction (const char *eqm, const char *prp, PRPSIG fcn, int mask, void *ref) |
| Registers a property signal function. More... | |
| int | RegisterServer (char *expName, int numdevices, char *deviceNameList[]) |
| Registers an internal equipment module with the TINE server engine An internal equipment module is provided by the TINE server engine. So for creating a TINE server it is sufficient to register properties and respective property handlers, see also API call RegisterPropertyAndHandler. More... | |
| int | RegisterStateChangeCallback (SCCBFCNP fcn, const char *eqm, const char *stateKey, void *reference) |
| Registers a state change callback dispatch function. More... | |
| short | RegisterXPropertyQueryFunction (char *eqm, int(*fcn)(char *devName, XPropertyQueryStruct **xpqs), int numprops) |
| Registers an extended property query function. More... | |
| int | RemoveDevice (char *eqm, char *devname) |
| Removes a device name from an equipment module's device list. More... | |
| int | RemoveEquipmentModule (const char *eqm) |
| Unregisters an equipment module with the TINE server engine and frees all associated memory. More... | |
| int | RemoveProperty (char *eqm, char *property) |
| Removes a property name from an equipment module's property list. More... | |
| int | RemoveRegisteredBCastNetsList (NAME64 *ipaddr, int rmvsiz) |
| removes those networks in the name list given from the current broadcast list. More... | |
| int | RemoveRegisteredNetsList (const char *eqm, NAME64 *ipaddr, int rmvsiz) |
| removes those networks in the name list given from the current network address access list. More... | |
| int | RemoveRegisteredUser (char *eqm, NAME16 *userlist, int listsize) |
| removes those users in the name list given from the current users access list. More... | |
| int | ResetServerBaseline (const char *eqm) |
| Resets a server baseline timestamp to the current time. More... | |
| char * | ResolveSystemAlias (char *alias) |
| Gets the registered property or registered device name for the given alias. More... | |
| int | SealTaggedStruct (char *tag, int size, int number) |
| Seals a tagged structure (registration finished!). More... | |
| int | sendNetGlobal (char *keyword, DTYPE *din, void(*callback)(int, int), int minPeriod, int maxPeriod, double tolerance) |
| registers and sends the accompanying keyword and data as a network global. More... | |
| int | sendNetGlobalEx (char *context, char *keyword, DTYPE *din, void(*callback)(int, int), int minPeriod, int maxPeriod, double tolerance) |
| registers and sends the accompanying keyword and data as a network global for the specific context given. More... | |
| void | SetAllowBackgroundTaskReentrancy (int value) |
| Determines whether equipment module background tasks may be re-entered (boolean). More... | |
| void | SetAllowNetworkAddressResolution (int value) |
| Determines whether NETWORK address resolution is allowed. More... | |
| void | SetAllowRemoteManagement (int value) |
| Determines whether remote management via stock properties is possible. More... | |
| void | SetAppDate (time_t appdate) |
| Sets the compilation date of the current running server process. More... | |
| void | SetAppVersion (int major, int minor, int revision) |
| Sets the application version of the current running server process. More... | |
| void | SetAutoAdjustWorkAreaSize (int value) |
| Sets 'auto-adjust work area size' (based on number of registered properties) More... | |
| int | SetCallPropertyInSeparateThread (char *eqm, char *property, int value) |
| Determines whether the specified property is called in a separate handler thread or not. More... | |
| void | SetClientListCapacity (int value) |
| Sets the maximum number of clients a server will service. More... | |
| void | SetConfigurationCoded (int value) |
| Determines whether TINE configuration files will be scanned or not. More... | |
| void | SetContractListCapacity (int value) |
| Sets the maximum number of contracts a server will service. More... | |
| void | SetContractSignalFunction (CONSIG fcn, int mask, void *ref) |
| Registers a contract signal function. More... | |
| void | SetDefaultDeviceRegion (char *eqmName, char *region) |
| Sets the default device region to the value specified. More... | |
| int | SetDeviceDescription (char *eqm, char *devname, char *description) |
| Assigns a device description to the specified device. More... | |
| int | SetDeviceLocation (char *eqm, char *devname, char *location) |
| Assigns a device location text to the specified device. More... | |
| int | SetDeviceMask (char *eqm, char *devname, int mask) |
| Assigns a device mask to the specified device. More... | |
| int | SetDeviceOfflineStatus (char *eqm, char *devname, int offline) |
| Assigns an offline status to the specified device. More... | |
| int | SetDeviceRegion (char *eqm, char *devname, char *region) |
| Assigns a region code to the device in question. More... | |
| int | SetDeviceZPosition (char *eqm, char *devname, float zpos) |
| Assigns a Z (logitudinal) direction to the specified device. More... | |
| void | SetEnforceMcaAcquisition (int value) |
| Forces multi-channel array handshaking if set to TRUE. More... | |
| void | SetEqmCompletion (char *eqm, char *errstr) |
| Sets the error string to accompany the current server call. More... | |
| void | SetExportedContext (char *eqmName, char *context) |
| Assigns the exported context associated with the equipment function name given. More... | |
| void | SetExportedSubSystem (char *eqmName, char *subsystem) |
| Assigns the exported subsystem associated with the equipment function name given. More... | |
| int | SetFailoverMaster (char *eqm, char *masterName) |
| Sets the designated server as a failover master. More... | |
| void | SetFailoverPollingInterval (int pollingInterval) |
| Sets the server failover interval to the value given. More... | |
| int | SetFailoverSlave (char *eqm, char *masterName, char *slaveMaster) |
| Declares the server a failover slave and targets the designated server. More... | |
| void | SetFailoverThreshold (int errorCounts) |
| Sets the server failover threshold to the value given. More... | |
| void | SetGCastTableCapacity (int value) |
| sets the globals multicast table capacity More... | |
| void | SetIgnoreCommonFiles (int value) |
| turns searching for common database files in the FEC_HOME directory on or off More... | |
| void | SetInitializeIdle (int value) |
| When set to TRUE, all equipment modules are initialized in an 'idle' state. More... | |
| void | SetLogFileAllowScan (int value) |
| Sets the allowed range of log file retrieval from a FEC process (via stock property SRVLOGFILE). More... | |
| void | SetlookupRedirectionNameStub (int(*fcn)(char *eqm, char *prpName, char *devName)) |
| Sets a stub to an existing lookupRedirectionNameStub function for cases where a Property Query Function is in force and the server needs to redirect calls. More... | |
| void | SetMinimumAllowedPollingInterval (int value) |
| Sets the minimum polling interval in milliseconds a server will allow. More... | |
| int | SetNameServerAddress (char *ens) |
| Sets the address of the Equipment Name Server via API call. More... | |
| int | SetPropertyBuffer (char *eqmName, char *prpName, BYTE *buffer) |
| Assigns a fixed buffer to handle output data for the given property. More... | |
| int | SetPropertySubscriptionRenewalLength (char *eqm, char *prpName, int value) |
| Sets the current subscription renewal length for the property specified. More... | |
| void | SetRedirectionParameters (char *eqm, char *rdrCnt, char *rdrSrv, char *rdrDev, char *rdrPrp) |
| Sets the redirection string to accompany the current server call. More... | |
| void | SetRejectOverloadedMetaProperties (int value) |
| Enables/Disables overloaded meta properties. More... | |
| void | SetRetardSingleContractRemoval (int value) |
| sets the retard contract removal state More... | |
| int | SetScanForNetsFiles (const char *eqm) |
| Instructs the initialization process to look for device and property specific 'ipnets' files. More... | |
| int | SetScanForUsersFiles (const char *eqm) |
| Instructs the initialization process to look for device and property specific 'users' files. More... | |
| void | SetSchedulerInterval (int value) |
| Sets the system scheduler interval. More... | |
| int | SetSizeDeviceCapacity (char *eqm, int size) |
| Sets (increases) the maximum size of the device table and associated tables. More... | |
| int | SetStandAlone (int value) |
| Sets stand-alone mode. More... | |
| int | SetSystemAlias (char *alias, char *name) |
| Sets an alias for either a registered property or registered device. More... | |
| int | SetSystemAttribute (char *attribute, void *value, int format) |
| void | SetSystemCycleDeadband (int value) |
| Sets the system cycle deadband. More... | |
| void | SetSystemSubscriptionRenewalLength (int value) |
| Sets the contract subscription renewal length. More... | |
| void | SetSystemSynchronizeContracts (int value) |
| Establishes the setting for general contract synchronization at the server. More... | |
| UINT32 | SystemGetProcessId (void) |
| Returns the process id of the running application if available. More... | |
| char * | SystemGetStartupCommand (void) |
| Returns the command line used to start this process. More... | |
| char * | SystemGetStartupDirectory (void) |
| Returns the working directory in use when this process started. More... | |
Variables | |
| int | MaxNumClients = CLIENTLIST_CAPACITY |
| Determines the maximum number of clients a server will service. More... | |
| int | MaxNumContracts = CONTRACTLIST_CAPACITY |
| Determines the maximum number of contracts a server will service. More... | |
TINE server engine and registration API routines.
The API routines presented here deal almost exclusively with server-side registration calls. All TINE servers must export their behavior in the form of properties, devices, server names, etc. The routines offered here provide ways to do this. In most cases there are also alternatives based on startup configuration files such as fecid.csv, exports.csv, etc. On front-end systems where a local disk is available, this is the suggested registration method, since it avoids the hard coding of 'names' inside of the server programs themselves.
| int AcquireAndRegisterBitfield | ( | const char * | devName, |
| char * | tag | ||
| ) |
Acquires the bitfield specified by the bitfield tag from the specified device server.
This routine is largly useful for generic applications which need to display results. Logic which requires knowing 'which field does what' will in general also require knowing a priori the bitfield fields.
| devName | is the targeted device server where the bitfield is registered. |
| tag | is the bitfield tag |
| int AddFieldToBitField | ( | char * | srv, |
| char * | tag, | ||
| UINT32 | mask, | ||
| char * | field | ||
| ) |
Adds a field definition to a registered bitfield.
| srv | is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this". |
| tag | is the bitfield tag |
| mask | is the mask to be applied to the bitfield value to obtain the field element |
| field | is the field name assigned to the masked value. |
Example:
| int AddFieldToStruct | ( | char * | tag, |
| int | addr, | ||
| int | size, | ||
| int | fmt, | ||
| char * | field | ||
| ) |
Adds a field description to a tagged structure.
Use this routine to register the fields of your structure within the structure registry. The fields can be any TINE format type or another tagger structure (in which case fmt = CF_STRUCT, and field = <parent tag>fieldname).
| tag | structure tag name |
| addr | is the address offset of this field inside the structure. |
| size | is the array length if the described field. (not the size in bytes) |
| fmt | format of the new struct element |
| field | field name |
Example:
References illegal_format, invalid_field, invalid_structure_tag, out_of_local_memory, and struct_sealed.
| int AppendRegisteredBCastNetsList | ( | NAME64 * | iplist, |
| int | listsize | ||
| ) |
appends the current network broadcast list with the name list given
The network broadcast list assigned to FEC is often read in via configuration file (see ipbcast.csv or fec.xml). However networks can also be assigned via this API call. The list given will be appended to any existing list of allowed network addresses. Generally use of this API call or configuration files is unncessary, as most modern operating systems will be able to receive TINE multicasts. Some legacy systems will not be able to do this however. In such cases, applying a broadcast list will re-send all multicasted transmission as UDP broadcasts to those networks specified in the list.
| iplist | is a list of network addresses to be appended to the current broadcast list. If a network address in the input is already in the current access list, nothing happens. |
| listsize | is the size of the input list. |
| int AppendRegisteredNetsList | ( | const char * | eqm, |
| NAME64 * | iplist, | ||
| int | listsize | ||
| ) |
appends the current network access list with the name list given
The network access list assigned to FEC is often read in via configuration file (see ipnets.csv or fec.xml). However networks can also be assigned via this API call. The list given will be appended to any existing list of allowed network addresses.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| iplist | is a list of network addresses to be appended to the current network access list. If a network address in the input is already in the current access list, nothing happens. |
| listsize | is the size of the input list. |
| int AppendRegisteredUsers | ( | const char * | eqm, |
| NAME16 * | userlist, | ||
| int | listsize | ||
| ) |
appends the current users access list with the name list given
The users access list assigned to an equipment module is often read in via configuration file (see users.csv or fec.xml). However users can also be assigned via this API call. The list given will be appended to any existing list of allowed users.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| userlist | is a list of users to be appended to the current users access list. If a user in the input is already in the current access list, nothing happens. |
| listsize | is the size of the input list. |
| int AssertIsAdministrator | ( | const char * | usr | ) |
returns TRUE if the given user is a registered administrator
An addional class of uses (applicable to the entire FEC process) can be registered by supplying an 'admins.csv' file in analogy with a users.csv file. Users in this category are merely classified as 'administrators' and as such have no systematic meaning within the TINE library. However an equipment module displatch routine (the equipment function) can make use of this routine in order to limit specific WRITE operations to administrators only. Typically one checks the caller's username and upon a return of 'FALSE' from AssertIsAdministrator() then one returns 'unauthorized_action' from the equipment function.
| usr | is the users name whose administrative credentials are being verified. |
| int AssignDataStampsToGlobal | ( | char * | keyword, |
| int | dataStamp, | ||
| int | sysStamp | ||
| ) |
Assigns additional data stamps to the registered global keyword.
The keyword supplied must already exist in the globals table, else an error occurs.
Returns 0 upon successful globals transmission, otherwise a TINE error code.
| keyword | is the globals KEYWORD which identifies the data set being sent. |
| dataStamp | is a user-defined integer value to accompany the globals multicast. |
| sysStamp | is a system-defined integer value to accompany the globals multicast. |
| int AssignDeviceAccessList | ( | const char * | eqm, |
| const char * | dev, | ||
| NAME16 * | users, | ||
| int | nusers | ||
| ) |
Assigns an access list for the device given.
In addtion to the overall access lists for the server process, devices can be individually assigned a user access list.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| dev | is the registered device for the access list is to be applied. |
| users | is a list of user names for whom WRITE access is to be granted. |
| nusers | is the size of the users list supplied. |
| int AssignDeviceListToProperty | ( | char * | eqm, |
| char * | prp, | ||
| NAME64 * | devlst, | ||
| int | lstlen | ||
| ) |
Assigns the given device list to the given registered property.
Properties (e.g. multi-channel array properties) which wish to present a property-specific device list can assign the list to the property in this way.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is property name for which the device list is to be assigned. |
| devlst | is the device list which is to be associated with the given property |
| lstlen | is the length of the device list. |
| int AssignDeviceNetsList | ( | const char * | eqm, |
| const char * | dev, | ||
| NAME64 * | ipnets, | ||
| int | nipnets | ||
| ) |
Assigns an ip nets access list for the device given.
In addtion to the overall access lists for the server process, devices can be individually assigned a network access list.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| dev | is the registered device for the access list is to be applied. |
| ipnets | is a list of network names for which WRITE access is to be granted. For example a list entry "192.168.100.18" would grant the host at "192.168.100.18" WRITE access. The list entry "192.168.100.255" would grant all hosts on the .100 subnet write access, and so on. |
| nipnets | is the size of the ipnets list supplied. |
| int AssignNumDevices | ( | char * | eqm, |
| int | num | ||
| ) |
Fixes the number of modules (devices) attached to the specified equipment module.
Servers generally do not need to make this call, as the number of modules or devices is either specified in the local database file 'exports.csv', or has been passed as an argument in a call to RegisterEquipmentModule(). However, in cases where the number so assigns represents an upper limit, and the actual number of modules is only known after the server is running, then a call to AssignNumDevices() can be made to reduce the querieable number of modules to this number.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| num | is the number of modules (devices) to be associated with the equipment module |
| int AssignPropertyAccessList | ( | const char * | eqm, |
| const char * | prp, | ||
| NAME16 * | users, | ||
| int | nusers | ||
| ) |
Assigns an access list for the property given.
In addtion to the overall access lists for the server process, properties can be individually assigned a user access list.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is the registered property for the access list is to be applied. |
| users | is a list of user names for whom WRITE access is to be granted. |
| nusers | is the size of the users list supplied. |
| int AssignPropertyList | ( | char * | eqm, |
| char * | devname, | ||
| char * | listname, | ||
| int | listsize, | ||
| NAME64 * | prplist | ||
| ) |
Assigns the given property list to the given device to be used in device-oriented queries.
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. Most device servers provide a list of all instances, a device list, and a list of all properties, where every instance (device) supports all exported properties. Under some circumstances, it is desireable to support only a (device-specific) subset of properties per device. This can be achieved by supplying a property query function, or by configuration file, or by using this call to assign a property list to the specified device. The latter is the preferred method, as then all registered properties are contained within the TINE property registry, which will contain sometimes crucial additional information about the registered property.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name in question (up to 32 characters, preferably 16 or less). |
| listname | is a 'tag' name to be assigned to the list. Where many devices share the same property list, this tag is used to avoid unnecessarily allocating new memory for the same list. |
| listsize | is the length of the property list. |
| list | is the property list as an array of NAME64 entities. If the list provided is not at least as long as indicated by parameter listsize, the server's behavior is undefined. |
References argument_list_error, and illegal_data_size.
| int AssignPropertyNetsList | ( | const char * | eqm, |
| const char * | prp, | ||
| NAME64 * | ipnets, | ||
| int | nipnets | ||
| ) |
Assigns an ip nets access list for the property given.
In addtion to the overall access lists for the server process, properties can be individually assigned a network access list.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is the registered property for the access list is to be applied. |
| ipnets | is a list of network names for which WRITE access is to be granted. For example a list entry "192.168.100.18" would grant the host at "192.168.100.18" WRITE access. The list entry "192.168.100.255" would grant all hosts on the .100 subnet write access, and so on. |
| nipnets | is the size of the ipnets list supplied. |
| int ExecLocalLink | ( | const char * | devName, |
| const char * | devProperty, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | access | ||
| ) |
Executes a synchronous link within the local process.
Synchronous data exchange within a process. ExecLocalLink() does not complete until the data transfer has completed or a timeout has ensued. ExecLocalLink() has marginal applicability other than processing and returning the result of a call within a server, which could be of use if multiple equipment functions are bound together or a server's background task needs to know the outcome of a call into the server, etc.
| devName | is the local device name, prefixed with the corresponding local equipment module name. (<Equipment Module Name>/<Device>) of the device to contact. For example: "BPMEQM/WL167". |
| devProperty | is the device property requested, for example "ORBIT.X" |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| din | is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server |
| access | is the data access mode. This can be any combination of TINE access code ORed together (e.g. CA_READ|CA_WRITE). |
References argument_list_error.
| int FindNameServerOnNetwork | ( | void | ) |
Issues a multicast (or broadcast) to which the TINE equipment name server responds.
In lieu of accessing the file 'cshosts.csv' (whose location is determined by the environment variable TINE_HOME) a server can make this call to ascertain the address(es) of the Equipment Name Server (ENS). This is an option for platforms which do not have a hard disk and do not know a-priori the address of the equipment name server. This call will in fact be made automatically as a last resort to find the ENS address if (1) there is no cshost.csv information, (2) the ENS address was not explicitly assigned, and (3) there is no DNS entry for 'tineens' (or 'tineens1', 'tineens2', 'tineens3') on the local domaine.
| int FindServerOnNetwork | ( | char * | context, |
| char * | eqmName, | ||
| char * | exportName, | ||
| FecAddrStruct * | fec, | ||
| ExpDataStruct * | srv | ||
| ) |
Issues a multicast (or broadcast) to which configured TINE central servers respond.
Diskless (or otherwise 'in-a-box') servers which need to find central servers such as the Equipment Name Server, Central Alarm Server, or Post-Mortem Server, etc. can issue this call to ascertain the address.
| 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(), link_timeout, NAME16::name, NAME32::name, and DUNION::vptr.
| void FlushContractTable | ( | void | ) |
Flushes the current contract and client entry tables.
Calling this routine will effectively disconnect all attached clients and remove all persistent contracts. This will appear to any connected client to be a server 'time-out' and attached clients will attempt to re-establish any lost connections. Any link callbacks a client might have will receive 'link_timeout' status messages during the reconnection interval. Thus this routine can effectively be used to signal a 'server restart' during server runtime.
| int GetAllowBackgroundTaskReentrancy | ( | void | ) |
Returns whether equipment module background tasks may be re-entered (boolean).
If set to TRUE, the server's background task will allow re-entrancy which might occur if the task rate instructs the background task to be called even though the previous call has not yet returned. In such cases the programmer must deal with whatever reentrancy issues there might be. This routine returns the current setting.
| int GetAllowedRemoteManagement | ( | void | ) |
Returns whether remote management via stock properties is possible.
The stock properties "SRVEXIT", "SRVINIT", "SRVRESET" will return 'not_allowed' unless remote managment is turned on (default OFF)
| int GetAllowNetworkAddressResolution | ( | void | ) |
returns whether NETWORK address resolution is allowed
In an ENS-less (minimal) infrastructure, an initializing client can attempt to find server addresses by sending a NETWORK (multicast) probe to ascertain a server's address. In lieu of an ENS configuration, this requires a running server (configured to respond to NETWORK requests). Otherwise the servers address cannot be resolved.
| int GetBitfieldAsString | ( | char * | srv, |
| char * | tag, | ||
| UINT32 | value, | ||
| char * | strbuf, | ||
| int | buflen | ||
| ) |
Retrieves the requested field value from a bit field as a string value.
| srv | (input) is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this". |
| tag | (input) is the bitfield tag |
| field | (input) is the field for which the values is desired |
| value | (input) is the full value of the bitfield (cast as a 32 bit integer) |
| strbuf | (output) is the string buffer which should contain the converted string value |
| buflen | (input) is the length of the supplied string buffer |
| char* GetCaller | ( | char * | eqmName | ) |
Gives the user name of the current caller.
If a call to an equipment module is made on behalf of more than one user, then GetCaller() only refers to the first in the list. Typically, GetCaller() is used to see who is making a WRITE access call, which is usually synchronous and has only one user attached. When more information is required or the contract is liable to be monitored by many clients, then GetCallerInfo() should be used instead.
| eqmName | (in) is the equipment function name (local name) for which the exported name is desired. |
Example:
References GetCallerInfo(), and NAME16::name.
| int GetCallerInfo | ( | char * | eqmName, |
| NAME16 * | un, | ||
| BYTE * | ipx, | ||
| UINT32 * | ip, | ||
| short * | prot, | ||
| int * | num | ||
| ) |
Returns the user name(s) and network address(es) of all callers interested in the current contract.
| eqmName | (in) is the equipment function name (local name) for which the exported name is desired. |
| un | (out) if non-NULL is a reference to an array of NAME16 objects to be filled with the caller list |
| ipx | (out) if non-NULL is a reference to a byte array to be filled with the IPX addresses of the caller(s). |
| ip | (out) if non-NULL is a reference to an unsigned long array to be filled with the IP addresses of the caller(s). |
| prot | (out) if non-NULL is a reference to a short array to be filled with the requested protocol level of the caller(s). |
| num | (in/out) is a reference to an int value which initially contains the buffer size of the array references used in the parameter list. Upon return of the call, it contains the actual number of callers. |
Example:
Referenced by GetCaller().
| int GetCallerInformation | ( | char * | eqm, |
| ClnInfo * | clnInfoList, | ||
| int * | num | ||
| ) |
Returns the user name, network address and other information of all callers interested in the current contract.
| 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:
| int GetClientListCapacity | ( | void | ) |
Gets the maximum number of clients a server will service.
A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number clients, then this value should be set accordingly at initialization time. The current setting can be obtained with this call
| int GetConfigurationCoded | ( | void | ) |
Returns whether TINE configuration files will be scanned.
| void** GetContractDataReference | ( | ExportListStruct * | el | ) |
returns a pointer to a useable reference pointer associated with the contract currently being accessed.
If some persistence is desired over the lifetime of a registered contract, this function may be used to associate a specific reference. A contract will provide a reference pointer initialized to a NULL pointer. By obtaining the pointer to this reference, a specific pointer can then be assigned. This is expected to be entirely managed by the user, who is then responsible for all cleanup activity when the contract goes out of scope.
| el | is a reference to the targeted Export List Structure (obtained via a call to GetExportListItem()). |
Referenced by GetContractDataReferenceByEqmName().
| void** GetContractDataReferenceByEqmName | ( | char * | eqm | ) |
returns a pointer to a useable reference pointer associated with the contract currently being accessed.
If some persistence is desired over the lifetime of a registered contract, this function may be used to associate a specific reference. A contract will provide a reference pointer initialized to a NULL pointer. By obtaining the pointer to this reference, a specific pointer can then be assigned. This is expected to be entirely managed by the user, who is then responsible for all cleanup activity when the contract goes out of scope.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
References GetContractDataReference().
| int GetContractListCapacity | ( | void | ) |
Gets the maximum number of contracts a server will service.
A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number contracts, then this value should be set accordingly at initialization time. The current setting can be obtained with this call
| int GetCurrentFailoverState | ( | void | ) |
Returns current master slave state of server.
If configured for master slave operation, the current state of a server is either master or slave. As this is defined for EQMs it could be possible to misconfigure a server such that one EQM operates as master and another as a slave. Until we can think of a meaningful usecase for such a configuration, we return an indicator for an inconsistent configuration in such a case. We use the Definitions: FAILOVER_NONE (0), FAILOVER_MASTER (1), FAILOVER_SLAVE (2), FAILOVER_MASTER | FAILOVER_SLAVE (3), ~FAILOVER_NONE (-1)
| int GetDefaultDeviceRegion | ( | char * | eqmName | ) |
Returns the default device region.
| eqmName | is the equipment function name (local name) for which the exported subsystem is desired. |
| char* GetDeviceDescription | ( | char * | eqm, |
| int | devnr | ||
| ) |
Gives the registered device description (if known) for the device number.
A server can determine the device description which has been associated with a device number by making this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devnr | is the device number to be looked up. |
| int GetDeviceGroups | ( | char * | eqm, |
| NAME64 * | groups, | ||
| int * | len | ||
| ) |
Gets a NAME64 list of registered device groups.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| groups | [out] is a pointer to a NAME64 buffers to receive the list |
| len | [in, out] is a pointer to buffer length (input) and contains the length of device groups list returned. |
| char* GetDeviceLocation | ( | char * | eqm, |
| int | devnr | ||
| ) |
Gives the registered device location (if known) for the device number.
A server can determine the device location which has been associated with a device number by making this call. This information should provide the physical location of the device hardware (e.g. Bldg 1, Rm 101, Rack 15, slot 2).
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devnr | is the device number to be looked up. |
| int GetDeviceMask | ( | char * | eqm, |
| int | devnr | ||
| ) |
Gives the registered device mask for the device number.
A server can determine the device mask which has been associated with a device number by making this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devnr | is the device number to be looked up. |
| char* GetDeviceName | ( | char * | eqm, |
| int | devnr | ||
| ) |
Gives the registered device name for the specified equipment module and device number.
A server can determine the name which has been associated with a device number by making this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devnr | is the device number to be looked up. |
Alias: GetModuleName
Example:
| int GetDeviceNumber | ( | char * | eqm, |
| char * | devname | ||
| ) |
Gives the registered device number for the specified device name.
Callers frequently address specific devices by their human-readable names rather than a device number (which might be an entry point into an array, for example). If the caller registers device names via calls to RegisterDeviceName() then the cross reference exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding device number from an input device name by calling GetDeviceNumber().
Passing a device name of the form "#7" will return '7'
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is the device name to be looked up |
Alias: GetModuleNumber
Example:
References GetValidDeviceNumber().
Referenced by ClearDeviceAlarm(), and RemoveDeviceAlarm().
| int GetDeviceNumberEx | ( | char * | eqm, |
| char * | devname, | ||
| char * | prpname | ||
| ) |
Gives the registered device number for the specified device name and property name.
Callers frequently address specific devices by their human-readable names rather than a device number (which might be an entry point into an array, for example). If the caller registers device names via calls to RegisterDeviceName() or has registered a "<property>.NAM" meta property (corresponding to a property-specific set of device names for <property>), then the cross reference exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding device number from an input device name by calling GetDeviceNumberEx().
Passing a device name of the form "#7" will return '7'
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is the device name to be looked up |
| prpname | if non-NULL should be the targeted property name for which the device names apply |
Example:
References GetValidDeviceNumber().
| int GetDeviceOfflineStatus | ( | char * | eqm, |
| int | devnr | ||
| ) |
Gives the current off line status for the device in question.
This is a software flag which can be used to steer the output in wildcard calls or certain multi-channel array calls.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devnr | is the device number to be looked up. |
| float GetDeviceZPosition | ( | char * | eqm, |
| int | devnr | ||
| ) |
Gives the registered device Z (or longitudinal) position for the device number.
A server can determine the device Z (or longitudinal) position which has been associated with a device number by making this call. This will give the position of the measurement along the path of the beam.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devnr | is the device number to be looked up. |
| int GetEnforceMcaAcquisition | ( | void | ) |
returns the setting for multi-channel array handshaking enforcement.
A server can absolutely enforce multi-channel array handshaking independent of the release level of the client. This has relevance as to whether persistent single-element links are allowed or not. If allowed then a 'modern' client might be able to latch on to a pre-existing single-element link established by an older client.
| char* GetExportedContext | ( | char * | eqmName | ) |
Returns the exported context associated with the equipment function name given.
A server as coded, frequently does not know the context under which it is registered, as this is information is often contained in a registration file such as 'fecid.csv' or 'exports.csv'. Nonetheless it might be desireable to know what name was actually exported, for use in say conditional trapping or logging. This call returns the name finally exported after the server has been initialized.
| eqmName | is the equipment function name (local name) for which the exported context is desired. |
| NAME64* GetExportedDeviceList | ( | char * | eqm | ) |
Returns the list of exported device names explicitly associated with the equipment module passed as the input parameter.
A server can retieve the list of explicitly exported device names by making this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| char* GetExportedFecName | ( | void | ) |
Returns the FEC name exported at the time of server initialization.
| char* GetExportedName | ( | char * | eqmName | ) |
Returns the exported name associated with the equipment function name given.
A server as coded, frequently does not know its system wide identity (i.e. its 'export name'), as this is information is contained in a registration file such as 'exports.csv'. Nonetheless it might be desireable to know what name was actually exported, for use in say conditional trapping or logging. This call returns the name finally exported after the server has been initialized.
| eqmName | is the equipment function name (local name) for which the exported name is desired. |
| char* GetExportedSubSystem | ( | char * | eqmName | ) |
Returns the exported subsystem associated with the equipment function name given.
A server as coded, frequently does not know the subsystem under which it is registered, as this is information is often contained in a registration file such as 'fecid.csv' or 'exports.csv'. Nonetheless it might be desireable to know what name was actually exported, for use in say conditional trapping or logging. This call returns the name finally exported after the server has been initialized.
| eqmName | is the equipment function name (local name) for which the exported subsystem is desired. |
| ExportListStruct * GetExportListItem | ( | char * | eqm | ) |
Returns a reference to the Export List Structure of the given equipment module.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| int GetFieldFromBitfield | ( | char * | srv, |
| char * | tag, | ||
| char * | field, | ||
| UINT32 | value | ||
| ) |
Retrieves the requested field value from a bit field.
| srv | is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this". |
| tag | is the bitfield tag |
| field | is the field for which the values is desired |
| value | is the full value of the bitfield (cast as a 32 bit integer) |
| int GetGCastTableCapacity | ( | void | ) |
gets the globals multicast table capacity (server-side)
| int GetGroupDeviceMembers | ( | char * | eqm, |
| char * | grpname, | ||
| NAME64 * | members, | ||
| int * | len | ||
| ) |
Gets the NAME64 list of member devices associated with the given group.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| grpname | is device group name |
| members | [out] is a pointer to a NAME64 buffers to receive the list |
| len | [in, out] is a pointer to buffer length (input) and contains the length of members list returned. |
| int GetIgnoreCommonFiles | ( | void | ) |
returns the current setting (default = FALSE)
When set to TRUE, attempts to read an exports.csv or related equipment module files which directly reside in the FEC_HOME directory (or working directory, if not set) are blocked. Any related files within the equipment module 'local name' sub-directory will still be scanned and read.
| char* GetLocalName | ( | char * | exportName | ) |
Returns the local equipment module name associated with the export name given.
| exportName | is the exported device server name for which the local equipment module name is desired. |
| int GetMinimumAllowedPollingInterval | ( | void | ) |
returns the minimum polling rate in milliseconds a server will allow.
A server will not honor polling rates smaller than this value. An attempt to poll a property a 1 msec for instance will be serviced at the MinPollingRate instead. If it is known that the server should support very fast polling rates, then this value should be set accordingly at initialization time.
| int GetNumberRegisteredDevices | ( | char * | eqm | ) |
Gives the number of registered devices explicitly associated with the equiment module name given.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| int GetNumCallers | ( | char * | eqm | ) |
Returns the current number of callers associated with the equipment module given.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
References GetNumConsumers().
| int GetNumCalls | ( | char * | eqm | ) |
Returns the current number of calls to the given equipment module since startup.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| int GetNumConsumers | ( | char * | eqm | ) |
Returns the current number of consumers associated with the equipment module given.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
Example:
Referenced by GetNumCallers().
| int GetNumContracts | ( | char * | eqm | ) |
Returns the current number of contracts associated with the equipment module given.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
Example:
| int GetPortOffset | ( | const char * | fecName | ) |
Obtains the FEC port offset appropriate for the give FEC name.
In cases where the pure registration API routines are used to register FEC and server information (as opposed to a common fecid.csv configuration file) it is often a more cumbersome task to ensure a unique FEC port on the host machine. This routine can be used to this end. It will search the existing FEC manifest on the current host in order to find the matching entry for the given FEC name. If the entry is not found, then the 'next free port' is returned. In this way the FEC can always register with its own proper FEC port, without the need to hard code this number.
If this routine is called after the server is running and the FEC name is not found in the manifest the -name_unknown is returned.
| fecName | is the FEC name in question (up to 16 characters). |
example
References argument_list_error, and not_implemented.
| BYTE* GetPropertyBuffer | ( | char * | eqmName, |
| char * | prpName | ||
| ) |
Returns the address of the buffer previously assigned to the property given.
Generally an equipment module's dispatch handler is called with a reference to an allocated buffer into which the property's output is written. In some circumstances (e.g. large video frames) it is prudent to instruct the dispatch handler to make use of a pre-assigned buffer area (which is likely already filled with data) and to forgo any double buffering and memory copying that might otherwise occur. If a buffer has been assigned, its address can be obtained with this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | is the registered property for which the buffer space is desired. |
| int GetPropertyId | ( | char * | eqm, |
| char * | prpName | ||
| ) |
Gives the associated property identifier for the given property name.
Callers will alway address properties by their human-readable names. Equipment modules can either initiate a series of strcmp()s in order to determine which property is being called or make direct use of the associated property identifier in a case switch or address table. Note that properties registered with RegisterProperty() simply return an index in the server's ordered list. You can associate any indentifier you like by calling either RegisterPropertyEx() or RegisterPropertyInformation() to register the property. The cross reference from property name to property identifier exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding identifier from an input property by calling GetPropertyId().
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | is the property name to be looked up |
Example:
| ExportPropertyListStruct* GetPropertyListStruct | ( | char * | eqm, |
| char * | prpName, | ||
| char * | devName | ||
| ) |
\intern Finds the 'first in the list' (i.e. last registered) 'default' property. Overloads are not considered.
Referenced by GetPropertySubscriptionRenewalLength(), GetRegisteredPropertyListStruct(), RegisterPropertyAccessDeadband(), RegisterPropertyAlias(), SetCallPropertyInSeparateThread(), and SetPropertySubscriptionRenewalLength().
| int GetPropertySubscriptionRenewalLength | ( | char * | eqm, |
| char * | prpName, | ||
| int * | value | ||
| ) |
Gets the current subscription renewal length for the property specified.
Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be retrieved with this call.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | is the registered property for the buffer is to be assigned. |
| value | is a reference to the integer variable to hold the returned setting. |
References argument_list_error, GetPropertyListStruct(), and invalid_property.
| char* GetRegisteredContext | ( | char * | eqm | ) |
Gives the registered context.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| char* GetRegisteredExportName | ( | char * | eqm | ) |
Gives the registered exported equipment module name.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| int GetRegisteredNetworks | ( | const char * | eqm, |
| NAME64 * | list, | ||
| int * | listsize | ||
| ) |
retrieves network list of ip addresses and subnets for which WRITE access is allowed
| list | (output) is a buffer to receive a list of relevant network addresses and subnets |
| listsize | (input/output) is the size of the input list. |
| int GetRegisteredPropertyList | ( | char * | eqm, |
| NAME64 * | prpNames, | ||
| int * | nprps | ||
| ) |
Returns the list of registered properties explicitly associated with the equipment module passed as the first argument input parameter.
A server can retieve the list of registered properties by making this call. This is sometimes useful when the property list is maintained in an 'exports.csv' file and the server application needs to retrieve this list.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpNames | (output) is the address location which is to hold the property list upon completion |
| nprps | (intput/output) is a pointer to an integer which as input specifies the size of the buffer pointed to by the second parameter. Upon return it contains the actual number of registered properties. |
| int GetRegisteredPropertyListStruct | ( | char * | eqm, |
| char * | prpName, | ||
| ExportPropertyListStruct * | prpLstStruct | ||
| ) |
Returns the ExportPropertyListStruct structure for the registered property specified by the first two arguments.
A server can retieve the ExportPropertyListStruct structure of the input registered property by making this. This will give the full information pertaining to the property given.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | (input) is the name of the property for which the ExportPropertyListStruct structure is desired. |
| prpLstStruct | (output) contains the output structure when the call completes. |
References argument_list_error, GetPropertyListStruct(), and not_registered.
Referenced by AssertRangeValid().
| int GetRegisteredUsers | ( | const char * | eqm, |
| NAME16 * | userlist, | ||
| int * | listsize | ||
| ) |
retrieves the currently assigned users with WRITE permissions on the equipment module in question.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| userlist | [output] is NAME16 array buffer to receive the list of users with WRITE privileges. |
| *listsize | [input,output] is a pointer reference to the initial size of the 'userlist' buffer. When the call completes *listsize will contain the actual number of users in the equipment module's user list. |
| int GetRejectOverloadedMetaProperties | ( | void | ) |
returns the current setting
Meta-properties such as .HIST or .NAM can be 'overloaded' by registering the appropriately named property. This will prevent the systematically available meta-property from being called. This is by default the case (if a property ABC.HIST is itself registered it will be called instead of the TINE local history). Explicitly calling SetRejectOverloadedMetaProperties(TRUE) will disable this feature.
| int GetRetardSingleContractRemoval | ( | void | ) |
returns the current setting of this feature.
When all clients disappear from a contract the contract is then scheduled for removal at the server. This can either happen 'immediately' or be 'retarded' for a duration of 1 second. Typically a synchronous READ or WRITE command establishes a transient contract which if allowed to persist for this extra second can handle 'RETRY' requests by returning the results of the contract. However this strategy also occupies a slot in the servers contract table until the contract is officially removed, when can effectively lock up the contract table if a large number of synchronous requests are issued (clients will receive a 'resources_exhausted' return code in such cases. If a server can tolerate idempotent requests (the same request twice, so to speak) then it might be advisable to turn this feature off.
| int GetSchedulerInterval | ( | void | ) |
Gets the system scheduler interval.
The TINE kernel will call the scheduler regularly in order to service the current contract list. Under some circumstances it may be wished to control this interval. For instance, if it is known a priori that a server will need to respond to heavy synchronous polling while at the same time maintaining a lengthy contract list, it is desireable to limit the number of passes through the scheduler per second (as this will traverse the contract list with each pass). Thus setting the scheduler interval to some reasonable number (e.g. 50 or 100 milliseconds) might significantly reduce the CPU load on the server. Note however, that this will impose a latency on all synchronous requests! If the value for the schedular interval is set to 0 (the default value) or less, then the scheduler will be called at often as necessary, usually at the system polling interval (as determined by the most eager contract) and/or following a client request.
| int GetSizeDeviceCapacity | ( | char * | eqm | ) |
Gives the maximum size of the device table associated with the equiment module name given.
This given the originally registered amount of device space for this equipment module. Attempts to register devices with device numbers greater than this value will fail.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| char * GetSystemAlias | ( | char * | name | ) |
Gets the alias for either a registered property or registered device.
A client can make use of an alias in place of either a registered device name or a registered property name in any call. The alias name will be replaced by its target within the contract tables. Property aliases are also returned in queries to obtain the registered property list.
| name | is the name of the alias target (either a registered device or a registered property). |
| int GetSystemCycleDeadband | ( | void | ) |
Gets the system cycle deadband.
A TINE client or server requires a 'cycler' to run either on separate thread (see SystemStartCycleTimer() where available) or as part of a user defined engine (running SystemCycle() in an infinite loop). The cycler will block on incoming network traffic for a duration up to the given system cycle deadband (typically 10 msec). Either a network request wakes the cycler up or the deadband timeout expires. Following this other background activity will take place (such as processing contracts, checking local histories, and alarms, etc.). The system cycle deadband can be read with this API call.
| 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.
| int GetSystemSynchronizeContracts | ( | void | ) |
Returns the setting for general contract synchronization at the server.
A server will try to schedule contracts at the regular intervals necessary to satisfy its clients' needs. If 'contract synchronization' is in effect, the server will attempt to call the relevant equipment module dispatch routines in a tight loop in order to collect and disperse information in the smallest number of data transfers (contract packing). You can ascertain the current setting with this API call.
| char* GetSystemVersionString | ( | void | ) |
Returns the system version appended with the library build id as a character string.
References SystemVersion().
| int GetValidDeviceNumber | ( | char * | eqm, |
| char * | devname, | ||
| char * | prpname, | ||
| int | ceiling | ||
| ) |
Gives the valid registered device number for the specified device name and property name.
Callers frequently address specific devices by their human-readable names rather than a device number (which might be an entry point into an array, for example). If the caller registers device names via calls to RegisterDeviceName() or has registered a "<property>.NAM" meta property (corresponding to a property-specific set of device names for <property>), then the cross reference exists in the form of a hash table. A server's equipment module can thus rapidly determine the corresponding device number from an input device name by calling GetValidDeviceNumber().
Passing a device name of the form "#7" and ceiling < 0 will return '7' only if '7' does in fact correspond to a valid device. This is different from a call to either GetDeviceNumber() or GetDeviceNumberEx(), which dutifully return the parsed and converted device number. To retain this behavior, you should pass ceiling = 0. Passing a value of ceiling > 0 will use the passed value to determine the validity of the device string.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is the device name to be looked up |
| prpname | if non-NULL should be the targeted property name for which the device names apply |
| ceiling | is the valid upper limit for a valid device number. This plays a role only if a devname with a leading '#' is passed. Pass a value < 0 to validate according to the registered device information. Pass a value > 0 to validate according to literal value passed. ceiling = 0 will simply return the converted string value (same behavior as GetDeviceName()). |
Referenced by GetDeviceNumber(), and GetDeviceNumberEx().
| int IsStandAlone | ( | void | ) |
Determines whether a client or server process is running in stand-alone mode.
Stand-alone mode is generally set by setting the environment variable TINE_STANDALONE to TRUE prior starting the client or server process. If TRUE, no attempt is made to contact the TINE equipment name server. Instead the local address CACHE is consulted. A server updates its own entry by supplying the registered port offset and the loopback address.
Default: FALSE.
| int JoinEquipmentGroup | ( | char * | eqm, |
| char * | groupname, | ||
| int | groupindex | ||
| ) |
Instructs the equipment module to join the specified equipment group.
It is sometimes desireable to access a collection of like devices via a device group, rather than a device server. This is of course true when the devices in the group span more than one physical device server. You can use this API call to instruct the equipment module to join the specified group. You should use this call prior to calling SystemCycle().
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| groupname | is the name of the group the equipment module is to join. |
| groupindex | is an ordered index, which can specify which location within the group this equipment module's devices are to have. If '0' is passed, the group server will assign an order. |
Example:
| int JoinEquipmentGroupEx | ( | char * | eqmName, |
| char * | groupname, | ||
| int | groupindex, | ||
| char * | devPrefix, | ||
| char * | devPostfix | ||
| ) |
Instructs the equipment module to join the specified equipment group.
It is sometimes desireable to access a collection of like devices via a device group, rather than a device server. This is of course true when the devices in the group span more than one physical device server. You can use this API call to instruct the equipment module to join the specified group. You should use this call prior to calling SystemCycle(). With the extended call you can also pass an optional prefix or postfix to be appended to the device names used at the group server. This can be a very useful option where multiple instances of a device server each supply a device list of identical names (e.g. where the device names do not correspond to specific locations, etc.).
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| groupname | is the name of the group the equipment module is to join. |
| groupindex | is an ordered index, which can specify which location within the group this equipment module's devices are to have. If '0' is passed, the group server will assign an order. |
| devPrefix | is a (up to 8-character) prefix to be added to all device names acquired from the physical server. |
| devPostfix | is a (up to 8-character) prostfix to be appended to all device names acquired from the physical server. |
Example:
| int OpenBitField | ( | char * | srv, |
| char * | tag, | ||
| int | fmt | ||
| ) |
Declares a bit field type and registers with the bitfield registry.
| srv | is the orginating server declaring the bitfield. A server declaring a bit field should pass a NULL or otherwise a simple tag such as "this". |
| tag | is the bitfield tag |
| fmt | is the bit field format (one of CF_BITFIELD8, CF_BITFIELD16, or CF_BITFIELD32). |
| int RedirectDeviceName | ( | char * | eqm, |
| char * | devname, | ||
| char * | rdr | ||
| ) |
Applies the redirection string to the given device for all properties.
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. A server can export devices which live on other servers. To do so a redirection string needs to be applied to the device in question.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name in question. |
| rdr | is the redirection string whose general form is "/<context>/<server>/<device>/[property]". The only relevant tag in the redirection string is the <server> tag as a call to RedirectDeviceName will apply to all properties for the specified device. The <context> tag is as yet always assumed to be the same context as the redirecting server. Thus the redirection string can be specified as simply "<server>" |
| int RedirectProperty | ( | char * | eqm, |
| char * | prop, | ||
| char * | rdr | ||
| ) |
Applies the redirection string to the given property.
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. A server can export properties or devices which live on other servers. To do so a redirection string needs to be applied to the property in question. As different registered devices can also be redirected to different servers. This routine can be called several times for the same property, once for each remote device.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prop | is property name in question (up to 64 characters). |
| rdr | is the redirection string of the form "/<context>/<server>/<device>/[property]" where <server> is the only non-optional entry in the redirection string. If <device> is omitted, all calls for the given property will be redirected to the given <server>. If device is included, only those calls to the specified device and property will be redirected. If <property> is specified then the given property name will be redirected to the remote <server> and the remote <property>. |
Example:
| int RegisterDeviceName | ( | char * | eqm, |
| char * | devname, | ||
| int | devnr | ||
| ) |
Assigns a device name to the specified device number.
Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is frequently very efficient to code in terms of device numbers which might be an index into an array, but to specify modules in calls by their human-readable names. For such purposes a device name can be assigned to a number at initialization via a call to RegisterDeviceName() (alias: RegisterModuleName()). An alternative is to provide a startup database file 'devices.csv' containing a cross-reference for numbers and names. Internally, a hash table is maintained for fast lookups inside equipment module routines.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| devnr | is the device number associated with the device name specified. |
Example:
| int RegisteredPropertyIsWritable | ( | char * | eqm, |
| char * | prpName | ||
| ) |
Returns TRUE if the given property is registered with the CA_WRITE access bit (in at least one overload). Otherwise the functionr returns FALSE.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | (input) is the name of the property for which the WRITE access is to be determined. |
| int RegisterEquipmentModule | ( | char * | expName, |
| char * | eqm, | ||
| int | ndevices, | ||
| int(*)(char *, char *, DTYPE *, DTYPE *, short) | fcn, | ||
| void(*)(void) | ini, | ||
| void(*)(void) | tsk, | ||
| int | rate, | ||
| void(*)(void) | exi | ||
| ) |
Registers an equipment module with the TINE server engine.
The point of contract between the TINE server engine and server-specific code is the equpment module, which can be regarded as an interupt service routine.
| expName | is the exported device server name to be associated with this equipment module. If this is NULL, then it is assumed that an 'exports.csv' local database file exists, which contains the export name. Otherwise it will contain a system-wide unique name (e.g. "HERA-P-BPM") |
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| ndevices | is this number of devices managed via this equipment module. If this is 0, then it is assumed that an 'exports.csv' local database file exists, which contains the number of devices. |
| fcn | is a reference to the equipment module, which must have the prototype shown. Namely, it is an interrupt service routine which will receive the device name, device property, the output data set, the input data set, and the data access flags as parameters. |
| ini | is a reference to an initialization routine which should be called prior to enabling the equipment module. It does not take arguments. |
| tsk | is a reference to a background task which will be called at regular intervals, and is frequently used for hardware IO, etc. Where multi-threaded servers are specified, or VxWorks tasks are available these tasks exists as separate threads, or tasks. In other cases, they are managed by the TINE server engine scheduler. |
| rate | is the rate in milliseconds used to schedule the background task supplied by the 'tsk' parameter. |
| exi | is a reference to an exit routine which should be called prior to shutting down the equipment module. It does not take arguments, and applies of course to graceful exits of the server. |
Example:
Referenced by RegisterServer().
| int RegisterEquipmentModuleEx | ( | char * | expName, |
| char * | eqmName, | ||
| int | numdevices, | ||
| int(*)(char *, char *, DTYPE *, DTYPE *, short, void *) | fcn, | ||
| void(*)(void *) | ini, | ||
| void(*)(void *) | tsk, | ||
| int | rate, | ||
| void(*)(void *) | exi, | ||
| void * | reference | ||
| ) |
Registers an equipment module with the TINE server engine (extended call)
The point of contract between the TINE server engine and server-specific code is the equpment module, which can be regarded as an interupt service routine. This extended call allows a reference to be passed, which in turn will be used in all associated dispatch routines.
| expName | is the exported device server name to be associated with this equipment module. If this is NULL, then it is assumed that an 'exports.csv' local database file exists, which contains the export name. Otherwise it will contain a system-wide unique name (e.g. "HERA-P-BPM") |
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| ndevices | is this number of devices managed via this equipment module. If this is 0, then it is assumed that an 'exports.csv' local database file exists, which contains the number of devices. |
| fcn | is a reference to the equipment module, which must have the prototype shown. Namely, it is an interrupt service routine which will receive the device name, device property, the output data set, the input data set, and the data access flags as parameters, as well as the original reference pointer. |
| ini | is a reference to an initialization routine which should be called prior to enabling the equipment module. When it is called, it passes the original reference pointer. |
| tsk | is a reference to a background task which will be called at regular intervals, and is frequently used for hardware IO, etc. When it is called, it passes the original reference pointer. Where multi-threaded servers are specified, or VxWorks tasks are available these tasks exists as separate threads, or tasks. In other cases, they are managed by the TINE server engine scheduler. |
| rate | is the rate in milliseconds used to schedule the background task supplied by the 'tsk' parameter. |
| exi | is a reference to an exit routine which should be called prior to shutting down the equipment module. When it is called, it passes the original reference pointer, and applies of course to graceful exits of the server. |
| reference | is a reference pointer which will be returned in all dispatch routines, and thus can be used as a means for de-referencing the equipment module container. |
Example:
| int RegisterFecInformation | ( | char * | name, |
| char * | sub, | ||
| char * | cntxt, | ||
| char * | dsc, | ||
| char * | loc, | ||
| char * | hdw, | ||
| char * | resp, | ||
| UINT16 | poff | ||
| ) |
Assigns a FEC Name and descriptive information to the server process.
Servers must be assigned to a Front End Computer (FEC), which for many operating systems corresponds to a process running on the computer rather than the computer itself (meaning there can in some cases be more than one servers with different 'FEC' names running on the same computer. There can be several device servers attached to the same FEC (i.e. sharing the same address space), so the FEC name is a distinct quantity from the device server name (see RegisterExport()), and this name must also be system-wide unique. The call RegisterFecInformation() supercedes RegisterFecNameEx() and RegisterFecName() and differs from them in that it accepts 'Context' and 'SubSystem' as parameters, both of which will be applied to all device servers attaching to the same FEC name.
The FEC name can also be (and frequently is) registered via the presence of an 'fecid.csv' startup database file.
| name | is the FEC name indentifying the Front End Computer and to which all registered equipment modules are bound. |
| sub | is the subsystem to which attached device servers belong. Note that the subsystem (unlike context) is itself not part of the name space, although the name space can be queried for device servers belonging to a subsystem. System. This information is now deduced automatically from the library build. |
| cntxt | is a 32-character string giving the context of all registered equipment modules. (earlier versions of TINE truncated at 16 characters). |
| dsc | is a 64-character desciption of the FECs server duties. A 'subsystem' can be associated with ALL equipment modules found on the FEC by prefixing the description with a subsystem tag of the form "[<tag>]". This information will be parsed by the Equipment name server and used for sub-system specific queries. For example, the associate the FEC "HEPHF" with the subsystem "RF", the description field might be "[RF]Hera Proton HF Control". |
| loc | is a 32-character string giving the phyical location of the FEC. |
| hwd | is a 32-character brief description of the IO hardware found on the FEC. |
| resp | is a 32-character string listing the developer(s) responsible for the FEC. Note: The Equipment Name Server will allow the removal of FECs and associated equipment modules to the user(s) specified here. |
| poff | is the 'Port Offset' to be applied to the FEC. This parameter plays an important role where more that one FEC is to run on a machine running an operating system using virtual memory. In such cases 'Front End Computer' is a misnomer, since "FEC" really refers to a process running on the computer to which one or more equipment modules are bound. For operating systems where all processes run in the same address space (such as VxWorks, Win16, NIOS) there is in fact only one such processes managing all requistered equipment modules. For systems using virtual memory (such as Linux, Solaris, HP-UX, Win32, etc.), you can have many such processes running independently of one another. Since each such process must listen on a unique set of server ports, you must see to it that all such FEC processes are registered with a unique 'Port Offset'. |
Example:
References argument_list_error.
Referenced by RegisterFecNameEx().
| int RegisterFecName | ( | char * | name, |
| char * | desc, | ||
| char * | os, | ||
| char * | loc, | ||
| char * | hdw, | ||
| char * | resp, | ||
| UINT16 | poff | ||
| ) |
Assigns a FEC Name to the server process.
Servers must be assigned to a Front End Computer (FEC), which for many operating systems corresponds to a process running on the computer rather than the computer itself (meaning there can in some cases be more than one servers with different 'FEC' names running on the same computer. There can be several device servers attached to the same FEC (i.e. sharing the same address space), so the FEC name is a distinct quantity from the device server name (see RegisterExport()), and this name must also be system-wide unique.
The FEC name can also be (and frequently is) registered via the presence of an 'fecid.csv' startup database file.
| name | is the FEC name indentifying the Front End Computer and to which all registered equipment modules are bound. |
| dsc | is a 64-character desciption of the FECs server duties. A 'subsystem' can be associated with ALL equipment modules found on the FEC by prefixing the description with a subsystem tag of the form "[<tag>]". This information will be parsed by the Equipment name server and used for sub-system specific queries. For example, the associate the FEC "HEPHF" with the subsystem "RF", the description field might be "[RF]Hera Proton HF Control". |
| os | is included for backward compatibility. Historicall it defined the FEC's Operating System. This information is now deduced automatically from the library build. |
| loc | is a 32-character string giving the phyical location of the FEC. |
| hwd | is a 32-character brief description of the IO hardware found on the FEC. |
| resp | is a 32-character string listing the developer(s) responsible for the FEC. Note: The Equipment Name Server will allow the removal of FECs and associated equipment modules to the user(s) specified here. |
| poff | is the 'Port Offset' to be applied to the FEC. This parameter plays an important role where more that one FEC is to run on a machine running an operating system using virtual memory. In such cases 'Front End Computer' is a misnomer, since "FEC" really refers to a process running on the computer to which one or more equipment modules are bound. For operating systems where all processes run in the same address space (such as VxWorks, Win16, NIOS) there is in fact only one such processes managing all requistered equipment modules. For systems using virtual memory (such as Linux, Solaris, HP-UX, Win32, etc.), you can have many such processes running independently of one another. Since each such process must listen on a unique set of server ports, you must see to it that all such FEC processes are registered with a unique 'Port Offset'. |
References RegisterFecNameEx().
| int RegisterFecNameEx | ( | char * | name, |
| char * | dsc, | ||
| char * | os, | ||
| char * | loc, | ||
| char * | hdw, | ||
| char * | resp, | ||
| UINT16 | poff, | ||
| char * | context | ||
| ) |
Assigns a FEC Name to the server process. Extended call.
Servers must be assigned to a Front End Computer (FEC), which for many operating systems corresponds to a process running on the computer rather than the computer itself (meaning there can in some cases be more than one servers with different 'FEC' names running on the same computer. There can be several device servers attached to the same FEC (i.e. sharing the same address space), so the FEC name is a distinct quantity from the device server name (see RegisterExport()), and this name must also be system-wide unique. The extended call RegisterFecNameEx() differs from RegisterFecName() in that it accepts the server 'Context' as an additional parameter. The context will be applied to all device servers attaching to the same FEC name.
The FEC name can also be (and frequently is) registered via the presence of an 'fecid.csv' startup database file.
| name | is the FEC name indentifying the Front End Computer and to which all registered equipment modules are bound. |
| dsc | is a 64-character desciption of the FECs server duties. A 'subsystem' can be associated with ALL equipment modules found on the FEC by prefixing the description with a subsystem tag of the form "[<tag>]". This information will be parsed by the Equipment name server and used for sub-system specific queries. For example, the associate the FEC "HEPHF" with the subsystem "RF", the description field might be "[RF]Hera Proton HF Control". |
| os | is included for backward compatibility. Historicall it defined the FEC's Operating System. This information is now deduced automatically from the library build. |
| loc | is a 32-character string giving the phyical location of the FEC. |
| hwd | is a 32-character brief description of the IO hardware found on the FEC. |
| resp | is a 32-character string listing the developer(s) responsible for the FEC. Note: The Equipment Name Server will allow the removal of FECs and associated equipment modules to the user(s) specified here. |
| poff | is the 'Port Offset' to be applied to the FEC. This parameter plays an important role where more that one FEC is to run on a machine running an operating system using virtual memory. In such cases 'Front End Computer' is a misnomer, since "FEC" really refers to a process running on the computer to which one or more equipment modules are bound. For operating systems where all processes run in the same address space (such as VxWorks, Win16, NIOS) there is in fact only one such processes managing all requistered equipment modules. For systems using virtual memory (such as Linux, Solaris, HP-UX, Win32, etc.), you can have many such processes running independently of one another. Since each such process must listen on a unique set of server ports, you must see to it that all such FEC processes are registered with a unique 'Port Offset'. |
| context | is a 32-character string giving the context of all registered equipment modules. (earlier versions of TINE truncated at 16 characters). |
References RegisterFecInformation().
Referenced by RegisterFecName().
| int RegisterMultiChannelGroupDevice | ( | char * | eqm, |
| char * | grpname, | ||
| char * | devname, | ||
| int | grpindex, | ||
| int | grpsize | ||
| ) |
Assigns a device name to the specified multi-channel group device.
In a device-oriented model, one can still make use of multi-channel array efficiency by registering a 'group' device which knows its device members and group size. Individual devices can then be designated as multi-channel array 'participants' such that any persistent client-side links to group members results in a delivery of the entire group to the client and an associated 'collapse' in the number of associated single-element contracts to a 'group' contract.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| grpname | is device group name |
| devname | is device name to be assigned to a group |
| grpindex | is the array index of the device member within the group |
| grpsize | is the array length of the group |
Example:
| int RegisterProperty | ( | char * | eqm, |
| char * | prop, | ||
| int | siz, | ||
| short | fmt, | ||
| short | acc, | ||
| char * | dsc | ||
| ) |
Assigns pertinent information for the specified property.
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prop | is property name in question (up to 64 characters). |
| siz | is expected data size (i.e. maximum allowed data size) for this property |
| fmt | is exected data format for this property |
| acc | is the data 'access' (CA_READ or CA_WRITE) accepted by the server. Note: Applying the CA_NETWORK flag to the access will enforce asynchronous NETWORK (i.g. multicast acquisition) by the client. |
| dsc | is the 64-character description of what the property reads or writes. returned in calls to GetPropertyId(). |
References RegisterPropertyEx().
| int RegisterPropertyAccessDeadband | ( | char * | eqm, |
| char * | property, | ||
| int | access, | ||
| int | deadbandInMilliSeconds | ||
| ) |
Assigns a minimum access deadband to the designated property.
By assigning a minimum access deadband to a property, a server can require that successive WRITE calls cannot be processed at a smaller time interval than the given deadband. Attempts to do so will receive an 'operation_busy' return code.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| property | is the property name in question (up to 64 characters). |
| access | is the data access for which the deadband is to be applied. (usually one of CA_READ, CA_WRITE, or CA_READ|CA_WRITE). |
| deadbandInMilliSeconds | is the desired deadband in milliseonds. A value of 0 (or less than 0) turns off the deadband checking. |
References GetPropertyListStruct().
| int RegisterPropertyAlias | ( | char * | eqm, |
| char * | property, | ||
| char * | alias | ||
| ) |
Assigns an alias to the specified property.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| property | is the property name in question (up to 64 characters). |
| alias | is an alias which maps to the property in question (up to 64 characters). |
References argument_list_error, GetPropertyListStruct(), and non_existent_property.
| int RegisterPropertyAndHandler | ( | char * | eqm, |
| EQMFCNP | hndlr, | ||
| char * | prp, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | acc, | ||
| short | atype, | ||
| UINT16 | rowlen, | ||
| char * | dsc, | ||
| PrpEgu * | egu, | ||
| PrpEgu * | xegu, | ||
| int | pid | ||
| ) |
Registers a device property and a property handler with the TINE server engine. If no equipment module name is given, an internal equipment module is provided by the TINE server engine, see API call RegisterServer. If not an internal equipment module but a specifically for this server created equipment module should be used, this can be indicated by the parameter eqmName, see below.
| eqm | defines the associated equipment module. If NULL then a TINE kernel internal equiment module is assumed, else it should be the registered 6-character local equipment module name (e.g. "BPMEQM") of the server to which the property belongs. |
| hndlr | is a reference to the property handler function, which must have the prototype |
int (*hndlr)(char *,char *,DTYPE *,DTYPE *,short)
Namely, it is an interrupt service routine which will receive the device name, device property, the output data set, the input data set, and the data access flags as parameters, as well as the original reference pointer.
the remaining parameters are exactly the same as in API call RegisterPropertyInformation
| prp | is property name in question (up to 64 characters). |
| dout | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the output data set to be returned by the server to the caller. |
| din | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the input data set to be supplied by the caller. |
| acc | is the data 'access' (e.g. CA_READ or CA_WRITE) accepted by the server. This parameter can be used to coerce client-side links into using preferred link attributes. For example, by applying the CA_NETWORK flag (CA_READ|CA_NETWORK) to the access, asynchronous NETWORK (i.g. multicast acquisition) will be enforced at the client side. Applying the CA_XREAD access flag will likewise allow exclusive READ access regarding the registered property (i.e. the same security rules applied to CA_WRITE will be in force for READ acquisitions, either permanently - no CA_READ flag, or temporarily in case of an applied access lock - if both CA_READ and CA_XREAD are applied). Applying the CA_SAVERESTORE flag will apply the internal save-and-restore logic to the registered property (restoring the last property settings upon server startup, and saving any changed property settings). |
| atype | is the data 'array type' (AT_SCALAR, AT_SINGLE, etc.) associated with the returned data. |
| rowlen | if > 0 gives the row length of the returned array data. This is most relevant for double arrays, where the number of rows is then given by the output data size divided by the row length. |
| dsc | is the 64-character description of what the property reads or writes. |
| egu | is a reference to a PrpEgu object containing the units and max and min settings for the nominal value of the property. |
| xegu | is a reference to a PrpEgu object containing the units and max and min settings for the x-axis value of the property in the event that the property returns a double array. |
| pid | is the property identifier to be associated with the property name returned in calls to GetPropertyId(). |
Example:
References RegisterPropertyAndHandlerEx().
| int RegisterPropertyAndHandlerEx | ( | char * | eqm, |
| XEQMFCNP | hndlr, | ||
| char * | prp, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | acc, | ||
| short | atype, | ||
| UINT16 | rowlen, | ||
| char * | dsc, | ||
| PrpEgu * | egu, | ||
| PrpEgu * | xegu, | ||
| int | pid, | ||
| void * | ref | ||
| ) |
Registers a device property and a property handler with the TINE server engine (extended call). If no equipment module name is given, an internal equipment module is provided by the TINE server engine, see API call RegisterServer. If not an internal equipment module but a specifically for this server created equipment module should be used, this can be indicated by the parameter eqmName, see below.
| eqm | defines the associated equipment module. If NULL then a TINE kernel internal equiment module is assumed, else it should be the registered 6-character local equipment module name (e.g. "BPMEQM") of the server to which the property belongs. |
| hndlr | is a reference to the property handler function, which must have the prototype |
int (*hndlr)(char *,char *,DTYPE *,DTYPE *,short,void *)
Namely, it is an interrupt service routine which will receive the device name, device property, the output data set, the input data set, and the data access flags as parameters, as well as the original reference pointer.
| prp | is property name in question (up to 64 characters). |
| dout | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the output data set to be returned by the server to the caller. |
| din | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the input data set to be supplied by the caller. |
| acc | is the data 'access' (e.g. CA_READ or CA_WRITE) accepted by the server. This parameter can be used to coerce client-side links into using preferred link attributes. For example, by applying the CA_NETWORK flag (CA_READ|CA_NETWORK) to the access, asynchronous NETWORK (i.g. multicast acquisition) will be enforced at the client side. Applying the CA_XREAD access flag will likewise allow exclusive READ access regarding the registered property (i.e. the same security rules applied to CA_WRITE will be in force for READ acquisitions, either permanently - no CA_READ flag, or temporarily in case of an applied access lock - if both CA_READ and CA_XREAD are applied). Applying the CA_SAVERESTORE flag will apply the internal save-and-restore logic to the registered property (restoring the last property settings upon server startup, and saving any changed property settings). |
| atype | is the data 'array type' (AT_SCALAR, AT_SINGLE, etc.) associated with the returned data. |
| rowlen | if > 0 gives the row length of the returned array data. This is most relevant for double arrays, where the number of rows is then given by the output data size divided by the row length. |
| dsc | is the 64-character description of what the property reads or writes. |
| egu | is a reference to a PrpEgu object containing the units and max and min settings for the nominal value of the property. |
| xegu | is a reference to a PrpEgu object containing the units and max and min settings for the x-axis value of the property in the event that the property returns a double array. |
| pid | is the property identifier to be associated with the property name returned in calls to GetPropertyId(). |
| ref | is a reference pointer which will be returned in the given property handler dispatch routines, and thus can be used as a means for de-referencing the container. |
Example:
Referenced by RegisterPropertyAndHandler().
| int RegisterPropertyEx | ( | char * | eqm, |
| char * | prop, | ||
| int | siz, | ||
| short | fmt, | ||
| short | acc, | ||
| char * | dsc, | ||
| int | prpId | ||
| ) |
Assigns pertinent information for the specified property.
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prop | is property name in question (up to 64 characters). |
| siz | is expected data size (i.e. maximum allowed data size) for this property |
| fmt | is exected data format for this property |
| acc | is the data 'access' (CA_READ or CA_WRITE) accepted by the server. Note: Applying the CA_NETWORK flag to the access will enforce asynchronous NETWORK (i.g. multicast acquisition) by the client. |
| dsc | is the 64-character description of what the property reads or writes. |
| propId | is the property identifier to be associated with the property name returned in calls to GetPropertyId(). |
Example:
References DTYPE::dArrayLength, DTYPE::dFormat, DTYPE::dTag, and RegisterPropertyInformation().
Referenced by RegisterProperty().
| int RegisterPropertyInformation | ( | char * | eqm, |
| char * | prop, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | acc, | ||
| short | atype, | ||
| UINT16 | rowlength, | ||
| char * | dsc, | ||
| int | propId, | ||
| char * | rdr | ||
| ) |
Assigns pertinent information for the specified property.
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prop | is property name in question (up to 64 characters). |
| dout | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the output data set to be returned by the server to the caller. |
| din | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the input data set to be supplied by the caller. |
| acc | is the data 'access' (e.g. CA_READ or CA_WRITE) accepted by the server. This parameter can be used to coerce client-side links into using preferred link attributes. For example, by applying the CA_NETWORK flag (CA_READ|CA_NETWORK) to the access, asynchronous NETWORK (i.g. multicast acquisition) will be enforced at the client side. Applying the CA_XREAD access flag will likewise allow exclusive READ access regarding the registered property (i.e. the same security rules applied to CA_WRITE will be in force for READ acquisitions, either permanently - no CA_READ flag, or temporarily in case of an applied access lock - if both CA_READ and CA_XREAD are applied). Applying the CA_SAVERESTORE flag will apply the internal save-and-restore logic to the registered property (restoring the last property settings upon server startup, and saving any changed property settings). Applying the CA_INDEPENDENT flag will signal that any WRITE calls to this property should not block equipment module access to other properties (if the property is to be called in its own thread). |
| atype | is the data 'array type' (AT_SCALAR, AT_SINGLE, etc.) associated with the returned data. |
| rowlength | if > 0 gives the row length of the returned array data. This is most relevant for double arrays, where the number of rows is then given by the output data size divided by the row length. |
| dsc | is the 64-character description of what the property reads or writes. |
| propId | is the property identifier to be associated with the property name returned in calls to GetPropertyId(). |
| rdr | is a redirection string, if the property is to be redirected to another server. Most properties are not redirected, and this parameter is usually NULL. If used, if will be parsed according to /<device context>/<device server>/<device name>[device property], where the 'device name' and 'device property' are optional. If 'device context' is not present, the same context will be assumed as the currently registered context. If 'device name' is not present, all devices will be redirected to the specified device server. If 'device property' is not present then the identical property name as registered will be redirected to the device server specified. If on the other hand, the device property is present in the string to be parsed, then the property registered will be redirected to the device server specified as well as to the device property specified. |
Example:
References RegisterPropertyInformationEx().
Referenced by RegisterPropertyEx().
| int RegisterPropertyInformationEx | ( | char * | eqm, |
| char * | prp, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | acc, | ||
| short | atype, | ||
| UINT16 | rowlen, | ||
| char * | dsc, | ||
| PrpEgu * | egu, | ||
| PrpEgu * | xegu, | ||
| int | pid, | ||
| char * | rdr | ||
| ) |
Assigns pertinent information for the specified property (extended version).
Servers export their behavior through Properties, which can be thought of as 'properties' in the Object Oriented sense with Get and Set methods. That is, any read or write access for a given property will call into the associated equipment module and be handled there. The general behavior of the property (including descriptions) can be specified with this call. Properties can also be (and frequently are) registered via the presence of an 'exports.csv' startup database file.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is property name in question (up to 64 characters). |
| dout | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the output data set to be returned by the server to the caller. |
| din | is a template data object (minus a data pointer) giving the default format size, and structure tag (if any) of the input data set to be supplied by the caller. |
| acc | is the data 'access' (e.g. CA_READ or CA_WRITE) accepted by the server. This parameter can be used to coerce client-side links into using preferred link attributes. For example, by applying the CA_NETWORK flag (CA_READ|CA_NETWORK) to the access, asynchronous NETWORK (i.g. multicast acquisition) will be enforced at the client side. Applying the CA_XREAD access flag will likewise allow exclusive READ access regarding the registered property (i.e. the same security rules applied to CA_WRITE will be in force for READ acquisitions, either permanently - no CA_READ flag, or temporarily in case of an applied access lock - if both CA_READ and CA_XREAD are applied). Applying the CA_SAVERESTORE flag will apply the internal save-and-restore logic to the registered property (restoring the last property settings upon server startup, and saving any changed property settings). Applying the CA_INDEPENDENT flag will signal that any WRITE calls to this property should not block equipment module access to other properties (if the property is to be called in its own thread). |
| atype | is the data 'array type' (AT_SCALAR, AT_SINGLE, etc.) associated with the returned data. |
| rowlen | if > 0 gives the row length of the returned array data. This is most relevant for double arrays, where the number of rows is then given by the output data size divided by the row length. |
| dsc | is the 64-character description of what the property reads or writes. |
| egu | is a reference to a PrpEgu object containing the units and max and min settings for the nominal value of the property. |
| xegu | is a reference to a PrpEgu object containing the units and max and min settings for the x-axis value of the property in the event that the property returns a double array. |
| pid | is the property identifier to be associated with the property name returned in calls to GetPropertyId(). |
| rdr | is a redirection string, if the property is to be redirected to another server. Most properties are not redirected, and this parameter is usually NULL. If used, if will be parsed according to /<device context>/<device server>/<device name>[device property], where the 'device name' and 'device property' are optional. If 'device context' is not present, the same context will be assumed as the currently registered context. If 'device name' is not present, all devices will be redirected to the specified device server. If 'device property' is not present then the identical property name as registered will be redirected to the device server specified. If on the other hand, the device property is present in the string to be parsed, then the property registered will be redirected to the device server specified as well as to the device property specified. |
Example:
Referenced by RegisterPropertyInformation().
| short RegisterPropertyQueryFunction | ( | char * | eqm, |
| int(*)(char *devName, PrpQueryStruct **prpqs) | fcn, | ||
| int | numprops | ||
| ) |
Registers a property query function.
If a server's properties are all registered via a call to RegisterPropertyInformation(), RegisterPropertyInformationEx(), RegisterProperty(), etc., then there is no need to deal with property query functions. Some servers may wish to have a different property list for any given device, in which case a one-time query of the list of properties will not apply in general. The suggested procedure is to register all properties that a device server might have to handle and then assign the relevant 'lists' of properties to those devices which require a subset (e.g. AssignDeviceListToProperty()). In this manner, the TINE kernel can maintain all known properties in a registry. Where this is impractical, a server can also register its own property query structure, which is required to field all property queries explicitly. The query function must have the propotype shown in the parameter 'fcn'. That is, it should be a routine which accepts a device name as a parameter, and returns via a second paramter a reference to a list of extended property query structures (PrpQueryStruct).
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| fcn | is the property query function which will handle property information queries |
| numprops | is the number of properties which are registered. |
Example:
| int RegisterPropertySignalFunction | ( | const char * | eqm, |
| const char * | prp, | ||
| PRPSIG | fcn, | ||
| int | mask, | ||
| void * | ref | ||
| ) |
Registers a property signal function.
If a property is accessed by remote callers, it will be represented within a server's contract list. The appropriate equipment module will be called, which is the extent of the transaction in most cases. The server can also optionally receive signals during the course of the transaction by attaching a signal function to the property in question. Signals will include
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prp | is the registered property for the signal function is to be applied. |
| fcn | is the property signal function of prototype: void sigfcn(int signal,int contractId,int propertyId,int currentStatus,void *reference); |
| mask | is a signal mask indicating which signals are of interest (use PS_ALL to receive all signals). |
| ref | is a caller supplied reference which will be returned when the signal function. As this is a void pointer, it can refer to any structure or function the caller wants to have returned when the signal function is called. |
example:
| int RegisterServer | ( | char * | expName, |
| int | numdevices, | ||
| char * | deviceNameList[] | ||
| ) |
Registers an internal equipment module with the TINE server engine An internal equipment module is provided by the TINE server engine. So for creating a TINE server it is sufficient to register properties and respective property handlers, see also API call RegisterPropertyAndHandler.
| expName | is the exported device server name to be associated with this equipment module. |
| ndevices | is this number of devices managed via this equipment module. |
| deviceNameList | can be an string array of the length of ndevices, containing device names. If NULL then a list of ndevices generic device names (00000000, 00000001, 00000002 ...) is generated. |
Example:
References argument_list_error, and RegisterEquipmentModule().
| 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:
| short RegisterXPropertyQueryFunction | ( | char * | eqm, |
| int(*)(char *devName, XPropertyQueryStruct **xpqs) | fcn, | ||
| int | numprops | ||
| ) |
Registers an extended property query function.
If a server's properties are all registered via a call to RegisterPropertyInformation(), RegisterPropertyEx(), or RegisterProperty(), then there is no need to deal with property query functions. Some servers may wish to have a different property list for any given device, in which case a one-time query of the list of properties will not apply in general. This is infrequently the case, but when it arises, a server will need to field all property queries explicitly by registering its own property query structure. The query function must have the propotype shown in the parameter 'fcn'. That is, it should be a routine which accepts a device name as a parameter, and returns via a second paramter a reference to a list of extended property query structures (PropertyQueryStructEx).
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| fcn | is the extended property query function which will handle property information queries |
| numprops | is the number of properties which are registered. |
| int RemoveDevice | ( | char * | eqm, |
| char * | devname | ||
| ) |
Removes a device name from an equipment module's device list.
This call will remove a previously assigned device from the current device list. That is, it will remove any allocated memory specific to the removed device. It does not remove the device slot and the device list capacity is unaltered by this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be removed |
| int RemoveEquipmentModule | ( | const char * | eqm | ) |
Unregisters an equipment module with the TINE server engine and frees all associated memory.
The point of contract between the TINE server engine and server-specific code is the equpment module, which can be regarded as an interupt service routine. This extended call allows a reference to be passed, which in turn will be used in all associated dispatch routines. Under (rare) circumstances it may be desired to unregister an equipment module. This routine can be used to accomplish that task.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
Example:
| int RemoveProperty | ( | char * | eqm, |
| char * | property | ||
| ) |
Removes a property name from an equipment module's property list.
This call will remove a previously assigned property from the current property list. The call does not free memory associated with the property or any of its overloads. This memory will only be freed if the equipment module itself is removed. Thus, calling RegisterPropertyInformation with the same property name following a a call to RemoveProperty will find and reuse the previously allocated memory.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| property | is property name to be removed |
| int RemoveRegisteredBCastNetsList | ( | NAME64 * | iplist, |
| int | listsize | ||
| ) |
removes those networks in the name list given from the current broadcast list.
The network broadcast list assigned to FEC is often read in via configuration file (see ipbcast.csv or fec.xml). However networks can also be removed via this API call. Items in the list given will be removed from the existing list of broadcasted network addresses.
| iplist | is a list of network addresses to be removed from the current broadcast list. If a network address in the input is not in the current access list, nothing happens. |
| listsize | is the size of the input list. |
| int RemoveRegisteredNetsList | ( | const char * | eqm, |
| NAME64 * | iplist, | ||
| int | listsize | ||
| ) |
removes those networks in the name list given from the current network address access list.
The network access list assigned to FEC is often read in via configuration file (see ipnets.csv or fec.xml). However networks can also be removed via this API call. Items in the list given will be removed from the existing list of allowed network addresses.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| iplist | is a list of network addresses to be removed from the current network access list. If a network address in the input is not in the current access list, nothing happens. |
| listsize | is the size of the input list. |
| int RemoveRegisteredUser | ( | char * | eqm, |
| NAME16 * | userlist, | ||
| int | listsize | ||
| ) |
removes those users in the name list given from the current users access list.
The users access list assigned to an equipment module is often read in via configuration file (see users.csv or fec.xml). However users can also be removed via this API call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| userlist | is a list of users to be removed from the current users access list. If a user in the input is not in the current access list, nothing happens. |
| listsize | is the size of the input list. |
| int ResetServerBaseline | ( | const char * | eqm | ) |
Resets a server baseline timestamp to the current time.
A client can monitor the stock property "SRVBASELINE" and react to jumps in the readback value. Normally this value will not change over the course of the server process's life cycle. The value will naturally change when a server is restarted. However the server process can call this routine when for instance the startup conditions change dynamically (e.g. a device was added or removed on-the-fly). A running client which monitors the SRVBASELINE will then have a chance to re-acquire startup information 'on-the-fly' as well.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| char * ResolveSystemAlias | ( | char * | alias | ) |
Gets the registered property or registered device name for the given alias.
A client can make use of an alias in place of either a registered device name or a registered property name in any call. The alias name will be replaced by its target within the contract tables. Property aliases are also returned in queries to obtain the registered property list.
| alias | is the alias target for which the real registered name is desired (either a registered device or a registered property). |
| int SealTaggedStruct | ( | char * | tag, |
| int | size, | ||
| int | number | ||
| ) |
Seals a tagged structure (registration finished!).
Call this routine to signal the structure registry that there are no more fields to be added to the tagged structure.
| tag | structure tag name |
| size | total size of the structure in bytes |
| number | number of elements of this structure to allocate |
References invalid_structure_tag, out_of_local_memory, and un_allocated.
| int sendNetGlobal | ( | char * | keyword, |
| DTYPE * | din, | ||
| void(*)(int, int) | callback, | ||
| int | minPeriod, | ||
| int | maxPeriod, | ||
| double | tolerance | ||
| ) |
registers and sends the accompanying keyword and data as a network global.
The keyword supplied is appended to the globals table if not already registered and sent immediately as a netork global per multicast if multicasting is enabled and/or per broadcast if a broadcast nets table has been registered (via the inclusion of a ipbcast.csv or ipxbcast.csv file in the startup database set). Multicasts/Broadcasts will then be scheduled according the the minPeriod, maxPeriod, and tolerance specified, in which case the din data object should contain a reference to a data object which will be regularly updated by the server code. Alternatively, the call can specify '0' (or a negative number) as minPeriod and maxPeriod, in which case the network global will only be sent upon a call to sendNetGlobal(). If a callback function is supplied, is it called following the successful transmission of the network global.
| keyword | is the globals KEYWORD which identifies the data set being sent. |
| din | is a pointer to the input data set, that is, the data set to be sent from the server If din is a NULL pointer or contains a NULL data set, sendNetGlobal() returns an error. |
| callback | is the address of the user-supplied callback routine to be called when data are sent from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| minPeriod | is the minimum period in milliseconds between scheduled multi/broadcasts |
| maxPeriod | is the maximum period in milliseconds between scheduled multi/broadcasts. If the data are still within tolerance at the end of this period, the data set will nonetheless be sent as a network global. |
| tolerance | is the allowed range between the current and previous data sets. If exceeded, the current data set is then sent as a network global. |
References MakeDataTimeStamp().
| int sendNetGlobalEx | ( | char * | context, |
| char * | keyword, | ||
| DTYPE * | din, | ||
| void(*)(int, int) | callback, | ||
| int | minPeriod, | ||
| int | maxPeriod, | ||
| double | tolerance | ||
| ) |
registers and sends the accompanying keyword and data as a network global for the specific context given.
The keyword supplied is appended to the globals table if not already registered and sent immediately as a netork global per multicast if multicasting is enabled and/or per broadcast if a broadcast nets table has been registered (via the inclusion of a ipbcast.csv or ipxbcast.csv file in the startup database set). Multicasts/Broadcasts will then be scheduled according the the minPeriod, maxPeriod, and tolerance specified, in which case the din data object should contain a reference to a data object which will be regularly updated by the server code. Alternatively, the call can specify '0' (or a negative number) as minPeriod and maxPeriod, in which case the network global will only be sent upon a call to sendNetGlobalEx(). If a callback function is supplied, is it called following the successful transmission of the network global.
| context | is the globals keyword context to which the globals keyword belongs. Usually the keyword context is identified by the server's host IP address and does not need to be explicitly send with the globals variable. However for circumstances where the same host is sending multiple globals under different contexts but with the same globals keyword then this additional parameter is needed. |
| keyword | is the globals KEYWORD which identifies the data set being sent. |
| din | is a pointer to the input data set, that is, the data set to be sent from the server If din is a NULL pointer or contains a NULL data set, sendNetGlobal() returns an error. |
| callback | is the address of the user-supplied callback routine to be called when data are sent from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| minPeriod | is the minimum period in milliseconds between scheduled multi/broadcasts |
| maxPeriod | is the maximum period in milliseconds between scheduled multi/broadcasts. If the data are still within tolerance at the end of this period, the data set will nonetheless be sent as a network global. |
| tolerance | is the allowed range between the current and previous data sets. If exceeded, the current data set is then sent as a network global. |
| 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. |
| void SetAllowNetworkAddressResolution | ( | int | value | ) |
Determines whether NETWORK address resolution is allowed.
In an ENS-less (minimal) infrastructure, an initializing client can attempt to find server addresses by sending a NETWORK (multicast) probe to ascertain a server's address. In lieu of an ENS configuration, this requires a running server (configured to respond to NETWORK requests). Otherwise the servers address cannot be resolved.
| value | is the desired setting (default = FALSE) |
References feclog().
| void SetAllowRemoteManagement | ( | int | value | ) |
Determines whether remote management via stock properties is possible.
The stock properties "SRVEXIT", "SRVINIT", "SRVRESET" will return 'not_allowed' unless remote managment is turned on (default OFF)
| value | is the desired setting |
| void SetAppDate | ( | time_t | appdate | ) |
Sets the compilation date of the current running server process.
The server's application creation date is queriable from a TINE server. However this information needs to be passed to the server engine at initialization time via this call.
| appdate | is the creation time as a UNIX time variable. |
| void SetAppVersion | ( | int | major, |
| int | minor, | ||
| int | revision | ||
| ) |
Sets the application version of the current running server process.
The server's application version number is queriable from a TINE server. However this information needs to be passed to the server engine at initialization time via this call.
| major | is the major version number of the application |
| minor | is the minor version number of the application |
| revision | is the revision version number of the application |
| void SetAutoAdjustWorkAreaSize | ( | int | value | ) |
Sets 'auto-adjust work area size' (based on number of registered properties)
| value | is the desired setting (default = TRUE). |
| int SetCallPropertyInSeparateThread | ( | char * | eqm, |
| char * | property, | ||
| int | value | ||
| ) |
Determines whether the specified property is called in a separate handler thread or not.
Some equipment module properties might take a non-negligible time to complete. In general the equipment module should try to minimize the time spent in the dispatch handler (i.e. simply copying results into the request buffer), but this is often not possible if long calculations need to be performed or hardware access is required, etc. If it is known before hand that this is the case it is advisable to specify that the property in question is called on a special dispatch handler thread (avialable only in the multi-threaded library build). Other properties to the equipment modules will not be called while such a call is underway, as it can not be known before hand if the equiment module is thread safe. However the caller will receive an 'operation busy' notification rather than a 'time out' if the callers timeout limit was exceeded.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| property | is the property which is to be called on a separate dispatch handler thread. |
| value | determines whether the property is called in a separate thread (TRUE) or not (FALSE). If specifically CA_WRITE|CA_INDEPENDENT (0x8002) is passed, then the property will also be flagged so as to not block other concurrent equipment module calls. |
References GetPropertyListStruct(), and illegal_property.
| void SetClientListCapacity | ( | int | value | ) |
Sets the maximum number of clients a server will service.
A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number clients, then this value should be set accordingly at initialization time.
| value | is the requested client table size |
Default: 100 (Or #define CLIENTLIST_CAPACITY in project.def)
References feclog(), and MaxNumClients.
| void SetConfigurationCoded | ( | int | value | ) |
Determines whether TINE configuration files will be scanned or not.
By default the TINE kernel will look for configuration files covering all ranges of server initialization as well as client initialization (such as the cshost.csv file giving a list of configured Equipment Name Servers). Some server builds might make use entirely and intentionally of API calls to establish all free configuration parameters. And in such cases it is possibly not desireable to even scan for the existence of such files (e.g. VxWorks CPUs which want to avoid querying the host parent's file system). By passing a value of TRUE this default scanning will be turned off.
| value | is the desired setting (default: FALSE); |
| void SetContractListCapacity | ( | int | value | ) |
Sets the maximum number of contracts a server will service.
A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number contracts, then this value should be set accordingly at initialization time.
| value | is the requested contract table size |
Default: 1000 (Or #define CONTRACTLIST_CAPACITY in project.def)
References feclog(), and MaxNumContracts.
| void SetContractSignalFunction | ( | CONSIG | fcn, |
| int | mask, | ||
| void * | ref | ||
| ) |
Registers a contract signal function.
If a property is accessed by remote callers, it will be represented within a server's contract list. The appropriate equipment module will be called, which is the extent of the transaction in most cases. The server can also optionally receive signals during the course of the transaction by attaching a signal function to the property in question (see RegisterPropertySignalFunction()), or by setting up a general contract signal function. A contract signal function will be called on behalf of any registered property from any registered equipment module. Signals will include
| fcn | is the contract signal function of prototype: void sigfcn(const char *eqm,const char *dev,const char *prp,int currentStatus,int signal,void *reference); |
| mask | is a signal mask indicating which signals are of interest (use PS_ALL to receive all signals). |
| ref | is a caller supplied reference which will be returned when the signal function. As this is a void pointer, it can refer to any structure or function the caller wants to have returned when the signal function is called. |
| void SetDefaultDeviceRegion | ( | char * | eqmName, |
| char * | region | ||
| ) |
Sets the default device region to the value specified.
This region code will be used in cases where it has not been overridden by a specific device.
| eqmName | is the equipment function name (local name) for which the exported subsystem is desired. |
| region | is the desired default device region tag |
| int SetDeviceDescription | ( | char * | eqm, |
| char * | devname, | ||
| char * | description | ||
| ) |
Assigns a device description to the specified device.
Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is occasionally useful to assign individual description texts pro device (e.g. a hardware address) An alternative is to provide a startup database file 'devices.csv' containing device descriptions.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| description | is the device description to be associated with the device specified. |
| int SetDeviceLocation | ( | char * | eqm, |
| char * | devname, | ||
| char * | location | ||
| ) |
Assigns a device location text to the specified device.
Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is occasionally useful to assign individual physical location information pro device, for instance when a device is an 'ethernet' device and the specific bldg, room, rack, etc. for the device needs to be made available. An alternative is to provide a startup database file 'devices.csv' containing device locations.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| location | is the device location to be associated with the device specified. |
| int SetDeviceMask | ( | char * | eqm, |
| char * | devname, | ||
| int | mask | ||
| ) |
Assigns a device mask to the specified device.
Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is occasionally useful to assign a type 'mask' to a device. Wild card calls with an input mask or meta-property calls with '.DEVMASK.' will then return only lists of devices with the corresponding mask bits set.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| mask | is the device mask to be associated with the device specified. |
| int SetDeviceOfflineStatus | ( | char * | eqm, |
| char * | devname, | ||
| int | offline | ||
| ) |
Assigns an offline status to the specified device.
This purely software flag can be used to steer the returned device list in wildcard or certain kinds of multichannel array calls.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| offline | is the offline status to be associated with the device specified. (non-zero => off-line). |
| int SetDeviceRegion | ( | char * | eqm, |
| char * | devname, | ||
| char * | region | ||
| ) |
Assigns a region code to the device in question.
Region codes can help determine the location of a device with a machine. This code is applied to the alarm message whenever a specific devices sets an alarm.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| region | is the alarm region tag to apply to the device |
| int SetDeviceZPosition | ( | char * | eqm, |
| char * | devname, | ||
| float | zpos | ||
| ) |
Assigns a Z (logitudinal) direction to the specified device.
Many servers handle instances of a given device type, such as a set of vacuum pumps, beam position monitors, magnet power supply controllers, etc. It is occasionally useful to assign a Z or longitudinal position to a device when the relative location along the direction of the beam is pertinent for the registered device.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| devname | is device name to be assigned |
| zpos | is the Z position to be associated with the device specified. |
| void SetEnforceMcaAcquisition | ( | int | value | ) |
Forces multi-channel array handshaking if set to TRUE.
A server can absolutely enforce multi-channel array handshaking independent of the release level of the client. This has relevance as to whether persistent single-element links are allowed or not. If allowed then a 'modern' client might be able to latch on to a pre-existing single-element link established by an older client.
| value | TRUE or FALSE |
| void SetEqmCompletion | ( | char * | eqmName, |
| char * | errStr | ||
| ) |
Sets the error string to accompany the current server call.
For user-defined errors codes (equal to or above 512) the accompanying error string should be defined by calling this routine prior to returning from the equipment module call. When system error codes such as 'illegal_format' are used, a call to SetEqmCompletion() is not necessary.
| eqmName | the local equipment module name whose completion code is to be set |
| errStr | is the 96-character string which is to accompany the outgoing error code. |
Example:
| void SetExportedContext | ( | char * | eqmName, |
| char * | context | ||
| ) |
Assigns the exported context associated with the equipment function name given.
Calling this function after the equipment module is registered will have no effect. Any argument list error will be logged but otherwise will have no effect.
| eqmName | is the equipment function name (local name) for which the exported context should be set. \context is the desired context |
Example:
| void SetExportedSubSystem | ( | char * | eqmName, |
| char * | subsystem | ||
| ) |
Assigns the exported subsystem associated with the equipment function name given.
Calling this function after the equipment module is registered will have no effect. Any argument list error will be logged but otherwise will have no effect.
| eqmName | is the equipment function name (local name) for which the exported subsystem should be set. \subsystem is the desired sub system |
| int SetFailoverMaster | ( | char * | eqm, |
| char * | masterName | ||
| ) |
Sets the designated server as a failover master.
A server can declared itself as a failover master, which will register a 'master' server name as an additional alias for the equipment module specified. A server master will always overwrite any prior entries for the master name within the ENS database.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| masterName | is the desired name of the server master. Ideally this is a distinct name different from the offically registered export name. A failover slave will use this same master name. |
| void SetFailoverPollingInterval | ( | int | pollingInterval | ) |
Sets the server failover interval to the value given.
If a server has declared itself as a failover slave then it monitors a designated master at the failover polling interval. The value of the polling interval can be set via this routine.
| pollingInterval | is the interval in milliseconds to check for connectivity with the targeted master (default: 1000 msec). |
| int SetFailoverSlave | ( | char * | eqm, |
| char * | masterName, | ||
| char * | slaveMaster | ||
| ) |
Declares the server a failover slave and targets the designated server.
A server can declared itself as a failover slave, which will monitor the designated 'master' and only assume the role master if the monitored server no longer responds.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| masterName | is the desired name of the server master. |
| slaveMaster | is the targeted name of the slave monitor. This will be the officially registered name of the server designated as the master (hopefully distinct from the 'master' name). |
| void SetFailoverThreshold | ( | int | timeoutCounts | ) |
Sets the server failover threshold to the value given.
If a server has declared itself as a failover slave then it monitors a designated master at the failover polling interval. If consecutive errors acrue such that the failover threshold is exceeded, then a failover slave will assume the roll of master.
| errorCounts | is the number of consecutive errors which triggers a role reversal of slave to master (default: 5). |
| void SetGCastTableCapacity | ( | int | value | ) |
sets the globals multicast table capacity
This establishes the maximum size of the (server-side) globals table which is to send network globals via multicast. (Default : 50).
| value | is the desired table size. |
| void SetIgnoreCommonFiles | ( | int | value | ) |
turns searching for common database files in the FEC_HOME directory on or off
When set to TRUE, attempts to read an exports.csv or related equipment module files which directly reside in the FEC_HOME directory (or working directory, if not set) are blocked. Any related files within the equipment module 'local name' sub-directory will still be scanned and read.
| value | is the desired setting. (default = FALSE). |
| void SetInitializeIdle | ( | int | value | ) |
When set to TRUE, all equipment modules are initialized in an 'idle' state.
If a Server is in an idle state no background activity occurs and the server's equipment function is temporarily disabled. Calls to the equipment function will receive the status code 'server_idle' if this is the case. This is sometime useful during initialization, so that no activity (from for example the local history subsystem) can occur. If this flag is set to TRUE, then all equipment modules must be activated following the initialization procedure by calling SetServerIdleState(FALSE);
| value | is the value of the default idle state. Any non-zero sets the default idle state to TRUE. A zero value sets the default idle state to FALSE. |
| void SetLogFileAllowScan | ( | int | value | ) |
Sets the allowed range of log file retrieval from a FEC process (via stock property SRVLOGFILE).
Gets the allowed range of log file retrieval from a FEC process (via stock property SRVLOGFILE).
A running FEC process will attempt to read and return the contents of the file name input to stock property SRVLOGFILE. The FEC process must have read permission in order to succeed. The setting of the LogFileAllowScan will further restrict the allowed directories from which files may be read. LogFileAllowScan = LOG_SCAN_FEC will only return the contents of files within the FEC_HOME or FEC_LOG directories and their subdirectories. LogFileAllowScan = LOG_SCAN_FULL will itself allow the entire file system. LogFileAllowScan = LOG_SCAN_NONE will not allow any files to be retrieved other than fec.log.
| value | is the desired scan range, one of: LOG_SCAN_NONE, LOG_SCAN_FEC, LOG_SCAN_FULL (default = LOG_SCAN_FEC). |
A running FEC process will attempt to read and return the contents of the file name input to stock property SRVLOGFILE. The FEC process must have read permission in order to succeed. The setting of the LogFileAllowScan will further restrict the allowed directories from which files may be read. LogFileAllowScan = LOG_SCAN_FEC will only return the contents of files within the FEC_HOME or FEC_LOG directories and their subdirectories. LogFileAllowScan = LOG_SCAN_FULL will itself allow the entire file system. LogFileAllowScan = LOG_SCAN_NONE will not allow any files to be retrieved other than fec.log.
| void SetlookupRedirectionNameStub | ( | int(*)(char *eqm, char *prpName, char *devName) | fcn | ) |
Sets a stub to an existing lookupRedirectionNameStub function for cases where a Property Query Function is in force and the server needs to redirect calls.
A lookupRedirectionNameStub function should return server_redirection if the property and device combination is to be redirected. It should also call the SetRPCRedirection() routine to establish the redirection string.
| fcn | is the address of the lookupRedirectionNameStub function. |
| void SetMinimumAllowedPollingInterval | ( | int | value | ) |
Sets the minimum polling interval in milliseconds a server will allow.
A server will not honor polling rates smaller than this value. An attempt to poll a property a 1 msec for instance will be serviced at the MinPollingRate instead. If it is known that the server should support very fast polling rates, then this value should be set accordingly at initialization time.
| value | is the desired minimum polling interval (Default: 20 ) |
| int SetNameServerAddress | ( | char * | ens | ) |
Sets the address of the Equipment Name Server via API call.
In lieu of accessing the file 'cshosts.csv' (whose location is determined by the environment variable TINE_HOME) a server can make this call to establish the address(es) of the Equipment Name Server (ENS). This is convenient for platforms which do not have a hard disk.
| ens | a string containing a list of the IP addresses of the ENSes to be used, separated by commas (','), and optionally providing a port offset (separated by a colon ':'). |
Example (sets two ENS addresses, the second with port offset = 2):
SetNameServerAddress("131.169.120.141,131.169.120.146:2");
References argument_list_error.
| int SetPropertyBuffer | ( | char * | eqmName, |
| char * | prpName, | ||
| BYTE * | buffer | ||
| ) |
Assigns a fixed buffer to handle output data for the given property.
Generally an equipment module's dispatch handler is called with a reference to an allocated buffer into which the property's output is written. In some circumstances (e.g. large video frames) it is prudent to instruct the dispatch handler to make use of a pre-assigned buffer area (which is likely already filled with data) and to forgo any double buffering and memory copying that might otherwise occur. This is accomplished with this call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | is the registered property for the buffer is to be assigned. |
| buffer | is the address of the buffer to assign to the property. |
| int SetPropertySubscriptionRenewalLength | ( | char * | eqm, |
| char * | prpName, | ||
| int | value | ||
| ) |
Sets the current subscription renewal length for the property specified.
Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant.
| eqm | (input) is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| prpName | is the registered property for the buffer is to be assigned. |
| value | is the desired setting |
References argument_list_error, feclog(), GetPropertyListStruct(), invalid_property, and out_of_range.
| void SetRedirectionParameters | ( | char * | eqmName, |
| char * | rdrCnt, | ||
| char * | rdrSrv, | ||
| char * | rdrDev, | ||
| char * | rdrPrp | ||
| ) |
Sets the redirection string to accompany the current server call.
This routine can be used when Property Query Functions are in play. In such cases the equipment module is responsible for deciding if a call should be redirected to another server or not. If so, the server can call this routine to set the redirection information.
| eqmName | the local equipment module name whose redirection parameters should be set |
| rdrCon | is the device context to which the call should be redirected |
| rdrSrv | is the device server to which the call should be redirected |
| rdrPrp | is the device property to which the call should be redirected. (Note that property length is restricted to 32 characters for redirected calls). |
| rdrDev | is the device name to which the call should be redirected (Note that device length is restricted to 32 characters for redirected calls). |
| void SetRejectOverloadedMetaProperties | ( | int | value | ) |
Enables/Disables overloaded meta properties.
Meta-properties such as .HIST or .NAM can be 'overloaded' by registering the appropriately named property. This will prevent the systematically available meta-property from being called. This is by default the case (if a property ABC.HIST is itself registered it will be called instead of the TINE local history). Explicitly calling SetRejectOverloadedMetaProperties(TRUE) will disable this feature.
| value | if non-zero will reject any meta-property overloads. (default: FALSE) |
| void SetRetardSingleContractRemoval | ( | int | value | ) |
sets the retard contract removal state
When all clients disappear from a contract the contract is then scheduled for removal at the server. This can either happen 'immediately' or be 'retarded' for a duration of 1 second. Typically a synchronous READ or WRITE command establishes a transient contract which if allowed to persist for this extra second can handle 'RETRY' requests by returning the results of the contract. However this strategy also occupies a slot in the servers contract table until the contract is officially removed, when can effectively lock up the contract table if a large number of synchronous requests are issued (clients will receive a 'resources_exhausted' return code in such cases. If a server can tolerate idempotent requests (the same request twice, so to speak) then it might be advisable to turn this feature off.
| value | is the desired setting. (default = TRUE). |
| int SetScanForNetsFiles | ( | const char * | eqm | ) |
Instructs the initialization process to look for device and property specific 'ipnets' files.
Normally this routine is not necessary. However for some systems such as VxWorks, where directory scanning only works in conjunction with NFS mounts it is then useful to explicitly intruct the initialization process to look for device and property specific ACL files (such as 'device1-ipnets.csv', etc.).
| int SetScanForUsersFiles | ( | const char * | eqm | ) |
Instructs the initialization process to look for device and property specific 'users' files.
Normally this routine is not necessary. However for some systems such as VxWorks, where directory scanning only works in conjunction with NFS mounts it is then useful to explicitly intruct the initialization process to look for device and property specific ACL files (such as 'device1-users.csv', etc.).
| void SetSchedulerInterval | ( | int | value | ) |
Sets the system scheduler interval.
The TINE kernel will call the scheduler regularly in order to service the current contract list. Under some circumstances it may be wished to control this interval. For instance, if it is known a priori that a server will need to respond to heavy synchronous polling while at the same time maintaining a lengthy contract list, it is desireable to limit the number of passes through the scheduler per second (as this will traverse the contract list with each pass). Thus setting the scheduler interval to some reasonable number (e.g. 50 or 100 milliseconds) might significantly reduce the CPU load on the server. Note however, that this will impose a latency on all synchronous requests! If the value for the schedular interval is set to 0 (the default value) or less, then the scheduler will be called at often as necessary, usually at the system polling interval (as determined by the most eager contract) and/or following a client request.
| value | is the desired scheduler interval in milliseconds. (default = 0). |
| int SetSizeDeviceCapacity | ( | char * | eqm, |
| int | size | ||
| ) |
Sets (increases) the maximum size of the device table and associated tables.
Servers spcecify the maximum device capacity with the equipment module registration, either through exports.csv, fec.xml or a call to RegisterEquipmentModule(). In some dynamic situations, a server might note the available capacity is too small and can augment it via this API call.
| eqm | is the local equipment module name (maximum 6 characters in length) For example: "BPMEQM". |
| size | is the maximum number (capacity) of allowed devices. If the 'size' passed is smaller than the current device list capacity, nothing happens, and the call returns 'already_assigned'. If the call is made before the initial capacity has been determined (through equipment module registration), the call returnes 'not_initialized'. |
| int SetStandAlone | ( | int | value | ) |
Sets stand-alone mode.
In lieu of setting the environment variable TINE_STANDALONE to TRUE prior starting a server process, this API call can set stand-alone mode if used prior to SystemInit(). If TRUE, no attempt is made to contact the TINE equipment name server. Instead the local address CACHE is consulted. A server updates its own entry by supplying the registered port offset and the loopback address.
Default: FALSE.
| int 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). |
| int SetSystemAttribute | ( | char * | attribute, |
| void * | value, | ||
| int | format | ||
| ) |
References invalid_name, and invalid_parameter.
| void SetSystemCycleDeadband | ( | int | value | ) |
Sets the system cycle deadband.
A TINE client or server requires a 'cycler' to run either on separate thread (see SystemStartCycleTimer() where available) or as part of a user defined engine (running SystemCycle() in an infinite loop). The cycler will block on incoming network traffic for a duration up to the given system cycle deadband (typically 10 msec). Either a network request wakes the cycler up or the deadband timeout expires. Following this other background activity will take place (such as processing contracts, checking local histories, and alarms, etc.). The system cycle deadband can be 'pinned' with this API call.
| value | is the desired system cycle deadband (default: OS dependent, typically 10 msec) |
References feclog().
| void SetSystemSubscriptionRenewalLength | ( | int | value | ) |
Sets the contract subscription renewal length.
Persistent contracts established by a client calling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The default value for subscription renewals can be adjusted with this call.
| value | is the desired contract renewal length. (mininum = default = 60; maximum = 32767) |
| void SetSystemSynchronizeContracts | ( | int | value | ) |
Establishes the setting for general contract synchronization at the server.
A server will try to schedule contracts at the regular intervals necessary to satisfy its clients' needs. If 'contract synchronization' is in effect, the server will attempt to call the relevant equipment module dispatch routines in a tight loop in order to collect and disperse information in the smallest number of data transfers (contract packing). You can control this behavior with this API call.
| value | is the desired setting for contract synchronization (default = TRUE); |
| UINT32 SystemGetProcessId | ( | void | ) |
Returns the process id of the running application if available.
| char* SystemGetStartupCommand | ( | void | ) |
Returns the command line used to start this process.
If available the command line used to start the process is returned including all command line argurments.
References feclogEx().
| char* SystemGetStartupDirectory | ( | void | ) |
Returns the working directory in use when this process started.
| int MaxNumClients = CLIENTLIST_CAPACITY |
Determines the maximum number of clients a server will service.
A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number clients, then this value should be set accordingly at initialization time.
Default: 50 (Or #define CLIENTLIST_CAPACITY in project.def)
Referenced by SetClientListCapacity().
| int MaxNumContracts = CONTRACTLIST_CAPACITY |
Determines the maximum number of contracts a server will service.
A server manages both a contract table and a client table, which are independent of one another except that when there is at least on contract there must be at least one client. The size of this table is pre-allocated at initialization time. If it is known that the server will have to support a large number contracts, then this value should be set accordingly at initialization time.
Default: 1000 (Or #define CONTRACTLIST_CAPACITY in project.def)
Referenced by SetContractListCapacity().
1.5.8