SQABasic "DDGUIUtilities" Library

 MODULE DESCRIPTION:

 Utility routines for working with actual GUI objects and object properties.

Declarations Constants Global Variables User-Defined Types Routine Details

User Dependencies:

(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)

Internal Dependencies:

(stuff this library needs at compile time.)

Exported Declarations

Function DDGGetGUIPropertyString  BasicLib DDGUIUtilities                
Function DDGGetGUIPropertyVariant  BasicLib DDGUIUtilities                
Function DDGGetGUIArrayPropertySize  BasicLib DDGUIUtilities                
Function DDGGetGUIArrayPropertyStrings  BasicLib DDGUIUtilities                
Function DDGGetGUIArrayPropertyVariants  BasicLib DDGUIUtilities                
Function DDGGetGUIObjectData     BasicLib DDGUIUtilities                
Function DDGGetRootNodeInfo      BasicLib DDGUIUtilities                
Function DDGGetObjectDataNodeInfo  BasicLib DDGUIUtilities                
Function DDGGetFullNodePath      BasicLib DDGUIUtilities                
Function DDGGetNodeNonBlankColValueCount  BasicLib DDGUIUtilities                
Function DDGGetGUIChildrenIDs    BasicLib DDGUIUtilities                
Function DDGGetGUIPropertyNames  BasicLib DDGUIUtilities                
Function DDGOutputGUIChildrenIDs  BasicLib DDGUIUtilities                
Function DDGOutputGUIPropertyNames  BasicLib DDGUIUtilities                
Function DDGPerformSAFSMAPSCheck  BasicLib DDGUIUtilities                
Function DDGGetDefaultAppMapSection  BasicLib DDGUIUtilities                
   Sub   DDGSetDefaultAppMapSection  BasicLib DDGUIUtilities                
Function DDGGetGUIID             BasicLib DDGUIUtilities                
Function DDGClearAppMapCache     BasicLib DDGUIUtilities                
Function DDGGetCompTypeFromGUIID  BasicLib DDGUIUtilities                
Function DDGWaitForSQAObject     BasicLib DDGUIUtilities                
Function DDGWaitForPropertyValue  BasicLib DDGUIUtilities                
Function DDGWaitForPropertyValueGone  BasicLib DDGUIUtilities                
Function DDGWaitForGUI           BasicLib DDGUIUtilities                
Function DDGWaitForGUIPropertyValue  BasicLib DDGUIUtilities                
Function DDGWaitForSQAObjectGone  BasicLib DDGUIUtilities                
Function DDGWaitForGUIGone       BasicLib DDGUIUtilities                
Function DDGWaitForGUIPropertyValueGone  BasicLib DDGUIUtilities                
Function DDGSetGUIProperty       BasicLib DDGUIUtilities                
Function DDGGetGUIEnvironment    BasicLib DDGUIUtilities                

Constants


'where to look in AppMap if not found in specified section
Const DDG_DEFAULT_FALLBACK_LOOKUP_SECTION = "APPLICATIONCONSTANTS"
Const DDG_APPMAP_DDVARIABLE_LOOKUP_PREFIX = "_DDV:"
Const DDG_APPMAP_DDVARIABLE_LOOKUP_PREFIX_LEN = 5


Globals


'these are transient values filled by various routines
'not all values are modified by all ObjectData routines
Global DDGObjDataRows as Integer   'max rows in array
Global DDGObjDataCols as Integer   'max cols in array
Global DDGobjDataRowMin as Integer 'lbound of row array dimension
Global DDGObjDataColMin as Integer 'lbound of col array dimension
Global DDGObjDataRootRow as Integer 'first row with data 
Global DDGObjDataRootCol as Integer 'first col with data
Global DDGObjDataCol as Integer    'last col accessed
Global DDGObjDataRow as Integer    'last row accessed
Global DDGObjDataNode as String    'value of last node accessed
Global DDGObjDataFullNodePath as String    'fullpath of last fullpath accessed


'DEPRECATED:
'Use DDG_FALLBACK_LOOKUP_SECTION to identify a particular section in an 
'Application map to use as the default lookup for values NOT found when 
'searching for Application Map GUI IDs or DDVariable values.
'This Global is deprecated. Use the following routines to Get/Set this value:
'
'       DDGGetDefaultAppMapSection
'       DDGSetDefaultAppMapSection

'Global DDG_FALLBACK_LOOKUP_SECTION As String 

User-Defined Types


Type ObjectDataNodeInfo
    FullPath As String
    Delimiter As String
    Row As Integer
    Column As Integer
    ChildCount As Integer
    FirstChildRow As Integer
    LastChildRow As Integer
    FullFoundPath As String
End Type


Routine Details



  Function DDGPerformSAFSMAPSCheck() as Long

 DESCRIPTION:

      Check to see if the SAFSMAPS service is already running.
      If not, see if AUTOLAUNCH is enabled and commence if it is.


 PARAMETERS:

      (none)


 RETURNS:

       TRUE (non-zero) or FALSE (zero)


 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: DEC 07, 2006
 History:

      DEC 07, 2006    Original Release




  Function DDGGetGUIPropertyVariant (guiID As String, property As String,
                                     value As Variant) As Integer

 DESCRIPTION:

      Retrieves a GUI object property value as a Variant along with status
      information just like SQAGetProperty.  However, the routine
      checks for unmodified, local (.\;), and desktop (\;) contexts for the
      object before returning a sqaObjectNotFound status (which SQA does not).

      This routine is only for single value properties.  If a property
      value is actually a list or array then you need to use
      DDGGetGUIArrayPropertyVariants.

      To get a single property value from within an array you must include
      the property name with an array syntax which includes the index into
      the array.  For example, to retrieve the 3rd value from the property
      List the property string would be "List(3)".

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-sensitive name of the property
                  to get the value from.

      value       Variant to receive the retrieved value

 RETURNS:

      0       Success.

      N       Failure status codes as describes by SQA's Object scripting
              routines.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JUL 27, 1999
 History:

      JUL 27, 1999    Original Release
      APR 28, 2005    (CANAGL) Additional performance enhancements




  Function DDGGetGUIPropertyString (guiID As String, property As String,
                                    value As String) As Integer

 DESCRIPTION:

      Retrieves a GUI object property value as a String along with status
      information just like SQAGetPropertyAsString.  However, the routine
      checks for unmodified, local (.\;), and desktop (\;) contexts for the
      object before returning a sqaObjectNotFound status (which SQA does not).

      This routine is only for single value properties.  If a property
      value is actually a list or array then you need to use
      DDGGetGUIArrayPropertyStrings.

      To get a single property value from within an array you must include
      the property name with an array syntax which includes the index into
      the array.  For example, to retrieve the 3rd value from the property
      List the property string would be "List(3)".

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-sensitive name of the property
                  to get the value from.

      value       String to receive the retrieved value

 RETURNS:

      0       Success.

      N       Failure status codes as describes by SQA's Object scripting
              routines.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JUL 27, 1999
 History:

      JUL 27, 1999    Original Release
      APR 28, 2005    (CANAGL) Additional performance enhancements




  Function DDGGetGUIArrayPropertySize (guiID As String, property As String,
                                       size As integer) As Integer

 DESCRIPTION:

      Returns the size of the property array for the given property.
      This can only be done on properties whose values are lists or arrays.
      If the property is not an array then an error will be returned.

      This routine attempts to locate the desired component by cycling
      through variations of the guiID provided to better facilitate a match.


 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-sensitive name of the property
                  to get the size of (and verify it is an array).

      size        will receive the number of elements in the array if successful.

 RETURNS:

       0  Success. "size" will exit with the number of elements in the array.

       N  Failure status codes as describes by SQA's Object scripting
          routines.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAY 26, 2000
 History:

      MAY 26, 2000    Original Release
      APR 28, 2005    (CANAGL) Additional performance enhancements




  Function DDGGetGUIArrayPropertyStrings (guiID As String, property As String,
                                          values() As String) As Integer

 DESCRIPTION:

      Returns a GUI object property value as an array of Strings.
      This can only be done on properties whose values are lists or arrays.
      If a propety value is actually a single value then you need to use
      DDGGetGUIPropertyString.

      We first call DDGGetGUIArrayPropertySize to
      ensure the property is actually an array with a size greater than 0.


 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-sensitive name of the property
                  to get the value from.

      values      a zero-based array of type String that has been declared
                  as follows:   Dim values() As String
                  This routine will handle the redimensioning of the array
                  to suit.


 RETURNS:

       0  Success.

       N  Failure status codes as describes by SQA's Object scripting
          routines.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JUL 27, 1999
 History:

      JUL 27, 1999    Original Release
      APR 28, 2005    (CANAGL) Additional performance enhancements




  Function DDGGetGUIArrayPropertyVariants (guiID As String, property As String,
                                           values() As Variant) As Integer

 DESCRIPTION:

      Returns a GUI object property value as an array of Variants.
      This can only be done on properties whose values are lists or arrays.
      If a propety value is actually a single value then you need to use
      DDGGetGUIPropertyVariant.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-sensitive name of the property
                  to get the value from.

      values      a zero-based array of type Variant that has been declared
                  as follows:   Dim values() As Variant
                  This routine will handle the redimensioning of the array
                  to suit.

 RETURNS:

       0  Success.

       N  Failure status codes as describes by SQA's Object scripting
          routines.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JUL 27, 1999
 History:

      JUL 27, 1999    Original Release
      APR 28, 2005    (CANAGL) Additional performance enhancements




  Function DDGGetGUIObjectData (guiID As String, values() As Variant, Optional dataTest As Variant) As Integer

 DESCRIPTION:

      Returns GUI object data as an array of Variants.
      This can only be done for objects that Robot can successfully execute
      an Object Data VP (CompareData or CompareMenu) on.  We use our own dummy VP data to get
      at this data.  The user does not have to have an existing VP to use this
      function.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      values      array of type Variant that has been declared as follows:

                       Dim values() As Variant

                  This routine will handle the redimensioning of the array
                  to suit.  The returned values array will be a 2D 1-based array.
                  That is, the first element is at row/col index 1,1.
                  Note, you will need to evaluate the actual contents of the
                  returned array for your needs.  It is possible that hidden
                  rows and columns will be surfaced in the array.  So data that
                  appears like it should be in cell 1,1 may actually be in
                  cell 2,2 (or elsewhere depending on "hidden" rows and columns).

      dataTest    optional string value that specifies the data to capture.
                  Depending on the GUI object, the user might be able to
                  capture different data, in addition to "Contents" which is
                  usually available to all objects. For example, "Visible Nodes"
                  and "Java Active State" are also available for JavaTrees.

                  The default is "Contents".
                  If "Menu" is provided then a dynamic Menu extraction will occur
                  where supported.

                  Values specified for datatest are currently case-sensitive.

 RETURNS:

       N  On Success, returns the number of ROWS returned in the values array.
          This will include any header row(s) and/or leftmost "hidden" column(s).

      -1  Fatal VP execution Error

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: NOV 20, 2002
 History:

      NOV 20, 2002    Original Release
      DEC 03, 2003    (YWANG)  Changed DDGGetGUIObjectData to allow different data test
      MAY 14, 2004    (CANAGL) Seeking performance improvements on data extraction.
      JUN 15, 2005    (CANAGL) Added datatest="Menu" support to DDGGetGUIObjectData




  Function DDGGetRootNodeInfo (nodes() As Variant,
                               rootRow as Integer, rootCol as Integer) As String

 DESCRIPTION:

      Find the first non-blank cell in the provided 2D array.
      Returns the string of that root node and fills in the variables rootRow
      and rootCol with the row and column where the root was found in the
      values array.

      This is generally useful for evaluating the ObjectData arrays returned
      from DDGGetGUIObjectData.


 PARAMETERS:

      nodes()     Generally, a 2D array of Variant values like those returned
                  from DDGGetGUIObjectData.
                  The array must be 0-based or higher.  Usually it is 1-based.

      rootRow     pass in a variable that will receive the row from which the
                  first non-blank cell was found.

      rootCol     pass in a variable that will receive the row from which the
                  first non-blank cell was found.

 RETURNS:

      String      The string value of that first non-blank cell,
                  or an emptry string.

 ERRORS:


      none

 Orig Author: Carl Nagle
 Orig   Date: JAN 17, 2003
 History:

      JAN 16, 2003    Original Release
      JUL 20, 2005    (CANAGL) Added Global var support for performance.




  Function DDGGetFullNodePath (nodepath as String, delimiter as String,
                               nodes() as Variant, Optional fuzzy, Optional matchIndex) as String

 DESCRIPTION:

      Find the fullNodePath string that proves our nodepath exists in the
      provided nodes array.  Normally, this requires an exact match, but we
      can allow for partial matches and case-insensitive comparisons and
      matching with the Optional "fuzzy" parameter.  The nodes
      array is expected to be configured as a 2D array representation of
      hierarchical data like that provided from DDGGetGUIObjectData.

      Our nodes array looks like this:

          root
              level1
              level1a
                     level2
                     level2a
              level1b
                     level2b
                     level2c
                            level3
              level1c

      So, you can see that "level1b" indicates the end of child nodes for
      "level1a".   "level1c" indicates the end of child nodes for "level2c"
      AND "level1b".

      nodepaths are hierarchical paths to individual leaf nodes using the specified
      delimiter between parent and child nodes.

      Example nodepaths with "->" delimiter:

          root->level1b->level2c->level3
          root->level1c

      Example fuzzy nodepaths with "->" delimiter:

          r->1b->2c->3
          oo->c
          t->level1b->2c->level

 PARAMETERS:

      nodePath    A string showing parent/child hierarchical information
                  separated by delimiters.

      delimiter   A String specifying the delimiter used to separate parent/child
                  relationsips.

      nodes()     Generally, a 2D array of Variant values like those returned
                  from DDGGetGUIObjectData.
                  The array must be 0-based or higher.  Usually it is 1-based.
                  The nodes array is expected to be configured as a 2D array representation of
                  hierarchical data like that provided from DDGGetGUIObjectData.

      fuzzy       Optional parameter to allow for partial text matches when
                  identifying nodes.
                  0=(default) exact match required.
                  1=case-insensitive partial matches allowed.

      matchIndex  Optional parameter to allow for the Nth match, not just the first.
                  This matchIndex only applies to the leaf nodes in the full path.
                  If provided the numeric integer value must be > 0.

      embedIndex  Optional parameter if true (non-zero) tells the routine to return ;Index=
                  information in the returned full path where discernable.
                  This can usually only be accomplished when fuzzy=0 (exact match required).
                  Returns paths like:
                  DupedNode;Index=2->BranchNode->LeafNode
                  RootNode->DupedNode;Index=2->LeafNode

  embedIndexBase  specify the base index when embedIndex is true.  By default this IndexBase
                  is 1.  However, things like .NET have made the Index= indexbase 0.  Thus,
                  for .NET embedIndexBase would need to be specified as 0.

 RETURNS:

      String      Upon success, we return the full exact match of the full
                  hierarchy path to the requested node.  Thus, if you provide
                  a fuzzy path, this routine will return the full complete
                  path string to the node--all fuzziness removed.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JAN 17, 2003
 History:

      JAN 16, 2003    Original Release
      JAN 24, 2003    (YWANG)  Fixed bug that incorrectly processes optional parameter fuzzy.
      DEC 03, 2003    (CANAGL) Added finding Nth match, not just the first.
      JUL 20, 2005    (CANAGL) Added Global var support for performance.  Also added support
                               for embedIndex and embedIndexBase and Nth item matching on
                               root or branch nodes.




  Function DDGGetNodeNonBlankColValueCount (nodes() As Variant,
                                            column as Integer) As Integer

 DESCRIPTION:

      Return the number of non-blank cells in the provided column of the 2D array.

      This is generally useful for evaluating the ObjectData arrays returned
      from DDGGetGUIObjectData.


 PARAMETERS:

      nodes()     Generally, a 2D array of Variant values like those returned
                  from DDGGetGUIObjectData.
                  The array must be 0-based or higher.  Usually it is 1-based.

      column      The column within the 2D array to evaluate.


 RETURNS:

      Integer     The number of non-blank values in the provided column.
                  -1 on error.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: APR 03, 2003
 History:

      APR 03, 2003    Original Release




  Function DDGGetObjectDataNodeInfo(data() As Variant, info As ObjectDataNodeInfo, children() As String, Optional match) As Integer

 DESCRIPTION:

      Retrieves information about a node of a tree captured in a 2D array.

      This is generally useful for evaluating the ObjectData arrays returned
      from DDGGetGUIObjectData.


 PARAMETERS:

      data    1-based 2D array of Variant values like those returned
              from DDGGetGUIObjectData.

      info    input/output parameter to store information about the node of
              interest. The FullPath and Delimiter fields of this user type
              are the input parameters, thus should be populated before
              passing to this function. The rest of the fields are output
              parameters populated by this function.

      children    output parameter. 1-based array storing all child nodes of
                  the target node. You should make sure info.ChildCount is not
                  0 before accessing elements in this array.

      match       Optional. 0 to match given path and object data exactly; 1
                  to partially match given path to object data. E.g.
                  "root->subfolder" is a partial match for object data node
                  "myroot->mysubfolder". Partial match is also case-
                  insensitive. Default is 0 (exact match).

 RETURNS:

      0   on success.
      1   on failure.

 ERRORS:

      none

 Orig Author: Yuesong Wang
 Orig   Date: DEC 03, 2003
 History:

      DEC 03, 2003    Original Release
      MAY 10, 2004    (YWANG) Added optional match parameter
      JUL 20, 2005    (CANAGL) Added Global var support for performance
      SEP 08, 2005    (bolawl) Updated to build the full path of the located node (since info.FullPath can be a partial
                               (fuzzy) path) and include it as info.FullFoundPath. RJL




  Function DDGGetGUIChildrenIDs (guiID As String, values() As String) As Integer

 DESCRIPTION:

      Fills the provided array of Strings with the full recognition strings
      of all the children (if any) of the provided guiID.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      values      a zero-based array of Strings that has been declared
                  as follows:   Dim values() As String
                  This routine will handle the redimensioning of the array
                  to suit.

 RETURNS:

       0  Success.

       N  Failure status codes as describes by SQA's Object scripting
          routines.

     1015 Generally indicates the object has no children or that
          an error occurred while filling up the array of child IDs.

      NOTE that the returned array may have valid entries even if an error occurs.


 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: FEB 24, 2000
 History:

      FEB 24, 2000    Original Release
      MAR 01, 2000    (CANAGL) Updated doc




  Function DDGGetGUIPropertyNames (guiID As String, values() As String) As Integer

 DESCRIPTION:

      Fills the provided array of Strings with all the available property
      names (if any) of the provided guiID.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      values      a zero-based array of Strings that has been declared
                  as follows:   Dim values() As String
                  This routine will handle the redimensioning of the array
                  to suit.

 RETURNS:

       0  Success.

       N  Failure status codes as describes by SQA's Object scripting
          routines.

     1015 Generally indicates the object has no properties (never seen it) or that
          an error occurred while filling up the array of property names.

      NOTE that the returned array may have valid entries even if an error occurs.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: FEB 25, 2000
 History:

      FEB 25, 2000    Original Release
      MAR 01, 2000    (CANAGL) Updated doc




  Function DDGOutputGUIChildrenIDs (guiID As String, filename As String) As Integer

 DESCRIPTION:

      Writes a file containing the full recognition strings
      of all the children (if any) of the provided guiID.
      The file will be automatically overwritten if it already exists.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      filename    filename to output the retrieved children recognition methods.
                  One child recognition per line in the file.
                  The file will be automatically overwritten if it already exists.

 RETURNS:

       0  Success.
      -1  Invalid or missing filename

      +N  Failure status codes as describes by SQA's Object scripting
          routines or file handling routines.

     1015 Generally indicates the object has no children or
          that an error occurred while filling up the array of child IDs.

      NOTE that the file or a partial file may be written even if an error occurs.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: FEB 24, 2000
 History:

      FEB 24, 2000    Original Release
      MAR 01, 2000    (CANAGL) Allowed file output even on certain errors.




  Function DDGOutputGUIPropertyNames (guiID As String, filename As String) As Integer

 DESCRIPTION:

      Writes a file containing all the available property names (if any)
      of the provided guiID.
      The file will be automatically overwritten if it already exists.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      filename    filename to output the retrieved property names.
                  One property name per line in the file.
                  The file will be automatically overwritten if it already exists.

 RETURNS:

       0  Success.
      -1  Invalid or missing filename

       N  Failure status codes as describes by SQA's Object scripting
          routines or file handling routines.

     1015 Generally indicates the object has no properties (never seen it) or
          that an error occurred while filling up the array of property names.

      NOTE that the file or a partial file may be written even if an error occurs.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: FEB 25, 2000
 History:

      FEB 25, 2000    Original Release
      MAR 01, 2000    (CANAGL) Allowed file output even on certain errors.




  Function DDGGetDefaultAppMapSection () As String

 DESCRIPTION:

      Returns a fallback lookup section for searching an Application
      Map.  If the fallback lookup section value has not been set, we will
      return the value of the DDG_DEFAULT_FALLBACK_LOOKUP_SECTION.
      In this way, the user does not have to perform the test and setting of
      the fallback lookup section to use.

      The FALLBACK LOOKUP SECTION is that section of the Application Map
      that will be searched for a matching componentID in the event that
      the specified windowsID section does not exist or does not contain that
      componentID.

      By default, this FALLBACK LOOKUP SECTION will be the ApplicationConstants
      section of the application map.  The user can change this setting by
      providing a new value to the DDGSetDefaultAppMapSection routine.


 PARAMETERS:

      (none)

 RETURNS:

      The Application Map section currently set as the FALLBACK LOOKUP SECTION
      to search when items are otherwise not found.  If no section was
      previously set, then we return the DEFAULT FALLBACK LOOKUP SECTION as
      defined in the Constants.

 ERRORS:

      (none)

 Orig Author: Carl Nagle
 Orig   Date: MAR 15, 2001
 History:

      MAR 15, 2001    Original Release
      AUG 07, 2001    (CANAGL) Removed the Global and added DDGDefaultAppMapSection
                               module variable.
      DEC 07, 2006    (CANAGL) Added direct STAF support to bypass DDVariableStore.DLL




  Sub DDGSetDefaultAppMapSection (section as String)

 DESCRIPTION:

      Sets the FALLBACK LOOKUP SECTION for searching an Application
      Map.

      The FALLBACK LOOKUP SECTION is that section of the Application Map
      that will be searched for a matching componentID in the event that
      the specified windowsID section does not exist or does not contain that
      componentID.

      By default, this FALLBACK LOOKUP SECTION will be the ApplicationConstants
      section of the application map.  The user can change this setting by
      providing a new value to this routine.


 PARAMETERS:

      section     The string name of the section in an AppMap to use.


 ERRORS:

      (none)

 Orig Author: Carl Nagle
 Orig   Date: AUG 07, 2001
 History:

      AUG 07, 2001    Original Release
      DEC 07, 2006    (CANAGL) Added direct STAF support to bypass DDVariableStore.DLL




  Function DDGGetGUIID (windowID As String,
                       componentID As String,
                       Optional appMapPath) As String

 DESCRIPTION:

      Retrieves the SQA recognition method for a given component in a given
      window.  It will find this value in the Global AUCurrentAppMap
      MAP file that should be valid prior to this call.  Optionally, a different
      app map file path can be provided.

      The routine stores all retrieved values into a static storage array so that
      it only has to resort to the file the first time a particular component is
      referenced.

      The retrieved value can, instead, be coded as an instruction to get
      the actual recognition string via a DDVariable lookup.  If the retrieved
      AppMap lookup value is prefixed with "_DDV:" then this routine will
      perform the DDVariable lookup to retrieve the final recognition string
      value.  The following rules will apply for identifying the name of the
      variable that will be sought:

      [WindowID]
      WindowID=ARecognitionString    (use AppMap recognition string)
      Component1=_DDV:               (use value from variable "Component1")
      Component2=_DDV:AVariableName  (use value from variable "AVariableName")

      Note: There may be the possibility of putting yourself into an infinite
      lookup loop if you use the _DDV: lookup mechanism that points to a variable
      that has not been defined (given a value) but points to an ApplicationConstants
      lookup value that also uses the _DDV: lookup mechanism that points to a
      variable of the same name that also has not been defined.  It sounds
      quite unlikely, but it is possible.



 PARAMETERS:

      windowID        String identifying the name of the window in which we
                      will find the componentID.
                      This is identical to a "Section" of an INI file which
                      our map files mimic.

                      If no value is provided("") then we will attempt to check the
                      section identified by the DDGGetDefaultAppMapSection routine.
                      Similarly, if a search using a WindowID finds no match, we will
                      check the DDGGetDefaultAppMapSection location.


      componentID     String identifying the name of the component for which
                      we are seeking the recognition method (GUIID).
                      This is identical to a "Key" of an INI file which our map
                      files mimic.


      appMapPath      Optional String specifying the path and name to an
                      alternate appmap to use.  If this is not provided then the
                      value found in Global AUCurrentAppMap is used
                      instead.
                      The file path and name can be relative to the current SQA
                      Repository, project, or datapool.
                      We use FindSQAFile to validate
                      the appMapPath provided.

 RETURNS:

      If successful, the GUIID string (recognition method) of the specified component.

      An empty string on failure ("").  This can be due to invalid values of any
      provided parameters, an unset or invalid AUCurrentAppMap, or other errors.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JUL 26, 1999
 History:

      JUL 26, 1999    Original Release
      AUG 04, 1999    (CANAGL) Complete redo of array storage and retrieval.
      AUG 25, 1999    (CANAGL) Modified for use with ApplicationUtilities
      JUL 20, 2000    (CANAGL) Optimized for performance.
      MAR 15, 2001    (CANAGL) Added checks in AppMap ApplicationConstants.
      AUG 03, 2001    (CANAGL) Converted to DDVariableStore.DLL
      JUN 18, 2002    (CANAGL) Added _DDV: variable lookup capability.
      DEC 07, 2006    (CANAGL) Added direct STAF support to bypass DDVariableStore.DLL




  Function DDGClearAppMapCache() As Long

 DESCRIPTION:

      Resets and clears any cached AppMap information.  This is sometimes
      necessary if the AppMap has been edited.  Calling this routine will
      force a reload of the AppMap file when it is next accessed.

      This Function requires DDVariableStore.DLL V2.02 (Dec 11, 2003) or
      later.

      If STAF is in use then it also requires the SAFSMAPS service
      released Dec 11, 2003 or later.


 PARAMETERS:

      (none)


 RETURNS:

      0   normal return
     -1   error occurred. DLL or STAF may not be a version supporting this.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: DEC 11, 2003
 History:

      DEC 11, 2003    Original Release
      Aug 13, 2004    (CANAGL) Fixed an early loading clear problem
      DEC 07, 2006    (CANAGL) Added direct STAF support to bypass DDVariableStore.DLL




  Function DDGGetCompTypeFromGUIID (guiID As String) As String

 DESCRIPTION:

      Retrieves the last component type specifier in the provided string.

      For example:

          guiID = "Type=HTMLDocument;Index=1;\;Type=Combobox;Name=MyCombo"

      would return "Combobox"


 PARAMETERS:

      guiID   String to locate the last component type specifier in.
              This is usually the recognition method of a component.

 RETURNS:

      If successful, the component type string of the component.

      An empty string on failure ("").

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: FEB 26, 2001
 History:

      FEB 26, 2001    Original Release




  Function DDGWaitForSQAObject (guiID As String,
                                Optional timeout) As Integer

 DESCRIPTION:

      Generates a wait state for a given SQAObject.  That is, attempt to
      locate the object within the timeout period and return success only
      if the object is found within that period.  A given object can be
      created even if it is not yet visible.  In some cases, Windows
      will be located successfully but a WindowsVP Exists will fail because
      of a lag time between when the object is created and when it is displayed.
      For this reason, once the object has been found to exist we will also
      test for the Property "Visible" to be "True".  We will not exit with
      error, however, if this latter property test cannot be satisfied.  It is
      merely an attempt to more accurately wait for the given object.

      The routine spends approx. .025 seconds on each of 3 different recognition
      methods trying to locate the object.  Thus consider a single search
      for the object to take up to around .08 seconds and then the search will
      continue again until the full timeout value has been reached.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.


      timeout     Optional Integer value in seconds to set as the timeout for
                  the operation.  15 seconds is the default timeout value.
                  If the timeout value provided is < 1 or is otherwise
                  an invalid number then we exit with error.

 RETURNS:

      -1 if input parameters are invalid
       0 on successfully finding the object within the timeout period.
       N error code returned from the SQAWaitForObject routine.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 20, 2000
 History:

      MAR 20, 2000    Original Release
      MAR 21, 2000    (CANAGL) Enhanced WaitFor routines for more accuracy.
      APR 23, 2001    (CANAGL) Removed looping delay.




  Function DDGWaitForPropertyValue (guiID As String, property As String, _
                                    value As String, Optional timeout) As Integer

 DESCRIPTION:

      Generates a wait state for a given SQAObject and continues looking for a
      particular property value in that object.
      That is, watch an object's property until the value matches that provided
      or until the timeout period is reached.

      The routine uses Robot's SQAWaitForPropertyValue.

      It spends .025 second on each of 3 different recognition
      methods trying to locate the object.  Thus consider a single search
      for the object to take up to around .08 seconds and then the search will
      continue again until the full timeout value has been reached.


 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-senstive name of the property to check.

      value       The case-sensitive String value we are looking for.


      timeout     Optional Integer value in seconds to set as the timeout for
                  the operation.  15 seconds is the default timeout value.
                  If the timeout value provided is < 1 or is otherwise
                  an invalid number then we exit with error.

 RETURNS:

      -1 if input parameters are invalid
       0 on successfully matching the property value.
       N error code returned from the SQAWaitForPropertyValue routine.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 01, 2001
 History:

      MAR 01, 2001    Original Release
      APR 23, 2001    (CANAGL) Removed looping delays.




  Function DDGWaitForSQAObjectGone (guiID As String,
                                    Optional timeout) As Integer

 DESCRIPTION:

      Generates a wait state for a given SQAObject to go away.  That is,
      attempt to locate the object and return success if the object
      disappears within the timeout period.

      The routine attempts 3 variations of the recognition method trying to
      locate the object.  It then waits up to the timeout period for the
      object to disappear checking at approx. .025 second intervals.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.


      timeout     Optional Integer value in seconds to set as the timeout for
                  the operation.  15 seconds is the default timeout value.
                  If the timeout value provided is < 1 or is otherwise
                  an invalid number then we exit with error.

 RETURNS:

      -2 if input parameters are invalid.

      -1 the object remains and did not disappear within the timeout period.

       0 on successfully finding the object and then seeing it disappear within
         the timeout period.

       1 if the object could not be initially found. This could be caused by a
         bad recognition method OR the object already disappeared prior to the
         call.

       N error code returned from the SQAFindObject routine if other than
         SQAObjectNotFound.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: APR 13, 2000
 History:

      APR 13, 2000    Original Release
      APR 23, 2001    (CANAGL) Removed looping delays.




  Function DDGWaitForPropertyValueGone (guiID As String, property As String, _
                                        value As String, Optional timeout) As Integer

 DESCRIPTION:

      Generates a wait state for a given SQAObject's Property Value to go away.
      That is, attempts to locate the object and return success if the specified
      property value changes (or the object goes away) within the timeout period.
      An intial test IS performed to see if the property value matched in
      the first place.

      The routine attempts 3 variations of the recognition method trying to
      locate the object.  It then waits up to the timeout period for the
      object or the property to disappear, checking at approx. .025 second intervals.

 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-senstive name of the property to check.

      value       The case-sensitive String value we are watching to go away.

      timeout     Optional Integer value in seconds to set as the timeout for
                  the operation.  15 seconds is the default timeout value.
                  If the timeout value provided is < 1 or is otherwise
                  an invalid number then we exit with error.

 RETURNS:

      -2 if input parameters are invalid.

      -1 the property value was found but did not change within the timeout period.

       0 on successfully finding the object and the property value and then
         seeing it disappear/or change within the timeout period.

       1 if the object or specified property value was never initially found.
         This could be caused by a bad recognition method * OR * the object or
         property value had already disappeared/changed prior to the call.

       N error code returned from the SQAFindObject routine if other than
         SQAObjectNotFound.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 01, 2001
 History:

      MAR 01, 2001    Original Release
      APR 23, 2001    (CANAGL) Removed looping delays.




  Function DDGWaitForGUI (windowID As String,
                          componentID As String,
                          Optional timeout,
                          Optional appMapPath) As Integer

 DESCRIPTION:

      Generates a wait state for a given component in a given
      window.  It will find this value in the Global AUCurrentAppMap
      APPLICATION MAP file that should be valid prior to this call.
      Optionally, a different application map file path can be provided.
      The routine waits for the given object to become valid within
      the timeout period.

 PARAMETERS:

      windowID        String identifying the name of the window in which we
                      will find the componentID.
                      This is identical to a "Section" of an INI file which
                      our application map files mimic.  This value must satisfy
                      the DDGGetGUIID windowID parameter.

      componentID     String identifying the name of the component for which
                      we are seeking the recognition method (GUIID).
                      This is identical to a "Key" of an INI file which our
                      application map files mimic.

      timeout         Optional Integer value In seconds to set as the timeout for the
                      operation.  15 seconds is the default timeout value.

      appMapPath      Optional String specifying the path and name to an
                      alternate appmap to use.  If this is not provided then the
                      value found in Global AUCurrentAppMap is used
                      instead.
                      The file path and name can be relative to the current SQA
                      Repository, project, or datapool.
                      We use FindSQAFile to validate
                      the appMapPath provided.

 RETURNS:

      -1 if input parameters are invalid
       0 on successfully finding the object within the timeout period.
       N error code returned from the SQAWaitForObject routine.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 20, 2000
 History:

      MAR 20, 2000    Original Release
      MAR 16, 2001    (CANAGL) Allow Application Map lookthru




  Function DDGWaitForGUIPropertyValue (windowID As String,
                          componentID As String,
                          property As String,
                          value As String,
                          Optional timeout,
                          Optional appMapPath) As Integer

 DESCRIPTION:

      Generates a wait state for a particular GUI object's property value.
      It will find this object in the Global AUCurrentAppMap
      APPLICATION MAP file that should be valid prior to this call.
      Optionally, a different application map file path can be provided.
      The routine will wait for the given object to become valid within
      the timeout period before checking the property value.

 PARAMETERS:

      windowID        String identifying the name of the window in which we
                      will find the componentID.
                      This is identical to a "Section" of an INI file which
                      our application map files mimic.  This must satisfy the
                      DDGGetGUIID windowID parameter.

      componentID     String identifying the name of the component for which
                      we are seeking the recognition method (GUIID).
                      This is identical to a "Key" of an INI file which our
                      application map files mimic.

      property        String which is the case-senstive name of the property to check.

      value           The case-sensitive String value we are watching for.

      timeout         Optional Integer value In seconds to set as the timeout for the
                      operation.  15 seconds is the default timeout value.

      appMapPath      Optional String specifying the path and name to an
                      alternate appmap to use.  If this is not provided then the
                      value found in Global AUCurrentAppMap is used
                      instead.
                      The file path and name can be relative to the current SQA
                      Repository, project, or datapool.
                      We use FindSQAFile to validate
                      the appMapPath provided.

 RETURNS:

      -1 if input parameters are invalid
       0 on successfully finding the object and property value within the timeout period.
       N error code returned from the WaitForPropertyValue routine.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 01, 2001
 History:

      MAR 01, 2001    Original Release
      MAR 16, 2001    (CANAGL) Allow Application Map lookthru




  Function DDGWaitForGUIGone (windowID As String,
                              componentID As String,
                              Optional timeout,
                              Optional appMapPath) As Integer

 DESCRIPTION:

      Generates a wait state for a given component in a given
      window to disappear.
      It will find this component in the Global AUCurrentAppMap
      APPLICATION MAP file that should be valid prior to this call.
      Optionally, a different application map file path can be provided.
      The routine waits for the given object to disappear within
      the timeout period.

 PARAMETERS:

      windowID        String identifying the name of the window in which we
                      will find the componentID.
                      This is identical to a "Section" of an INI file which
                      our application map files mimic.

      componentID     String identifying the name of the component for which
                      we are seeking the recognition method (GUIID).
                      This is identical to a "Key" of an INI file which our
                      application map files mimic.

      timeout         Optional Integer value In seconds to set as the timeout for the
                      operation.  15 seconds is the default timeout value.

      appMapPath      Optional String specifying the path and name to an
                      alternate appmap to use.  If this is not provided then the
                      value found in Global AUCurrentAppMap is used
                      instead.
                      The file path and name can be relative to the current SQA
                      Repository, project, or datapool.
                      We use FindSQAFile to validate
                      the appMapPath provided.

 RETURNS:

      -2 if input parameters are invalid.

      -1 the object remains and did not disappear within the timeout period.

       0 on successfully finding the object and then seeing it disappear within
         the timeout period.

       1 if the object could not be initially found. This could be caused by a
         bad recognition method OR the object already disappeared prior to the
         call.

       N error code returned from the SQAFindObject routine if other than
         SQAObjectNotFound.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: APR 13, 2000
 History:

      APR 13, 2000    Original Release
      MAR 16, 2001    (CANAGL) Allow Application Map lookthru




  Function DDGWaitForGUIPropertyValueGone (windowID As String,
                              componentID As String,
                              property As String,
                              value As String,
                              Optional timeout,
                              Optional appMapPath) As Integer

 DESCRIPTION:

      Generates a wait state for a given SQAObject's Property Value to go away.
      That is, attempts to locate the object and return success if the specified
      property value changes (or the object goes away) within the timeout period.
      An intial test IS performed to see if the property value matched in
      the first place.

      It will find this component in the Global AUCurrentAppMap
      APPLICATION MAP file that should be valid prior to this call.
      Optionally, a different application map file path can be provided.

 PARAMETERS:

      windowID        String identifying the name of the window in which we
                      will find the componentID.
                      This is identical to a "Section" of an INI file which
                      our application map files mimic.  The provided value
                      must satisfy the DDGGetGUIID windowID parameter.

      componentID     String identifying the name of the component for which
                      we are seeking the recognition method (GUIID).
                      This is identical to a "Key" of an INI file which our
                      application map files mimic.

      property        String which is the case-senstive name of the property to check.

      value           The case-sensitive String value we are watching to go away.

      timeout         Optional Integer value In seconds to set as the timeout for the
                      operation.  15 seconds is the default timeout value.

      appMapPath      Optional String specifying the path and name to an
                      alternate appmap to use.  If this is not provided then the
                      value found in Global AUCurrentAppMap is used
                      instead.
                      The file path and name can be relative to the current SQA
                      Repository, project, or datapool.
                      We use FindSQAFile to validate
                      the appMapPath provided.

 RETURNS:

      -2 if input parameters are invalid.

      -1 the property value remains and did not change within the timeout period.

       0 on successfully finding the object's property value and then seeing it
         change or the object disappear within the timeout period.

       1 if the property value was not initially as expected or the object was not
         found. This could be caused by a bad recognition method OR the object
         disappeared or property value already changed prior to the call.

       N error code returned from the WaitForPropertyValueGone routine if other than
         SQAObjectNotFound.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 01, 2001
 History:

      MAR 01, 2001    Original Release
      MAR 16, 2001    (CANAGL) Allow Application Map lookthru




  Function DDGSetGUIProperty (guiID As String, property As String,
                                    value As String) As Integer

 DESCRIPTION:

      Sets an object property value for a GUI object.  However, the routine
      checks for unmodified, local (.\;), and desktop (\;) contexts for the
      object before returning a sqaObjectNotFound status (which SQA does not).

      This routine is only for single value properties.  If a property
      value is actually a list or array this function will not support it.


 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.

      property    String which is the case-sensitive name of the property
                  to set the value to.

      value       String to set the property value

 RETURNS:

      0       Success.

      N       Failure status codes as describes by SQA's Object scripting
              routines.

 ERRORS:

      none

 Orig Author: Dawn Coen
 Orig   Date: NOV 3, 2004
 History:

      NOV 3, 2004    Original Release




  Function DDGGetGUIEnvironment (guiID As String) As String

 DESCRIPTION:

      Attempts to retrieve or deduce the object's Environment.
      Normally this is provided from the object's Environment property,
      however some configurations do not properly return a value for that
      property.  In that case, we must attempt to deduce it through other
      avenues.

      Typical Environment values are:

          Java, .NET, Visual Basic, Html, Win

      (The 'Win' environment is defined by us from SHELL32.DLL and other MS DLLs.)


 PARAMETERS:

      guiID       String which is the recognition method of the GUI object.
                  Normally this is retrieved through lookup or use from
                  the Application Map prior to this call.


 RETURNS:

      The String environment value or an empty string.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: FEB 28, 2006
 History:

      FEB 28, 2006    Original Release


Copyright (C) SAS Institute
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php 
==============================================================================