Date, Time and Calendar Functions

@TIME()

The @TIME function returns the total runtime, in seconds, required so far to generate and solve the model. @TIME is available only in the data and calc sections, and is not allowed in the constraints of a model. For example, the following output statement writes the solution time to the standard output device:

CALC:

  @WRITE('Solve time in seconds =', @TIME());

ENDCALC

@YMD2STM( year, month, day, hour, minute, second)

The @YMD2STM function takes a date and time as input and returns the equivalent scalar time, where scalar time is the number of seconds since the start of the base date of 1 Jan 1900. Note that dates prior to 1 Jan 1900 will return negative scalar time values. The first five arguments must be integral values, while the number of seconds can be fractional. If the seconds value is fractional, it will be rounded to the nearest 10 microseconds (or .00001 seconds). Hours are reported using military time and can range from 0 to 23. An example follows:

CALC:

 !Convert two dates to scalar time;

 STM1 = @YMD2STM( 2013, 1, 24, 13, 30, 10.5);

 STM2 = @YMD2STM( 1787, 9, 17, 0, 0, 0);

ENDCALC

Here, we compute the scalar time for the two dates and times: 1/24/2013 13:30:10.5 and 9/17/1787 00:00:00. The solution report lists the following values:

Variable                    Value

         STM1        3568023010.500000

   STM2       -3543523200.000000

There are two things to note: First, STM1 has a fractional value of .5, given that its time includes .5 fractional seconds. Second, STM2 is negative reflecting the fact that its date if prior to the base date to 1 Jan 1900.

YEAR, MON, DAY, DAYOFWEEK, HOUR, MIN, SEC = @STM2YMD( stm)

The @STM2YMD function takes a standard time value and returns the year, month, day of month, day of week (Sunday being day 1), hour, minute and second. Any of the left-hand side arguments may be omitted if they are not of interest. Below, we pass the current standard time via @STMNOW (see below) to @STM2YMD and then display the results:

MODEL:

 

SETS:

 MONTHS / JAN..DEC/;

 DAYS / SUN..SAT/;

ENDSETS

 

CALC:

 

 ! Convert the current standard time to human

   readable form;

 YR, MN, DAY, DWK, HR, MI, SE = @STM2YMD( @STMNOW());

 

 @WRITE(

  '       Year: ', YR, @NEWLINE( 1),

  '      Month: ', MONTHS( MN), @NEWLINE( 1),

  '        Day: ', DAY, @NEWLINE( 1),

  'Day of week: ', DAYS( DWK), @NEWLINE( 1),

  '       Hour: ', HR, @NEWLINE( 1),

  '     Minute: ', MI, @NEWLINE( 1),

  '     Second: ', SE, @NEWLINE( 2)

 );

ENDCALC

 

END

The output from the model shows the current date and time:

      Year: 2016

     Month: FEB

       Day: 11

Day of week: THU

      Hour: 9

    Minute: 14

    Second: 36.427

The @STM2YMD function may be used in calc sections only and may not be used in the optimizable sections of a model.

@STM2YR( stm) / @STM2MON( stm) / @STM2DAY( stm)

@STM2HR( stm) / @STM2MIN( stm) / @STM2SEC( stm)

These six functions are the inverses of the @STM2YR function presented above. Each function takes a scalar time value as input and returns, respectively, the year, month, day, hour, minute or second of the point in time represented by the scalar time value. Note that @STM2SEC can return fractional seconds. The following example takes a date and time, converts it to scalar time, and then converts the scalar time back to the original date and time:

SETS:

 MONTHS /JAN..DEC/;

 DAYS /SUN..SAT/;

ENDSETS

 

CALC:

 !Convert a date to scalar time;

 STM = @YMD2STM( 1787, 9, 17, 12, 0, 0);

 

 !Convert the scalar time back to the original date and time;

 YR = @STM2YR( STM);

 MO = @STM2MON( STM);

 DA = @STM2DAY( STM);

 

 HR = @STM2HR( STM);

 MN = @STM2MIN( STM);

 SC = @STM2SEC( STM);

 

 DOW = @STM2DWK( STM);

 

 !Write out the original date;

 @WRITE( 'Date: ',

   DA, ' ', MONTHS( MO), ' ', YR,

   @NEWLINE( 1);

 );

 

 !And the original date;

 @WRITE( 'Time: ',

   HR, ':',

   @FORMAT( MN, '%02g'), ':',

   @FORMAT( SC, '%02g'),

   @NEWLINE( 1);

 );

 

 !And the day of the week;        

 @WRITE( 'Day:  ',

   DAYS( DOW),

   @NEWLINE( 2);

 );

 

ENDCALC

The output from this sample follows:

Date: 17 SEP 1787

Time: 12:00:00

Day:  MON

@STMNOW()

The @STMNOW returns the current date and time as a scalar time value, where scalar time is the number of seconds since the base date of 1 Jan 1900. The returned may be fractional to indicate fractions of a second. The returned value can be broken down into the corresponding year, month, day, hour, minute and second by calling the @STM2* inverse functions described above. An example for displaying the current date and time follows:

MODEL:

 

SETS:
 MONTHS /JAN..DEC/;

 DAYS /SUN..SAT/;

ENDSETS

 

CALC:

 

  T = @STMNOW();

 

  YR = @STM2YR( T);

  MO = @STM2MON( T);

  DA = @STM2DAY( T);

  HR = @STM2HR( T);

  MN = @STM2MIN( T);

  SC = @STM2SEC( T);

  DWK = @STM2DWK( T);

 

  @SET( 'TERSEO', 1);

 

  @WRITE( '  The current date and time is:',

    ' ', DAYS( DWK),

    ' ', DA,

    ' ', MONTHS( MO),

    ' ', YR,

    ', ', HR,

    ':', @FORMAT( MN, '%02g'),

    ':', @FORMAT( SC, '%04.1f'),

    @NEWLINE( 2)

  );

 

ENDCALC

 

END

Here, we retrieve the current date and time as a scalar time value using @STMNOW. We then convert the scalar time to a calendar date and time and then write out the result. The following is a sample of output from the model:

The current date and time is: MON 11 FEB 2013, 15:54:56.7

@STM2DWK( stm)

The @STM2DWK function takes a scalar time and returns the index of its day of the week, with Sunday returning 1 and Saturday returning 7. An example of @STM2DWK can be found immediately above.