Test Script Services Reference

prevnext

Synchronization Class


Use the synchronization methods to synchronize virtual testers during script playback. You can insert synchronization points and wait periods, and you can manage variables shared among virtual testers.


Applicability

Commonly used with TestManager.


Summary

The following table lists the synchronization methods. They are static methods of class TSSSync.

Method Description
sharedVarAssign() Performs a shared variable assignment operation.
sharedVarEval() Gets the value of a shared variable and operates on the value as specified.
sharedVarWait() Waits for the value of a shared variable to match a specified range.
syncPoint() Puts a synchronization point in a script.


TSSSync.sharedVarAssign()

Performs a shared variable assignment operation.


Syntax

void sharedVarAssign(String name, int val, int op, TSSInteger 
returnVal)

Element Description
name The name of the shared variable to operate on.
value The right-side value of the assignment expression.
op Assignment operator. Can be one of the following:
  • SHVOP_assign

  • SHVOP_add

  • SHVOP_subtract

  • SHVOP_multliply

  • SHVOP_divide

  • SHVOP_modulo

  • SHVOP_and

  • SHVOP_or

  • SHVOP_xor

  • SHVOP_shiftleft

  • SHVOP_shiftright

returnVal OUTPUT. If not specified as NULL, the resulting value of name after application of op value.


Exceptions

These methods may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

Shared variables require configuration. For details, see the following example and Appendix A.


Example

This example adds 5 to the value of the shared variable lineCounter, puts the new value of lineCounter in returnval, and configures the variable by adding it to an array naming all shared variables used in the script. This configuration code can occur anywhere in the script.

TSSInteger returnVal = new TSSIngeger(0);
TSSSync.sharedVarAssign("lineCounter", 5, SHVOP_add, returnVal);
...
public static class SharedVarConfig extends SharedVarInfo {
	 public SharedVarConfig() {
	 	 String sv[] = {
	 	 	 "lineCounter",
	 	 	 ....
	 	 }
	 	 setSharedVarNames(sv);
	 }
}

See Also

sharedVarEval(), sharedVarWait()


TSSSync.sharedVarEval()

Gets the value of a shared variable and operates on the value as specified.


Syntax

void sharedVarEval(String name, TSSInteger value, int op)

Element Description
name The name of the shared variable to operate on.
value OUTPUT. A local container into which the value of name is retrieved. For the implementation of this argument's data type, see TSSInteger.
op Increment/decrement operator for the returned value: Can be one of the following:
  • SHVADJ_none SHVADJ_pre_inc

  • SHVADJ_post_inc

  • SHVADJ_pre_dec

  • SHVADJ_post_dec


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

Shared variables require configuration. For details, see Appendix A.


Example

This example post-decrements the value of shared variable lineCounter and stores the result in val.

TSSInteger val = new TSSInteger(0);
TSSSync.sharedVarEval("lineCounter",val,SHVADJ_post_inc);

See Also

sharedVarAssign(), sharedVarWait()


TSSSync.sharedVarWait()

Waits for the value of a shared variable to match a specified range.


Syntax

int sharedVarWait(String name, int min, int max, int adjust, 
int timeout, TSSInteger returnVal)
int sharedVarWait(String name, int min)

Element Description
name The name of the shared variable to operate on.
min The low range for the value of name.
max The high range for the value of name.
adjust The value to increment/decrement the named shared variable by once it meets the min - max range.
timeout The time-out preference (how long to wait for the condition to be met). Enter one of the following:
  • A negative number for no time-out.

  • 0 to return immediately with an exit value of 1 (condition met) or 0 (not met).

  • The number of milliseconds to wait for the value of name to meet the criteria, before timing out with and returning an exit value of 1 (met) or 0 (not met).

returnVal OUTPUT. The value of name at the time of the return, before any possible adjustment. If timeout expired before the return, the value is not adjusted. Otherwise, returnVal is incremented/decremented by adjust. For the implementation of this argument's data type, see TSSInteger.


Return Value

On success, this method returns 1 (condition was met before time-out) or 0 (time-out expired before the condition was met).


Exceptions

These methods may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

This call provides a method of blocking a virtual tester until a user-defined global event occurs.

If virtual testers are blocked on an event using the same shared variable, TestManager guarantees that the virtual testers are unblocked in the same order in which they were blocked.

Although this alone does not ensure an exact multiuser timing order in which statements following a wait are executed, the additional proper use of the arguments min, max, and adjust allows control over the order in which multiuser operations occur. (UNIX or Windows NT determines the order of the scheduling algorithms. For example, if two virtual testers are unblocked from a wait in a given order, the tester that was unblocked last might be released before the tester that was unblocked first.)

If a shared variable's value is modified, any subsequent attempt to modify this value -- other than through sharedVarWait() -- blocks execution until all virtual testers already blocked have had an opportunity to unblock. This ensures that events cannot appear and then quickly disappear before a blocked virtual tester is unblocked. For example, if two virtual testers were blocked waiting for name to equal or exceed N, and if another virtual tester assigned the value N to name, then TestManager guarantees both virtual testers the opportunity to unblock before any other virtual tester is allowed to modify name.

Offering the opportunity for all virtual testers to unblock does not guarantee that all virtual testers actually unblock, because if sharedVarWait() is called with a nonzero value of adjust by one or more of the blocked virtual testers, the shared variable value changes during the unblocking script. In the previous example, if the first user to unblock had called sharedVarWait() with a negative adjust value, the event waited on by the second user would no longer be true after the first user unblocked. With proper choice of adjust values, you can control the order of events.

Shared variables require configuration. For details, see Appendix A.


Example

This example returns 1 if the shared variable inProgress reaches a value between 10 and 20 within 60000 milliseconds of the time of the call. Otherwise, it returns 0. svVal contains the value of inProgress at the time of the return, before it is adjusted. (In this case, the adjustment value is 0 so the value of the shared variable is not adjusted.)

TSSInteger svVal = new TSSInteger(0);
int retVal= TSSSync.sharedVarWait("inProgress",10,20,0,60000,svVal);

See Also

sharedVarAssign(), sharedVarEval()


TSSSync.syncPoint()

Puts a synchronization point in a script.


Syntax

void syncPoint(String label)

Element Description
label The name of the synchronization point.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

A script pauses at a synchronization point until the release criteria specified by the suite have been met. If the criteria are met, the script delays a random time specified in the suite and then resumes execution.

Typically, it is better to insert a synchronization point into a suite from TestManager rather than use the syncPoint() call inside a script.

If you insert a synchronization point into a suite, synchronization occurs at the beginning of the script. If you insert a synchronization point into a script with syncPoint(), synchronization occurs at the point of insertion. You can insert the command anywhere in the script.

Shared variables require configuration. For details, see the following example and Appendix A.


Example

This example creates a sync point named BlockUntilSaveComplete and configures the sync point. The configuration statement may appear anywhere inside the script.

TSSSync.syncPoint("BlockUntilSaveComplete");
...
public static class SyncPointConfig extends SyncPointInfo {
        public SyncPointConfig() {
            String points[] = {
                "BlockUntilSaveComplete"};
            setSyncPointNames(points);
	 	 	 }
}

prevnext


Rational Test Script Services for Java Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com