SQABasic "DDDriverFlowCommands" Script

 MODULE DESCRIPTION:

 The documentation for each function is provided as reference for DDE users
 when developing DDE test tables.  This DDE format and syntax information IS
 intended for public use and does not normally change with the underlying code.

 The routines themselves are not intended for public use.
 Their internal functionality and their declaration prototypes
 are subject to change as deemed necessary to support the drivers
 mentioned above.


 This library is defined by:

 DDDriverFlowCommands.SBL      Sourcecode and Detailed Documentation
 DDDriverFlowCommands.SBX      Compiled executable library

 Orig Author: Carl Nagle
 Orig   Date: JUL 16, 2002
 History:

      JUL 16, 2002    Original Release. Extracted from DDDriverCommands.SBL
      AUG 08, 2002    (YWANG)  Added DriverCommands OnGUIExistsGotoBlockID, OnGUINotExistGotoBlockID
      OCT 22, 2002    (CANAGL) Warn of unimplemented CF and CW record types.
      FEB 25, 2004    (YWANG)  Changed Block ID lookup to allow variable/expression
      APR 19, 2004    (CANAGL) Increment GeneralSuccess when processing EXITTABLE.
      JUN 17, 2004    (YWANG)  Changed to better handle Block ID lookup
      MAR 29, 2005    (RDUCHARME) Fixed double counting of errors if block ID does not exist
      APR 01, 2005    (RDUCHARME) Added logic to support table caching
      JUL 20, 2005    (CHSCHR) Added OnMenuItemContainsStateGoToBlockID
      JUL 20, 2005    (CHSCHR) Added OnPartialMenuItemContainsStateGoToBlockID
      NOV 15, 2005    (bolawl) Updated Failure message in DDELocateBlockID and Changed all
                               "Missing Required Parameter" messages from WARNINGS to FAILURES. (RJL)

 Copyright (C) SAS Institute
 GNU General Public License: http://www.opensource.org/licenses/gpl-license.php
Action Commands Global Variables 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.)

DDE Action Commands

   *** NO SUPPORTED ACTION COMMANDS SECTION FOUND ***

Globals

    (none)

Routine Details



  Function DDECallScript(scriptName as String,
                         guiInfo As AUGUIInfo,
                         statusInfo As AUStatusInfo
                        ) As Integer

 DESCRIPTION:

      Invokes an automation tool script with the provided scriptName.  The
      routine logs the start and end of the script and sets and receives
      the global ApplicationUtilities' ScriptGUIInfo and ScriptStatusInfo
      structures for the script.  ApplicationUtilities also contains the
      routines necessary to increment appropriate test status counters.

      No error detection is done on the provided scriptName.  The script should
      already have been verified to exist prior to this call.  This is handled
      by the DDEDriverCommand and DDEImpliedCallScript routines.


      CALLING A SCRIPT AND PASSING PARAMETERS TO IT:

      You should assign script arguments or parameters to DDVariables as shown in the
      example below.  You can simply retrieve the value of each variable using
      the DDVariableStore.DDVGetVariableValue routine.

      CALLING SCRIPTS EXAMPLES:

      EnterNewUser   ^name.first=John   ^name.last=Smith   ^dept=BST   ^ext=x9999
      or
      C   CallScript   EnterNewUser   ^name.first=John   ^name.last=Smith   ^dept=BST   ^ext=x9999

      < continue with more table records >

      See Using DDVariables for more information on this nifty capability!


      This routine is not intended for public use.
      Internal functionality and declaration prototypes
      are subject to change as deemed necessary to support the core drivers.


 PARAMETERS:

      scriptName      String name of the script to call. (no file extension)
      AUGUIInfo       from the calling Driver
      AUStatusInfo    from the calling Driver

 RETURNS:

      Returns DDU_NO_SCRIPT_FAILURE if Script processing occurred.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: APR 23, 2001
 History:

      APR 23, 2001    Original Release




  Function DDEDriverFlowCommand(DriverCMD As String, guiInfo As AUGUIInfo, statusInfo As AUStatusInfo) As Integer

 DESCRIPTION:

      Processes a DDE DRIVER COMMAND from the AUGUIInfo.InputRecord provided.
      Driver commands are not treated as test commands but instructions to
      the Drivers for setting parameters of the test environment, running
      other scripts, or other stuff (whatever gets in here).

      Different driver commands have different parameters as described below.
      For reference, the first fields are defined below:

      Field #1:   The "C" = DRIVER COMMAND.
      Field #2:   The Driver Command to execute. (see definitions below).

      Example:

          c , SetApplicationMap , "AppMap.map"


      Parameters must be placed in the order specified.
      Parameters numbered in brackets are optional.
      However, to use an optional parameter which follows other optional
      parameters all the preceding parameters must exist or at least have
      field delimited space reserved for them.


         COMMAND         Fld# PARAMETER
      ==============      ====================================================

      CallScript          3 - The name of the script to execute.
                              Since the script is executed as a command of the
                              Driver and NOT a test; test_record, test_passes, and
                              test_failures information within the AUStatusInfo structure
                              is not updated.  If the called script wishes to record
                              tests attempted, pass, and failure counts then it must
                              do so itself by updating the ScriptStatusInfo fields
                              accordingly.  The name of the script must not include
                              the file extension.
                          4-N Any number of parameters you wish to pass to the script.
                              These parameters are passed as DDVariables.
                              The Script can retrieve DDVariable values from the DDVariableStore.
                              These parameters are, of course, specific to each called script.
                              The variables and their values are available to the script
                              and the rest of the DDE.


      CallCycle           3 - The name of the Cycle table to execute.
                              Since the Cycle is executed as a driver command
                              and NOT as test record; the call to the Cycle itself is
                              not calculated as a test pass or fail.

                          4 - The field separator needed for this file if different from what may
                              already be set for CycleDriver. Use an empty string ("") to keep
                              the current separator.

                          5-N Any number of parameters you wish to pass to the Cycle.
                              These parameters can be passed as literals or as DDVariables.



      CallSuite           3 - The name of the Suite table to execute.
                              You cannot use the command in a Cycle table.
                              Since the suite is executed as a driver command
                              and NOT as test record; the call to the suite itself is
                              not calculated as a test pass or fail.

                          4 - The field separator needed for this file if different from what may
                              already be set for SuiteDriver. Use an empty string ("") to keep
                              the current separator.

                          5-N Any number of parameters you wish to pass to the suite.
                              These parameters can be passed as literals or as DDVariables.



      CallStep            3 - The name of the framework Step table to execute.
                              The command is only applicable at the Step level.
                              You do not use this command within Suites or Cycles.
                              Since the CallStep is executed as a command of the
                              StepDriver and NOT as test record; the call to the Step table itself is
                              not calculated as a test pass or fail.

                          4 - The field separator needed for this file if different from what may
                              already be set for StepDriver. Use an empty string ("") to keep
                              the current separator.

                          5-N Any number of parameters you wish to pass to the Step table.
                              These parameters can be passed as literals or as DDVariables.



        ExitTable           - Immediately exit the current table.  No parameters required.


        ExitSuite           - Immediately exit the current Step AND Suite table.
                              No parameters required.


        ExitCycle           - Immediately exit the current Step, Suite, AND Cycle table.
                              No parameters required.


       GotoBlockID        3 - The BlockID within the current table to find and
                              transfer control to.


   OnEqualGotoBlockID     3 - The BlockID within the current table to find and
                              transfer control to IF the two values in Fields 4 and 5
                              are equal.
                          4 - value1 for the comparison.
                          5 - value2 for the comparison.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred. If the values
                              can be converted to numbers they are converted and a
                              numerical comparison is performed.  If the values cannot
                              be converted to numbers then a string comparison is performed
                         [6]- string comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison for string comparisons. Omit or set to any other value
                              to perform a case-sensitive string comparison.


   OnLessThanGotoBlockID  3 - The BlockID within the current table to find and
                              transfer control to IF the value in Field 4 is less than
                              the value in Field 5 via a numeric or string comparison.
                          4 - value to be compared.
                          5 - value to be compared against.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred. If the values
                              can be converted to numbers they are and a numerical
                              comparison is performed.  If the values cannot be converted to
                              numbers a string comparison is used.
                         [6]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.


 OnGreaterThanGotoBlockID 3 - The BlockID within the current table to find and
                              transfer control to IF the value in Field 4 is greater than
                              the value in Field 5 via a numeric or string comparison
                          4 - value1 number to be compared.
                          5 - value2 number to be compared against.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred. If the values
                              can be converted to numbers they are and a numerical
                              comparison is performed.  If the values cannot be converted to
                              numbers a string comparison is used.
                         [6]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.


   OnInRangeGotoBlockID  3 - The BlockID within the current table to find and
                              transfer control to IF Field 4 is within the range
                              identified by Field 5 and Field 6 values via a numeric
                              or string comparison
                          4 - value1 number to be compared.
                          5 - value2 low end of range to compared against.
                          6 - value3 high end of range to compared against.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred  If the values
                              can be converted to numbers they are and a numerical
                              comparison is performed.  If the values cannot be converted to
                              numbers a string comparison is used.
                         [7]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison string comparison. Omit or set to any other value to
                              perform a case-sensitive comparison.


   OnNotInRangeGotoBlockID  3 - The BlockID within the current table to find and
                              transfer control to IF Field 4 is not within the range
                              identified by Field 5 and Field 6 values via a numeric
                              or string comparison
                          4 - value1 number to be compared.
                          5 - value2 low end of range to compared against.
                          6 - value3 high end of range to compared against.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred. If the values
                              can be converted to numbers they are and a numerical
                              comparison is performed.  If the values cannot be converted to
                              numbers a string comparison is used.
                         [7]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              string comparison. Omit or set to any other value to
                              perform a case-sensitive string comparison.


   OnContainsGotoBlockID  3 - The BlockID within the current table to find and
                              transfer control to IF the value in Field 4 contains Field 5
                              pass a case-sensitive string comparison.
                          4 - value1 for the case-sensitive comparison.
                          5 - value2 for the case-sensitive comparison.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                         [6]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.



   OnNotContainsGotoBlockID  3 - The BlockID within the current table to find and
                              transfer control to IF the value in Field 4 does not contain Field 5
                              pass a case-sensitive string comparison.
                          4 - value1 for the case-sensitive comparison.
                          5 - value2 for the case-sensitive comparison.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                         [6]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.



   OnNotEqualGotoBlockID  3 - The BlockID within the current table to find and
                              transfer control to IF the two values in Fields 4 and 5
                              do not pass a case-sensitive string comparison.
                          4 - value1 for the case-sensitive comparison.
                          5 - value2 for the case-sensitive comparison.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                         [6]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.



   OnFileExistGotoBlockID 3 - The BlockID within the current table to find and
                              transfer control to IF the file in field 4
                              exists.
                          4 - filename of file for existince verification.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                              The file is assumed to be in Datapool\Test unless
                              the user specifies a full or relative path to some
                              other location. If a relative path is specified, it is
                              relative to the project directory.
                         [5]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.



   OnFileNotExistGotoBlockID

                          3 - The BlockID within the current table to find and
                              transfer control to IF the file in field 4
                              does not exist.
                          4 - filename of file for existince verification.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                              The file is assumed to be in Datapool\Test unless
                              the user specifies a full or relative path to some
                              other location. If a relative path is specified, it is
                              relative to the project directory.
                         [5]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.


   OnDirectoryExistGotoBlockID

                          3 - The BlockID within the current table to find and
                              transfer control to IF the Directoryname in field 4
                              exists.
                          4 - directoryname of directory for existince verification.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                              The directory always requires to be specified in a full
                              path to some other location.
                         [5]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.



   OnDirectoryNotExistGotoBlockID

                          3 - The BlockID within the current table to find and
                              transfer control to IF the Directory in field 4
                              does not exist.
                          4 - directoryname of directory for existince verification.
                              Values are retrieved with GetTrimmedQuotedField AFTER
                              normal variable substitutions have occurred.
                              The directory always requires to be specified in a full
                              path to some other location.
                         [5]- comparison mode. (Default to case-sensitive mode)
                              Set to "CaseInsensitive" to perform a case-insensitive
                              comparison. Omit or set to any other value to perform a
                              case-sensitive comparison.


   OnGUIExistsGotoBlockID 3 - The BlockID within the current table to find and
                              transfer control to IF the GUI component specified
                              in Fields 4 and 5 is found on the screen within the
                              timeout period.
                          4 - The WINDOW ID of the object to look for. Use the named
                              reference given the window in the application map.
                          5 - The COMPONENT ID of the object to look for. Use the
                              named reference given the component in the application
                              map. If the window IS the object to look for then both
                              field 4 and 5 will be the same.
                         [6]- maximum timeout in seconds to wait for the GUI before
                              exiting (no branch). Default is 15 seconds.


   OnGUINotExistGotoBlockID   3 - The BlockID within the current table to find and
                                  transfer control to IF the GUI component specified
                                  in Fields 4 and 5 is not found on the screen within
                                  the timeout period.
                              4 - The WINDOW ID of the object to look for. Use the named
                                  reference given the window in the application map.
                              5 - The COMPONENT ID of the object to look for. Use the
                                  named reference given the component in the application
                                  map. If the window IS the object to look for then both
                                  field 4 and 5 will be the same.
                             [6]- maximum timeout in seconds to wait for the GUI to
                                  disappear before exiting (no branch). Default is 15 seconds.


   OnMenuItemContainsStateGotoBlockID
                          3 - The BlockID within the current table to find and
                              transfer control to if the value in Field 5 is
                              part of the state information of the menuitem in Field 6.
                          4 - The window name from the data table
                          5 - The component name from the data table
                          6 - Menu->MenuItem hierarchy string to identify which menuitem
                              to test. This menu hierarchy is case-sensitive
                          7 - Expected status string (or part thereof) to verify.
                              Ex: "Enabled Checked" OR "Disabled Grayed" etc. Each item
                              separated by a space will be evaluated separately so the order
                              of the status items does not matter. These status items are
                              case-sensitive.

   OnPartialMenuItemContainsStateGotoBlockID
                          3 - The BlockID within the current table to find and
                              transfer control to if the value in Field 5 is
                              part of the state information of the menuitem in Field 6.
                              This command allows for a partial match on the menuItem.
                          4 - The window name from the data table
                          5 - The component name from the data table
                          6 - Menu->MenuItem hierarchy string to identify which menuitem
                              to test. This menu hierarchy is case-sensitive
                          7 - Expected status string (or part thereof) to verify.
                              Ex: "Enabled Checked" OR "Disabled Grayed" etc. Each item
                              separated by a space will be evaluated separately so the order
                              of the status items does not matter. These status items are
                              case-sensitive.


 SetNoScriptFailureBlock [3] - The BlockID within the current table to execute
                              upon NoScriptFailure status.  Clear the setting
                              by using an empty string "" or by providing no
                              BlockID.


 SetGeneralScriptFailureBlock [3] - The BlockID within the current table to execute
                              upon GeneralScriptFailure status.  Clear the setting
                              by using an empty string "" or by providing no
                              BlockID.


 SetScriptWarningBlock   [3] - The BlockID within the current table to execute
                              upon ScriptWarning status.  Clear the setting
                              by using an empty string "" or by providing no
                              BlockID.


 SetInvalidFileIOBlock   [3] - The BlockID within the current table to execute
                              upon InvalidFileIO status.  Clear the setting
                              by using an empty string "" or by providing no
                              BlockID.


 SetExitTableBlock       [3] - The BlockID within the current table to execute
                              upon ExitTable command.  Clear the setting
                              by using an empty string "" or by providing no
                              BlockID.


 SetScriptNotExecutedBlock [3] - The BlockID within the current table to execute
                              upon ScriptNotExecuted error.  Clear the setting
                              by using an empty string "" or by providing no
                              BlockID.



      This DDEDriver Command routine is not intended for public use.
      Internal functionality and declaration prototypes
      are subject to change as deemed necessary to support the core drivers.


 PARAMETERS:

      DriverCMD       from the calling DDDriverCommands library.
      AUGUIInfo       from the calling Driver
      AUStatusInfo    from the calling Driver

 RETURNS:

      Normally DDU_NO_SCRIPT_FAILURE unless something unforeseen causes the
      routine to exit prematurely.

      Returns DDU_SCRIPT_NOT_EXECUTED if no matching driver command was found.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 16, 2002
 History:

      JUL 16, 2002    Original Release Extracted from DDDriverCommands.SBL
      AUG 08, 2002    (YWANG)  Added DriverCommands OnGUIExistsGotoBlockID, OnGUINotExistGotoBlockID
      OCT 22, 2002    (CANAGL) Warn of unimplemented CF and CW record types.
      NOV 27, 2002    (jaimbr) Added DriverFlowCommand OnContainsGotoBlockID
      MAY 05, 2003    (rdant) Added Driver Flow Commands OnLessThanGotoBlockID, OnGreaterThanGotoBlockId
      MAY 13, 2003    (rdant) Added Driver Flow Commands OnInRangeGotoBlockID, OnNotInRangeGotoBlockId
      APR 19, 2004    (CANAGL) Increment GeneralSuccess when processing EXITTABLE.
      NOV 05, 2004    (RDUCHARME)   Added OnNotContainsGotoBlockID to script
      MAR 29, 2005    (RDUCHARME)   Added flags to DDELocateBlockID calls to avoid counting errors more than once.
      APR 26, 2005    (CANAGL) Removed Warning of unimplemented CF and CW record types.  Duplicate warnings issued.
      JUL 20, 2005    (CHSCHR) Added OnMenuItemContainsStateGoToBlockID
      JUL 20, 2005    (CHSCHR) Added OnPartialMenuItemContainsStateGoToBlockID
      NOV 15, 2005    (bolawl) Changed all "Missing Required Parameter" messages from WARNINGS to FAILURES. (RJL)


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