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

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.

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.