System Functions

function name	description
messageBox	generate a message box containing the supplied text
processId	return the id of the current process
threadId	return the id of the current thread
wait	wait for one of the supplied events to be set within the supplied number of milliseconds
sleep	wait for the supplied number of milliseconds
time	return the system time
formattedTime	format the current, or supplied, time
uniqueId	generate a unique id -- unique within this process
chmod	change file permissions
system	run a system command - this could be an executable file or a batch file/shell script
systemInfo	return information about the particular Operating System
spawn	run a system command and control whether or not to wait for the command to complete
hostName	lookup the supplied host name
getenv	lookup the value for the supplied environment variable
putenv	set the value for the supplied environment variable
sendWindowMessage	send a Windows message to the supplied window

`messageBox`

Generate a message box containing the supplied text. The caller can optionally determine the type of dialog box and the title etc.

Along with the text to be displayed in the message box, this function takes two optional arguments. The first is the title for the box (the default is Error). The second is an integer formed by combining the following hex values with a bitwise-or operator. The default is

    MB_SETFOREGROUND | MB_TASKMODAL | MB_ICONSTOP | MB_OK

constant	hex value
MB_OK	0x00000000
MB_OKCANCEL	0x00000001
MB_ABORTRETRYIGNORE	0x00000002
MB_YESNOCANCEL	0x00000003
MB_YESNO	0x00000004
MB_RETRYCANCEL	0x00000005
MB_ICONHAND	0x00000010
MB_ICONQUESTION	0x00000020
MB_ICONEXCLAMATION	0x00000030
MB_ICONASTERISK	0x00000040
MB_DEFBUTTON1	0x00000000
MB_DEFBUTTON2	0x00000100
MB_DEFBUTTON3	0x00000200
MB_DEFBUTTON4	0x00000300
MB_NOFOCUS	0x00008000
MB_APPLMODAL	0x00000000
MB_SYSTEMMODAL	0x00001000
MB_TASKMODAL	0x00002000
MB_HELP	0x00004000
MB_NOFOCUS	0x00008000
MB_SETFOREGROUND	0x00010000
MB_DEFAULT_DESKTOP_ONLY	0x00020000
MB_TOPMOST	0x00040000
MB_RIGHT	0x00080000
MB_RTLREADING	0x00100000

Arguments:

text	`String`
title (optional)	`String`
type (optional)	`Integer`

Return type: String

The value returned is a string which indicates which button on the message box was clicked:

abort
cancel
ignore
no
ok
retry
yes

`processId`

Return the id of the current process.

Arguments: none

Return type: Integer

`threadId`

Return the id of the current thread.

Arguments: none

Return type: Integer

`wait`

Wait for one of the supplied events to be set within the supplied number of milliseconds. There is a system limitation which means that at most 64 events can be waited for at any one time.

A negative timeout means 'wait forever'. A zero timeout means 'test the events and return immediately'.

Arguments:

eventList	`List`
timeout	`Integer`

Return type: returns the empty List () if none of the events is set in time, otherwise the Integer index (starting from zero) of an event which was set is returned.

`sleep`

Wait for the supplied number of milliseconds.

Arguments:

timeout Integer

Return type: the empty List ()

`time`

With no arguments, this returns the time (milliseconds) the system has been running. An optional String argument has the following effect:

argument	effect
`epoch`	return the time (seconds) since the beginning of the epoch ie. since midnight (00:00:00) 1 January 1970
`milli`	return the time (milliseconds) the system has been running
`25-Dec-2000 00:10:11`	if a date and time is presented in this format, the corresponding number of seconds in the epoch for the supplied date is returned
`25-12-2000 00:10:11`	if a date and time is presented in this format, the corresponding number of seconds in the epoch for the supplied date is returned
`001225001011Z`	UTC time format -- if a date and time is presented in this format, the corresponding number of seconds in the epoch for the supplied date is returned

Arguments: none or a single String

Return type: Integer

`formattedTime`

Format the current, or supplied, time. If no time is supplied, the current time is used.

To format the time for mail messages (as defined in RFC 1123 which extends RFC 822) then use the format MIME.

The supplied format string can contain the following commands:

NOTE: The returned string form of the time is the local time -- i.e. it is in the local time zone and takes daylight saving into account.

command	description
`%a`	abbreviated weekday name
`%A`	full weekday name
`%b`	abbreviated month name
`%B`	full month name
`%c`	date and time representation appropriate for locale
`%d`	day of month as decimal number (01 to 31)
`%H`	hour in 24-hour format (00 to 23)
`%I`	hour in 12-hour format (01 to 12)
`%j`	day of year as decimal number (001 to 366)
`%m`	month as decimal number (01 to 12)
`%M`	minute as decimal number (00 to 59)
`%p`	current locales A.M./P.M. indicator for 12-hour clock
`%S`	second as decimal number (00 to 59)
`%U`	week of year as decimal number, with Sunday as first day of week (00 to 53)
`%w`	weekday as decimal number (0 to 6; Sunday is 0)
`%W`	week of year as decimal number, with Monday as first day of week (00 to 53)
`%x`	date representation for current locale
`%X`	time representation for current locale
`%y`	year without century, as decimal number (00 to 99)
`%Y`	year with century, as decimal number
`%z`	time-zone name or abbreviation; no characters if time zone is unknown
`%%`	percent sign

Arguments:

format	`String`
time (optional)	`Integer`

Return type: String

`uniqueId`

Generate a unique id -- unique within this process.

Arguments: none

Return type: String

`chmod`

Change the file permissions. E.g. to make the file readable and writeable:

    (chmod "c:/temp/myfile.txt" "rw")

Arguments:

filename	`String`
permissions	`String`

Return type: the empty List ()

`system`

Run a system command - this could be an executable file or a batch file/shell script. For example, the following displays the current directory listing on Microsoft platforms:

    (system "dir")

The integer return code shows whether the command succeeded -- zero is returned for success.

Arguments:

command Object

Return type: Integer

`systemInfo`

Return information about the particular Operating System. With no arguments, it returns the information as an attribute/value List. With a single String argument it returns the individual piece of information. Valid arguments are:

platform
major
minor
build
patch
user
rootDir
systemDir
computerName

The value returned for the platform is one of the following:

Windows 3.1
Windows 95
Windows 98
Windows NT
Windows 2000 ME
Windows 2000

Arguments:

(optional) key String

Return type: Object

`spawn`

Run a system command - this could be an executable file or a batch file/shell script. This is a slightly more flexible version of system since it can either wait for the invoked command to complete or continue without waiting.

Suppose a command fred.exe takes 2 arguments -- it can be invoked as follows:


    (spawn "nowait" "fred.exe" "one" "two")

The integer return code shows whether the command succeeded -- zero is returned for success.

Arguments:

waiting	`String`
command	`String`
...	`String`

Return type: Integer

`hostName`

Look up the supplied host name or IP address.

Arguments:

name String

Return type: String -- an error is raised if the hostname could not be resolved.

`getenv`

Lookup the value for the supplied environment variable. If the variable is defined, the String value is returned, otherwise the empty List () is returned.

Arguments:

name String

Return type: String or the empty List ()

`putenv`

Set the value for the supplied environment variable.

Arguments:

name	`String`
value	`String`

Return type: the empty List ()

`sendWindowMessage`

Send a Windows message to the supplied window handle. The final wait argument, if present and non-NIL, will wait for the recipient Window thread to process the message before this function returns.

This wraps up the system calls PostMessage and SendMessage.

Arguments:

hWnd	`Integer`
messageId	`Integer`
wParam	`Integer`
lParam	`Integer`
(optional) wait	`Object`

Return type: Integer

Contents

Index

Current topic: functions