SQABasic DDDriverFlowCommands Script

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.)

'$INCLUDE: "DDEngine.SBH"

Internal Dependencies:

(stuff this library needs at compile time.)

(none)

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 
==============================================================================