File: OS.em
Description: POL System Environment Functions
Last Modified:
10/27/2007
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 |
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. |
OpenURL(
character, url ) |
---|
Parameters: |
---|
Name | Type |
character | Player
Character Ref |
url | String |
Explanation |
---|
Sends an Open URL packet to the client, to open
the url in their Default Browser. |
Return
values |
---|
1 on success |
Errors |
---|
"No client attached" |
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" |
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 |
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 |
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 polteam@polserver.com
Copyright ©2003-2006 David Carpman and POL Development Team, all rights
reserved. DO NOT REPRODUCE, MIRROR, ALTER, SPINDLE, MUTILATE, OR SIT
ON.