File: OS.em
Description: POL
System Environment Functions
Last Modified: 2/11/2003
File Constants:
// set_script_option constants
const SCRIPTOPT_NO_INTERRUPT := 1; // if 1, script runs until it sleeps
const SCRIPTOPT_DEBUG := 2; // if 1, prints any debug info included
const SCRIPTOPT_NO_RUNAWAY := 3; // if 1, doesn't warn about runaway conditions
const SCRIPTOPT_CAN_ACCESS_OFFLINE_MOBILES := 4;
Clear_Event_Queue() |
Explanation |
Empties the current script's event queue |
Return values |
1 on success |
Create_Debug_Context() |
Explanation |
TBD |
Return values |
TBD |
Events_Waiting() |
Explanation |
Returns the number of events waiting in the event queue for
this script. |
Return values |
Integer number of events
waiting |
Getpid() |
Explanation |
Returns the Process ID for this script. |
Return values |
Integer Process ID |
GetProcess(pid) |
Parameters: |
Name |
Type |
pid |
Integer process ID of a script |
Explanation |
Gets a script process object for the given script's
PID. |
Return values |
A Script object |
Errors |
"Process not found" |
"Invalid parameter type" |
Related |
Script |
Is_Critical() |
Explanation |
Returns true if the script is critical (by using
set_critical()) |
Return values |
1 if critical, else 0. |
Run_Script_To_Completion( script_name, param :=
0 ) |
Parameters: |
Name |
Type |
script_name |
String name and path of script to run |
param |
object to pass to the script. Only one param may be passed.
(optional) |
Explanation |
Starts a new CRITICAL script. Runs until the script exits,
returns the return value of the started script. |
Tip: write your script to expect a struct or array as its
only parameter, so you may pass multiple pieces of data through the struct
or array. |
Every 1000 instructions, "Script X running.." is printed to
the console |
Return values |
The return value of the started script, or 1 if no value was
returned |
Errors |
"Unable to read script" |
"Script exited with an error condition" |
"Script does not exist" |
"Script descriptor error" |
Set_Critical( critical ) |
Parameters: |
Name |
Type |
critical |
Boolean (0/1) |
Explanation |
critical scripts run if they are not blocked, without
interruption. |
An infinite loop in a critical script will hang the
server |
Use this in blocks by setting 'critical' to 1 before the
critical code and to 0 after it. |
Use this function sparingly, only in parts of code that must
execute without interruption |
Return values |
1 on success |
Errors |
"Invalid parameter type" |
Set_Debug( debug ) |
Parameters: |
Name |
Type |
debug |
Boolean (0/1) |
Explanation |
if debug=1, and the script was compiled with 'ecompile -i
[script].src', each script source line will be printed as it is
executed. |
if debug=0, disables this output. |
Return values |
1 on success |
Errors |
"Invalid parameter type" |
Set_Event_Queue_Size(size) |
Parameters: |
Name |
Type |
size |
Integer new size |
Explanation |
Changes the maximum number of events the current script will
keep in the queue (additional events will be discarded). |
If not called, the default size is 20 events. |
Return values |
Integer old queue size. |
Errors |
"Invalid parameter type" |
Set_Priority( priority ) |
Parameters: |
Name |
Type |
priority |
Integer 1..255 |
Explanation |
the priority of a script is how many instructions it
executes before switching to another script. |
default script priority is 1. |
Return values |
Integer previous priority |
Errors |
"Invalid parameter type" |
Set_Script_Option( optnum, optval
) |
Parameters: |
Name |
Type |
optnum |
Integer constant |
optval |
boolean (0/1) |
Explanation |
Sets one or more options on or off for this script |
Constants for this function: |
const SCRIPTOPT_NO_INTERRUPT := 1; // if 1, script runs until it sleeps
const SCRIPTOPT_DEBUG := 2; // if 1, prints any debug info included
const SCRIPTOPT_NO_RUNAWAY := 3; // if 1, doesn't warn about runaway conditions
const SCRIPTOPT_CAN_ACCESS_OFFLINE_MOBILES := 4; |
set_script_option(SCRIPTOPT_NO_INTERRUPT,1) is the same as
set_critical(1) |
set_script_option(SCRIPTOPT_DEBUG,1) is the same as
set_debug(1) |
Return values |
1 on success |
Errors |
"Unknown Script Option" |
"Invalid parameter type" |
Sleep( num_seconds ) |
Parameters: |
Name |
Type |
num_seconds |
Integer |
Explanation |
Puts the current script to sleep for num_seconds. No further
instructions in this script will be processed in this script until the
time expires. |
DO NOT USE IN A CRITICAL BLOCK! Your server will freeze for
the duration! |
If this script is attached to a character (like a
UseScript), calling detach() before the sleep will allow other scripts to
run while this script sleeps. |
Return values |
0 after sleep |
Sleepms( num_milliseconds ) |
Parameters: |
Name |
Type |
num_milliseconds |
Integer |
Explanation |
Puts the current script to sleep for num_milliseconds. No
further instructions in this script will be processed in this script until
the time expires. |
DO NOT USE IN A CRITICAL BLOCK! Your server will freeze for
the duration! |
If this script is attached to a character (like a
UseScript), calling detach() before the sleep will allow other scripts to
run while this script sleeps. |
You're not likely to get any faster resolution than
10ms |
Return values |
0 after sleep |
Start_Script( script_name, param := 0
) |
Parameters: |
Name |
Type |
script_name |
String name and path of script to run |
param |
object to pass to the script. Only one param may be passed.
(optional) |
Explanation |
Starts a new script running. |
Tip: write your script to expect a struct or array as its
only parameter, so you may pass multiple pieces of data through the struct
or array. |
Return values |
A Script object for the started script on
success. |
Errors |
"Error in script name" |
"Script X does not exist." |
"Unable to start script" |
"Invalid parameter type" |
Related |
Script |
Syslog( text ) |
Parameters: |
Name |
Type |
text |
String |
Explanation |
write text to the console, and to the log file includes
context (calling script name) |
Return values |
1 on success |
System_RPM() |
Explanation |
returns the system RPM, which is the number of "game loop
rotations" completed in the last minute. |
Return values |
Last System RPM integer |
Unload_Scripts(scriptname :=
"") |
Parameters: |
Name |
Type |
scriptname |
String filename of script without extension (optional) |
Explanation |
unload scripts from the script cache (they will be reloaded
from disk on demand) currently running scripts will continue as
normal. |
Passing "" will unload all scripts. |
Return values |
Number of scripts unloaded |
Errors |
"Invalid parameter type" |
Related |
Script |
Wait_For_Event( num_seconds_timeout
) |
Parameters: |
Name |
Type |
num_seconds_timeout |
Integer |
Explanation |
The primary access to a script's event queue. If there is an
event waiting, the function immediately returns with the event (could be a
string, int, struct, etc). |
If no event is waiting, the script sleeps for
num_seconds_timeout or until a new event arrives. If the timeout is
reached, the function returns 0. |
if timeout is 0, returns immediately |
Return values |
object on event recv, 0 on
timeout |
If you know if
any information is incorrect on these pages, mail your corrections to
racalac@burdell.org
Copyright ©2003
David Carpman, all rights reserved. DO NOT REPRODUCE, MIRROR, ALTER, SPINDLE,
MUTILATE, OR SIT ON.