NAME

      rtperl - RTAP perl (Practical Extraction and Report Language)

SYNOPSIS

      rtperl <with same options as perl>

INTRODUCTION

      rtperl is perl with RTAP extensions as classes. The classes are object
      oriented with the following heirarchy:


      CRtap ------> CRtapDb -------> CRtapSs
        |              |
        |              |-----------> CRtapDh
        |              |
        |              |-----------> CDbUtil
        |
        |---------> CRtapTk


      All methods in the CRtap class is available to all of the other
      classes, all methods in the CRtapDb class is available to the CRtapSs
      and CRtapDh classes, etc.

      The CRtap class provides for asynchronous handling of RTAP messages
      (see registerCallback method below).

      Please see other fine references for perl specifics (eg. "Programming
      Perl" by Larry Wall, Tom Christiansen & Randal L. Schwartz; O'Reilly &
      Associates, Inc.; ISBN 1-56592-149-6).



RTAP Extensions

      This section describes each of the classes for the RTAP extensions.

CRtapClass

      The CRtap class provides the base RTAP functionality and all methods
      are available to all other classes.

      The new method is used to create an instance of this class. This
      method takes the following hash values for it's arguments:


           env  Specifies the RTAP environment to attach to. If this value
                is not specified, the contents of the environment variable
                RTAPENV will be used.

           argv0
                Specifies the RTAP process name to register as. This value
                must be specified.

Example:

      use CRtap;

      $env = "jck";

      # Remove leading path info from our name.
      $nm = $0;
      $nm =~ s!.*/!!;

      $rtap = CRtap->new ('argv0' => "$nm", 'env' => "$env");
      if (! defined $rtap) {
          print "Failed to register with RTAP environment.\n";
          exit (-1);
      }


      The following describes the methods available for this class:


           char *getEnvDir ()
                Returns the environment directory. A NULL string will be
                returned if an error occurs.

           int getEnvMode ()
                Returns the current operating mode of the local host and
                environment (see rtMAIN and rtSTANDBY below).

           char *getMyName ()
                Returns the RTAP process name of the calling process.

           getMyProcId ()
                Returns a hash reference with the following values:

Hash Name Description
procEnv RTAP Environment name.
procNum RTAP Process Number.
                If the call fails it will return an undefined value.

Example:

                $procId = $rtap->getMyProcId ();

                if (! defined $procId) {
                    print "ERROR: getMyProcId call failed.\n";
                    $rtap->printError ();
                }
                else {
                    print "Procid env = $procId->{'procEnv'}\n"
                        if defined $procId->{'procEnv'};
                    print "Procid num = $procId->{'procNum'}\n"
                        if defined $procId->{'procNum'};
                }



           int getPidByName (char *name)
                Returns the OS process ID for the RTAP process name. Returns
                rtSUCESS or rtFAILED.

           int getPidByProcNum (int num)
                Returns the OS process ID for the RTAP process number num.
                Returns rtSUCESS or rtFAILED.

           char *getProcName (int num, char *env =NULL)
                Returns the RTAP process name for the RTAP environment env
                (default =NULL) and RTAP process number num.  NULL.

           int getProcNum (char *name, char *env =NULL)
                Returns the RTAP process number for the RTAP process name
                name in the RTAP environment env (default =NULL).

           int getQueue (int num, char *env =NULL)
                Returns the the message queue ID for the RTAP process number
                num in the RTAP environment env (default =NULL).

           int getUid ()
                Returns the current effective RTAP user ID.

           int getUidByName (char *name)
                Returns the RTAP user ID for the user name name.

           void logError (char *mesg =NULL)
                Logs the current RTAP error through to RtapMonitor(1) with
                the error message mesg.

           void logMessage (char *mesg)
                Logs the message mesg through to RtapMonitor(1).

           int makeMeRtap ()
                Sets the calling process to set its effective RTAP user ID
                to user rtap. Returns either rtSUCCESS or rtFAILED (see
                below).

           int monitorQueue (int state =1)
                Provides a process the ability to monitor its input for
                messages. state indicates whether monitoring is to be
                enabled (state > 0) or disabled (state = 0); the default
                value is one. Returns rtSUCCESS or rtFAILED (see CRtap
                Symbols below).

           rtMsgHeader *msgRecv ()
                Returns an RTAP message header object that can be used in
                the processMessage method.

           int msgSend (char *mesg, int procNum, char *name =NULL, char *env
           =NULL)
                Sends an rtASCII_MESSAGE message type message to the
                specified RTAP process number procNum if not zero. If the
                process number passed in is zero, a lookup on the process
                name name will be done. The RTAP environment used is
                specified in env. The return value is either rtSUCCESS or
                rtFAILED (see CRtap Symbols below).

           void printError ()
                Prints the RTAP errno structure out to stdout.

           void processMessage (rtMsgHeader *msgHdr)
                Parses the message msgHdr and calls any callbacks
                registered.

	   int rawMsgSend (unsigned int msgType, unsigned char *typeMsg,
	      int typeMsgSize, unsigned char *msgBody, int msgBodySize,
	      int procNum, char *name =NULL, char *env =NULL)
                Sends a message of msgType type to the specified RTAP
		process number procNum if not zero. The message will
		be composed of the typeMsg of length typeMsgSize,
		and msgBody of length msgBodySize. If the process number
		passed in is zero, a lookup on the process name name will
		be done. The RTAP environment used is specified in env.
		The return value is either rtSUCCESS or rtFAILED (see
		CRtap - Symbols below).


           void registerCallback (func, int mType)
                Registers the specified function func to be called when an
                RTAP message type mType is received. mType can be specified
                using the symbols defined below.  Note that only one
                function can be registered for a particular message type. If
                a subsequent call is made for an already registered message
                type, only the last registered function will be called.

                func can be a string for the function name, or a reference
                to a function.

Examples:

                sub fred
                {
                    print "Hello there.\n";
                }

                $rtap->registerCallback ("fred", CRtap::rtASCII_MESSAGE);
                $rtap->registerCallback (fred, CRtap::rtEVENT_MESSAGE);

                $ref = fred;
                $rtap->registerCallback ($ref, CRtap::rtPS_OBITUARY);
                $rtap->registerCallback ( sub { print "Hello there.\n" },
                                          CRtap::rtTK_MESSAGE);


                All functions will be passed a reference to a hash except
                for the rtASCII_MESSAGE type which will be passed a
                character string.

                The hash parameter(s) passed into the functions are:


                rtEVENT_MESSAGE

Hash Name Description
rtEventHeader Hash reference (see below).
sys Hash reference only if event type is rtSYSTEM_EVENT.
db Hash reference only if event type is rtDATABASE_EVENT.
app Hash reference only if event type is rtAPPLICATION_EVENT.
                     The rtEventHeader hash reference contains the following
                     values:

Hash Name Description
hangerSize Event hanger size.
eventSize Event type header size.
hangerSource Hash reference to process ID (see getMyProcId above).
triggerSource Hash reference to process ID (see getMyProcId above).
triggerUId User ID of trigger.
trigger Mask of event trigger that caused the event.
enable Mask of enable bits that was set for the hanger.
type Specifies the type of event as either rtSYSTEM_EVENT, rtDATABASE_EVENT, or rtAPPLICATION_EVENT.
id Hash reference of the event ID (see below).
                          The id hash reference contains the following
                          values:

Hash Name Description
procEnv Process environment name.
event Event number.
                     The sys hash reference (only available if the event
                     type is rtSYSTEM_EVENT) contains the following values:

Hash Name Description
type Type of system event as either rtCE_ERROR, rtPRINTER_SWITCH or rtDB_SNAPSHOT_COMPLETED.
ceMath Hash reference only available if the type is rtCE_ERROR.
pd Hash reference only available if the type is rtPRINTER_SWITCH.
dbSnapshot Hash reference only available if the type is rtDB_SNAPSHOT_COMPLETED.
                          The ceMath hash reference (only available is the
                          system event type is rtCE_ERROR) contains the
                          following values:

Hash Name Description
plin PLIN number of CE error.
ain AIN number of CE error.
error Hash reference for RTAP errno (see below).
                               The error hash reference contains the
                               following values:

Hash Name Description
errorTime Error time in seconds since Jan. 1, 1970.
ignoreError Flag for ignoring errors.
errorCount Number of context errors.
errorList An array of hashes reference for the single errors (see below).
                                    Each errorList array reference value is
                                    a hash reference that contains the
                                    following values:

Hash Name Description
sourceId Error source ID.
procNum RTAP process number.
errorNumber RTAP error number.
sourceName Error source name.
envName RTAP environment name.
progName Program name.
functionName Program's function name.
errorString Actual error string.
messageString Error message string.
location Error location.
                     The pd hash reference contains the following values:

Hash Name Description
oldPD Old printer device.
newPD New printer device.
procId Hash reference to process ID (see getMyProcId above).
                     The dbSnapshot hash reference contains the following
                     values:

Hash Name Description
status Snapshot status.
timeCompleted Hash reference for an rtTime structure that contains time completed (see below).
                          The timeCompleted hash reference contains the
                          following values:

Hash Name Description
tv_sec Number of seconds since Jan. 1, 1970.
tv_usec Number of micro-seconds.
                     The db hash reference (only available if the event type
                     is rtDATABASE_EVENT) contains the following values:


Hash Name Description
plin PLIN number of database event.
ain AIN number of database event.
type Attribute type as either rtSCALAR, rtVECTOR or rtTABLE.
scalar Hash reference that is only available if the attribute type is rtSCALAR.
vector Hash reference that is only available if the attribute type is rtVECTOR.
table Hash reference that is only available if the attribute type is rtTABLE.
                          The scalar hash reference contains the following
                          values:

Hash Name Description
deType RTAP data element type of attribute (see CRtap Symbols below).
oldQuality Old attribute quality as either rtATTR_OK, rtATTR_SUSPECT, rtATTR_ERROR or rtATTR_DISABLED.
newQuality New attribute quality (see oldQuality above).
values An array reference that contains the previous and current attribute value.
                          The vector hash reference contains the following
                          values:

Hash Name Description
startElement Start vector element.
endElement End vector element.
                          The table hash reference contains the following
                          values:

Hash Name Description
startRecord Start table record.
endRecord End table record.
startField Start table field.
endField End table field.
                rtTK_MESSAGE

Hash Name Description
rtTimerId Hash reference for the timer ID (see below).
rtUserMessage User message if any.
                     The rtTimerId hash reference contains the following
                     values:

Hash Name Description
time Hash reference of the alarm (see timeCompleted above).
id Hash reference of the time request.
                          The id hash reference contains the following
                          values:

Hash Name Description
time Timer ID time hash reference (see timeCompleted above).
procid Process ID hash reference (see getMyProcId above).
                rtPS_OBITUARY

Hash Name Description
debug Debug flag.
restart Restart flag.
name Name of deceased process.
deceased Process ID hash reference for the deceased process (see getMyProcId above).
exitStatus Exit value of deceased process.
           void run ()
                This call will infinitely loop receiving messages and
                processing them.

           scheduleProcess (char *rStr, int flag =rtMERGE_RUNSTRING, char *env
           =NULL)
                Returns a hash reference of the process ID of the process
                that was scheduled through RTAP. If the call fails, an
                undefined value is returned. The parameters rStr specifies
                the run string, flag specifies additional features
                (rtDEFAULT_RUNSTRING, rtMERGE_RUNSTRING, rtNOTIFY) that can
                be or'ed together, and env specifies the RTAP environment
                name.

           int setMyName (char *name)
                Sets the RTAP process name of the calling process to name.
                Returns rtSUCCESS or rtFAILED (see CRtap Symbols below).

           int setRestart (int type)
                Sets the calling process restart type to type (either rtNO,
                rtPROGRAM, or rtENVIRONMENT). Returns rtSUCCESS or rtFAILED
                (see CRtap Symbols below).

           int setUid (int uID, char *password)
                Sets the calling process effective RTAP user ID to uID if
                the correct password password is given. Returns rtSUCCESS or
                rtFAILED (see CRtap Symbols below).

           int setUidByName (char *uName, char *password)
                Sets the calling process effective RTAP user ID to uName if
                the correct password password is given. Returns rtSUCCESS or
                rtFAILED (see CRtap Symbols below).

           int shutdownEnv (int type =rtSOFT)
                Requests a shutdown of the current RTAP environment. type
                specifies the shutdown type as either rtSOFT (default) or
                rtHARD.Returns rtSUCCESS or rtFAILED (see CRtap Symbols
                below).

           int startNextPhase ()
                Sends a message to RtapScheduler(1) to enter the next
                startup phase in the RtapEnvTable(4).

CRtapSymbols

      The following symbols can be accessed by prefixing it with the class
      name and two colons (eg. CRtap::rtASCII_MESSAGE).

rtABS_TIME rtAPPLICATION_EVENT rtASCII_MESSAGE
rtATTR_DISABLED rtATTR_ERROR rtATTR_OK
rtATTR_SUSPECT rtBYTES12 rtBYTES128
rtBYTES16 rtBYTES20 rtBYTES256
rtBYTES32 rtBYTES4 rtBYTES48
rtBYTES64 rtBYTES8 rtBYTES80
rtCE_ERROR rtDATABASE_EVENT rtDATE
rtDB_SNAPSHOT_COMPLETED rtDB_XREF rtDEFAULT_RUNSTRING
rtDOUBLE rtENVIRONMENT rtEVENT_MESSAGE
rtFAILED rtFLOAT rtHARD
rtINT16 rtINT32 rtINT8
rtLOGICAL rtMAIN rtMERGE_RUNSTRING
rtNO rtNOTIFY rtNO_TIMEOUT
rtPOLAR rtPRINTER_SWITCH rtPROGRAM
rtPS_OBITUARY rtRECTANGULAR rtSCALAR
rtSOFT rtSTANDBY rtSUCCESS
rtSYSTEM_EVENT rtTABLE rtTIME_OF_DAY
rtTK_MESSAGE rtUINT16 rtUINT32
rtUINT8 rtUNDEFINED rtUSER_MESSAGE
rtVECTOR

                The rtDB_XREF data element type is a hash reference
                with the following values:

Hash Name Description
nameType Type of the direct address as either: rtDIR_INVALID, rtDIR_PLIN, rtDIR_AIN, rtDIR_REC_EL, rtDIR_FIELD.
pointId.plin PLIN number.
pointId.ain AIN number.
pointId.startRecEl Start record.
pointId.endRecEl End record.
pointId.startField Start field.
pointId.endField End field.

CRtapDb Class

      The CRtapDb class provides access into the RTAP database as well as to
      some plot configuration calls. This class inherits all of the methods
      available from the CRtap class.

      All database query call will return a value if successful and return
      undefined if the call fails.

      All database config and control calls will return either rtSUCCESS or
      rtFAILED.

      The CRtapDb class now provides support for the tesserNet
      point types and point groups as created with dbBuildCreator(1) via
      the tnCreatePtTypeNm, tnCreatePtTypeCls, and tnCreatePtGroup methods.
      The point types and point groups are read in from the
      configuration files on the first call to any of the above methods.
      Note that the pre and post command scripts will be run
      as specified in the point type and point group configuration. If
      the pre-command script returns non-zero, the point type/group will
      not be added. Note that for these methods, the database
      configuration interlock will be set by the method; the user should
      not set the configuration interlock prior to calling these
      methods.

      The new method is used to create an instance of this class. This
      method takes the following hash values for it's arguments:


           env  Specifies the RTAP environment to attach to. If this value
                is not specified, the contents of the environment variable
                RTAPENV will be used.

           argv0
                Specifies the RTAP process name to register as. This value
                must be specified.

           dbenv
                Specifies the RTAP database environment to open. If this
                value is not specified, the contents of the environment
                variables RTAPDB or RTAPENV will be used.

Example:

      use CRtapDb;

      $env = "jck";

      # Remove leading path info from our name.
      $nm = $0;
      $nm =~ s!.*/!!;

      $rtapDb = CRtapDb->new ('argv0' => "$nm", 'env' => "$env");
      if (! defined $rtapDb) {
          print "Failed to either register with RTAP environment,\n";
          print "or open database connection.\n";
          exit (-1);
      }


      The following describes the methods available for this class:


           void attachEvent (int enable, char *addr =NULL, char *msg =NULL, char
           *env =NULL)
                Attachs a database event and returns a hash reference if
                successful; otherwise returns undefined. Uses the following
                arguments:

Argument Description
enable Event enable flag is either rtDB_LESS, rtDB_LESS_OR_EQUAL, rtDB_EQUAL, rtDB_GREATER_OR_EQUAL, rtDB_GREATER, rtDB_NOT_EQUAL, rtDB_ANY_WRITE.
addr The database address for the event.
msg Contains an ASCII hanger message that will be delivered with the event.
env The RTAP environment.
                The hash reference returned contains the following values:

Hash Name Description
env RTAP environment name.
event An event ID number.
           int configAddField (char *fieldName, unsigned int deType, char *nm =NULL)

                Adds a field to the specified table. Note that this
                method is only available with RTAP 7.0+.

           int configAddNullPt (char *ptName, char *aName, int res
           =rtRAM_RESIDENT, int cat =CATEGORY_ALL, int ceOper =rtCE_ENABLED, exOrder
           =rtNATURAL, char *nm =NULL)

                Creates an empty point in the database using the following
                arguments:

Argument Description
ptName Point name of new point.
alias Alias name of new point.
res Residence of new point (either rtRAM_RESIDENT or rtDISK_RESIDENT).
cat Categories of new point. Can be an OR'ed combination of CATEGORY_0, CATEGORY_1, CATEGORY_2, CATEGORY_3, CATEGORY_4, CATEGORY_5, CATEGORY_6, CATEGORY_7, CATEGORY_8, CATEGORY_9, CATEGORY_10, CATEGORY_11, CATEGORY_12, CATEGORY_13, CATEGORY_14, CATEGORY_15, CATEGORY_16, CATEGORY_17, CATEGORY_18, CATEGORY_19, CATEGORY_20, CATEGORY_21, CATEGORY_22, CATEGORY_23, CATEGORY_24, CATEGORY_25, CATEGORY_26, CATEGORY_27, CATEGORY_28, CATEGORY_29, CATEGORY_30, CATEGORY_31. Or can be CATEGORY_ALL which sets all of the category bits.
ceOper CE operation indicator as either rtCE_ENABLED, rtCE_DISABLED or rtCE_ENABLED_OPT_A.
exOrder CE expression order as either rtNATURAL or rtUSER_DEFINED.
nm Parent alias name.
           int configAddScalar (char *attrName, int deType, int rGroup
           =GROUP_ALL, int wGroup =GROUP_ALL, char *nm =NULL)

                Adds a scalar attribute using the following arguments:

Argument Description
attrName Name of new attribute.
deType Specifies the data element type as either rtLOGICAL, rtUINT8, etc. (see CRtap Symbols).
rGroup Specifies the read groups as an OR'ed combination of GROUP_0, GROUP_1, GROUP_2 or GROUP_3. Or can be GROUP_ALL which sets all of the group bits.
wGroup Specifies the write groups (see rGroup above).
nm Specifies the alias of the point to create the attribute in. If this value is not specified, the attribute will be created in the current working point.
           int configAddTable (char *attrName, int recCnt, fields, int rGroup
           =GROUP_ALL, int wGroup =GROUP_ALL, char *nm =NULL)

                Creates a table attribute using the following arguments:

Argument Description
attrName Name of new attribute.
recCnt Number of records for the table.
fields An array of hash references (see below).
rGroup Specifies the read groups (see configAddScalar above).
wGroup Specifies the write groups (see configAddScalar above).
nm Specifies the alias of the point to create the attribute in. If this value is not specified, the attribute will be created in the current working point.
                The fields array of hash references should contains the
                following information:

Hash Name Description
name Specifies the field name.
deType Specifies the field's data element type as rtLOGICAL, rtUINT8, etc (see CRtap Symbols above).
           int configAddVector (char * attrName, int deType, int elemCnt,
                int rGroup =GROUP_ALL, int wGroup =GROUP_ALL, char *nm
                =NULL)

                Creates a vector attribute using the following arguments:

Argument Description
attrName Name of new attribute.
deType Specifies the data element type as either rtLOGICAL, rtUINT8, etc. (see CRtap Symbols above).
elemCnt Number of records for the vector.
rGroup Specifies the read groups (see configAddScalar above).
wGroup Specifies the write groups (see configAddScalar above).
nm Specifies the alias of the point to create the attribute in. If this value is not specified, the attribute will be created in the current working point.
           int configAlias (char *alias, char *nm =NULL)
                Configures the alias name to alias. nm specifies the alias
                of the point to change. If nm is not specified the current
                working point's alias will be changed.

           int configAttrAin (int ain, char *nm =NULL)
                Configures the attribute index number to ain for the specified
                attribute nm. If nm is not specified the current
                working point's attribute will be used. If ain is negative,
                the next available attribute index number will be used. Note that
                this method is only available with RTAP 7.0+.

           int configAttrName (char *aName, char *nm =NULL)
                Configures the attribute name to aName. nm specifies the
                attribute to change. If nm is not specified the current
                working point's attribute name will be changed.

           int configCategories (unsigned int cat, char *nm =NULL)
                Configures the point's categories to cat. nm specifies the
                alias of the point to change. If nm is not specified the
                current working point's categories will be changed.

           int configCopyAttr (char *toPt, char *newAttrName =NULL, char *nm
           =NULL)
                Copies an attribute to the point given by toPt. If
                newAttrName is specified, the attribute's name will be
                changed.  nm specifies the attribute to copy. If nm is not
                specified the current working point's attribute will be
                copied.

           int configCopyBranch (char *toPt, char *newName =NULL, char *nm =NULL)
                Copies a database branch to the point given by toPt. If
                newName is specified, the top point's name will be changed.
                nm specifies the point to copy. If nm is not specified the
                current working point will be copied.

           int configCopyPoint (char *toPt, char *newName =NULL, char *nm =NULL)
                Copies a database point to the point given by toPt. If
                newName is specified, the point's name will be changed.  nm
                specifies the point to copy. If nm is not specified the
                current working point will be copied.

           int configDefinition (char *def, char *nm =NULL)
                Configures the attributes definition to def. If nm is
                specified, that attributes definition will be changed;
                otherwise the current working point's attribute will be
                changed.

           int configDelAttr (char *nm =NULL)
                Deletes the specified attribute nm is specified; otherwise
                deletes the current working point's attribute.

           int configDelBrChk (char *nm =NULL)
                Checks to see if the branch given by nm can be successfuly
                deleted. If nm is not specified, checks the current working
                point.

           int configDelBranch (char *nm =NULL)
                Deletes the branch given by nm. If nm is not specified, the
                current working point's branch will be deleted.

           int configDelField (char *nm =NULL)
                Deletes the field given by nm. If nm is not specified, the
                current working point's field will be deleted. Note that
                this method is only available with RTAP 7.0+.

           int configDeType (unsigned int deType, char *nm =NULL)
                Changes the data element type for the specified attribute or field nm
                to the specified value deType. If nm is not specified,
                the current working point's attribute/field will be used. Note that
                this method is only available with RTAP 7.0+.

           int configExprOrder (int exOrd, char *nm =NULL)
                Configures the CE expression order specified by exOrd (as
                either rtNATURAL or rtUSER_DEFINED) on the point specified
                by nm. If nm is not specified, the current working point's
                CE expression order will be configured.

           int configFieldName (char * fieldName, char *nm =NULL)
                Configures the specified field nm to the specified new name fieldName.
                If nm is not specified, the current working point's field will be
                used. Note that this method is only available with RTAP
                7.0+.

           int configGroups (int rGroup, int wGroup, char *nm =NULL)
                Configures the read (rGroup) and write (wGroup) groups (see
                configAddScalar above) on the attribute specified in nm. If
                nm is not specified, the current working point's attribute's
                groups will be configured.

           int configMovePoint (char *toPt, char *newName =NULL, char *nm =NULL)
                Moves the specified point, nm, to the new parent, toPt. If
                newName is specified the point's name will be changed. if nm
                is not specified, the current working point will be moved.

           int configPlotBeginBranchCopy ()
                Begin a branch copy with plot points.

           int configPlotCopyAbsolute (char *fromPt, char *toPt, char *pPlot
           =NULL, char *nAlias =NULL, char *nPtName =NULL)

                Copies the plot point using the following arguments:

Argument Description
fromPt Plot point template to copy.
toPt New parent point.
pPlot Parent plot heirarchy point.
nAlias New alias name.
nPtName New point name.
           int configPlotCopyRelative ((char *fromPt, char *toPt, char *pPlot
           =NULL, char *nAlias =NULL, char *nPtName =NULL)

                Copies the plot point using the following arguments:

Argument Description
fromPt Plot point template to copy.
toPt New parent point.
pPlot Parent plot heirarchy point.
nAlias New alias name.
nPtName New point name.
           int configPlotDeletePoint (char *nm)
                Deletes the plot point specified in nm.

           int configPlotEndBranchCopy ()
                End branch copy of an RTAP branch containing plot points.

           int configPlotMoveAbsolute (char *fromPt, char *toPt, char *pPlot
           =NULL)
                Moves a plot point using the following arguments:

Argument Description
fromPt Plot point to move.
toPt New parent point.
pPlot Parent plot heirarchy point.
           int configPtClass (unsigned int pClass, char *nm =NULL)
                Configures the point class to pClass of the point specified
                in nm. If nm is not specified, the current working point is
                used.

           int configPtName (char *pName, char *nm =NULL)
                Configures the point name to pName of the point specified in
                nm. If nm is not specified, the current working point is
                used.

           int configRecElCnt (unsigned int rCnt, char *nm =NULL)
                Configures the record element count to rCnt for the
                attribute specified in nm. If nm is not specified, the
                current working point's attribute is used.

           int configRecElCntCheck (unsigned int rCnt, char *nm =NULL)
                Configures the record element count to rCnt for the
                attribute specified in nm. If nm is not specified, the
                current working point's attribute is used. This method uses the new call
                in RTAP 7.0+; which checks to ensure that there are no CE dependencies
                before resizing the vector/table.

           int configResidence (int res, char *nm =NULL)
                Configures the residence to res (either rtRAM_RESIDENT or
                rtDISK_RESIDENT) for the point specified in nm. If nm is not
                specified, the current working point is used.

           int controlAddUsage (usage, char *nm =NULL)
                Adds usage flags to the point specified in nm. If nm is not
                specified, the current working point is used. usage is an
                array reference containing hash references or a single hash
		reference if only one usage flag is to be added. The hash
                reference(s) should contain the following values:

Hash Name Description
ain AIN number for usage flag.
usageType Usage number.
           int controlCeOper (int ceOper, char *nm =NULL)
                Sets the CE operation indicator to ceOper (either
                rtCE_DISABLED, rtCE_DISABLED_NORUN, rtCE_ENABLED, or
                rtCE_ENABLED_OPT_A) for the point specified in nm. If nm is
                not specified, the current working point is used.

           int controlDelUsage (usage, char *nm =NULL)
                Deletes usage flags for the point specified in nm. If nm is
                not specified, the current working point is used. usage is
                an array reference containing hash references or a single hash
                reference if only one usage flag is to be deleted (see
                controlAddUsage above for the hash reference values).

           int controlDisableSnaps ()
                Disables database snapshotting.

           int controlEnableSnaps ()
                Enables database snapshotting.

           int controlLockPt (time, nms)
                Locks all points specified in nms. time is a hash reference
                that contains the following values:

Hash Name Description
tv_sec Number of seconds for lock.
tv_usec Number of micro-seconds for lock.
                If the default time of three seconds is desired, an
                undefined value can be passed as time.

                nms is either an array reference containing point aliases of
                the point(s) for the lock or a single character alias. If
                nms is not specified, the current working point is used.

           int controlRelCfi ()
                Releases the configuration interlock.

           int controlReusePlins (plins)
                Releases one or more PLINs for reuse. plins is an array
                reference containing the list of PLINs.

           int controlRunCe (nms =NULL)
                Runs the calculation engine (CE) on the points listed in
                nms. nms is either an array reference containing point
                aliases or a single character alias. If nms is not
                specified, the current working point is used.

           int controlSetCfi (int attempts =1, int timeout =1000)
                Attempts to set the configuration interlock. attempts
                specifies how many re-tries to perform if unable to set the
                configuration interlock, and timeout specifies the number of
                milli-seconds between attempts.

           int controlSetCwp (char *nm)
                Sets the current working point to nm. If nm contains
                all digits (0-9), then it will be used as a PLIN number.

           int controlSetRdrCfi (int attempts =1, int timeout =1000)
                Attempts to set the reader configuration interlock. attempts
                specifies how many re-tries to perform if unable to set the
                configuration interlock, and timeout specifies the number of
                milli-seconds between attempts.

           int controlSetUsage (usage, char *nm)
                Sets the usage flags for point nm. If nm is not specified,
                the current working point is used. usage is an array
                reference containing hash references or a single hash
                reference if only one usage flag is to be set (see 
		controlAddUsage above for the hash reference values).

           int controlSnapshot (int snap =rtCURRENT_SNAP)
                Forces a database snapshot using the mode specified in snap
                (either rtCURRENT_SNAP or rtFORE_GND_SNAP).

           int controlUnlockPt (nms)
                Unlocks the points specified in nms. nms is either an array
                reference containing point aliases or a single character
                alias. If nms is not specified, the current working point is
                used.

           int controlXferLock (xfer, nms)
                Transfer all or some of it's locked points to a second
                process. xfer is a hash reference with the following values:

Hash Name Description
procNum RTAP process number to transfer to.
lockTime.tv_sec New lock seconds.
lockTime.tv_usec New lock micro-seconds.
                nms is either an array reference containing point aliases or
                a single character alias. If nms is not specified, the
                current working point is used.

           int detachEvent (int enable, ev)
                Detachs a database event. enable is the event enable flag
                (see attachEvent above for values). ev is the hash reference
                returned from the attachEvent call.

           void getCurPt ()
                Returns the current working point if successful; otherwise
                returns undefined.

           void initializePtTypes ()
                Initializes the loading of point types and point groups. This
                function is automatically called when either tnCreatePtTypeNm,
                tnCreatePtTypeCls, or tnCreatePtGroup methods are called.
                This function will create a hash called POINT_TYPES that contains
                the following:

Hash Name Description
names This is another hash reference that allows access via the point type's name as the key and the point type's class as the value.
classes This is another hash reference that allows access via the point type's class as the key and the point type's name as the value.
                Some examples:

                    # Initialize our point types and point groups.
                    initializePtTypes ();

                    # Get the class for point type name 'Analog Input'
                    my $ptClass = $CRtapDb::POINT_TYPES{'names'}->{'Analog Input'};

                    # Get the name for point type class 30000.
                    my $ptTypeNm = $CRtapDb::POINT_TYPES{'classes'}->{'30000'};

                    # Print out out list of point groups.
                    foreach my $ptGrp (@CRtapDb::POINT_GROUPS) {
                        print "$ptGrp\n";
                    }

                This function will also create an array called POINT_GROUPS
                that contains a list of point group names. Note that the POINT_TYPES
                and POINT_GROUPS variables are part of the class being used.

           void matchPoints (int returnType, char *test, scope =NULL, char *env
           =NULL)
                Returns an array reference list of points that match a
                certain criteria if successful; otherwise returns an
                undefined value using the following arguments:

Argument Description
returnType Specifies the type of return values as either rtDB_PT_LIST_PLINS or rtDB_PT_LIST_ALIAS.
test Criteria to match on (see below).
scope Hash reference (see below).
env RTAP environment name.
                The test criteria to match on uses the following format:

                 '(' "and"               <expr> [<expr>...]              ')'
                 '(' "or"                <expr> [<expr>...]              ')'
                 '(' "not"               <expr>                          ')'
                 '(' "classes"           <integer> [<integer>...]        ')'
                 '(' "categories"        <integer>                       ')'
                 '(' "name"              '"'<regexp>'"'                  ')'
                 '(' "alias"             '"'<regexp>'"'                  ')'
                 '(' <attribute> [<op> <attribute>]                      ')'
                 '(' <attribute> [<op> '('<deType>')' '"'<string>'"']    ')'

                where:
                        <expr> = one of the above
                        <integer> = integer
                        <regexp> = regular expression (see regexp(5))
                        <op> = '<', '<=', '>', '>=', '!=', '=='
                        <deType> = rtLOGICAL, rtUINT8, etc.
                        <string> = string value convertable to a value using rtStrToType(3).
                        <attribute> = attribute name of the form '[.attribute]'

                        anything enclosed in single quotes must be entered as is
                        anything enclosed in square brackets are optional

                Some examples:

                        # matches all aliases
                        '(alias ".*")'

                        # match only aliases that start with "UIT"
                        '(alias "^UIT.*")'

                        # not class 1000, 1015, or 1020
                        '(not (classes 1000 1015 1020))'

                        # class 1015 points
                        '(classes 1015)'

                        # class 1015 and 1011 points
                        '(classes 1015 1011)'

                        # class 1015 and aliases that start with "UIT"
                        '(and (classes 1015) (alias "^UIT.*"))'

                        # class 1000 or aliases that start with "WELL"
                        '(or (classes 1000) (alias "^WELL.*"))'

                        # points with a ".raw value" greater than 10
                        '([.raw value] > (rtUINT32) "10")'

                        # points with a ".raw value" greater than or equal to
                        # "ABC.setpoint value"
                        '([.raw value] >= [ABC.setpoint value])'

                        # points with a ".raw value" less than "1.234"
                        '([.raw value] < (rtDOUBLE) "1.234")'
                        # points with a ".output value" equal to one
                        '([.output value] == (rtLOGICAL) "1")'

                        # points with a readable ".send output" attribute
                        '([.send output])'

                scope is a hash reference with the following values:

Hash Name Description
scopeType Specifies which points in the sub-tree are to be checked (rtDB_MATCH_SUBTREE, rtDB_MATCH_NTH_LEVEL, rtDB_MATCH_TO_NTH_LEVEL, or rtDB_MATCH_PAST_NTH_LEVEL).
level Specifies the level in the sub-tree. If this value is not specified, a default value of zero will be used.
subRoot Specifies the alias of the sub-root to search. If this value is not specified, the current working point will be used.
           void queryAlias (char *nm =NULL)
                Returns the alias name of the specified point nm if
                successful; otherwise returns undefined. If nm contains
                all digits (0-9), then it will be used as a PLIN number.
                If nm is not specified, the current working point
                will be used.

           void queryAttrAccess (char *nm =NULL)
                Returns a hash reference for the specified point nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point is used. The hash
                reference contains the following values:

Hash Name Description
readAccess Read access.
writeAccess Write access.
           void queryAttrCnt (char *nm =NULL)
                Returns the attribute count for the specified point nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point is used.

           void queryAttrName (char *nm =NULL)
                Returns the attribute name for the specified attribute nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point's attribute is used.

           void queryAttrQuality (char *nm =NULL)
                Returns the attribute quality (rtATTR_OK, rtATTR_DISABLED,
                rtATTR_ERROR, or rtATTR_SUSPECT) for the specified attribute
                nm. If nm is not specified, the current working point's
                attribute will be used.

           void queryAttribute (char *nm =NULL)
                Returns a hash reference for the attribute specified in nm
                if successful; otherwise returns undefined. If nm is not
                specified, the current working point's attribute is used.
                The hash reference returned contains the following values:

Hash Name Description
type Attribute type (rtSCALAR, rtVECTOR, or rtTABLE).
fieldCnt Field count.
recElCnt Record/element count.
recordSize Record size.
recsUsed Number of records used.
           int queryCategories (char *nm =NULL)
                Returns the categories for the point specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working is used.

           SV * queryCategNames ()
                Returns an array reference containing all of the category names if
                successful; otherwise returns undefined.

           SV * queryCeDepRef ()
                Returns an array reference containing a list of the CE
                dependency PLIN references.

           SV * queryCeDepUpd ()
                Returns an array reference containing a list of the CE
                dependency PLIN updates.

           int queryCeOper ()
                Returns the CE operation indicator (either rtCE_DISABLED,
                rtCE_ENABLED, rtCE_ENABLED_OPT_A, or rtCE_DISABLED_NORUN) if
                successful; otherwise returns undefined.

           void queryConnInfo ()
                Returns a hash reference if successful; otherwise returns
                undefined. The hash reference contains the following values:

Hash Name Description
currPoint PLIN of current working point.
groups Group security.
security Current security as either rtAPPLICATION_SECURITY or rtADMINISTRATION_SECURITY.
ptReadCats Read categories.
ptWriteCats Write categories.
           void queryDefinition (char *nm =NULL)
                Returns the definition of the attribute specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point's attribute is used.

           void queryExprOrder (char *nm =NULL)
                Returns the CE expression order (rtNATURAL or
                rtUSER_DEFINED) for the attribute specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point's attribute is used.

           void queryFirstChild (char *nm =NULL)
                Returns the PLIN number of the first child for the point
                specified in nm if successful; otherwise returns undefined.
                If nm is not specified, the current working point is used.

           void queryGroups (char *nm =NULL)
                Returns a hash reference of the groups for the attribute
                specified in nm if successful; otherwise returns undefined.
                If nm is not specified, the current working point's
                attribute is used. The hash reference returned contains the
                following values:

Hash Name Description
readGroups Read groups.
writeGroups Write groups.
           void queryNextSibling (char *nm =NULL)
                Returns the PLIN number of the next sibling for the point
                specified in nm if successful; otherwise returns undefined.
                If nm is not specified, the current working point is used.

           void queryParent (char *nm =NULL)
                Returns the PLIN number of the parent for the point
                specified in nm if successful; otherwise returns undefined.
                If nm is not specified, the current working point is used.

           void queryPtClass (char *nm =NULL)
                Returns the point class for the point specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point is used.

           void queryPtName (char *nm =NULL)
                Returns the point name for the point specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point is used.

           void queryResidence (char *nm =NULL)
                Returns the residence for the point specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point is used.

           void querySpace ()
                Returns a hash reference containing the following values:

Hash Name Description
headers Hash reference (see below).
ramValues Hash reference (see below).
diskValues Hash reference (see below).
points Hash reference (see below).
types Hash reference (see below).
                Each of the hash references above contain the following
                values:

Hash Name Description
maxUsed Maximum used space.
totalSize Total size of space.
           void querySymAbs (char *nm =NULL)
                Returns the symbolic absolute address for the address
                specified in nm if successful; otherwise returns undefined.
                If nm is not specified, the current working point is used.

           void querySymAlias (char *nm =NULL)
                Returns the symbolic alias for the address specified in nm
                if successful; otherwise returns undefined. If nm is not
                specified, the current working point is used.

           void querySymRel (char *nm =NULL)
                Returns the symbolic relative address for the address
                specified in nm if successful; otherwise returns undefined.
                If nm is not specified, the current working point is used.

           void queryUsage (char *nm =NULL)
                Returns a hash reference for the point specified in nmnm is not specified,
                the current working point will be used. The hash reference returned
                contains the following values:

Hash Name Description
ain Attribute Index Number.
usageType Usage number for the specified AIN.
           void queryUsageNames ()
                Returns an array reference containing all of the usage names if
                successful; otherwise returns undefined. Note that this
                method is only available with RTAP 7.0+.

           void readAttr (char *nm =NULL)
                Returns the value for the address specified in nm if
                successful; otherwise returns undefined. If nm is not
                specified, the current working point is used. The value
                returned is dependant upon the attribute type. If the
                attribute type is a scalar, the value is returned as a
                scalar. If the attribute type is a vector, the value
                returned is an array reference. If the attribute type is a
                table, the value returned is an array reference to hash
                references. The array reference for the table represents
                each record requested for. The hash reference will have
                values for each field in the the record. The hash names used
                to access each field is either the field name or the field
                number.

           int setIgnoreCeErrors ()
                Sets the CE ignore error flag.

           void toSymbolicAin (int ain)
                Returns a symbolic name corresponding to the givin AIN ain
                if successful; otherwise returns undefined.

           void toSymbolicDbXref (xref)
                Returns a symbolic name corresponding to the given database
                cross reference hash reference xref if successful; otherwise
                returns undefined.

           void toSymbolicPlin (int plin)
                Returns a symbolic name corresponding to the given PLIN plin
                if successful; otherwise returns undefined.

           int tnCreatePtGroup (char * ptGroupName, subStrs, rtuStr, char *nm =NULL)
                Creates the point group in the database specified by the point
                group name ptGroupName. The subStrs parameter can
                be either an array reference containing a list of sub-string
                substitution values, or a single string value if only one
                sub-string substitution value is required as part of the point
                group. The rtuStr is the RTU scan device alias. If this is
                not required as part of the point type, use undef as the
                argument value. The parent of the new point group can be
                specified by the nm argument. If not specified, the current
                working point will be used. Returns rtSUCCESS if successful;
                otherwise returns rtFAILED.

           int tnCreatePtTypeCls (unsigned short ptTypeClass, char *aliasName,
               char *ptName, char *nm =NULL)

                Creates a point in the database given the point type class
                ptTypeClass. The new point will have an alias name as specified by
                aliasName, and a point name specified by ptName. The parent
                of the new point can be specified by the nm argument. If not
                specified, the current working point will be used. Returns rtSUCCESS
                if successful; otherwise returns rtFAILED.

           int tnCreatePtTypeNm (char *ptTypeName, char *aliasName, char *ptName,
               char *nm =NULL)

                Creates a point in the database given the point type name
                ptTypeName. The new point will have an alias name as specified by
                aliasName, and a point name specified by ptName. The parent
                of the new point can be specified by the nm argument. If not
                specified, the current working point will be used. Returns rtSUCCESS
                if successful; otherwise returns rtFAILED.

           int unsetIgnoreCeErrors ()
                Unsets the CE ignore error flag.

           int writeAttr (val, char *nm =NULL)
                Writes the specified value(s) val to the address specified
                in nm. The value returned is either rtSUCCESS or rtFAILED.
                The value to write val depends on the attribute type being
                written to. If the attribute type is a scalar, val should be
                a scalar value. If the attribute type is a vector, val
                should be an array reference; unless only a single value is
                to written in which case val should be a scalar. If the
                attribute type is a table, val should be an array reference
                to hash references (see description in readAttr for hash
                reference values); unless only a single value is to be
                written in which case val should be a scalar value.

CRtapDbSymbols

      The following symbols can be accessed by prefixing it with the class
      name and two colons (eg. CRtapDb::rtNATURAL). Note that all symbols
      defined for the CRtap are also available.

CATEGORY_0 CATEGORY_1 CATEGORY_10
CATEGORY_11 CATEGORY_12 CATEGORY_13
CATEGORY_14 CATEGORY_15 CATEGORY_16
CATEGORY_17 CATEGORY_18 CATEGORY_19
CATEGORY_2 CATEGORY_20 CATEGORY_21
CATEGORY_22 CATEGORY_23 CATEGORY_24
CATEGORY_25 CATEGORY_26 CATEGORY_27
CATEGORY_28 CATEGORY_29 CATEGORY_3
CATEGORY_30 CATEGORY_31 CATEGORY_4
CATEGORY_5 CATEGORY_6 CATEGORY_7
CATEGORY_8 CATEGORY_9 CATEGORY_ALL
GROUP_0 GROUP_1 GROUP_2
GROUP_3 GROUP_ALL rtADMINISTRATION_SECURITY
rtAPPLICATION_SECURITY rtCE_DISABLED rtCE_DISABLED_NORUN
rtCE_ENABLED rtCE_ENABLED_OPT_A rtCURRENT_SNAP
rtDB_ANY_WRITE rtDB_EQUAL rtDB_GREATER
rtDB_GREATER_OR_EQUAL rtDB_LESS rtDB_LESS_OR_EQUAL
rtDB_MATCH_NTH_LEVEL rtDB_MATCH_PAST_NTH_LEVEL rtDB_MATCH_SUBTREE
rtDB_MATCH_TO_NTH_LEVEL rtDB_NOT_EQUAL rtDB_PT_LIST_ALIAS
rtDB_PT_LIST_PLIN rtDISK_RESIDENT rtFORE_GND_SNAP
rtNATURAL rtRAM_RESIDENT rtUSER_DEFINED
rtDIR_INVALID rtDIR_PLIN rtDIR_AIN
rtDIR_REC_EL rtDIR_FIELD
POINT_TYPES POINT_GROUPS

CRtapSs Class

      The CRtapSs class provides access into the RTAP scan system. This
      class inherits all of the methods available from the CRtapDb and CRtap
      classes.

      The new method is used to create an instance of this class. This
      method takes the following hash values for it's arguments:

           env  Specifies the RTAP environment to attach to. If this value
                is not specified, the contents of the environment variable
                RTAPENV will be used.

           argv0
                Specifies the RTAP process name to register as. This value
                must be specified.

           dbenv
                Specifies the RTAP database environment to open. If this
                value is not specified, the contents of the environment
                variables RTAPDB or RTAPENV will be used.

Example:

      use CRtapSs;

      $env = "jck";

      # Remove leading path info from our name.
      $nm = $0;
      $nm =~ s!.*/!!;

      $rtapSs = CRtapSs->new ('argv0' => "$nm", 'env' => "$env");
      if (! defined $rtapSs) {
          print "Failed to either register with RTAP environment;\n";
          print "or open scan system connection.\n";
          exit (-1);
      }


      The following describes the methods available for this class:


           int getScanConfigPlin ()
                Returns the scan config PLIN number if successful; otherwise
                rtFAILED.

           int querySsState ()
                Returns the scan system state if successful; otherwise
                rtFAILED.

           int queryScanTaskState (char *nm)
                Returns the scan task state for nm if successful; otherwise
                rtFAILED.

           int cntrlDisableSS (int respond =rtSCAN_RESPOND)
                Disables the scan system. respond indicates whether the call
                is synchronous or asynchronous. Returns either rtSUCCESS or
                rtFAILED.

           int cntrlEnableSS (int respond =rtSCAN_RESPOND)
                Enables the scan system. respond indicates whether the call
                is synchronous or asynchronous. Returns either rtSUCCESS or
                rtFAILED.

           void cntrlDisableCp (nms =NULL, int respond =rtSCAN_RESPOND)
                Disables communication port(s) specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlEnableCp (nms =NULL, int respond =rtSCAN_RESPOND)
                Enables communication port(s) specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlDisableSdSi (nms =NULL, int respond =rtSCAN_RESPOND)
                Disables scan device scan input(s) specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlEnableSdSi (nms =NULL, int respond =rtSCAN_RESPOND)
                Enables scan device scan input(s) specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlDisableSdSo (nms =NULL, int respond =rtSCAN_RESPOND)
                Disables scan device scan output(s) specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlEnableSdSo (nms =NULL, int respond =rtSCAN_RESPOND)
                Enables scan device scan output(s) specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlDisableSdSiPt (nms =NULL, int respond =rtSCAN_RESPOND)
                Disables scan device scan input point(s) specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlEnableSdSiPt (nms =NULL, int respond =rtSCAN_RESPOND)
                Enables scan device scan input point(s) specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlDisableSdSoPt (nms =NULL, int respond =rtSCAN_RESPOND)
                Disables scan device scan output point(s) specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlEnableSdSoPt (nms =NULL, int respond =rtSCAN_RESPOND)
                Enables scan device scan output point(s) specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlCommPortMode (int mode, nms =NULL, int respond
           =rtSCAN_RESPOND)
                Sets the communication port mode to mode (either
                rtPOLLED_PRBX, rtPOLLED_PRBX_SRBX or rtSRBX) for the points
                specified in nms. respond indicates whether the call is
                synchronous or asynchronous. nms is either a single address
                or an array reference to multiple addresses. If nms is not
                specified, the current working point will be used. The
                return value will a scalar value if a single address was
                specified; otherwise an array reference for each address
                will be returned.

           void cntrlPollPeriod (int pType, int pSec, nms, int respond
           =rtSCAN_RESPOND)
                Sets the poll type specified in pType to the poll period
                (seconds) specified in pSec for the points specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlPrbxPeriod (int pType, int pSec, nms, int respond
           =rtSCAN_RESPOND)
                Sets the PRBX type specified in pType to the PRBX period
                (seconds) specified in pSec for the points specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlPollPeriodMs (int pType, int pSec, int pMSec, nms, int
           respond =rtSCAN_RESPOND)
                Sets the poll type specified in pType to the poll period
                (seconds) specified in pSec and pMSec (milli-seconds) for
                the points specified in nms. respond indicates whether the
                call is synchronous or asynchronous. nms is either a single
                address or an array reference to multiple addresses. If nms
                is not specified, the current working point will be used.
                The return value will a scalar value if a single address was
                specified; otherwise an array reference for each address
                will be returned.

           void cntrlPrbxPeriodMs (int pType, int pSec, int pMSec, nms, int
           respond =rtSCAN_RESPOND)
                Sets the PRBX type specified in pType to the PRBX period
                (seconds) specified in pSec and pMSec (milli-seconds) for
                the points specified in nms. respond indicates whether the
                call is synchronous or asynchronous. nms is either a single
                address or an array reference to multiple addresses. If nms
                is not specified, the current working point will be used.
                The return value will a scalar value if a single address was
                specified; otherwise an array reference for each address
                will be returned.

           void cntrlPollType (unsigned int pType, nms, int respond
           =rtSCAN_RESPOND)
                Sets the poll type specified in pType for the scan records
                specified in nms. respond indicates whether the call is
                synchronous or asynchronous. nms is either a single address
                or an array reference to multiple addresses. If nms is not
                specified, the current working point will be used. The
                return value will a scalar value if a single address was
                specified; otherwise an array reference for each address
                will be returned.

           void cntrlPrbxType (unsigned int pType, nms, int respond
           =rtSCAN_RESPOND)
                Sets the PRBX type specified in pType for the scan devices
                specified in nms. respond indicates whether the call is
                synchronous or asynchronous. nms is either a single address
                or an array reference to multiple addresses. If nms is not
                specified, the current working point will be used. The
                return value will a scalar value if a single address was
                specified; otherwise an array reference for each address
                will be returned.

           void cntrlForcePollType (unsigned int pType, nms, int respond
           =rtSCAN_RESPOND)
                Forces the scan system to execute a poll for the poll type
                specified in pType for the addresses specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlForcePrbxType (unsigned int pType, nms, int respond
           =rtSCAN_RESPOND)
                Forces the scan system to execute a PRBX for the PRBX type
                specified in pType for the addresses specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlForcePoll (nms =NULL, int respond =rtSCAN_RESPOND)
                Forces a poll on the addresses specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlForcePrbx (nms =NULL, int respond =rtSCAN_RESPOND)
                Forces a PRBX on the addresses specified in nms. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlColdRstDevice (nms =NULL, int respond =rtSCAN_RESPOND)
                Forces a cold restart on the addresses specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlPriorityPoll (nms =NULL, int respond =rtSCAN_RESPOND)
                Forces a priority poll on the addresses specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlPriorityPollType (unsigned int pType, nms, int respond
           =rtSCAN_RESPOND)
                Forces the scan system to execute a priority poll for the
                poll type specified in pType for the addresses specified in
                nms. respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlWarmRstDevice (nms =NULL, int respond =rtSCAN_RESPOND)
                Forces a warm restart on the addresses specified in nms.
                respond indicates whether the call is synchronous or
                asynchronous. nms is either a single address or an array
                reference to multiple addresses. If nms is not specified,
                the current working point will be used. The return value
                will a scalar value if a single address was specified;
                otherwise an array reference for each address will be
                returned.

           void cntrlSnap (int type, nms, int respond =rtSCAN_RESPOND)
                Forces the scan system to send appropriate commands to cause
                the device to execute a snap for the addresses specified in
                nms. type is either rtSCAN_SYNC or rtSCAN_ASYNC. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void cntrlSnapWithVerify (int type, nms, int respond =rtSCAN_RESPOND)
                Forces the scan system to send appropriate commands to cause
                the device to execute a snap with verify for the addresses
                specified in nms. type is either rtSCAN_SYNC or
                rtSCAN_ASYNC. respond indicates whether the call is
                synchronous or asynchronous. nms is either a single address
                or an array reference to multiple addresses. If nms is not
                specified, the current working point will be used. The
                return value will a scalar value if a single address was
                specified; otherwise an array reference for each address
                will be returned.

           void cntrlSetTime (int type, nms, int respond =rtSCAN_RESPOND)
                Forces the scan system to send appropriate commands to set
                the current time in the devices, for the addresses specified
                in nms. type is either rtSCAN_SYNC or rtSCAN_ASYNC. respond
                indicates whether the call is synchronous or asynchronous.
                nms is either a single address or an array reference to
                multiple addresses. If nms is not specified, the current
                working point will be used. The return value will a scalar
                value if a single address was specified; otherwise an array
                reference for each address will be returned.

           void readSsma (char *nm)
                Returns a hash reference for the SSMA value(s) specified by
                the scan input record nm. The returned hash reference
                contains the following values:

Hash Name Description
offset SSMA offset for the specified scan input record.
failCnt Fail count for the specified scan input record.
ssmaQlty SSMA quality (either rtSSMA_NO_DATA, rtSSMA_OK, rtSSMA_FAILED, rtSSMA_DISABLED) for the specified scan input record.
dataBuffer Data values as either a scalar value or an array reference for the specified scan input record.
stBuffer Scan task buffer values as a bytes string for the specified scan input record. This value is only available if the scan task buffer size is greater than zero.
           void readSsmaWithLock (char *nm)
                Returns a hash reference for the SSMA value(s) specified by
                the scan input record nm with lock (see readSsma for
                description of returned hash reference).

           int sizeSsma ()
                Returns the current SSMA size.

           int spareSsma ()
                Returns the current SSMA spare size.

           int writeSsma (unsigned int offset, int ssmaQlty, int failCnt, int deType,
               val, stBufferVal =NULL)

                Writes the specified value(s) val into SSMA at offset with
                ssmaQlty quality (should be either rtSSMA_NO_DATA, rtSSMA_OK,
                or rtSSMA_FAILED), failCnt fail count and data element type
                of deType. Note that the data element type should match what
                is expected at the SSMA offset (i.e. there is no coersion to
                the expected data element type). The scan task buffer value,
                stBufferVal, is currently not supported and should not be
                specified.

           int writeToScanSys (char *addr, int deType, val, int commType =rtSCAN_SYNC)
                Writes the specified value(s) val of data element type deType,
                to the scan system address specified in addr. The address
                should be specified to the scan output record level. The
                communication type commType should be specified as either
                rtSCAN_SYNC or rtSCAN_ASYNC.

CRtapSsSymbols

      The following symbols can be accessed by prefixing it with the class
      name and two colons (eg. CRtapSs::rtSCAN_ENABLED). Note that all
      symbols defined for the CRtapDb and CRtap classes are also available.

rtPOLLED_PRBX rtPOLLED_PRBX_SRBX rtSCAN_ASYNC
rtSCAN_DISABLED rtSCAN_ENABLED rtSCAN_FAILED
rtSCAN_NO_RESPOND rtSCAN_RESPOND rtSCAN_SYNC
rtSCAN_UNKNOWN rtSRBX rtSSMA_DISABLED
rtSSMA_NO_DATA rtSSMA_OK rtSSMA_FAILED

CRtapDhClass

      The CRtapDh class provides access into the RTAP data historian. This
      class inherits all of the methods available from the CRtapDb and CRtap
      classes.

      All of the control and config methods return either rtSUCCESS or
      rtFAILED.

      All of the query methods return a value if the call was successful
      otherwise undefined is returned.

      The new method is used to create an instance of this class. This
      method takes the following hash values for it's arguments:


           env  Specifies the RTAP environment to attach to. If this value
                is not specified, the contents of the environment variable
                RTAPENV will be used.

           argv0
                Specifies the RTAP process name to register as. This value
                must be specified.

           dhenv
                Specifies the RTAP data historian environment to open. If
                this value is not specified, the contents of the environment
                variables RTAPDH or RTAPENV will be used.

           table
                Specifies the data historian table to open. This value must
                be specified.

Example:

      use CRtapDh;

      $env = "jck";
      $table = "HISTORY 1";

      # Remove leading path info from our name.
      $nm = $0;
      $nm =~ s!.*/!!;

      $rtapDh = CRtapDh->new ('argv0' => "$nm", 'env' => "$env",
                              'table' => "$table");
      if (! defined $rtapDh) {
          print "Failed to either register with RTAP environment;\n";
          print "or open data historian table.\n";
          exit (-1);
      }


      The following describes the methods available for this class:


           int configAddTablePoint (char *ptName, char *alias, int recCnt,
                rItems, char *par ="historian config", int res
                =rtDISK_RESIDENT, uStats =NULL)

                Adds a new historian table with the following arguments:

Argument Description
ptName New historian table's point name.
alias New historian table's alias name.
recCnt Number of records.
rItems An array reference of hash references for the record items (see below).
par Parent point.
res Table residence (either rtRAM_RESIDENT or rtDISK_RESIDENT).
uStats An array reference of hash references for the user statistics (see below).
                The rItems and uStats arguments are array references to hash
                references. The hash references should contain the following
                values:

Hash Name Description
name Field name.
deType Field data element type (see CRtap Symbols above for values).
           int configAutoReArm (int setup, int state)
                Configures the auto re-arm state specified in state (either
                rtDH_DISABLE_STATE or rtDH_ENABLE_STATE) for the setup
                specified in setup (either 1 or 2).

           int configCopyAbsPoint (char *nParent, char *nAlias, char *nPtName
           =NULL)
                Copies the current historian table using the following
                arguments:

Argument Description
nParent Alias of new parent.
nAlias New alias name.
nPtName New point name.
           int configCopyRelPoint (char *nParent, char *nAlias, char *nPtName
           =NULL)
                Copies the current historian table (see configCopyAbsPoint
                above for a description of arguments).

           int configDeleteTablePoint ()
                Deletes the current historian table.

           int configOutputTrigger (char *tAddr, int tState =rtDH_DISABLE_STATE)
                Configures the current historian table with the output
                trigger address specified in tAddr and the trigger state
                specified in tState (either rtDH_DISABLE_STATE or
                rtDH_ENABLE_STATE).

           int configRecordData (rData)
                Configures the current historian table with the record data
                specified in rData. rData is an array reference containing
                alias names for each of the record data. If an array value
                is missing it is assumed to be blank. Note that this call
                will replace all of the record data, therefore if an item
                was configured originally and not specified in the array, it
                will be removed from the configuration.

           int configSetup (int sNum, setup)
                Configures the current historian table's setup number
                specified in sNum (either 1 or 2) with the values specified
                in setup. setup is a hash reference with the following
                values:

Hash Name Description
setupEnable Setup enable status as either rtDH_DISABLE_STATE or rtDH_ENABLE_STATE.
startCondition Start condition as either rtDH_SETUP_START_ARMED, rtDH_SETUP_START_TIMED, rtDH_SETUP_START_EVENT.
triggerStates Trigger states as an OR'ed combination of rtDH_EV_TRIG_ALL, rtDH_EV_TRIG_ADDR, rtDH_EV_LESS_THAN_START, rtDH_EV_EQUAL_TO_START, rtDH_EV_GREATER_THAN_START, rtDH_EV_LESS_THAN_STOP, rtDH_EV_EQUAL_TO_STOP, rtDH_EV_GREATER_THAN_SOPT.
startTime A hash reference for the start time (see below). This value is only required if the start condition is timed.
startTrigAddr The database address for the start trigger. This value is only required if the start condition is event.
sampleType The sample type as either rtDH_SAMPLE_DAYS, rtDH_SAMPLE_HOURS, rtDH_SAMPLE_MINUTES, or rtDH_SAMPLE_SECONDS.
samplePeriod The sample period value.
stopCondition The stop condition as either rtDH_STOP_NONE, rtDH_STOP_TIMED, rtDH_STOP_EVENT, or rtDH_STOP_COUNT.
stopTrigAddr The database address for the stop trigger. This value is only required if the stop condition is event.
stopType The stop type as either rtDH_STOP_DAYS, rtDH_STOP_HOURS, rtDH_STOP_MINUTES or rtDH_STOP_SECONDS. This value is only required if the stop condition is timed.
stopPeriod The stop period value. This value is only required if the stop condition is timed.
stopCount The stop count value. This value is only required if the stop condition is count.
autoReArm The auto re-arm value as either rtDH_DISABLE_STATE or rtDH_ENABLE_STATE.
                The startTime hash reference contains the following values:

Hash Name Description
year Year
month Month
day Day
hour Hour
minute Minute
second Second
usec Micro-seconds
           int configStatistics (unsigned int avgTime, unsigned int avgCount, int
           state, int statType)
                Configures the statistics on the current historian table
                with the following arguments:

Argument Description
avgTime Averaging number.
avgCount Averaging sample count.
state An OR'ed combination of rtDH_STATS_MIN_MAX, rtDH_STATS_CNT_AVG or rtDH_STATS_TIME_AVG
statType Time units for avgTime value as either rtDH_STAT_DAYS, rtDH_STAT_HOURS, rtDH_STAT_MINUTES, rtDH_STAT_SECONDS.
           int configTableName (char *nm)
                Configures the current historian table's name to nm.

           int configTableResidence (int res)
                Configures the current historian table's residence to res
                (either rtRAM_RESIDENT or rtDISK_RESIDENT).

           int configTableSize (int recs)
                Configures the current historian table's record count to
                recs.

           int controlArmTable ()
                Arms the current historian table.

           int controlAutoArmDisable ()
                Disables auto-arm on the current historian table.

           int controlAutoArmEnable ()
                Enables auto-arm on the current historian table.

           int controlClearTable ()
                Clears the current historian table.

           int controlDatawrapDisable ()
                Disables data-wrap on the current historian table.

           int controlDatawrapEnable ()
                Enables data-wrap on the current historian table.

           int controlDisableTable ()
                Disables the current historian table.

           int controlDisarmTable ()
                Disarms the current historian table.

           int controlEnableTable ()
                Enables the current historian table.

           int controlOneshotTable ()
                Causes a one-shot of the current historian table.

           int openDh (char *table, char *env =NULL)
                Opens the historian table specified in table and RTAP
                environment env.

           void queryAutoArm ()
                Returns the auto-arm state for the current historian table
                if successful.

           void queryAutoReArm (int setup =1)
                Returns the auto re-arm status for the specified setup setup
                if successful.

           void queryDataWrap ()
                Returns the data wrap status for the current historian table
                if successful.

           void queryOutputTrigger ()
                Returns a hash reference for the output trigger for the
                current historian table if successful. The returned hash
                reference contains the following values:

Hash Name Description
trigAddr Database address of trigger.
trigState Trigger state as either rtDH_DISABLE_STATE or rtDH_ENABLE_STATE.
           void queryRecordData ()
                Returns an array reference containing the database addresses
                for the record data if successful.

           void querySetup (int setup)
                Returns a hash reference containing the setup information
                for the specified setup setup (see configSetup above for a
                description of the returned hash reference values).

           void querySetupNum ()
                Returns the number of setups for the current historian table
                if successful.

           void querySetupStatus (int setup)
                Returns the setup status for the specified setup number
                setup. If setup is zero, an array reference will be returned
                containing the status for all setups. The returned value(s)
                are either rtDH_TABLE_DISABLED, rtDH_TABLE_IDLE,
                rtDH_TABLE_ARMED, or rtDH_TABLE_RUNNING.

           void querySourceCount ()
                Returns the source count for the current historian table if
                successful.

           void queryStatistics ()
                Returns a hash reference for the current historian table's
                statistics if successful. The returned hash reference
                contains the following values:

Hash Name Description
avgTime Averaging number.
avgCount Averaging sample count.
state An OR'ed combination of rtDH_STATS_MIN_MAX, rtDH_STATS_CNT_AVG or rtDH_STATS_TIME_AVG
statType Time units for avgTime value as either rtDH_STAT_DAYS, rtDH_STAT_HOURS, rtDH_STAT_MINUTES, rtDH_STAT_SECONDS.
           void queryTableConfig ()
                Returns a hash reference for the current historian table's
                table configuration if successful. The returned hash
                reference contains the following values:

Hash Name Description
tableState Table state hash reference (see queryTableState below for a description of the hash values).
statistics Table statistics hash reference (see queryStatistics above for a description of the hash values).
outputTrigger Table output trigger hash reference (see queryOutputTrigger above for a description of the hash values).
autoArm Auto-arm value as either rtDH_DISABLE_STATE or rtDH_ENABLE_STATE.
autoWrapEnable Auto wrap value as either rtDH_DISABLE_STATE or rtDH_ENABLE_STATE.
recordData Table's record data array reference (see queryRecordData above for a description of the values).
           void queryTableConnPlin ()
                Returns the table's PLIN number for the current historian
                table if successful.

           void queryTableList ()
                Returns an array reference for the current list of historian
                tables if successful. All non-existant database addresses
                are returned as undefined values.

           void queryTableListCnt ()
                Returns the number of historian tables if successful.

           void queryTableName ()
                Returns the table name for the current historian table if
                successful.

           void queryTableResidence ()
                Returns the table's residence for the current historian
                table if successful.

           void queryTableSize ()
                Returns the table size for the current historian table if
                successful.

           void queryTableState ()
                Returns a hash reference for the current historian table's
                state if successful. The hash reference contains the
                following values:

Hash Name Description
nextRecord Next historian table record.
remainingSamples Samples remaining in history table.
lapCounter Number of times a wrapped table has wrapped.
clearCounter Number of times a table has been cleared.
tableStatus Status of table (either rtDH_TABLE_DISABLE, rtDH_TABLE_IDLE, rtDH_TABLE_ARMED, or rtDH_TABLE_RUNNING).

CRtapDhSymbols

      The following symbols can be accessed by prefixing it with the class
      name and two colons (eg. CRtapDh::rtDH_SAMPLE_DAYS). Note that all of
      the symbols defined for the CRtapDb and CRtap classes are also
      available.

rtDH_DISABLE_STATE ENABLE_STATE EV_EQUAL_TO_START
rtDH_EV_EQUAL_TO_START EV_EQUAL_TO_STOP EV_EQUAL_TO_STOP
rtDH_EV_GREATER_THAN_START EV_GREATER_THAN_START EV_GREATER_THAN_STOP
rtDH_EV_GREATER_THAN_STOP EV_LESS_THAN_START EV_LESS_THAN_START
rtDH_EV_LESS_THAN_START EV_LESS_THAN_STOP EV_LESS_THAN_STOP
rtDH_EV_TRIG_ADDR EV_TRIG_ADDR EV_TRIG_ALL
rtDH_EV_TRIG_ALL SAMPLE_DAYS SAMPLE_HOURS
rtDH_SAMPLE_MINUTES SAMPLE_SECONDS SETUP_START_ARMED
rtDH_SETUP_START_EVENT SETUP_START_TIMED STATS_CNT_AVG
rtDH_STATS_MIN_MAX STATS_TIME_AVG STAT_DAYS
rtDH_STAT_HOURS STAT_MINUTES STAT_SECONDS
rtDH_STOP_COUNT STOP_DAYS STOP_EVENT
rtDH_STOP_HOURS STOP_MINUTES STOP_NONE
rtDH_STOP_SECONDS STOP_TIMED TABLE_ARMED
rtDH_TABLE_DISABLED TABLE_IDLE TABLE_RUNNING

CDbUtilClass

      The CDbUtil class provides access to methods for traversing the
      RTAP database. This class inherits all of the methods available from the
      CRtapDb and CRtap classes.

      Call the setFunction method to setup the perl subroutine to call for
      each point. The matching point's PLIN number will be passed into the
      subroutine as it's only argument.

      All of the traversal methods return the return value from the perl
      subroutine.

      The new method is used to create an instance of this class. This
      method takes the following hash values for it's arguments:


           env  Specifies the RTAP environment to attach to. If this value
                is not specified, the contents of the environment variable
                RTAPENV will be used.

           argv0
                Specifies the RTAP process name to register as. This value
                must be specified.

           dbenv
                Specifies the RTAP database environment to open. If this
                value is not specified, the contents of the environment
                variables RTAPDB or RTAPENV will be used.

Example:

      use CDbUtil;

      $env = "jck";

      # Remove leading path info from our name.
      $nm = $0;
      $nm =~ s!.*/!!;

      $dbUtil = CDbUtil->new ('argv0' => "$nm", 'env' => "$env");
      if (! defined $dbUtil) {
          print "Failed to either register with RTAP environment,\n";
          print "or open database connection.\n";
          exit (-1);
      }


      The following describes the methods available for this class:


           void setFunction (func)
                Registers the specified function func to be called
                for each point in the traversal. Note that only one function
                can be registered at any one time. If a subsequent call is
                made, only the last registered function will be called. The
                PLIN number of the RTAP point will be passed as the only
                argument to the registered function. The registered function
                should return CDbUtil::rtSUCCESS to continue the
                traversal, and CDbUtil::rtFAILED to stop the
                traversal.

                func can be a string for the function name, or a
                reference to a function.


           int traverse (startingAlias)
                Traverses all points starting at the specified alias
                startingAlias. startingAlias is optional, and if
                not specified will default to the current working point.


           int traversePlinsInClass (cls, startingAlias)
                Traverses all points that match the specified class
                cls starting at the specified alias startingAlias.
                startingAlias is optional, and if not specified will
                default to the current working point.


           int traverseMatch (test, scope)
                Traverses all points that match the specified test
                test for the specified scope scope. test is a
                string that specified the match criteria (see matchPoints
                above). scope is a hash reference that describes where
                in the database to match (see matchPoints above).


CRtapTkClass

      The CRtapTk class provides access into the RTAP timekeeper. This class
      inherits all of the methods available from the CRtap class.

      The new method is used to create an instance of this class. This
      method takes the following hash values for it's arguments:


           env  Specifies the RTAP environment to attach to. If this value
                is not specified, the contents of the environment variable
                RTAPENV will be used.

           argv0
                Specifies the RTAP process name to register as. This value
                must be specified.

Example:

      use CRtapTk;

      $env = "jck";

      # Remove leading path info from our name.
      $nm = $0;
      $nm =~ s!.*/!!;

      $rtapTk = CRtapTk->new ('argv0' => "$nm", 'env' => "$env");
      if (! defined $rtapTk) {
          print "Failed to register with RTAP environment.\n";
          exit (-1);
      }


      The following describes the methods available for this class:


           int cancelTimer (timerId)
                Cancels the timer identified by timerId. timerId is a hash
                reference returned by the startTimer or delay methods.
                Returns rtSUCCESS or rtFAILED.

           void delay ()
                Returns a timerId hash reference if successful.

           void getNext ()
                Returns a hash reference containing the next alarm if
                successful. The returned hash reference contains the
                following values:

Hash Name Description
tv_sec Seconds since Jan. 1, 1970.
tv_usec Micro-seconds.
           int requestTimeReport (char *filename)
                Prints a time report to the specified filename filename.
                Returns rtSUCCESS or rtFAILED.

           int setDelay (unsigned int secs, int usecs)
                Sets the delay parameters secs seconds and usecs micro-
                seconds. Returns rtSUCCESS or rtFAILED.

           void setEnv (char *env =NULL)
                Sets the RTAP environment name.

           int setInterval (int secs =0, int mins =0, int hours =0, int days =0,
           int usecs =0)
                Sets the interval parameters for the startTimer call using
                the following arguments:

Argument Description
secs Interval seconds.
mins Interval minutes.
hours Interval hours.
days Interval days.
usecs Internval micro-seconds.
           void setMessage (char *msg =NULL)
                Sets the timer message for the startTimer or delay methods.

           void setPriority (int prior =0)
                Sets the message priority for the startTimer or delay
                methods.

           int setStartTime (int sHour =0, int sMin =0, int sSec =0, int sUSec
           =0, int sYear =-1, int sMon =-1, int sDay =-1))

                Sets the start time for the startTimer method using the
                following arguments:

Argument Description
sHour Start hour.
sMin Start minute.
sSec Start second.
sUSec Start micro-seconds.
sYear Start year.
sMon Start month.
sDay Start day.
           void setVerify (int verify =0)
                Sets the verify to verify. If verify is zero, the startTimer
                call will wait forever for the timekeeper to respond to the
                request. If verify is greater than zero, the startTimer call
                will wait the specified number of seconds for a response
                from the timekeeper. If verify is less than zero, the
                startTimer call will not wait for a response from the
                timekeeper.

           void startTimer ()
                Sends a timekeeper request for the start time (filled in
                using the setStartTime method) and interval (filled in using
                the setInterval method).

SEE ALSO

      perl(1)

      Programming Perl Larry Wall, Tom Christiansen, Randal L. Schwartz.

AUTHORS

      rtperl was developed by tesserNet Systems Inc.