Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

The Tsentry library is composed of a set of classes to facilitate the creation and usage of real-time processes on the Windows NT/2000/XP platform.  While the list of included classes is extensive and in some cases very specialized, several interfaces have been written for use in a general Tsentry system:

  • tpriProc – Interface for a generic Tsentry process, including process initialization, periodic timers, priority selection, etc.

  • tpriGsm – Support for creating, mapping, interfacing, and destroying global shared memory segments.

  • tpriGsmDDCom  –  Support for a data dictionary for externally referencing global shared memory by variable string name, as well as allowing for prescribed initial, minimum, and maximum values, formatting string, description, etc.

  • tpriLogMsg – Support for multiple queues into which any process can drop text messages for later processing or asynchronous display.

  • tpriTimer – Support for setting and testing timers.

  • tpriAppThread – Support for creating, managing, and destroying application threads.

  • tpriIniFile – Support for ini file read and write access.

tpriProc – TSENTRY Process class

 Overview

The Tsentry process class encapsulates the functionality required of a generic Tsentry process.

 Class Interface

The following public member functions are provided as part of the tpriProc class:

static int Create(int create = 0);

Attach the current process to a tpriProc class object.

static int Destroy();

Detach the current process from its tpriProc class object.
static int PrIni(int argc, char **argv);

Initialize the current process based on the command line and the default parameters read from the initialization file.
static int PrWait();

  • Sleep until any of the following events occur:

  1. The next timer interval has expired.

  2. An Activate for this process is requested.

  3. A Resume for this process occurs.

static int Activate(char *appName);

Request the process manager to activate the specified process. 

static int Resume(char *appName = NULL);

tatic int Resume(int startOrder);

static int Resume(HANDLE hResume);

Wake the specified process if it is currently sleeping.

 

static int Suspend(char *appName);

static int Suspend(int startOrder);

Suspend a process so that it does not awake from the next call to PrWait().

 

static int Deactivate(char *appName = NULL);

Request that the process manager to deactivate the specified process.

 

int countRunningProcs();

Return the number of currently running processes.

 

static HANDLE openResumeHandle(char *appName);

Open a handle to allow for fast resumes of another process.

 

static int closeResumeHandle(HANDLE hResume);

Close a resume handled opened with openResumeHandle(..).

 

static int getAppName(char *pBuf, unsigned int szBuf);

Export the application name of the current process to the supplied buffer.

 

static int getAppName(char *pBuf, unsigned int szBuf, int startOrder);

Export the application name of the current process to the supplied buffer.

 

static int getBinName(char *pBuf, unsigned int szBuf,char *appName = NULL);

Export the binary file name of the specified process to the supplied buffer.

 

static float getIntervalPct(char *appName = NULL);

Return the current value of the percent interval utilized for the specified process.

 

static float getIntervalPctMax(char *appName = NULL);

Return the current value of the maximum percent interval utilized for the specified process.

 

static int getDbgLevel(char *appName = NULL);

Return the debug level for the specified process.

 

static int setDbgLevel(char *appName, int dbglvl);

Set the debug level for the specified process.

 

static tpriProcGroup getProcGroup(char *appName = NULL);

Return the process group identifier for the specified process.

 

static DWORD getPid (char *appName = NULL);

Return the process ID for the specified process.

 

static int getRestart(char *appName = NULL);

Return the auto-restart flag for the specified process.

 

static int setRestart(char *appName, int restart);

Set the auto-restart flag for the specified process.

 

static long getRepRate(char *appName = NULL);

Return the periodic repetition rate for the specified process (ms).

 

static int getRunMode(char *appName = NULL);

Return the run mode (Win32, RTSS) for the specified process.

 

static tpriProcState getState(char *appName = NULL);

Return the current state for the specified process.

 

static inline tpriProcState getMgrState();

Return the current state of the process manager.

 

static int getStartOrder(char *appName = NULL);

Return the start order for the specified process.

 

static __int64 getStateTime64(char *appName = NULL);

Return the amount of time the specified process has been in its current state (100 ns increments).

 

static long getStateTime(char *appName = NULL);

Return the amount of time the specified process has been in its current state (1 second increments).

 

static const char *getStateDesc(tpriProcState state);

Return a description of the specified state.

 

static const char *getStateDesc(char *appName = NULL);

Return a description of the current state for the specified process.

 

static int exportProdef(prodef *pprodef, char *appName = NULL);

static int exportProdef(prodef *pprodef, int startOrder);

Export a copy of the entire process definition of the specified process.

 

static inline void setState(tpriProcState newState);

Set the state for the current process.

 

static void setDispStatus(const char *fmt, ...);

Set the display status string for the current process.

 

static int getDispStatus(char *pBuf, unsigned int szBuf, char *appName = NULL);

Export the current display status for the specified process.

 

static int clearErrorState(char *appName = NULL);

Clear the error state associated with the specified process.

 

static time_t time(time_t *timer);

Return the current time (seconds since 1/1/1970 12:00 am UTC).

 

static struct tm *lcltime(struct tm *ltm);

Return the current local time.

 

static void ftime(struct _timeb *timeptr);

Return the current time (seconds and milliseconds since 1/1/1970 12:00 am UTC).

 

static inline void setWDog(int wd);

Set the watchdog flag associated with the current process.

tpriGsm – Global shared memory (GSM) class

 Overview

The tpriGsm class facilitates the mapping and access of shared memory segments within a Tsentry process.  For the most part, this class need not be directly used, as the data dictionary provides higher-level functions to automate the use of all global memory segments; however for specific applications, more specialized functionality may be required and thus a direct interface to the tpriGsm class is provided.

 Class Interface

The following public member functions are provided as part of the tpriGsm class:

tpriGsm(char *gsmName, int gsmSize = 0);

Create and/or map a shared memory segment with the given name and size.

 

tpriGsm(char *gsmName, void *pVaddr, int gsmSize);

Wrap a tpriGsm object around an existing memory segment.

 

~tpriGsm();

Destroy a tpriGsm object.

 

void *getVaddr(int offset = 0);

Return the virtual address of the shared memory segment at the given byte offset.

 

int getStatus();

Return the current status of the shared memory segment.

 

int getLastError();

Return the most recent error associated with the shared memory segment.

 

char *getName();

Return the name of the shared memory segment.

 

void mapGsm(char *gsmName, int gsmSize);

Map the shared memory segment into the current process under the specified name.

 

int clearGsm();

Zero the entire shared memory segment.

 

int saveGsm(char *fileName);

Write a binary copy of the shared memory segment to the specified disk file.

 

int restoreGsm(char *fileName);

Read a binary copy of the shared memory segment from the specified disk file.

tpriGsmDDCom - GSM Data Dictionary Class

 Overview

The data dictionary allows global common variables to be referenced by their string name.  At runtime, the Data Dictionary is itself maintained in a shared memory segment, and thus the tpriGsmDDCom class is derived from the tpriGsm class.

 Class Interface

The following public member functions are provided as part of the tpriGsmDDCom class above and beyond the default tpriGsm member functions:

 

static int Create(int create = 0);

Start the data dictionary for the current process.

 

static int Destroy();

Shut down the data dictionary for the current process.

 

static char *getVarName(char *pName);

Parse the true variable name from a possibly augmented (with <, >, =, etc. characters) name.

 

static void *getVarPtr(char *pName, long *pSize = NULL,

    unsigned short *pVType = NULL,

 long *pOffset = NULL);

Return a pointer to the specified variable in memory and optionally return the variable’s size, type, and offset.

 

static long getVarSize(char *pName);

Return the size of the specified variable.

 

static VARIANT getVariant(char *pName, void **pPtr = NULL, long *pSize = NULL);

Return a VARIANT object containing the current value of the specified variable, and optionally return parameters to use to update the variant.

 

static int updateVariant(VARIANT *var, void *ptr, long size);

Update the specified variant using the parameters returned from getVariant(..).

 

static int writeVariant(VARIANT *var, void *ptr, long size, VARIANT *orig);

Write the value of the specified variant back to the memory associated with the original variant.

 

static unsigned short getVarType(char *pName);

Return the data type of the specified variable.

 

static const char *getVarTypeName(char *pName);

Return a string description of the data type of the specified variable.

 

static unsigned long getVarGsmMask(char *pName);

Return the GSM Mask bitmask for the specified variable.

 

static const void *getVarInitPtr(char *pName);

Return a pointer to the initial value associated with the specified variable.

 

static const void *getVarMinPtr(char *pName);

Return a pointer to the minimum value associated with the specified variable.

 

static const void *getVarMaxPtr(char *pName);

Return a pointer to the maximum value associated with the specified variable.

 

static const char *getVarFmt(char *pName);

Return a pointer to the formatting string associated with the specified variable.

 

static const char *getVarDesc(char *pName);

Return a pointer to the description associated with the specified variable.

 

static const char *fmtVarInit(char *pName);

Return a pointer to a string containing the initial value of the specified variable formatted according to it’s formatting string.

 

static const char *fmtVarMin(char *pName);

Return a pointer to a string containing the minimum value of the specified variable formatted according to it’s formatting string.

 

static const char *fmtVarMax(char *pName);

Return a pointer to a string containing the maximum value of the specified variable formatted according to it’s formatting string.

 

static int setVarInit(char *pName, void *pData);

Set the initial value of the specified variable.

 

static int setVarMin(char *pName, void *pData);

Set the minimum value of the specified variable.

 

static int setVarMax(char *pName, void *pData);

Set the maximum value of the specified variable.

 

static int setVarFmt(char *pName, char *pFmt);

Set the formatting string of the specified variable.

 

static int setVarDesc(char *pName, char *pDesc);

Set the description of the specified variable.

 

static int setVarData(char *pName, void *pData);

Set the current value of the specified variable.

 

static int getStructInfo(char *pName, long *size,

 unsigned short *vType, long *offset);

Return various structure information about the specified variable.

 

static int traverseTree(char *pName,

unsigned long mask = GSMDEFMASK_ALL);

Traverse the data dictionary tree and export the name of each leaf to the specified buffer.

 

static int searchTree(char *strSearch, char *pName);

Search the data dictionary tree for the given string and return the name of the first variable containing the search string.

 

static tpriGsm *findTpriGsm(char *gsmName);

Return a pointer to the tpriGsm object associated with the specified GSM name.

 

static void *mapGsm(char *varName, int create /* = 0 */);

Map or create the specifed GSM region.

 

static int attachGsm(tpriGsm **ppGsm, char *varName,

  char *varType, char *mask,

  char *ascFile, int takeCtrl /* = 1 */);

Attach an existing tpriGsm object into the data dictionary.

 

static int mapAllGsm(int create = 0);

Map all GSM regions into the current process.

 

static int restoreGsm(char *gsmName, char *fileName = NULL);

Perform a binary restore of the specified GSM from an existing disk file.

 

static int restorePersist(char *varName,

  char *fileName = NULL);

static int restorePersist(char *varName,

  tpriIniFile *pIniFile);

Restore the given variable by name from the specified file.

 

static int restoreAllPersist(char *fileName = NULL);

Restore all variables in the specified file by name.

 

static int restorePersistByList(char *listFile, char *listSect,

        char *varFile = NULL);

Restore a list of variables identified in one file from a second data file.  The variable list should be stored in [listSect] of the file listFile with one variable name per line.  The variable data will be restored from the file varsFile or, if NULL, in the persistent data file specified for each variable's global common in the data dictionary variable initialization file.

 

static int saveGsm(char *gsmName, char *fileName = NULL);

Perform a binary save of the specified GSM to a disk file.

 

static int savePersist(char *varName, char *fileName = NULL);

static int savePersist(char *varName, tpriIniFile *pIniFile);

Save the given variable by name from the specified file.

 

static int saveAllPersist(char *fileName = NULL);

Save all variables in the specified file by name.

 

static int savePersistByList(char *listFile, char *listSect,

     char *varFile = NULL);

Save a list of variables identified in one file from a second data file.  The variable list should be stored in [listSect] of the file listFile with one variable name per line.  The variable data will be stored in the file varsFile or, if NULL, in the persistent data file specified for each variable's global common in the data dictionary variable initialization file.

tpriLogMsg – Log Message Class

 Overview

The tpriLogMsg class provides a way for processes to post text messages to global queues for later processing or asynchronous display.  The available queues are defined at system startup time through an ini file.  In addition, there is always a default queue named “LogMsg” to which any process may post messages.  Messages in this default queue are displayed on the NtRtMgr console.  While only a finite number of messages are kept in memory (specifically, the last 512), the NtRtMgr automatically logs messages posted to these queues to files on the disk.

DumpHex is a utility function that uses the LogMsg function to display the contents of a memory area in both hex and ascii formats.  

 Initialization Files

An entry in the system initialization file (i.e. that file which is passed on the command line to the NtRtMgr) specifies the LogMsg specific initialization file.  The following entry must be found in the [General] section of the system initialization file:

# Define the LogMsg initialization file

Logs=D:\locNtRt\sys\pif\sysLogs.ini

An example of a sysLogs.ini file follows:

#  LogMsg Initialization File
 
[General]
# Specify the disk log directory for the default "LogMsg" queue.
LogMsgDir=D:\locNtRt\sys\Logs

# Specify the default maximum number of days to keep files in
# the above directory.
#LogMsgMaxDays=90

[Queues]
#Specify any additional queues.
#Queue Name    #Disk log directory       #Max Days
OprMsgD:\locNtRt\sys\Logs       100
 Log Message Calls

The following are examples of log message calls

// this is a normal LogMsg call
LogMsg("myFunction", DBDEBUG, "Log this message\n");

// this LogMsg call does the same thing as the above call
LogMsg("myFunction", "LogMsg" DBDEBUG, "Log this message\n");

// this LogMsg call sends the message instead to the OprMsg queue
LogMsg("myFunction", "OprMsg" DBDEBUG, "Log this message\n");

// this LogMsg call sends the message to both queues
LogMsg("myFunction", "LogMsg&OprMsg" DBDEBUG, "Log this message\n");
 Global Structures

The following structure is used to define a single log message stored in any one of the message queues:

#define MAX_LOGMSG_NAME       32       // max size of process/function name
#define MAX_LOGMSG_CHARS      256      // max size of single message
#define MAX_LOGMSGS  512      // Max messages in a queue

struct s_LogMsg
   {
   long idx;// index of message
   struct timestamp 
      {
      long seconds;  // seconds since 1/1/1970
      long nanoseconds;       // nanoseconds past seconds
      } dt; // time of message
   char proc[MAX_LOGMSG_NAME];// name of process that generated message
   char func[MAX_LOGMSG_NAME];// name of function that generated message
   char msg[MAX_LOGMSG_CHARS];// message text
   };
 Global and Static Class Functions
void LogMsg(char *name, char *queue, int msglv, const char *fmt, ...)
Global function to post a message to a given message queue if the message level is less than the debug level for a process.
Inputs:
char *name      Name of originating function for reference.
char *queue      Name of destination queue.  Messages can be passed to multiple queues in the same call by passing a string containing the names of each of the desired destination queues delimited with ampersand (‘&’) characters.
int msglv      Message level.
const char *fmt      Formatting string equivalent to that passed to printf(..).
Return value:
This function does not return a value.

void LogMsg(char *name, int msglv, const char *fmt, ...)
This is identical to a call to the original LogMsg(..) function above with the destination queue set to the default queue “LogMsg”.

static int getLastIdx(char *queue)
Return the index of the last logged message in the specified queue.  Messages that are posted via calls to LogMsg(..) are automatically given an index by which they can be sequentially retrieved.  The last 512 messages are stored in memory.
Inputs:
char *queue      Name of queue.
Return value:
A return value of -1 indicates that the specified queue cannot be found.

static int getLogMsg(char *queue, int idx, struct s_LogMsg *pMsg)
Copy a message out of the specified queue and into the supplied structure.
Inputs:
char *queue      Name of queue.
int idx      Index of the desired message.
s_LogMsg *pMsg      Pointer to destination message structure.
Return value:
A return value of 0 indicates success, -1 indicates the specified queue cannot be found, and -2 indicates that the message has expired.

There are several overloaded calling formats for the DumpHex function as follows:
void DumpHex(char *name, char *queue, int msglv, char *pmem, unsigned int reladr, unsigned int num, const char *fmt, ...)
void DumpHex(char *name, char *queue, int msglv, char *pmem, unsigned int reladr, unsigned int num, int bCompress, const char *fmt, ...)
void DumpHex(char *name, int msglv, char *pmem, unsigned int reladr, unsigned int num, const char *fmt, ...)
void DumpHex(char *name, int msglv, char *pmem, unsigned int reladr, unsigned int num, int bCompress, const char *fmt, ...)  
void DumpHex(int msglv, char *pmem, unsigned int reladr, unsigned int num, char *headr)
void DumpHex(int msglv, char *pmem, unsigned int reladr, unsigned int num, int bCompress, char *headr)
void DumpHex(int msglv, unsigned char *pmem, unsigned int reladr, unsigned int num, char *headr)
void DumpHex(int msglv, unsigned char *pmem, unsigned int reladr, unsigned int num, int bCompress, char *headr)
   
Inputs:
char *name  Name of originating function for reference.
char *queue  Name of destination queue.  Messages can be passed to multiple queues in the same call by passing a string containing the names of  each of the desired destination queues delimited with ampersand (‘&’)  characters. (Default = LogMsg queue)
int msglv        Message level.
char *pmem  Start address of memory to be displayed
unsigned int reladr  Relative address (offset) into memory buffer to be displayed
     This offset is added to the address supplied in pmem
unsigned int num    Number of bytes to be displayed
int bCompress        0 - display data in uncompressed format (default)
     1 - display data and compress sequential identical bytes 
 to reduce the number of lines required to display the contents
 of the memory area 
const char *headr    Formatted string equivalent to that passed to printf(..).
      This string is displayed as part of the 1st line of the 
      memory display and is normally used to identify the contents
 Example Code

The following code sequentially processes messages from a tpriLogMsg queue.

static int msgIdx = -1;
   int lastIdx;
   s_LogMsg msgInfo;

   // check for any new messages
   lastIdx = tpriLogMsg::getLastIdx("MsgQueue");
   if (lastIdx >= (msgIdx + MAX_LOGMSGS))
      {
      if (msgIdx >= 0)
{
// we lost some messages
LogMsg("Tc1CsfMsg", DBERR, "Lost >= %d messages from MsgQueue\n",
   lastIdx - msgIdx);
}

      // just start up again with the latest
      msgIdx = lastIdx;
      }

   while (lastIdx > msgIdx)
      {
      // get the next message
      msgIdx += 1;
      fstatus = tpriLogMsg::getLogMsg("MsgQueue", msgIdx, &msgInfo);
      if (fstatus != 0)
{
LogMsg("Tc1CsfMsg", DBERR, "Error %d retrieving MsgQueue[%d]\n",
   fstatus, msgIdx);
}
      else
{
// process the message ...
}
      }

tpriIniFile - Ini File Support Class

 Overview

This class defines basic .ini file operations, such as opening the file, finding a section (denoted '[SectionName]", retrieving lines from the file, and closing them when finished.

 Class Interface

The following public member functions are provided as part of the tpriIniFile class:

  • tpriIniFile(char *pfileName);
    Constructor for the ini file class, passed file name as character string.

  • tpriIniFile(FILE *fp);
    Constructor for the ini file class, passed file descriptor.

  • tpriIniFile(char *pBuf,int nBytes);
    Constructor for the ini file class; passed file as array of characters.

  • ~tpriIniFile();
    Destructor for the ini file class.

  • int findSection(char *sectionName);
    Find a section within the file and prepare to read the lines immediately following.

  • int getLineCount(char *sectionName);
    Get the count of lines in a given section.

  • int getNextLine(char *pLine, int szLine);
    Get the next valid (non-comment, non-whitespace) line in the ini file.

  • int getKeyValue(char *keyName, char *defValue, char *pValue, int szValue);
    Get a key within the current section.

  • int getKeyValues (char *keyName, char *defValue, char *pValue, int szValue, const char *fmt, int cnt, _);
    Get a key within the curent section. Decode using the format "fmt" and return values in passed variables.

  • int getKeyValue(char *sectionName, char *keyName, char *defValue, char *pValue, int szValue);
    Get the value associated with a section/key in the ini file.

  • int getKeyValues (char *sectionName, char *keyName, char *defValue, char *pValue, int szValue, const char *fmt, int cnt, _);
    Get the value associated with a section/key in the ini file. Decode using the format "fmt" and return values in passed variables.

  • int getKeyValueEnv(char *keyName, char *defValue, char *pValue, int szValue);
    Get a key within the current section and translate any environment variables out of the value.

  • int getKeyValueEnv(char *sectionName, char *keyName, char *defValue, char *pValue, int szValue);
    Get the value associated with a section/key in the ini file and translate any of the environment variables out of the value.

  • int setKeyValue(char *sectionName, char *keyName, char *pValue);
    Set the value associated with a section/key in the ini file.

  • int writeLine(char *cStr);
    Write a line to the ini file.

  • int cleanSection(char *sectionName);
    Clean all the lines of data out of a section.

  • int deleteSection(char *sectionName);
    Delete an entire section from the ini file.

  • int deleteKey(char *sectionName, char *keyName);
    Delete the specified key from the specified section.

  • int deleteLine();
    Delete a line from the ini file.

  • int commit();
    Commit any changes back to disk.

  • inline int getError();
    Get error/return status.

  • inline const char *getBuffer();
    Return pointer to ini file buffer.

  • inline int getSize();
    Return file size in bytes.

  • static int getLineCount(char *sectionName, char *fileName);
    Return the number of lines in a given section.

  • static int getKeyValue(char *sectionName, char *keyName, char *defValue, char *pValue, int szValue, char *fileName);
    Get the value associated with a section/key in the ini file.

  • static int getKeyValues (char *sectionName, char *keyName, char *defValue, char *pValue, int szValue, char *filename, const char *fmt, int cnt, _);
    Get the value associated with a section/key in the ini file "filename". Decode using the format "fmt" and return values in passed variables.

  • static int getKeyValueEnv(char *sectionName, char *keyName, char *defValue, char *pValue, int szValue, char *fileName);
    Get the value associated with a section/key in the ini file and translate any environment variables out of the value.

  • static int setKeyValue(char *sectionName, char *keyName, char *pValue, char *fileName);
    Set the value associated with a section/key in the ini file.

  • static int cleanSection(char *sectionName, char *fileName);
    Clean all the lines of data out of a section in an ini file.

  • static int deleteSection(char *sectionName, char *fileName);
    Delete an entire section in an ini file.

  • static int deleteKey(char *sectionName, char *keyName, char *fileName);
    Delete the specified key from the specified section in an ini file.

  • static char *extractIniString(char *pbuf);
    Extract a string from an ini initialization line. If the first non-whitespace character is a double quotes, the string is assumed to be contained within a pair of quotes. Otherwise, the string is space delimited.

tpriTimer – Timer Support Functions

 Overview

These functions encompass basic timer functions. These functions may be called by any application task to set and test timers. The timer values are allocated and maintained in user defined variables and are tested by user calls. 

 Class Interface

The following public functions are provided as part of the tpriTimer support:

  • TIMERVAL SetUTimer (int us);
    Return the value of a timer that will expire in 'us' microseconds.
    If us = 0, turn timer off

  • TIMERVAL SetMTimer (int ms);
    Return the value of a timer that will expire in 'ms' milliseconds.
    If ms = 0, turn timer off

  • TIMERVAL SetSTimer (int s);
    Return the value of a timer that will expire in 's' seconds.
    If s = 0, turn timer off

  • TIMERVAL AddUTimer (TIMERVAL timer, int us);
    Return the value of a timer that is set to expire 'us' microseconds after (if 'us' is positive) or before (if 'us' is negative) the timer value passed in 'timer'.  The current passed 'timer' may be scheduled to expire in the future or may have already expired.  If 'timer' is off (inactive), set the timer to expire 'us' microseconds into the future.

  • TIMERVAL AddMTimer (int ms);
    Return the value of a timer that is set to expire 'ms' milliseconds after (if 'ms' is positive) or before (if 'ms' is negative) the timer value passed in 'timer'.  The current passed 'timer' may be scheduled to expire in the future or may have already expired. If 'timer' is off (inactive), set the timer to expire 'us' microseconds into the future.

  • TIMERVAL AddSTimer (int s);
    Return the value of a timer that is set to expire 's' seconds after (if 's' is positive) or before (if 's' is negative) the timer value passed in 'timer'.  The current passed 'timer' may be scheduled to expire in the future or may have already expired.  If 'timer' is off (inactive), set the timer to expire 'us' microseconds into the future.

  • __int64 RemUTimer (TIMERVAL timer);
    Return the value of the time in microseconds remaining on timer 'timer'.  If the timer has already expired, return the number of microseconds in the past as a negative number.  If the timer is off (inactive), return a value of zero.

  • TIMERVAL AddMTimer (int ms);
    Return the value of the time in milliseconds remaining on timer 'timer'.  If the timer has already expired, return the number of milliseconds in the past as a negative number.  If the timer is off (inactive), return a value of zero.

  • TIMERVAL AddSTimer (int s);
    Return the value of the time in seconds remaining on timer 'timer'.  If the timer has already expired, return the number of seconds in the past as a negative number.  If the timer is off (inactive), return a value of zero

  • int TstTimer(TIMERVAL timer);
    Test for current status of the timer 'timer'
    Return value as as follows:
    +1 = Timer still active and not timed out yet
    0  = Timer is off (inactive)
    -1 = Timer has timed out

tpriAppThread – Application Thread Functions

 Overview

These functions allow the user to create, manage, and destroy an (additional) application thread. These functions may be called by any application task.

 Class Interface

The following public functions are provided as part of the tpriAppThread support:

  • tpriAppThread();
    Create an application thread instance

  • ~tpriAppThread();
    Destroy an application thread instance

  • int StartAppThread(
       int iTimer1,
       int iTimer2,
       PTHREAD_START_ROUTINE userThreadFunction,
       LPVOID userThreadFunctionArg,
       int iPriority,
       unsigned long CreateFlags);
    Start execution of an application thread, where:
       iTimer1 = initial (first time) repeat interval (ms)
       iTimer2 = Subsequent repeat interval (ms)
       userThreadFunction -- thread function to be executed
       userThreadArg -- list of function arguments
       iPriority -- thread priority
       CreateFlags -- thread creation flags, as passed to Microsoft
          CreateThread function.
    return value: 0 = successful

  • int ThreadShutdownRequest()
    Setting this class variable to non-zero will cause the thread to exit on its next execution.

 Example

The following code snippet is an example of creating and starting an application thread:

int fstatus = 0;
   class tpriEgd *pEgd;
   class tpriAppThread *pTap;             // class pointer
   int TimedProduceCmd(void *pParam);     // function prototype
   int iTimer1 = 1000;
   int iTimer2 = 25;

   pEgd = this;
   pTAP = new class tpriAppThread;

   fstatus = pTAP->StartAppThread(
                iTimer1, 
                iTimer2, 
                (LPTHREAD_START_ROUTINE)TimedProduceCmd, 
                (LPVOID)pEgd,
                THREAD_PRIORITY_TIME_CRITICAL, 
                NULL);
   if (fstatus != 0)
      {
      LogMsg("MyFunc", DBERR,
             "StartAppThread error: %d\n", fstatus);
      }

tpriUtil – Utility Support Functions

 Overview

This library provides basic support and utility functions.  These functions may be called by Win32 and/or RTSS application processes. 

 Library Functions

The following public function drives the output LEDs of a ppLED test module.  This module is connected to the parallel port #1 of the system:

int ppLed(int val, int mask);
where:
    val  = word data containing updated data bits
  bits in val should be set on or off as desired
    mask = bit mask describing bit(s) to be modified
Examples:
   ppLed(0x01, 0x01)   set lsb on, all others unmodified
   ppLed(0x00, 0x01)   set lsb off, all others unmodified
   ppLed(0x01, 0x03)   set 2 lsbs to b00000001 
     all others unmodified
   ppLed(0xff, 0x03)   set 2 lsbs to b00000011 
     all others unmodified

The following public function transforms an input string by substituting string segments of the form %XXX% with their system environment ‘YYY’ defined strings.  If called by a RTSS process, no string substitution takes place.

char *tpriEnvStr (char *inString,
char *outString = NULL,
int outsize = 2048);
Transform inString to outString by substitution of system environment variables.

Return is always a character pointer to the resulting string. If outString is not equal to NULL, the string is also copied into outString. If outString is specified, then the size of outString should be specified in the parameter outsize. The value of the outsize parameter cannot be greater than 2048 bytes.

public: int tpriCleanDir(
char *pDir,
timestamp age,
char *pPattern /* = NULL */
)

  • Description:
    Finds and deletes all files in a specified directory older than the specified amount of time.

Parameters:

  • pDir
    Pointer to directory name to search.

  • age
    Maximum age of file to leave in directory.

  • pPattern
    String pattern for file search; only files whose name matches this pattern will be deleted.  A NULL pointer is equivalent to "*", matching all files.

  • Return Value:
    Zero to indicate success.

tpriVop – Variable Operation Class

 Overview

The tpriVop class provides the functionality for parsing a variable operation from a string, validating the operation, and evaluating the operation.

 Variable Operation Format

A variable operation is a string expression containing variables from global common and/or constant values.  The condition is considered true if the expression evaluates to a non-zero value, otherwise the condition is considered false.  All expressions must be specified as one of the following:

  • The fully qualified name of variable in global common whose type is int, float, double, long, short, char, or char[].

  • A constant value such as a scalar numeric value, a single ASCII character enclosed in single quotes, or a string of characters enclosed in double quotes.

  • An expression in the following form and enclosed in parentheses:
    (Expression1 Operator Expression2)

where:

Expression1 and Expression2 are any two sub-expressions, and Operator is one of the following operators:

&&

Logical AND operator

||

Logical OR operator

< 

Less than

<=

Less than or equal to

> 

Greater than

>=

Greater than or equal to

==

Equal to

!=

Not equal to

+

Add

-

Subtract

*

Multiply

/

Divide

The following special conditions apply:

  • The result of an expression containing one of the logical operators (<, <=, >, >=, ==, or !=) evaluates to the value 1 if true and 0 if false.

  • Variables of different types can be combined in a single expression; in this case the variables will be converted to a type consistent with their native types and the operation.

  • Global common variables that are character arrays are treated as strings and within a single expression or sub-expression can only be used with other character array variables or string constants.

  • Character arrays and string constants can only be used with logical operators (<, <=, >, >=, ==, or !=) and are evaluated in a manner consistent with the strcmp(..) C function. 

Following are examples of valid expressions:

(mycommon.myfloat > 0)
(mycommon.mychar == 'a')
(mycommon.myfloat >= mycommon.myint)
(mycommon.mystring != "samplestring")
(mycommon.myfloat > (mycommon.myint - 3.141))
((mycommon.myfloat > mycommon.myint) && (mycommon.mystring != "string"))
 Public Constructors

tpriVop()

Description:

Class constructor.

Inputs:

None.

Return value:

None.

 Public Functions

virtual int Reset()

Description:

Reset the contents of the variable operation object to an uninitialized state.

Inputs:

None.

Return value:

Zero for success, non-zero for error.

virtual int Format(char *buf, int size)

Description:

Format the operation into a string.

Inputs:

char *buf

Output buffer.

int size

Size of output buffer.

Return value:

Zero for success, non-zero for error.

virtual char *Parse(char *buf, int bValidate = 1)

Description:

Parse the operation from a string.

Inputs:

char *buf

Input buffer.

int bValidate

Flag to force immediate validation.

Return value:

Zero for success, non-zero for error.

virtual char *Validate()

Description:

Validate the variable operation.

Inputs:

None.

Return value:

[-1] Fatal validation error.

[+1] Non-fatal validation error (warning).

[0] Success.

virtual char *Evaluate()

Description:

Evaluate the variable operation.  A pointer to the output value can be retrieved with the GetOutputValue() function.

Inputs:

None.

Return value:

Zero for success, non-zero for error.

unsigned short GetNativeType()

Description:

Return the native type for the variable operation.  By default, the variable operation is evaluated to a native value whose type is most appropriate for the operation and operands in the variable operation; this function returns the variant type of this native value.  

Inputs:

None.

Return value:

Native type for the variable operation.  This value will equal one of the Windows Variant types (VT_XX).

long GetNativeSize()

Description:

Return the native type for the variable operation.  By default, the variable operation is evaluated to a native value whose type is most appropriate for the operation and operands in the variable operation; this function returns the size in bytes of this native value.

Inputs:

None.

Return value:

Native size for the variable operation.

int SetOutputInfo(unsigned short vType, long size)

Description:

Set the output type information for the variable operation.  During evaluation, the native value is converted to this type for output.

Inputs:

unsigned short vType

Desired output type.

long size

Desired output size.

Return value:

Zero for success, non-zero for error.

unsigned short tpriVop::GetOutputType()

Description:

Return the output type for the variable operation.  This is the type of the value that is pointed to by the GetOutputValue() function.  

Inputs:

None.

Return value:

Output type for the variable operation.  This value will equal one of the Windows Variant types (VT_XX).

void *GetOutputValue()

Description:

Return a pointer to the output value.  Once the operation has been evaluated this will point to the output value of the operation.  

Inputs:

None.

Return value:

Pointer to the output value.

int SetDepth(int ndepth)

Description:

Set the output type information for the variable operation.  During evaluation, the native value is converted to this type for output.

Inputs:

int ndepth

Desired logging depth.  This is the depth at which all LogMsg calls should be logged, i.e. the number of spaces x2 inserted into the message buffer before the message text itself.

Return value:

Zero for success, non-zero for error.

tpriRps – Rules Processing Classes

 Overview

The Rules Processing System API consists of a set of hierarchical classes defined in the TSENTRY tpriNtRt C/C++ library.  With the exception of the classes defined to read and write the XML rule definition files, which utilize the Microsoft .NET Framework, the rules processing system API classes are all coded in ANSI C/C++ in order to make them as portable as possible.

 Classes

Brief descriptions of each of the individual rules processing classes are provided below:

Class Name

Class Description

tpriRpsAction

Defines base class for rule actions.

tpriRpsModifyVarAction

Defines specific type of rule action which modifies a variable in global shared memory.

tpriRpsCriteria

Defines base class for rule criteria.

tpriRpsVarCriteria

Defines specific type of rule criteria whose condition is a Boolean statement containing variables from global shared memory.

tpriRpsCriteriaGroup

Defines specific type of rule criteria which consists of several sub-criteria.

tpriRpsRule

Defines base class for rule, which is itself a criteria group.

tpriRpsFile

Defines base class for persistent storage of rule definition to a disk file.

tpriRpsXmlFile

Defines specific implementation of rule file stored as an XML file.

tpriRpsRuleGroup

Defines base class for a group of rules associated with one another.

tpriRpsProcessor

Defines base class for a rules processor, which is itself a rule group.

  • No labels

© 2022 TelePro, Inc.
3811 Illinois Avenue, Suite 100, St. Charles, IL 60174