Stock Properties

All TINE servers support a standard set of "Stock" properties, giving general information about the running server. These stock properties can either be 'FEC-specific' (i.e. pertaining to the Front End Controller process itself) or 'Device Server-specific' (i.e. pertaining to the device server). In either case, stock propererties are called on behalf of an equipment module (the dispatch handler for a registered device server). FEC-specific stock properties differ from server-specific properties in that they apply equally to any equipment modules associated with the FEC and can be accessed prior to initialization (or registration) of an equipment module.

A list of FEC specific stock properties and a brief description follows below.

• "APPDATE" returns the application compile time as a string (string data type such as CF_NAME32 or CF_TEXT) or as a UTC integer (CF_INT32). Note: this stock property depends on the FEC calling SetAppDate()!
• "APPVERSION" returns the application version as a string (use a string data type such as CF_NAME32 or CF_TEXT) in the form "major.minor.revision". Note: this stock property depends on the FEC calling SetAppVersion().
• "CONNECTIONS" returns a list of the current active links the server has (as a client) to other servers. For most server this will be a null list, but many and especially middle layer server will themselves be clients to other servers. This client-side connection table can be obtained with this call asking for a tagged structure of type "CONTBLr4", a ConTblInfo structure type (shown below).

  typedef struct
  {              
    char expName[EXPORT_NAME_SIZE];  /* eqm function name */
    char prpName[PROPERTY_NAME_SIZE];/* eqm property */
    char devName[DEVICE_NAME_SIZE];  /* eqm device name */
    char context[CONTEXT_NAME_SIZE]; /* eqm context */
    char eqm[EQM_NAME_SIZE];         /* the eqm name */
    UINT16 mode;                     /* used by subscriptions */
    short access;                    /* data access */
    short formatIn;                  /* eqp data format down */
    short formatOut;                 /* eqp data format up */
    UINT32 sizeIn;                   /* data array size down */
    UINT32 sizeOut;                  /* data array size up */
    char strTagIn[TAG_NAME_SIZE];    /* eqm structure tag down */
    char strTagOut[TAG_NAME_SIZE];   /* eqm structure tag up */
    UINT32 pollRate;                 /* polling rate for connectioned clients */
    UINT32 heartbeat;                /* used by subscriptions */
    UINT32 starttime;                /* entry into table (used by subscriptions) */
    UINT32 dtimestamp;               /* arriving TINE timestamp */
    int dtimestampMSEC;              /* arriving TINE timestamp (msec fraction) */
    int  counter;                    /* current subscription counter */
    short linkStatus;                /* current link status */
    short reserved;
  } ConTblInfo;
  

• "MESSAGE" is a WRITE-only property which accepts a message and displays it at the console and writes an entry in the log file. This property is typically accessed by the Equipment Name Server (ENS) to inform a booting server if its name is already in use by another server.
• "STRUCTFORMAT" returns the tagged structure information for the given input tagged structure. This should be obtained by asking for an array of data type CF_NAME64DBLDBL, where an entry consists of the triplet "field-format-size". The input data is of a simple string type and should specify the tagged structure tag. The last entry will contain the format CF_NULL as the data type, the structure tag as the field name, and the raw size in bytes of the structure as the size. This stock property can be used to 'discover' the contents of a user-defined tagged structure. If a field itself is a tagged structure, the field format will be CF_STRUCT and the field will contain the the embedded structure tag as well as the field name in the form "\<tag\>.field". Generic applications such as the instant client make use of this stock property in order to discover (and register) the necessary tagged structure and be able to display it.
• "BITFIELDFORMAT" returns the bitfield information for the given input bitfield. This is in analogy with tagged structures except that here the returned data consists of an array of data type CF_NAME16I, i.e. a doublet of the form "field-mask". A bitfield already has a known data size in bytes, so important is only the data bask to apply in order to obtain the bits relevant to the field. Generic applications such as the instant client make use of this stock property in order to discover (and register) the necessary bitfield and be able to display it.
• "NSTOCKPROPS" returns the number of stock properties available (type CF_INT16 or CF_INT32).
• "STOCKPROPS" returns the available stock properties of a server. A simple list can be obtained by asking for a string format type such as CF_NAME32. A more in-depth list (property query structure) or targetted query (input the requested property as a string format type) can be obtained by asking for a tagged structure of type "PRPQSr4". In general, most TINE browsing utilities make use of this stock property in this manner. Calls such as GetSystemPropertyInformation() (in C) or TQuery.getPropertyInformation() (in Java) utilize this stock property are are the preferred way to obtain property information, as is GetSystemProperties() (in C) or TQuery.getDeviceProperties() (Java) to obtain a property list.
• "NIPNETS" returns the number of IP Nets with Write Access to the FEC (type CF_INT16 or CF_INT32).
• "IPNETS" returns a list of IP Nets with write Access to the FEC, obtained by asking for a string type (such as CF_NAME16). See 'ipnets.csv' in the configuration section.
• "ADDIPNET" is a WRITE-only property which appends the input IP address to the network specific access list. Note that the caller must have WRITE access in order to successfully use this stock property.
• "DELIPNET" is a WRITE-only property which deletes the input IP address from the network specific access list. Note that the caller must have WRITE access in order to successfully use this stock property.
• "NIPXNETS" returns the number of IPX Nets with write Access (if IPX is used as an internet transport protocol).
• "IPXNETS" returns a list of IPX Nets with Access List (if IPX is used as an internet transport protocol). Note: IPX is essentially a 'deprecated' protocol and is unlikely to be in use.
• "DEBUGLEVEL" can be used to get or set the FEC's debug level (type CF_INT16 or CF_INT32). This will enable (or disable) console output at the FEC which can be useful for debugging purposes. If a console is not visible (because the server is running in the background or as a GUI) then the 'attachfec' utility can be used to obtain a 'pipe' into the server and thereby observe the debugging output.
• "LOGCOMMANDS" can be used to get or set the command logging flag (type CF_INT16 or CF_INT32). If TRUE, this flag will enable the automatic logging of all WRITE access commands with are processed by the FEC (prior to calling the server's dispatch routine). This is TRUE by default, but in some cases (Servers which systematically expect many WRITE commands) might be turned off via code (see putCommandsInFeclog), or via this using this stock property.
• "LOGDEPTH" can be used to get or set the log file depth in lines (type CF_INT16 or CF_INT32). (See also fecLogFileDepth).
• "LOGFILE" returns the FEC's log file (type CF_TEXT). The amount of text returned is governed by the requested output size (in characters). The most recent text is always returned.
• "SRVVERSION" returns the TINE Server Version Number obtained by asking for a string format type (such as CF_NAME16).
• "SRVOS" returns the (general) FEC operating system obtained by asking for a string format type (such as CF_NAME16).
• "SRVLOCATION" returns the physical location of the FEC obtained by asking for a string format type (such as CF_NAME16). Note: This merely reflects the information registered at startup. There is otherwise no guarantee that this information is either complete or accurate.
• "SRVSTATS" returns a (structured) array of up to 16 integers (type CF_INT32) giving the current statistics counters maintained by the FEC kernel. At the time of this writing, there are currently 11 counters available, namely
  • AveBusyTime gives the estimated (by the TINE kernel) load within the dispatch routines in percent.
  • CycleCounts gives the current number of TINE kernel cycles per second.
  • MaxCycleCounts gives the maximum achieved number of TINE kernel cycles per second.
  • SingleLinkCount gives the accumulated number of single transactions (excluding persistent contracts)
  • ClientMisses gives the accumulated number of late deliveries from server to client (indicating a busy server).
  • ClientReconnects gives the accumulated number of unexpected client re-connections, indicating that a client is experiencing link timeouts.
  • ClientRetries gives the accumulated number of client retry attempts (either transactions or persistent links).
  • ContractMisses gives the accumulated number of times a contract was late in calling the equipment module dispatch routine (indicating a busy server). This counter is sometimes approximately in parallel with ClientMisses.
  • ContractDelays gives the accumulated number of times a contract dispatch routine was bypassed due to prior delivery being still underway.
  • BurstLimitReachedCount gives the accumulated number of times the registered 'burst limit' was exceeded. This would indicate a contract sending a very large amount of data, required a large number of individual packets. The default burst limit is 1000 packets (the default MTU being 1472 bytes).
  • DataTimeStampOffset gives the current data timestamp offset (if a TINE time server is in play) in milliseconds. Generic applications such as the FEC Remote Panel and the FEC statistics server and viewer make use of this stock property.
• "SRVALIASLIST" gives a simple list of name/alias pairs according to the registered alias list. This is best obtained by using a string data type such as NAME32. The returned data will be an even number of names in a name-alias pair sequence.
• "ADDALIAS" is a WRITE-only stock property which appends the input alias pair to the registered alias list. As input, an array of NAME64 entries of length 2 is expected. The first element is the name (either property or device) which is to receive an alias and the second element is the assigned alias.
• "SRVSTARTTIME" returns the server startup time as a string (string data type such as CF_NAME32 or CF_TEXT) or as a UTC integer (CF_INT32).
• "SRVCMDLINE" returns the command line used to start the server process. (string data type CF_TEXT of up to 132 characters.)
• "SRVCWD" returns the working directory in force when the server process started. (string data type CF_TEXT of up to 132 characters.)
• "SRVPID" returns the process id in force when the server process started. (integer data type CF_INT32).
• "SRVLOGFILES" returns a list of available (text based) log files found on the server's log file repository (the location specified by either FEC_LOG or FEC_HOME). The list is best obtained by using a string type data type (CF_NAME32 or CF_NAME64).
• "SRVLOGFILE" is analogous to "LOGFILE" in that it returns the logfile specified (type CF_TEXT). If no log file is specified, it returns the FEC's log file (fec.log). Otherwise it will try to locate the file specified with the device name parameter (in this case the 'device' name is a 'file' name). If the device name does not specify a path, the path specified by FEC_LOG or FEC_HOME is assumed. This stock property also allows one to WRITE a text log file by passing the file contents as text based (type CF_TEXT) input.
• "SRVBINFILE" is analogous to "SRVLOGFILE" except that it obtains the specified file as a binary file (use data format type CF_BYTE). The file specified is simply opened in binary mode and returned. Note: in this case, if the contents need to be trunctated (because the caller did not specify a large enough buffer size) the file is truncated at the end. In the case of log (i.e. text based) files, the file truncation takes place at the beginning of the file.
• "SRVGLOBALS" returns a list of TINE network globals that this FEC is sending. This is delivered via the data type CF_NAME64DBLDBL, i.e. a triplet of values giving a triplet of "keyword-format-size". Note: typically only the TINE globals server will deliver non-null results when this stock property is called.
• "SRVEXIT" is a WRITE only stock property which causes the server to exit. Note: a server must allow this property to be accessed (e.g. SetAllowRemoteManagement(TRUE)). If no input is given, the server will exit with error code '0', otherwise the property may be called with an integer value input (CF_INT16 or CF_INT32) in order to supply a desired error code. Scope: All device server attached to the FEC.
• "SRVRESET" is a WRITE only stock property which causes the server FEC process to de-register all equipment modules by first calling their associated exit routines. All associated memory is returned to the heap (the caller is responsible for freeing any device-server allocated memory in the exit routin). The server FEC process is then re-initialized by calling the registered PostSystemInit routine (see SetPostSystemInitFunction()). Scope: All device server attached to the FEC. Note: a server must allow this property to be accessed (e.g. SetAllowRemoteManagement(TRUE)).

A given device server, after it has been initialized will also have a list of stock properties which pertain to it specifically (at least in part). These include the following

• "ACCESSLOCK" is both a READ and WRITE stock property which governs the behavior of an access lock on the device server addressed. As a READ property, "ACCESSLOCK" will return up to 3 string values (e.g. type CF_NAME32) containing
  • the user name of the current owner of the access lock (if locked)
  • the address of the current owner of the access lock
  • the time remaining on the access lock As a WRITE property, 2 integer values are accepted (type CF_INT32 or CF_INT16) giving the requested lock type and the duration. Access locks are best dealt with via the Access Lock API. See SetAccessLock(), FreeAccessLock(), GetAccessLockStatus(), GetAccessLockInformation().
• "ACTIVITY" gives the current FEC/server activity as a structure (CF_STRUCT) with tag "AQS". This is the primary activity displayed in the FEC Remote Control Panel. The Activity Query Structure is shown below.

  typedef struct
  {
    char FecName[FEC_NAME_SIZE]; /* FEC name */
    char reserved[4];
    UINT32 localtime;            /* server's clock in UTC */
    UINT32 starttime;            /* startup time in UTC */
    UINT32 systemPollingRate;    /* cycle rate in msec */
    short  numBkgTsks;           /* number registered background tasks */
    short  numTotalContracts;    /* total contracts all equipment modules */
    short  numTotalClients;      /* total clients all equipment modules */
    short  numTargetContracts;   /* total contracts this equipment module */
    short  numTargetClients;     /* total clients this equipment module */
    short  numConnections;       /* number connections (as client) */ 
    UINT32 numConnectionTimeouts;/* number connection timeouts (as client) */
    UINT32 numConnectionArrivals;/* number contract requests */
    UINT32 numUDPpkts;           /* total number UDP packets */
    UINT32 numTCPpkts;           /* total number TCP packets */
    UINT32 numIPXpkts;           /* total number IPX packets */
    UINT32 numSPXpkts;           /* total number SPX packets */
  } ActivityQueryStruct;
  

• "CONTRACTS" gives the current contract table for the device server addressed as a structure (CF_STRUCT) with tag "CTQSr4". The Contract query structure is shown below.

  typedef struct             
  {
    char   EqmProperty[PROPERTY_NAME_SIZE];
    char   EqmDeviceName[DEVICE_NAME_SIZE];
    char   EqmName[EQM_NAME_SIZE];
    UINT32 EqmSizeIn;
    UINT32 EqmSizeOut;
    BYTE   hEqmName;
    BYTE   EqmAccess;
    BYTE   EqmFormatIn;
    BYTE   EqmFormatOut;
    char   strTagIn[TAG_NAME_SIZE];
    char   strTagOut[TAG_NAME_SIZE];
    SINT32 pollrate;
    SINT32 nclients;
  } CONTRACT;
  

• "CLIENTS" gives the current client table for the device server addressed as a structure (CF_STRUCT) with tag "CLNQS". The client query structure is shown below.

  typedef struct
  {
    char userName[USERNAME_SIZE];
    IPXAddress IPXaddress;       /* if 0 then IPX is used */
    BYTE node[6];                /* IPX routing node (Immediate Address) */
    struct sockaddr_in IPaddress;/* IP address */
    short ncontracts;            /* number of registrations */
    short tineProtocol;          /* target client protocol level */
  } CLNQS;
  

• "NPROPERTIES" (synonym for "NPROPS") gives the number of registered properties for the device server addressed (type CF_INT16 or CF_INT32).
• "PROPERTIES" (synonym for "PROPS") gives a list of registered properties for the device server addressed. This can be a simple list when a simple string data type such as CF_NAME64 or CF_NAME32 is used or a list containing property information when a structure data type (CF_STRUCT) with tag "PRPQSr4" is used. If input is specified, then only the property information pertaining to the input is returned. That is the input can specify wildcard characters (e.g. "ABC*" delivers all properties beginning with "ABC") or a targetted property, in which case only the registered overloaded property information for the targetted property is returned (in most cases a single entry). Calls such as GetSystemPropertyInformation() (in C) or TQuery.getPropertyInformation() (in Java) utilize this stock property are are the preferred way to obtain property information, as is GetSystemProperties() (in C) or TQuery.getDeviceProperties() (Java) to obtain a property list.
• "NDEVICES" gives the number of registered devices for the device server addressed (type CF_INT16 or CF_INT32).
• "DEVICES" gives a list of registered properties for the device server addressed. This is a simple list of a string data type (such as CF_NAME64). In general one should make use of calls such as GetSystemDevices() to obtain this information rather than directly addressing the stock properties.
• "DEVDESCRIPTION" gives a description for the registered device (if a description has been registered seperately). This should be obtained with a string based data type (CF_NAME64, etc.).
• "NALARMS" provides the current alarm information maintained by the local alarm server for the device server addressed. If obtained as a single integer (CF_INT16 or CF_INT32) this is simply the total number of alarms for the device name specified. If a single wildcard '*' is used as the device name, then this number is the total number of alarms for all devices. This stock property is actually a structured array of 6 counters, which is in fact what the Central Alarm Server (CAS) uses to monitor the alarms on a particular server. These 6 integer counters are given by:
  • total number of alarms
  • time stamp (UTC) of the most recent alarm
  • highest severity of the alarms in the local alarm table
  • number of alarms at the most recent timestmp
  • number of alarms with the highest severity
  • number of registered alarm definitions
• "ALARMS" (synonym "ALARMSEXT") gives a list of alarms in the local alarm table as a structure (CF_STRUCT) with tag "AMSr4". The alarm list will refer to the device name specified or return all alarms if a single wildcard '*' is used as the device name. Input data can contain 3 long values (type CF_INT32) specifying a time range (stop time as UTC, start time as UTC) and a minimum severity of interest. If no input is given, the the default time range covers the entire UTC epoch and the minimum severity of interest is 0. The Alarm Message structure is shown below.

  typedef struct AlarmMsgStruct
  {
    char server[EXPORT_NAME_SIZE];
    char device[DEVICE_NAME_SIZE];
    char alarmTag[ALARM_TAG_SIZE];
    UINT32 alarmCode;
    UINT32 timestamp;
    UINT32 timestampUSec;
    UINT32 starttime;
    UINT32 starttimeUSec;
    UINT32 alarmMask;
    BYTE alarmData[ALARM_DATA_SIZE];
    BYTE alarmDataFormat;
    BYTE alarmDataArraySize;
    BYTE severity;
    BYTE descriptor;
    UINT16 alarmSystem;
    BYTE reserved[2];
  } AMS;
  

• "NALMDEFS" gives the number of registered alarm definitions for the device server addressed (type CF_INT16 or CF_INT32).
• "ALMDEFS" gives the registered alarm definition table for the device server addressed as a structure (CF_STRUCT) with tag "ADSr4". The Alarm definition structure is shown below.

  typedef struct ADStag    
  {
     char alarmTag[ALARM_TAG_SIZE];
     UINT32 alarmCode;  
     UINT32 alarmMask;  
     UINT16 alarmSystem;
     short  alarmSeverity;
     BYTE alarmDataFormat;
     BYTE alarmDataArraySize;
     BYTE reserved[2];
     char alarmText[ALARM_TEXT_SIZE];
     char deviceText[ALARM_TEXT_SIZE];
     char dataText[ALARM_TEXT_SIZE];
     char url[ALARM_TEXT_LONGSIZE];
  } ADS;
  

• "NALMWATCH" gives the size of the registered alarm watch table for the device server addressed (type CF_INT16 or CF_INT32).
• "ALMWATCHTBL" gives the registered alarm watch table for the device server addressed as a structure (CF_STRUCT) with tag "AWSr4". This stock property also accepts a new entry to the table as input (also CF_STRUCT, tag = "AWSr4"). The alarm watch table structure is shown below.

  typedef struct AlarmWatchStruct
  {
    char eqm[EQM_NAME_SIZE];
    char dev[DEVICE_NAME_SIZE];
    char prp[PROPERTY_NAME_SIZE];
    int  siz;               /* data array size */
    int  fmt;               /* data type */
    int  atyp;              /* array type */
    int  asys;              /* alarm system id */
    int  sev;               /* general highest severity */
    int  hisev;             /* high severity */
    int  hiwarnsev;         /* high warning severity */
    int  losev;             /* low severity */
    int  lowarnsev;         /* low warning severity */
    int  chkNormal;         /* != 0 => check vs normal; FALSE = check threshold */
    UINT32 mask;            /* if fmt is an integer type */
    UINT32 normal;          /* normal non-alarm state value (after mask) */ 
    int  cnt;               /* counter */
    int  cntThreshold;      /* set alarm when counter > threshold */
    float hi;               /* high threshold */
    float lo;               /* low threshold */
    float hiwarn;           /* high warn threshold */
    float lowarn;           /* low warn threshold */
  } AWS;
  

• "NUSERS" gives the number of users with WRITE access for the device server addressed (type CF_INT16 or CF_INT32).
• "USERS" gives a simple list of users with WRITE access for the device server addressed as an array of string types (e.g CF_NAME16). If the list is empty, then all users have WRITE access.
• "ADDUSER" is a WRITE-only stock property which appends the input user (or users) to the allowed users list. Note: the caller must himself have WRITE access, and as an added precaution, the current users list must NOT be empty. As input, a string type is expected (e.g. CF_TEXT, CF_NAME16, etc.) If CF_TEXT is used as input, then no more than a single user may be appended at a time. An array type such as CF_NAME16 or CF_STRING will allow a list of users to be granted WRITE access with a single call.
• "DELUSER" is a WRITE only stock property which serves as the counterpart to "ADDUSER". Use this stock property to remove a user (or users) from the list of users with WRITE access.
• "NHISTORIES" gives the size of the local history table for the device server addressed (type CF_INT16 or CF_INT32).
• "HISTORIES" gives the local history table for the device server addresses as a simple list of property names (string data type CF_NAME64, etc.). The property query for the properties returned in this list will give the full local history information.
• "ADDHISTORY" is a WRITE only stock property that will append the input data to the current local history table if the entry is new, or edit the local history table to reflect the updated history parameters otherwise. The input data must be a structure type (CF_STRUCT) with tag "HQS". The History record Structure is shown below.

  typedef struct
  {
    char property[PROPERTY_NAME_SIZE]; /* property name of the record */
    char device[DEVICE_NAME_SIZE]; /* device name of the record */
    int  datasiz;               /* call size of the record */
    int  datafmt;          /* calling format of the record */
    int  pollingRate;              /* polling rate in msec */
    int  archiveRate;              /* archive rate in msec */
    int  depthShort;             /* for short term storage */
    int  depthLong;               /* for long term storage */
    int  heartbeat;            /* archive heartbeat in sec */
    float pTolerance;                 /* percent tolerance */
    float aTolerance;                /* absolute tolerance */
  } HRS; 
  

• "SRVADDR" returns server address parameters as a structured list of strings (use a string data type, e.g. CF_NAME16 or CF_NAME32, etc.). The contents are
  • port offset
  • fec name
  • context name
  • equipment module name
  • device server name
  • sub system
• "SRVDESC" returns the registered server description as text (type CF_TEXT or CF_NAME64).
• "SRVSUBSYSTEM" returns the registered server subsystem as text (type CF_TEXT or CF_NAME16).
• "SRVINIT" is a WRITE only stock property which causes the server to reinitialize the device server addressed. Note: a server must allow this property to be accessed (e.g. SetAllowRemoteManagement(TRUE)).
• "SRVIDLE" is a stock property which can allow the server to enter an 'idle' state, where no activity on any registered background funtions, local history or local alarm subsystems, and other dispatch routines associated with the equipment module are permitted. Attempts to address the equipment module will receive the link status 'server_idle'. The property accepts integer input (CF_INT16 or CF_INT32) to set the idle state (FALSE = not idle, TRUE = idle). The current idle state can be read out at any time.
• "SRVLASTACCESS" returns the most recent WRITE access (command) information as a array of text strings (type CF_NAME16 or CF_NAME32). This will include:
  • the user name who issued the last command
  • the address which issued the last command
  • the last command property
  • the last command device
  • the time of the last command
• "SRVCOMMANDS" returns up to the last 100 WRITE access commands as a array of WriteAccessQuery structures (type CF_STRUCT with tag "WRACCTBL") containing essentially the same informaton as a call to "SRVLASTACCESS". A WriteAccessQuery structure is given below:

  typedef struct
  {
    char user[USERNAME_SIZE];
    char addr[ADDR_SIZE];
    char prp[PROPERTY_NAME_SIZE];
    char dev[DEVICE_NAME_SIZE];
    double timestamp;
  } WriteAccessQuery;