MFP language Help: How to Use Time, Date and System Functions
Reading and setting time and date is an important capability in any serious programming language including MFP. Furthermore, MFP provides some APIs to access some operation system functions and commands.
Section 1 Time and Date Functions
Time and date functions provided by MFP programming language are listed as below:
|
Function Name |
Function Info |
|
get_day_of_month |
get_day_of_month(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_day_of_week |
get_day_of_week(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_day_of_year |
get_day_of_year(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_hour |
get_hour(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_millisecond |
get_millisecond(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_minute |
get_minute(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_month |
get_month(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_second |
get_second(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
get_time_stamp |
get_time_stamp(1...) : get_time_stamp(string_or_year, ...) returns the timestamp determined by the parameters. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. This function supports two modes. First mode is get_time_stamp(string_time_stamp) where there is only one string based parameter which must be formatted as yyyy-mm-dd hh:mm:ss[.f...]. The fractional second may be omitted. The second mode is get_time_stamp(year, month, day, hour, minute, second, millisecond). All the parameters except year are optional. If omitted, the default value for the parameters hour, minute, second and millisecond is 0, and the default value for the parameters month and day is 1. For example, get_time_stamp("1981-05-30 17:05:06") returns a timestamp at 17:05:06.000 on May 30, 1981. And it works exactly in the same way as get_time_stamp(1981, 5, 30, 17, 5, 6, 0). |
|
get_year |
get_year(1) : get_year(timestamp), get_month(timestamp), get_day_of_year(timestamp), get_day_of_month(timestamp), get_day_of_week(timestamp), get_hour(timestamp), get_minute(timestamp), get_second(timestamp) and get_millisecond(timestamp) return the year, month, day of year, day of month, day of week, hour, minute, second and millisecond of the timestamp parameter respectively. Timestamp is the difference, measured in milliseconds, between the time it represents and midnight, January 1, 1970 UTC. And day of week is an integer corresponding to Sunday if 0, Monday if 1, ... Saturday if 6. For example, get_day_of_week(get_time_stamp(2014, 12, 21)) returns 0 (Sunday). |
|
now |
now(0) : now() returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. |
As shown above, get_day_of_month, get_day_of_week, get_day_of_year, get_hour, get_millisecond, get_minute, get_month, get_second and get_year convert a timestamp, which is the number of elapsed milliseconds from 12:00 AM on January 1st, 1970 (UTC), to an integer which represents the day of month, day of week (Sunday is 0, Monday is 1, Tuesday is 2, etc), day of year, hour (0 to 23), millisecond, minute, month, second and year respectively. On the other hand, get_time_stamp converts a string based time which can be read by human being to a timestamp. And function now returns the current timestamp.
The following code is an example for the above functions. It can be found in the examples.mfps file in time date and sys libs sub-folder in the manual’s sample code folder.
Help
@language:
test time and date functions
@end
@language:simplified_chinese
测试日期和时间相关函数
@end
endh
function testTimeDate()
variable var1
print("\n\nget_time_stamp(\"1970-01-01 00:00:00.0\") = " _
+ get_time_stamp("1970-01-01 00:00:00.0"))
// test to convert an invalid time string to a time stamp.
// Result depends on OS
try
print("\n\nget_time_stamp(\"1980-12-71 00:00:00.0\") = ")
print(get_time_stamp("1980-12-71 00:00:00.0"))
catch (var1 = info) == info
print("throws an exception")
endtry
// test now function
printf("\n\nnow year = %d, month = %d, day of year = %d, " _
+ "day of month = %d, day of week = %d, hour = %d, " _
+ "minute = %d, second = %d, ms = %d", _
get_year(now()), get_month(now()), get_day_of_year(now()), _
get_day_of_month(now()), get_day_of_week(now()), _
get_hour(now()), get_minute(now()), get_second(now()), _
get_millisecond(now()))
// test time stamp conversions
print("\n\nget_millisecond(get_time_stamp(2015, 3, 8, 21, 22, 9, 7)) = " _
+ get_millisecond(get_time_stamp(2015, 3, 8, 21, 22, 9, 7)))
print("\n\nget_second(get_time_stamp(2015, 3, 8, 21, 22, 19, 700)) = " _
+ get_second(get_time_stamp(2015, 3, 8, 21, 22, 19, 700)))
print("\n\nget_month(get_time_stamp(2000, 2,29, 16, 58, 9, 700)) = " _
+ get_month(get_time_stamp(2000, 2,29, 16, 58, 9, 700)))
print("\n\nget_year(get_time_stamp(2014, 12,15, 16, 58, 9, 700)) = " _
+ get_year(get_time_stamp(2014, 12,15, 16, 58, 9, 700)))
print("\n\nget_day_of_week(get_time_stamp(2014, 12,15, 16, 58, 9, 700)) = " _
+ get_day_of_week(get_time_stamp(2014, 12,15, 16, 58, 9, 700)))
print("\n\nget_day_of_month(get_time_stamp(2001, 2,29, 16, 58, 9, 700)) = " _
+ get_day_of_month(get_time_stamp(2001, 2,29, 16, 58, 9, 700)))
print("\n\nget_day_of_year(get_time_stamp(2014, 12,15, 16, 58, 9, 700)) = " _
+ get_day_of_year(get_time_stamp(2014, 12,15, 16, 58, 9, 700)))
// test conversion of an invalid time. Result depends on OS
try
print("\n\nget_hour(get_time_stamp(2014, 12,15, 116, 58, 9, 700)) = " _
+ get_hour(get_time_stamp(2014, 12,15, 116, 58, 9, 700)))
catch (var1 = info) == info
print("\n\nget_hour(get_time_stamp(2014, 12,15, 116, 58, 9, 700)) " _
+ "throws an exception")
endtry
endf
The result of the above example is:
get_time_stamp("1970-01-01 00:00:00.0") = -36000000
get_time_stamp("1980-12-71 00:00:00.0") = throws an exception
now year = 2015, month = 8, day of year = 228, day of month = 16, day of week = 0, hour = 22, minute = 13, second = 9, ms = 363
get_millisecond(get_time_stamp(2015, 3, 8, 21, 22, 9, 7)) = 7
get_second(get_time_stamp(2015, 3, 8, 21, 22, 19, 700)) = 19
get_month(get_time_stamp(2000, 2,29, 16, 58, 9, 700)) = 2
get_year(get_time_stamp(2014, 12,15, 16, 58, 9, 700)) = 2014
get_day_of_week(get_time_stamp(2014, 12,15, 16, 58, 9, 700)) = 1
get_day_of_month(get_time_stamp(2001, 2,29, 16, 58, 9, 700)) = 1
get_day_of_year(get_time_stamp(2014, 12,15, 16, 58, 9, 700)) = 349
get_hour(get_time_stamp(2014, 12,15, 116, 58, 9, 700)) = 20
Note that if the parameter of get_time_samp is not a valid string based time expression, e.g. "1980-12-71 00:00:00.0" (invalid date), the behavior of get_time_stamp is undefined. In some OSes an error is reported, while in others a timestamp is returned. Therefore it is user’s responsibility to keep the parameter right.
Section 2 System Related Functions
MFP provides two system related functions which are sleep and system.
Sleep suspends a running task for a while and then resumes it. The right way to call sleep is sleep(x) where x is a positive value which means the number of milliseconds to sleep. This function returns nothing.
System runs an OS command and returns OS command’s returned value. It can be used in two ways. First is simply using the command as its single parameter, which is the only way for Scientific Calculator Plus version 1.6.6 or earlier. Restriction is that the command must be an executable file with its parameters. This means, if using Scientific Calculator Plus for JAVA in windows, calling system("dir") will fail because dir is not an executable file but an internal function of the executable file named cmd.exe. As such, user has to call system("cmd /c dir") instead of system("dir"). Similarly, if running in Linux (not Android), user has to call system("sh -c ls") instead of system("ls").
Though the above way to call system function works on any JAVA platform, it fails in Android. Therefore, from revision 1.6.7, a new way to call system function is introduced. System function still accepts one parameter. However, this parameter must be a string array and each element in the array is a part of the OS command. For example, in order to run "sh -c ls", user may call system(["sh", "-c", "ls"]) in Android. However, to change file1’s name to file2, user has to call system(["sh", "-c", "mv file1 file2"]) because "mv file1 file2" is an internal command of sh and it cannot be further separated.
User has to keep in mind that, at this stage, system function cannot accept user’s input from command line. Only output can be printed. Also, if the command does not exist, system function throws an exception.
System function works pretty well in Scientific Calculator Plus for JAVA. However, in Android many restrictions and limitations exist because Android does not provide a complete set of sh (shell) functions. Some function calls, e.g. system(["sh", "-c", "echo hello"]), may work well in some mobiles but report error in others. For this reason, if user wants to operate files (e.g. copy, move and delete file or folder) in a mobile, file operating functions listed in Section 5 of Chapter 6 is strongly recommended against calling system(["sh", "-c", "cp file1 file2"]).
Although use of system function is limited in Android, it is still the best approach to start an Android app using MFP programmatically. However, user needs to know the package id of the Android app and its main activity (starting activity)’s name. The usage is:
system("am start –n package_id/main_activity_name")
For example, if user has Smart Photographic Calculator (another app from the same developer of Scientific Calculator Plus) installed, the command to start it is:
system("am start –n com.cyzapps.SmartMath/com.cyzapps.SmartMath.ActivitySmartCalc")
, where com.cyzapps.SmartMath is the package id of Smart Photographic Calculator and its main activity name is com.cyzapps.SmartMath.ActivitySmartCalc.
Scientific Calculator Plus is able to build APKs. The package id of a generated APK is set by user. However, the main activity name is always com.cyzapps.AnMFPApp.ActivityAnMFPMain (this name may change in a future release of Scientific Calculator Plus). Since package id and main activity name are both known, user is allowed to launch apps created by him or herself.
User is not allowed to terminate a running app by calling system function because this is unsafe.
The following code is an example for the above functions. It can be found in the examples.mfps file in time date and sys libs sub-folder in the manual’s sample code folder.
Help
@language:
test sleep and system functions
@end
@language:simplified_chinese
测试sleep和system函数
@end
endh
function testSleepSys()
print("Now sleep 3 seconds\n")
sleep(3000)
print("Now wake up!\n")
// If you have installed Smart Photographic Calculator, this will work
pause("Now try to start Smart Photographic Calculator. Press Enter to continue")
system("am start –n com.cyzapps.SmartMath/com.cyzapps.SmartMath.ActivitySmartCalc")
endf
Running the above code, user will see an output message printed which is
Now sleep 3 seconds
, and then the program suspends for 3 seconds, then prints another message which is
Now wake up!
. After that, the program tries to start Smart Photographic Calculator. If not successful, an error message is reported.
Summary
Time and date functions are an important component for any programming languages. In OS time is stored as timestamp which is represented as the number of milliseconds elapsed since the mid-night of January 1st, 1970 (UTC). MFP provides a list of API functions to convert between a timestamp and a string based time descriptor readable to human being so that programmers can access and operate time easily.
MFP also includes some system related functions. Function sleep suspends the current running program and function system calls an OS command. Note that in Android directly calling a shell command is not recommended as support to shell may not be completely implemented in some devices. The main use of system function in Android is to start another app if user knows its package id and main activity name.