Home • Corporate • Contacts •

TETware Java API Overview

Products

Solutions

Information

Datasheet

Documentation

FAQ

Knowledgebase

13. Test Case Synchronization

Introduction

This method enables parts of a distributed test purpose or user-supplied startup or cleanup method that are running on different systems to synchronize to an agreed point in the executing code. Refer to the chapter entitled "Test case synchronisation'' in the TETware User Guide for an overview of TETware synchronisation.

tet_remsync()

      // public class TestSession
      public void tet_remsync(long syncptno, int[] sysnames, int waittime,
                 int vote, SyncMessage msg) throws TetException

A call to tet_remsync() causes the calling process's system to synchronise with one or more of the other systems that are participating in the same distributed test case. The call can only succeed if each of the systems specified in the call also expect to synchronise with each other and with the calling process.

sysnames is a list of IDs of the other systems with which the calling process wishes to synchronise. The system ID of the calling process is ignored if it appears in the list.

syncptno specifies the sync point number to which the calling process wishes to synchronise. If syncptno is zero, a successful call to tet_remsync() returns as soon as all participating systems have synchronised to the next sync point. If syncptno is greater than zero, a successful call to tet_remsync() returns as soon as all participating systems have synchronised using a sync point number which is not less than syncptno. When syncptno is greater than zero, a call to tet_remsync() will fail if a sync point has already occurred during the lifetime of the current test case whose number is greater than or equal to syncptno. The results are undefined if a negative syncptno is specified.

waittime specifies the number of seconds that may elapse between synchronisation requests from other participating systems before the calling process times out. If waittime is greater than zero, a call to tet_remsync() will be successful if all the participating systems synchronise to the specified sync point with no more than waittime seconds between each request. If waittime is zero, a call to tet_remsync() will return immediately, whether or not it is successful. If waittime is negative, a call to tet_remsync() will wait indefinitely for the specified sync point to occur or until the request fails for some reason. Test suite authors should be aware of the potential for deadlock if a negative waittime is specified.

vote specifies how the calling system wishes to vote in the synchronisation event. This parameter should be set to one of the defined constants TET_SV_YES or TET_SV_NO, to indicate a yes vote or a no vote, respectively. These constants are defined in the TestSession class. When the calling process specifies a yes vote, a call to tet_remsync() can only be successful if all the other participating systems also specify a yes vote. When the calling process specifies a no vote, the API does not use the votes specified by the other participating systems when determining whether or not a call to tet_remsync() in that process is successful.

It is possible for a process which calls tet_remsync() to exchange sync message data with other participating systems which synchronise exactly to the sync point specified by syncptno. This is done by calling tet_remsync() with a non-null value of msg. When msg is non-null, it refers to a user-supplied SyncMessage object.

When tet_remsync() is called by parts of a distributed test purpose, one system sends data which may be received by other systems. The API associates the sync message data with the particular sync point specified by the syncptno parameter used in the tet_remsync() call on the sending system. In order to receive the message data, the syncptno parameter in calls to tet_remsync() on receiving systems must reference this sync point exactly, either by specifying the same value for syncptno as that used on the sending system, or by specifying a zero syncptno.

The test purpose part on the sending system should indicate a desire to send sync message data by creating a SyncMessage object prepared for the transmission of a message, like this:

         data = new byte[] { (byte)1, (byte)2, (byte)3 };
         msg = new SyncMessage(data);

The test purpose part on the sending system should indicate their willingness to receive sync message data by creating a SyncMessage object prepared for the reception of a message, like this:

         msg = new SyncMessage(SyncMessage.TET_SMMSGMAX);

If the call to tet_remsync() is successful, then on return the SyncMessage object on each system can be examined to determine the outcome of the data transfer. You can use the following methods to do this:

         message()
         truncated()
         duplicated()
         sender()
         getSysID()

If more than one system tries to send sync message data for a particular sync point, tet_remsync() chooses one system from which to accept data and re-designates the other sending systems as receiving systems. After the call to tet_remsync() returns, the SyncMessage objects on all systems will return true on the duplicated() method and sender() will return true on the single sending system and false on the re-designated systems.

If a process tries to send a message which is larger than the maximum permitted message size, as defined by SyncMessage.TET_SMMSGMAX, the message is truncated to the maximum size before sending, and SyncMessage.truncated() will return true on all systems after the call.

If a process running on a particular systems calls tet_remsync() with a null msg, then the API regards it as a receiving system but does not return any message data to it.

This function does not return a value.

tet_remsync() throws a TetException object if the API encounters an error while processing the request. An error can occur as a result of one of the following conditions:

• More than waittime seconds elapse between synchronisation requests from participating systems.
• A related synchronisation request times out on one of the other participating systems.
• The user-supplied method in a test case on one of the other participating systems returns control to its TCM before synchronising.
• The sync point specified by syncptno has already occurred.
• A yes sync vote is specified in the call but another participating system specifies a no vote for this sync point.
• sysnames is null.
• A system ID appears more than once in the sysnames array.
• An invalid parameter is specified in the call.
• The API encounters a problem while processing the request.

The TetException object thrown contains an array of SyncState objects in the public field sync_state. The elements of this array give details of the synchronisation states for each of the other systems participating in the event. The SyncState class contains the following fields:

      /**
       * System ID.
       */
      public int tsy_sysid;
      /**
       * State of synchronization. Consists of a bit mask of TET_SS_..
       * values.
       */
      public int tsy_state;
      The TET_SS_.. values are defined in the SyncState class. They are:
      /**
       * Value for tsy_state, indicating that the
       * synchronization request was not received.
       */
      public static final int TET_SS_NOTSYNCED = 1;
      /**
       * Value for tsy_state, indicating that the system voted
       * YES.
       */
      public static final int TET_SS_SYNCYES                   = 2;

      /**
       * Value for tsy_state, indicating that the system voted
       * NO.
       */
      public static final int TET_SS_SYNCNO                   = 3;
      /**
       * Value for tsy_state, indicating that the system timed
       * out.
       */
      public static final int TET_SS_TIMEDOUT = 4;
      /**
       * Value for tsy_state, indicating that the process
       * exited.
       */
      public static final int TET_SS_DEAD                     = 5;

The TetException object thrown also contains the following field:

      /**
       * The sync point at which this exception occurred.
       */
      public long syncpt;

In TETware-Lite, this method always throws a TetException object. Refer to the corresponding section in the chapter entitled "The C API" in the TETware Programmers Guide.

Refer to the corresponding section in the chapter entitled "The C API" in the TETware Programmers Guide.

Return to Contents