LibCommon_Sync.ttcn

          log("**** f_clientSync: Execution status indicates that execution of test component behavior was not successful - sync client will ask sync server to stop test case! ****") ;
          f_clientSendStop(); // function will not return!
        }
        if ( p_syncId == c_prDone ) {
          log("**** f_clientSync: Sync client successfully passed PREAMBLE synchronization point. ****") ;
        } else if ( p_syncId == c_tbDone ) {
          log("**** f_clientSync: Sync client successfully passed TEST BODY synchronization point. ****") ;
        } else {
          log("**** f_clientSync: Sync client successfully passed synchronization point. ****") ;
        }
        return e_success ;

      } // end function f_clientSync

      /**
       * @desc   This function can be used to request the shutdown a
       *         multi component test case _prior_ to reaching a
       *         synchronization point. It sends a STOP message to
       *         the sync server and awaits then the STOP from the server
       *         which will trigger the shutdown default (if activated).
       *         This function will set the server verdict to INCONC (and
       *         stop the test case) if no shutdown default is activated.
       *         This function will set only the client verdict to INCONC
       *         (and stop its execution) if no STOP response is received
       *         from the server within the PX_TSYNC_TIME_LIMIT
       *         or if no shutdown default is activated. In all other
       *         cases the client verdict is NOT set.
       * @remark The use of this function requires prior connection
       *         of the client sync port!
       * @see    LibCommon_Sync.f_connect4ClientSync
       * @see    LibCommon_Sync.f_connect4SelfOrClientSync
       * @see    LibCommon_Sync.PX_TSYNC_TIME_LIMIT
       * @see    LibCommon_Sync.a_dummyShutDown
       */
      function f_clientSendStop()
      runs on ClientSyncComp {
        log("**** f_clientSendStop: Sync client requesting from server to stop test case (including itself). ****") ;
        syncPort.send(m_syncClientStop) ;
        tc_sync.start;
        alt{
          [] tc_sync.timeout{
              log("**** f_clientSendStop: Stopping sync client without shutdown - either no shutdown default active or no stop received from server. ****") ;
              setverdict(inconc);
              stop ;
             }
        }//end alt
        tc_sync.stop;
        stop; // stop here if shutdown default does not stop
      }

    } // end group clientRelated

  } // end group advancedUserRelevantDefinitions

  group otherSyncModuleDefinitions {

    group syncModuleparams {
      /**
       *
       * @desc  Default time limit for a sync client to reach a
       *        synchronization point
       */
      modulepar float PX_TSYNC_TIME_LIMIT := 120.0;

      /*
       * @desc  Default time limit for a sync client to finish
       *        its execution of the shutdown default
       */
      modulepar float PX_TSHUT_DOWN_TIME_LIMIT := 120.0;
    }

    group otherSyncTypes {

      type record of charstring SyncPointList;

      type record of ClientSyncComp ClientSyncCompList;

    } // end group otherSyncTypes

    group otherSelfSyncRelatedDefinitions {

      /**
       * @desc  This function creates the connection needed to
       *        execute self sync functions
       * @see   LibCommon_Sync.f_selfSync
       * @see   LibCommon_Sync.f_selfSyncStop
       */
      function f_connect4SelfSync()
      runs on SelfSyncComp {
        connect(self:syncSendPort, self:syncPort);
      }// end function f_connect4SelfSync

      /**
       * @desc  This function removes the connection needed
       *        to execute self sync functions
       * @see   LibCommon_Sync.f_selfSync
       * @see   LibCommon_Sync.f_selfSyncStop
       */
      function f_disconnect4SelfSync()
      runs on SelfSyncComp {
        disconnect(self:syncSendPort, self:syncPort);
      }// end function f_disconnect4SelfSync

      /**
       * @desc  This function combines MTC verdict setting with self
       *        synchronization for use in the preamble / test body / postamble
       * @param p_syncId Synchronization point name/id
       * @param p_ret Current behavior execution status
       * @see   LibCommon_VerdictControl.f_setVerdict
       * @see   LibCommon_Sync.f_selfSync
       * @see   LibCommon_Sync.a_dummyShutDown
       */
      function f_selfSyncAndVerdict(  in charstring p_syncId,
                      in FncRetCode p_ret )
      runs on SelfSyncComp {
        if(vc_testcaseStep == e_preamble) {
            f_selfSyncAndVerdictPreamble(p_syncId, p_ret);
        } else if(vc_testcaseStep == e_testBody) {
            f_selfSyncAndVerdictTestBody(p_syncId, p_ret);
        }
        else {
            f_selfSyncAndVerdictPostamble(p_syncId, p_ret);
        }
      }

      /**
       * @desc  This function combines MTC verdict setting with self
       *        synchronization for use after the preamble.
       * @param p_syncId Synchronization point name/id
       * @param p_ret Current behavior execution status
       * @see   LibCommon_VerdictControl.f_setVerdictPreamble
       * @see   LibCommon_Sync.f_selfSync
       */
      function f_selfSyncAndVerdictPreamble(  in charstring p_syncId,
                          in FncRetCode p_ret )
      runs on SelfSyncComp {
        f_setVerdictPreOrPostamble(p_ret);
        f_selfSync(p_syncId,p_ret);
        vc_testcaseStep := e_testBody;
      }
      
      /**
       * @desc  This function combines MTC verdict setting with self
       *        synchronization for use after the test body.
       * @param p_syncId Synchronization point name/id
       * @param p_ret Current behavior execution status
       * @see   LibCommon_VerdictControl.f_setVerdict
       * @see   LibCommon_Sync.f_selfSync
       */
      function f_selfSyncAndVerdictTestBody(  in charstring p_syncId,
                          in FncRetCode p_ret )
      runs on SelfSyncComp {
        f_setVerdict(p_ret);
        f_selfSync(p_syncId,p_ret);
        vc_testcaseStep := e_postamble;
      }

      /**
       * @desc  This function combines MTC verdict setting with self
       *        synchronization for use after the postamble.
       * @param p_syncId Synchronization point name/id
       * @param p_ret Current behavior execution status
       * @see   LibCommon_VerdictControl.f_setVerdictPostamble
       * @see   LibCommon_Sync.f_selfSync
       */
      function f_selfSyncAndVerdictPostamble( in charstring p_syncId ,
                          in FncRetCode p_ret )
      runs on SelfSyncComp {
        f_setVerdictPreOrPostamble(p_ret);
        f_selfSync(p_syncId,p_ret);
      }

      /**
       * @desc   This function synchronizes a MTC with itself. In case
       *         of a non successful execution status it sends a STOP
       *         message to itself and invokes that way the
       *         shutdown default (if activated).
       *         This function will set the server verdict to INCONC (and
       *         stop the test case) if no shutdown default is activated.
       *         Otherwise no verdict is set.
       * @remark Sync ports should be connected prior to the invocation
       *         of this function!
       * @param  p_syncId Synchronization point name/id
       * @param  p_ret Current behavior execution status
       * @return Updated execution status
       * @see    LibCommon_Sync.f_connect4SelfSync
       * @see    LibCommon_Sync.a_dummyShutDown
       */
      function f_selfSync(  in charstring p_syncId ,
                  in FncRetCode p_ret )
      runs on SelfSyncComp
      return FncRetCode{
        if (p_ret != e_success){
          f_selfSyncStop() ; // function will not return!
        }
        if ( p_syncId == c_prDone ) {
          log("**** f_selfSync: Successfully passed PREAMBLE synchronization point. ****") ;
        } else if ( p_syncId == c_tbDone ) {
          log("**** f_selfSync: Successfully passed TEST BODY synchronization point. ****") ;
        } else {
          log("**** f_selfSync: Successfully passed synchronization point. ****") ;
        }
        return e_success ;
      }// end function f_selfSync

      /**
       * @desc   This function can be used to shut down a test case _prior_
       *         to reaching a synchronization point. it sends a STOP
       *         message to itself and invokes that way the
       *         shutdown default (if activated).
       *         This function will set the server verdict to INCONC (and
       *         stop the test case) if no shutdown default is activated.
       *         Otherwise no verdict is set.
       * @remark  Sync ports should be connected prior to the invocation
       *          of this function!
       * @see     LibCommon_Sync.f_connect4SelfSync
       */
      function f_selfSyncStop()
      runs on SelfSyncComp {

        log("**** f_selfSyncStop: MTC requests to stop test case (itself). ****") ;
        syncSendPort.send(m_syncServerStop) ; // this MUST be _server_ for the default to catch!
        tc_sync.start(PX_TSYNC_TIME_LIMIT);
        alt{
          [] tc_sync.timeout{
              log("**** f_selfSyncStop: Stopping MTC without shutdown - either no shutdown default active or missing syncPort connection ****") ;
              setverdict(inconc);
              stop ;
             }
        }//end alt
        tc_sync.stop;
        stop; // if shutdown default is not activated or if it does not stop
      } // end function f_selfSyncStop

    } // end group otherSelfSyncRelatedDefinitions

    /**
     *
     * @desc The sychronization protocol is conceptually based on
     *       named synchronization. Each synchronization point
     *       has it own specific synchronization message. This
     *       makes each synchronization unique, and allows, e.g., to
     *       ensure that a server synchronizes only clients which have
     *       reached the same synchronization point.
     */
    group syncProtocolDefinition {

      type union SyncCmd {
        ClientReady clientReady,
        ServerReady serverReady,
        ClientStop  clientStop,
        ServerStop  serverStop
      }

      type record ClientReady {
        charstring syncPointId
      }

      type record ServerReady {
        charstring syncPointId
      }

      type record ClientStop {}

      type record ServerStop {}

    } // end group syncProtocolDefinition

    group syncMessages {
      template SyncCmd m_syncClientReady( template (present) charstring p_syncId ) := {
        clientReady := { p_syncId }
      }

      template SyncCmd m_syncServerReady( template (present) charstring p_syncId ) := {
        serverReady := { p_syncId }
      }

      template SyncCmd m_syncClientStop := {
        clientStop := {}
      }

      template SyncCmd m_syncServerStop := {
        serverStop := {}
      }

    } // end group syncMessages

    group otherSyncFunctions {

      /**
       * @desc  Makes server send a sync message to all known clients
       * @param p_clientRefs List of client references to which the message is to be send
       * @param p_syncCmd The actual synchronization message to be sent out
       */
      function f_serverSendToAllClients(  in ClientSyncCompList p_clientRefs,
                        in template (value) SyncCmd p_syncCmd)
      runs on ServerSyncComp {
        var integer i:=0;
        for (i:=0; i< sizeof(p_clientRefs); i:=i+1 ){
          syncPort.send(p_syncCmd) to valueof(p_clientRefs[i]);
        }
      } // end function f_serverSendToAllClients

      /**
       * @desc  This function is intended only for use on server in concurrent
       *        TTCN-3 test cases. It waits for all components to shut down
       *        within the PX_TSHUT_DOWN_TIME_LIMIT. If a timeout occurs
       *        it aborts the test case (no matter how far clients got with their
       *        shutdown).
       *        This function sets the server verdict.
       */
      function f_serverWaitForAllClientsToShutDown()
      runs on ServerSyncComp {

        tc_shutDown.start(PX_TSHUT_DOWN_TIME_LIMIT);
        alt {
          [] syncPort.receive {
          	// clients may still try to send some sync message
          }        	
          [] all component.done {
            tc_shutDown.stop;
            log("**** f_serverWaitForAllClientsToShutDown: All components have properly shut down. Sync server will now terminate the test case. ****") ;
             }
          [] tc_shutDown.timeout {
            log("**** f_serverWaitForAllClientsToShutDown: Not all clients have properly shutdown within the shut down time limit. Sync server will now terminate test case! ****") ;
             }
        } // end alt
        // cover case that shut down default is NOT activated
        setverdict(inconc);
          //mtc.stop;
		syncPort.send(m_syncServerStop) to self; // this MUST be _server_ for the default to catch!
		tc_sync.start(PX_TSYNC_TIME_LIMIT);
		alt{
		  [] tc_sync.timeout{
			  log("**** f_selfSyncStop: Stopping MTC without shutdown - either no shutdown default active or missing syncPort connection ****") ;
			  setverdict(inconc);
			  stop ;
			 }
		}//end alt
		tc_sync.stop;
		stop; // if shutdown default is not activated or if it does not stop
      } // end function f_serverWaitForAllClientsToShutDown

		function f_isPresentInArray(in ClientSyncComp p_clientRef, in ClientSyncCompList p_clientRefs)
		return boolean {
			var integer i;
			for(i:=0; i < sizeof(p_clientRefs); i:=i+1) {
				if(p_clientRefs[i] == p_clientRef) {
					return true;
				}
			}
			return false;
		}
    } // end group otherSyncFunctions

  } // end group otherSyncDefinitions

} // end module LibCommon_Sync