Appendix U - Miscellaneous Modeling Functions

• GET_CSIM_VERSION() - Returns the version of CSIM being used as a floating-point number.
  Formal definition:     float GET_CSIM_VERSION();
  Example:
          {
            float vers;
           
            vers = GET_CSIM_VERSION();
            printf("Version = %3.2f\n", vers );
          }

• CSIM_SET_EVENT_PRIORITY( int priority ) - Sets the priority level of subsequently scheduled events. Events are always scheduled in time order, according to the time they are scheduled to occur. However, events of the same priority that are scheduled to occur at the same time (ties) will be served in the order they were scheduled. The default priority level is 10. Events having higher priority will be served before lower priority events. It is effectively a tie-breaker. This function enables you to force certain events to occur sequentially before or after other events scheduled for the same time.

  The intended usage is to raise or lower the priority level with CSIM_SET_EVENT_PRIORITY just prior to scheduling a future event(s), and then to reset the priority level with CSIM_SET_EVENT_PRIORITY to the default value after scheduling. Future events are scheduled by the TRIGGER_THREAD, CALL_THREAD, and SCHEDULE_RESUME_WITH_PARAM functions.

  Example usages would be to cause a certain event(s) to occur before or after any or all other events that occur at a given time.
  Example:

  	CSIM_SET_EVENT_PRIORITY( 20 );
  	TRIGGER_THREAD( collect_stats, dT, 0 );
  	TRIGGER_THREAD( collect_stats, dT + 1.0, 0 );
  	CSIM_SET_EVENT_PRIORITY( 10 );
  	

• CSIM_RESET_EVENT_QUEUE() - Removes all pending future events from the time-event queue. This function is useful when restarting a simulation without leaving the simulator, such as when one of the objects within a modeled system is constructed to manage running Monte Carlo experiments. A simple example of using this function can be viewed at reset_event_queue_test.sim.

• csim_initialize(argc, argv) and csim_main() - These are normally considered private internal functions of CSIM, but are documented here for advanced users who are integrating CSIM with legacy simulation models. Such legacy models may require their own main routine. CSIM normally has its own main routine when run as a stand-alone process. CSIM's main routine looks like this:

          int main( int argc, char *argv[] )
          {
           csim_initialize( argc, argv );
           csim_main();
          }

  In such situations, CSIM's main routine can be renamed to old_main. Then your other code can have its own main. However, before your models schedule any events, your code should first call:
                csim_initialize( argc, argv );
  When you are ready to begin simulating, you then call:
                csim_main();
  If your legacy main function iteratively calls the CSIM simulation as a subroutine, such as to manage Monte Carlo runs, it should also call CSIM_RESET_EVENT_QUEUE(), before csim_initialize, as described directly above.

• double CSIM_TONE()   - This function returns the next scheduled event-time that is after the current time. In other words, it provides the value of the next scheduled time-change. TONE is an acronym standing for Time Of Next Event. This function can be useful for interfacing to simulation federations, such as HLA.

• double CSIM_Get_Next_Event_Time()   - This function returns time of next event, if any, even if it is the same as current time. If there are no further events, it returns MAX_FLT. This function is similar to CSIM_TONE() above, but unlike that function, it may return the current time. This function can be useful for interfacing to simulation federations, such as HLA.

• void DELTA_DELAY()   - Delay for infinitesimal time. This function is supplied to support inter-simulator interfaces, such as MSI and HLA. It delays the calling thread until the clock is about to change, but prior to it's changing. So it is a zero time-delay, and just a sequential delay.