The following built-in functions are functions that return information from the operating system, such as the current time and date, or the value of some environment variable.

DATE Returns the current date in the local timezone.
GETENV Returns the value of an environment variable.
GETPID Returns the process ID of the program that launched your REXX script.
TIME Returns the current time in the local timezone.
UNAME Returns information about the operating system and CPU.
USERID Returns the current user's name.


DATE

Returns the current date in the local timezone. Supports numerous formats for expressing the date, for example listing the month and day first, followed by the year in 2 digit form. DATE() can also be used to convert a particular date from one format to another format.

Synopsis

date = DATE(final_format, old_date, old_format)

Args

final_format is one of the desired format options as so:

Option Meaning
B (Basedate) Return the number of days (not including the current day) since (and including) January 1, 0001. This is the date based upon the Gregorian calendar.
D (Days) Return the number of days since the beginning of the current year (ie, how many days since Jan 1 of the current year until today, inclusive).
E (European) Return the date in European format. This consists of a 2 digit day of month (number), followed by a 2 digit month (number), and the last 2 digits of the year (number), each separated by a slash (ie, "dd/mm/yy"). If any of the numbers is single digit, it will have a leading zero.
M (Month) Return the full name of the current month, for example, 'January'.
N (Normal) Return the date in Normal format. This consists of the day of the month (number), followed by the name of the month abbreviated to only 3 letters (with the first letter capitalized), followed by the 4 digit year, each separated by a space (ie, "dd Mmm yyyy"). If the day is only a single digit, it does not have a leading zero.
O (Ordered) Return the date in Ordered format. This consists of the last 2 digits of the year (number), followed by a 2 digit month (number), and a 2 digit day of month (number), each separated by a slash (ie, "yy/mm/dd"). If any of the numbers is single digit, it will have a leading zero.
S (Standard) Return the date according the format specified by International Standards Organization Recommendation ISO/R 2014-1971 (E). This consists of a 4 digit year (number), followed by a 2 digit month (number), and a 2 digit day of the month (number), with no separation (ie, "yyyymmdd"). Leading zeros may be included where needed to ensure that the date is expressed in 8 characters.
U (USA) Return the date in USA format. This consists of a 2 digit month (number), followed by a 2 digit day of the month (number), and the last 2 digits of the year (number), each separated by a slash (ie, "mm/dd/yy"). If any of the numbers is single digit, it will have a leading zero.
W (Weekday) Return the full name of the weekday, for example, 'Monday'.

If final_format is omitted, it defaults to 'N'.

If old_date is specified, then DATE() does not return the current date. Instead, it is assumed that old_date is some date that you would like converted from one format to another format. old_format tells what format old_date is currently in. (It should be any one of the above formats except for 'M' or 'W'). DATE() will then reformat old_date into the final_format you specify, and return that new string. If old_format is omitted, it defaults to 'N'.

Returns

The date formatted as per final_format.

Notes

The 'B' final_format can be used to determine the number of the current day of the week. DATE('B')//7 returns a number in the range 0-6, where 0 is Monday and 6 is Sunday. This is different than the 'W' final_format, which returns the name of the day.

The date is not affected by the NUMERIC settings.

All of the calls to DATE() within the same REXX instruction will return the same date, even if the date were to change during execution of that one REXX instruction. (ie, The current date is not allowed to change in the middle of a REXX instruction).

Examples

Assume that the current date is January 6th 1992:

Example use Return value
DATE('B')
'727203'
DATE('D')
'6'
DATE('E')
'06/01/92'
DATE('M')
'January'
DATE('N')
'6 Jan 1992'
DATE('O')
'92/01/06'
DATE('S')
'19920106'
DATE('U')
'01/06/92'
DATE('W')
'Monday'

The following examples do not return the current date. Instead, because old_date has been specified, these examples convert old_date.

Example use Return value
DATE('O', '13 Feb 1923')
 '23/02/13'
DATE('O', '06/01/50', 'U')
 '50/06/01'

See also

TIME


GETENV

Returns the value of an environment variable.

Synopsis

value = GETENV(variable)

Args

variable is the name of the variable whose value is to be gotten.

Returns

The variable's current value.

Notes

Some interpreters do not implement this function.

If there is no environment variable by that name, and you are handling NOVALUE, then Reginald will raise a NOVALUE condition. CONDITION('D') will then return the name of the environment variable which does not exist.

Examples

Example use Return value
GETENV('MyDir')
/* Returns the value of the environment variable named 'MyDir' */

See also

VALUE


GETPID

Returns the process ID of the program that launched your REXX script.

Synopsis

id = GETPID()

Args

None.

Returns

The process ID number.

Notes

Some interpreters do not implement this function.

This function is very dependent upon the operating system of your computer. A process ID can be any number having any meaning. Use it only where documentation explicitly tells you to obtain a process ID.

See also

UNAME


TIME

Returns the current time in the local timezone. Supports numerous formats for expressing the time, for example military (24 hour based) or civil (12 hours in a day) formats. TIME() can also be used to convert a particular time from one format to another format.

Synopsis

time = TIME(final_format, old_time, old_format)

Args

final_format is one of the desired format options as so:

Option Meaning
C (Civil) Return the time in Civil format. This consists of a 1 or 2 digit hour, followed by a colon, a 2 digit minute, and either 'am' or 'pm'. The hour will be 1 to 12, inclusive.
N (Normal) Return the time in Normal format. This consists of a 2 digit hour (with leading zero if necessary), followed by a colon, a 2 digit minute, another colon, and a 2 digit second (ie, 'hh:mm:ss'). The hour is 0 to 24 (ie, military, 24 hour clock).
L (Long) Return the time in Long format. This consists of a 2 digit hour (with leading zero if necessary), followed by a colon, a 2 digit minute, another colon, a 2 digit second, a decimal point, and then 6 digits after the decimal point which represent the amount of microseconds (ie, 'hh:mm:ss.nnnnnn'). The hour is 0 to 24 (ie, military, 24 hour clock).
H (Hours) Return the number of hours that have passed since midnight. This will be a number from 0 to 23 (where 0 is midnight).
M (Minutes) Return the number of minutes that have passed since the top of the hour. This will be a number from 0 to 59.
S (Seconds) Return the number of seconds that have passed since the top of the minute. This will be a number from 0 to 59.
E (Elapsed) Return the elapsed seconds and microseconds since the internal stopwatch was reset. The number will be a floating point with 6 digits after the decimal point. (ie, The decimal part is the microsecond accuracy).
R (Reset) Resets the internal stopwatch so that the 'E' option starts counting from 0 again.

If final_format is omitted, it defaults to 'C'.

If old_time is specified, then TIME() does not return the current time. Instead, it is assumed that old_time is some time that you would like converted from one format to another format. old_format tells what format old_time is currently in. (It should be any one of the above formats except for 'E' or 'R'). TIME() will then reformat old_time into the final_format you specify, and return that new string. If old_format is omitted, it defaults to 'N'.

Returns

The time formatted as per final_format.

Notes

The time is not rounded off. Instead, it is truncated. For example, if the current time is 5:58am and you want to fetch the hours since midnight via TIME('H'), then a '5' is returned, even though it is closer to 6 am.

The time is not affected by the NUMERIC settings.

All of the calls to TIME() within the same REXX instruction will return the same time, even if the time were to change during execution of that one REXX instruction. (ie, The current time is not allowed to change in the middle of a REXX instruction).

Examples

Assume that the current time (in Long format) is '14:32:58.987654':

Example use Return value
TIME('C')
 '2:32pm'
TIME('H')
 '14'
TIME('M')
 '32'
TIME('S')
 '58'
TIME('N')
 '14:32;58'

The following examples do not return the current time. Instead, because old_time has been specified, these examples convert old_time.

Example use Return value
TIME(('C', '11:27:21')
'11:27am'
TIME('N', '11:27am', 'C')
'11:27:00'

See also

DATE


UNAME

Returns information about the operating system and CPU.

Synopsis

info = UNAME(option)

Args

option indicates what information is desired. It must be one of the following:

Option Meaning
S (System) Return the operating system name. For example, Windows may return the string 'WIN32'.
N (Name) Return the computer (user) name. May be the same as the USERID() built-in. On Windows, this returns the computer (WORKGROUP) name, rather than the name of the current user.
R (Release) Return the operating system's release (revision) number.
V (Version) Return the operating system's version number.
M (Machine) Return the computer (CPU) type. For example, a Pentium may return 'i586', whereas an 80486 would return 'i486', and an 80386 would return 'i386'.
A (All) Return a string containing all of the information above, in the order listed above, with each piece of information separated by a space.
Any number Any positive number (from 1 on up) returns the name of the appropriate REXX level (ie, subroutine/function).

If omitted, option defaults to 'A'.

Returns

A string containing the requested information, or an empty string if no such information is available.

Notes

Some interpreters do not implement this function.

If you issue the statement 'OPTIONS OS' prior to calling UNAME() to get the operating system name, then Reginald will return a more detailed operating system name. See Getting the operating system for details.

The Windows version of Reginald has a limit of 100 characters for the user name. Any longer name will be truncated.

Reginald supports a numeric option which may be useful when you have several subroutines/functions that all CALL or SIGNAL to the same piece of code, and you'd like that piece of code to be able to do different things depending upon who the caller is. For example, here we have two subroutines named MySub1 and MySub2. Both call the function named Shared. Shared passes UNAME option of 2, which will return the name of next level up. (ie, A 1 returns name of the current level).

MySub1:
   CALL Shared
   RETURN

MySub2:
   CALL Shared
   RETURN

Shared:
   SAY "I was called by" UNAME(2)
   RETURN
Note that if the main level of a script calls Shared, then UNAME(2) would return the name of the script itself.

As another example, assume that MySub1 and MySub2 both jump to the same label. At that label, you can call UNAME(1) to determine which subroutine was the one that jumped there:

MySub1:
   /* Some code here to do something */
   SIGNAL MyLabel

MySub2:
   /* Some code here to do something */
   SIGNAL MyLabel

MyLabel:    /* Both MySub1 and MySub2 jump here */
   SAY UNAME(1) "jumped here."
   RETURN

Passing a value of 0 returns the main script's name.

If you use UNAME to ask for a level that doesn't exist, then an empty string is returned. For more examples, see Functions/Subroutines in REXX.

Examples

Example use Return value
UNAME('S')
 /* Returns the operating system name */

See also

USERID


USERID

Returns the computer user's name, according to the operating system.

Synopsis

name = USERID()

Args

None.

Returns

A string containing the computer (ie, user) name, or an empty string if no such information is available.

Notes

The Windows version of Reginald has a limit of 100 characters for the name. Any longer name will be truncated. This returns the current user's name, rather than the computer (WORKGROUP) name. Use UNAME to return the latter.

Examples

Example use Return value
USERID()
 /* Returns the user's name */

See also

UNAME