Studio:AutoScript

From STRIDE Wiki
Revision as of 19:01, 7 July 2008 by Chrisj (talk | contribs)
Jump to navigation Jump to search

 

Introduction 

Ascript is the definitive hierarchy of methods, objects, and properties provided by Autosense. While Autosense helps the user find the script methods/data desired in a script, Ascript is the definitive source of what is available from STRIDE when using Autosense.

The ascript object provides functionality that allows host-based scripts to interact with target-based binaries through the STRIDE Runtime. Through ascript, you can:

  • call target-based functions and messages (synchronously or asynchronously)
  • set and read parameter values orf these functions and messages
  • transparently emulate (mock) target-based functions

Automation API

Ascript

When creating a script, the user types in Ascript followed by dot '.' to get Autosense to display. The user may select methods to be used within his script. The user may access property data within his script. this API is the definitive API for Autosense. The following table outlines the main objects and collections available to the user.

Member
 Type
 Description
Arguments Collection Collection of arguments.
Constants Collection Collection of constants.
Database Object  Database settings.
Functions Collection Collection of functions.
void Initialize (
   String STIDName,
   String databaseFile,
   Integer messageBoxTimeout [optional]
) 		Method Initializes and ascript object instance that has been created outside of tghe STRIDE Studio environment. This call is needed only on an explicitly-created ascript instance. This call should not be made on an ascript instance automatically created and injected into a script by STRIDE Studio.
IsEventPending Property,
Read-only,
bool 		Contains true if there is at least one event in this script's message queue. Events are retrieved from the queue using ascript.WaitForEvent();
LogicalPath Property,
Read-only,
String 		Contains the script's path in the STRIDE Studio workspace tree.
void MessageBox( 
   String message,
   String title [optional], 
   String type
) 		Method Displays a model message box dialog.
Messages Collection Collection of messages.
Output Property,
(String, integer, or object) 		This is the return value from a RunBlocking() call that invoked this script. This works only when the script is invoked using RunBlocking() in the studio object model.
RspTimeoutPeriod Property,
Integer 		This is the timeout threshold for synchronous function and message calls (in milliseconds). A zero value indicates no timeout.
ScriptName Property,
Read-only,
String 		Contains the name of the currently running script with extension and without path. If the current ascript instance was instantiated and initialized outside of STRIDE Studio, this value will reflect the STIDName passed to ascript.Initialize().
void Sleep(
   Integer period
) 		Method Time to pause (in milliseconds). Allowable range is 0 -1440000 (24 hours).
Test Units Collection Collection of test units.
Timers Collection Collection of timers.
Object WaitForEvent ( void ) Method Pauses script execution until an event is detected in this script's event queue.
WaitTimeoutPeriod Property,
String 		The timeout threshold (in milliseconds) for asynchronous function and message calls. A zero value indicates no timeout.


Ascript.Arguments

The Arguments collection represents the arguments passed to a script which has been invoked via one of the following methods of the Studio Object Model's File object:

  • RunBlocking([arg1], [arg2], ...)
  • RunNonBlocking([arg1], [arg2], ...)

The default sort order of the member argument objects is the order in which the arguments were given in the call where the script was invoked.

Member
 Type
 Description
Count Property,
Read-only,
Integer 		Returns the number of Arguments in this collection.

object Item (
    Integer index
)

Method
 Retrieves the argument at the given index. An exception is thrown if the index is out of range.

object Item (
    String name
)

Method
 Retrieves the argument with the given name. If a named argument doesn't exist, null is returned.



Ascript.Arguments.Item

The ascript Arguments Collection's Item() method returns a Argument Object.

Member
 Type
 Description
Name Property,
Read-only,
String

The argument name. The name may have been specified in the studio automation RunBlocking() or RunNonBlocking() call that launched the script or if not specified the name is synthesized by the ascript object.

When synthesized, the name is of the form "Unnamed_N" where 'N' is a monotonically incremented number starting from 0.

Value  Property,
Read-only,
String, Integer, or Object 		The argument value.


Ascript.Constants

The Constants collection contains Constant objects that represent all constants in C/C++ source code compiled by the STRIDE compiler. Constants include all #define symbols and enumerated constants.

Member
 Type
 Description
void ArrangeBy (
   String By [optional],
   String Order [optional]
) 		Method Sorts the Constants collection so that indexing by position yields predictable results.

The 'By' parameter may only be "Name". If not specified, the default is "Name". This represents how Constants should be sorted in the collection.

The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending".

Exception thrown if either argument is outside legal values.
Count Property,
Read-only,
Integer 		Returns the number of Constants in this collection.

object Item (
    Integer index
)

Method
 Retrieves the constant at the given index. An exception is thrown if the index is out of range.

object Item (
    String name
)

Method
 Retrieves the constant with the given name. If a named constant doesn't exist, null is returned.




Ascript.Constants.Item

The ascript Constants Collection's Item() method returns a Constant object.

Member
 Type
 Description
Value  Property,
Read-only,
String 		The value of the constant.



Ascript.Database

Database is an object containing properties related to the database managed by Ascript. You can combine the values of the database path and name to construct a fully-qualified filename. For example:

var dbFullPath = ascript.Database.Path + "\\" + ascript.Database.Name;

Member
 Type
 Description
Name Property,
Read-only,
String 		The name of the database in use. The database name includes the ".sidb" extension.
Path
 Property,
Read-only,
String 		The path to the STRIDE database in use. The path does not contain a trailing backslash.


Ascript.Functions

Accessing Ascript.Functions properties requires getting ahold of an actual function object. Ascript.Functions is actually a collection. Accessing a single function is performed via ascript.Functions.Item.[property]. Below is a table of function attributes that may be retrieved:

Member
 Type
 Description
Name Property,
Read-only,
bool 		Function's name.
Owner Property,
Read-only,
Object 		Function's owner object. The owner object provides access to properties and methods used by the owner-side of the function interface. The owner-side of the interface is used by the implementor of the function.
SUID Property,
Read-Only,
integer 		STRIDE Unique IDentifier assigned by compiler.
Type Property,
Read-Only,
String 		Contains the string "Function".
User Property
Read-Only,
Object 		Function's user object. The user object provides access to properties and methods used by the user-side of the function interface. The user-side of the interface is used by the caller of the function.


Ascript.Functions.Item.Owner

Member
 Type
 Description
IsOverrideRegistered Property,
Read-Only,
bool 		Contains true if owner function override is registered.
IsRegistered Property,
Read-only,
bool 		Contains true if owner function is registered.
Name Property,
Read-only,
bool 		Owner name.
OutPointers Property,
Read-only,
? 		TBD.
ParameterList Property,
Read-only,
Integer 		STRIDE Unique IDentifier assigned by compiler.
HRESULT Register (void) Method Registers owner.
HRESULT RegisterOverride (void) Method Registers owner override.
HRESULT Return (
   bool* result
) 		Method TBD.
ReturnValue Property,
Read-only,
Integer 		STRIDE Unique IDentifier assigned by compiler.
SUID Property,
Read-only,
Integer 		STRIDE Unique IDentifier assigned by compiler.
Type Property,
Read-only,
String 		Contains "Function".
HRESULT Unregister (void) Method Function's user object.
HRESULT UnregisterOverride (void) Method Function's user object.


Ascript.Functions.Item.User

Member
 Type
 Description
HRESULT Call (void) Method TBD.
HRESULTCallBypassOverride (void) Method TBD.
HRESULTCallBypassOverrideNonBlocking (void) Method TBD.
HRESULTCallNonBlocking (void) Method TBD.
IsOverrideRegistered Property,
Read-only,
bool 		Contains true if user override is registered.
IsRegistered Property,
Read-only,
bool 		Contains true if user is registered.
Name Property,
Read-only,
bool 		User function name.
OutPointers Property,
Read-only,
? 		TBD.
ParameterList Property,
'Read-only,
integer 		STRIDE Unique IDentifier assigned by compiler.
ReturnValue Property,
Read-only,
integer 		STRIDE Unique IDentifier assigned by compiler.
SUID Property,
Read-only,
,integer 		STRIDE Unique IDentifier assigned by compiler.
Type Property,
Read-only,
String 		Contains "Function".



Ascript.Messages

Messages is a collection of messages contained and managed through Ascript.

Member
 Type
 Description

object Item (
    integer index
)

Method
 Retrieves the message at the given index.



Ascript.Messages.Item

Member
 Type
 Description
Owner Property,
Read-only,
Object 		Message's owner object.
SMID Property,
Read-only,
integer 		STRIDE Message IDentifier assigned by compiler.
SUID Property,
Read-only,
integer 		STRIDE Unique IDentifier assigned by compiler.
User Property,
Read-only,
Object 		Message's user object.


Ascript.Messages.Item.Owner
Member
 Type
 Description
HRESULT Broadcast (void) Method Broadcast method.
HRESULT Register (void) Method Register method.
HRESULT RegisterOverride (void) Method Register override method.
HRESULT SendRsp (void) Method Send response method.
HRESULT Unregister (void) Method Unregister method.
HRESULT UnregisterOverride (void) Method Unregister override method.


Ascript.Messages.Item.User
Member
 Type
 Description
HRESULT SendAndRead (bool* value) Method Send and read method.

HRESULT SendAndReadBypassOverride (

bool* value

)

Method Send and read bypass override method.
HRESULT SendCmd (void) Method Send command method.
HRESULTSendCmdBypassOverride (
   bool* value
) 		Method Send command bypass override method.
HRESULTSubscribe (void) Method Subscribe method.
HRESULT Unsubscribe (void) Method Unsubscribe method.



Ascript.TestUnits

TestUnits is a collection of test units contained and managed through Ascript.

Member
 Type
 Description
void ArrangeBy (
   String By [optional],
   String Order [optional]
) 		Method Sorts the Test Units collection so that indexing by position yields predictable results.

The 'By' parameter may be either "Name" or "SUID". If not specified, the default is "Name". This represents how Test Units should be sorted in the collection.

The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending".

Exception thrown if either argument is outside legal values.
Count Property,
Read-only,
Integer 		Returns the number of Test Units in this collection.

object Item (
    integer index
)

Method
 Retrieves the test unit at the given index.



Ascript.TestUnits.Item

The Test Unit object represents a captured Test Unit interface in the currently active STRIDE database. A Test Unit object always exists as a member of the TestUnits collection and is accessed from the collection using the item(#) interface.

Member
 Type
 Description
Arguments Object Test Unit parameter list payload.
Name Property,
Read-only,
String 		Test Unit name.
IsRegistered Property,
Read-only,
bool 		Contains true if the Test Unit owner has registered on the target side.
void Run (void)  Method Method to run the test unit.
Suite  Property,
object 		An object of type Reporter's TestSuite. By default after a run this object is a sub-Suite of ascript.TestSuite with the same name as the Test Unit (null if no reporting performed). Setting Suite to a concrete external TestSuite prior to execution will override default creation behavior (set to null to revert to default behavior).
Summary Property,
integer 		Contains static payload object of type srTestCaseTotals_t with result (i.e. pass, fail, in progress, not in use).
Type Property,
Read-only,
String 		Contains test unit type (i.e. TestClass, TestCClass, or TestFList).



Ascript.Timers

The Timers collection manages a set of Timer Objects. The Timers allow scripts to generate periodic or 'one-shot' timed events. Upon creation, the Timers collection is empty. The Timers collection is the only read/write collection in STRIDE; member Timer objects can be added (implicitly created) and removed by scripts. From the collection's point of view, member Timers have two states: dead and alive. Timers are alive upon creation and remain so as long as they exist in the collection. A Timer object that is removed from the collection is considered dead. Any operation on a dead timer will cause an exception to be thrown.

Member
 Type
 Description
object Add (
    object timerObject
) 		Method
 Adds a new timer object.
void ArrangeBy (
   String By [optional],
   String Order [optional]
) 		Method Sorts the Timers collection so that indexing by position yields predictable results.

The 'By' parameter may only be "Name". If not specified, the default is "Name". This represents how Timers should be sorted in the collection.

The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending".

Exception thrown if either argument is outside legal values.
Count Property,
Read-only,
Integer 		Returns the number of Timers in this collection.
object Item (
    integer index
) 		Method
 Retrieves the Timer object for the given index.
object Remove (
    integer index
) 		Method
 Removes the timer at the given index.
A timer object that is removed from the collection is automatically stopped before removal if it is active. No event is generated in this case.



Ascript.Timers.Item

The ascript Timers Collection's Item() method returns a Timer Object. The Timer object enables scripting clients to synthesize and receive timer-based periodic or one-shot events.

When a timer expires and rires its event, the event is queued and can be accessed by the ascript.WaitForEvent() method. The expired timer object will be returned by WaitForEvent();

Member
 Type
 Description
Active Property,
Read-only,
bool 		Contains timer operation state. True if timer is in operation (i.e. it will generate an event at some time in the future). A newly created timer is inactive by default.
Id Property,
Read-only,
long 		Contains timer identifier.
Duration Property,
long 		Timer duration in milliseconds.
Name Property,
Read-only,
String 		Name assigned when the timer was created. Default names are "Timer_n" where 'n' is the nth named time created by this ascript object.
Periodic Property,
bool  		When false, the time will fire only once (one-shot mode). When true, the time automatically restarts after each event is fired. This property can be changed regardless of the state of the timer. This field is false by default when a timer is created. 
void Start (void) Method
 Transitions an inactive timer to active. Once started, the timer will run for the length of time specified by its Duration property. Calling Start on a timer with a zero/negative duration will cause an exception to be thrown. Calling Start on a timer that has already started will also cause an exception to be thrown.
void Stop (void) Method
 Transitions an active timer to inactive. Calling Stop on a timer that is not active will cause an exception to be thrown.
Type Property,
Read-only,
String 		Contains the string "Timer". This property is typically used to classify an object that is returned from ascript.WaitForEvent().
Retrieved from "https://www.stridewiki.com/index.php?title=Studio:AutoScript&oldid=5830"