server-side JavaScript: Prototypes of built-in classes, objects and functins

Discussion in 'Javascript' started by GVDC, Jun 28, 2008.

  1. GVDC

    GVDC Guest

    Prototypes of built-in classes, objects and functions available with server-side JavaScript
    Contents of README_serverside_javascript_prototypes.txt Readme file:

    Grom persistent interpreter connector
    GromJS SpiderMonkey server-side JavaScript

    Manual includes prototypes of built-in classes, objects and functions available
    with GromJS server-side JavaScript. In addition to this manual see sample
    server-side JavaScript Web scripts provided in directory with this Readme.

    The definitions of classes and objects and function prototypes are given in

    - Top level functions
    - Cgi object (handles receival of client-sent data ie. GET/POST data,
    uploaded files, cookies, etc, and provides metods for manipulation of
    these values; see examples below)
    - Server object (includes set of functions related to interpreter
    process itself ie. getpid, various utility functions ie. getenv, time,
    rand, FS manipulation ie. mkdir, rmdir, unlink, link, symlink, chmod
    - Session object (disk-based session variables for data persistence
    between script executions)
    - File class (manipulation of files on server, ie. open, close, read,
    write, seek, truncate, lock etc)
    - Sqlite class (SQLite3 API ie. open, close, exec, query, fetchrow)
    - Pipe class (executing external programs and communicating through Unix
    - Dictionary class (hash array, unlimited size, configurable

    uint printf(string DATA [,string DATA2 ...]); //print arguments
    void load(string SCRIPTPATH [,string SCRIPTPATH2 ...]); //load script(s) on SCRIPTPATH
    void include(string SCRIPTPATH [,string SCRIPTPATH2 ...]); //same as "load"

    Built-in "Cgi" object provides access to client-sent data ie. query string, POST
    data, uploaded files, cookies etc. SpiderMonkey interpreter is configured to
    automatically output CGI response headers and Cgi.header() function is available
    for setting arbitrary response-headers.

    object Cgi {
    string query([string VARNAME] [, object DEFAULTVAL]); //used with no argument, returns whole querystring; with
    argument VARNAME returns VARNAME's value; if variable not found returns empty string
    string post([string VARNAME] [, object DEFAULTVAL]); //same as above, values searched in POST data
    string any(string VARNAME [, object DEFAULTVAL]); //same as above; fetch from any available source,
    querystring or POST data, in that order
    //Methods Cgi.query() Cgi.any() by default return an empty string if requested var not found
    //Optional 2nd arg can be supplied which functions can return when var is not found, ie.:
    //var myval = Cgi.any("myvar", null); //return null if myvar not found

    array names(); //returns array of strings with all var names from querystring and postdata ie.
    script called with URL such as "myscript.js?nam1=val1&nam2=val2" returns array containing "nam1", "nam2" .
    void separators(string SEPARATORS); //use alternative separator (delimiter) chars for querystring/postdata; default
    are "=" and "&" Example: Cgi.separator("=;") to use "=" and ";" as delimiters
    string getcookie(string COOKIENAM); //get value of COOKIENAM (available in "HTTP_COOKIE" environment variable)
    void header(string HEADER); //add arbitrary response header ie. Cgi.header("Content-Type: image/gif") ;

    array Files; //array of "Uploadedfile" objects; see "Uploadedfile" prototype below

    //HTTP request querystring: /myscript.js?somevar=someval&myvar=myval
    printf(Cgi.any("myvar") +"<br>"); //print value of "myvar"
    printf(Cgi.getcookie("myid") +"<br>"); //print value of "myid" cookie

    object Uploadedfile {
    string name; //name of HTML form input field ie "myphoto1"
    string filename; //filename on client's disk ie. "c:\files\myfile.gif" or "/files/myfile.gif"
    string tmpfile; //location of newly created uploaded file ie. /tmp/fileupload23457742463624355325.dat
    string type; //file type ie. image/gif
    string encoding; //encoding
    uint size; //size of uploaded file in bytes

    //array length indicates the number of uploaded files
    if ( Cgi.Files.length>0 ) {
    var Uplfile = Cgi.Files[0]; //get 0'th Uploadedfile object
    printf(; //print the name of uploaded file

    Built-in "Server" object includes a set of functions (methods) related to
    JavaScript interpreter process itself such as process PID, errno, exit etc.,
    various utility functions such as current time, rand etc., file-system
    interaction functions ie. mkdir, chmod, stat, file copy, unlink etc.

    object Server {
    void timeout(uint SECONDS); //script timeout; set max SECONDS allowed for script execution after which
    process exits, ie. abort script in infinite loop
    uint sleep(uint SECONDS); //put process to sleep for SECONDS seconds
    void gc(); //run garbage-collector; Ie. after many vars used, large arrays, database
    reads/writes etc.
    void buffer(uint BUFFER); //output buffer; 0 == no buffer, output is sent immediately; non-zero ==
    output is buffered and sent in blocks of that size, ie. 0xFFFF for 64k; default is buffered to 64kb (max)
    void fflush(); //force output from buffer (flush output buffer)
    void exit([string MSG]); //abort script execution and exit process; before exit print MSG if
    void quit([string MSG]); //abort script execution but persistent process remains active
    uint uptime(); //number of seconds process is active
    uint requests(); //number of requests (scripts) process has executed ie. 1, 2, 50, 5000
    uint rss(); //process resident set size (memory footprint), in kilobytes
    uint rand(); //random unsigned integer number
    uint time(); //current time, in seconds; number of seconds since epoch time
    uint microtime(); //current time in microseconds
    string localdate([uint SECONDS]); //local date string, if no args date is for current time, identical to
    calling Server.localdate(Server.time())
    string gmtdate([uint SECONDS]); //GMT date
    uint getpid(); //process PID no
    string getcwd(); //get current working dir
    //system error functions
    uint errno([uint ERRNO]); //system errno. With no argument, get system error number. If argument is
    provided and value 0, sets errno to zero
    string errstr([uint ERRNO]); //system error string. If ERRNO supplied, string for that specific ERRNO
    string errnstr([uint ERRNO]); //returns string with joined errno() and errstr(). If ERRNO supplied,
    string for that specific ERRNO

    string array dirlist(string DIRPATH); //list filenames in DIRPATH and return as array of strings, without "."
    and ".." entries
    string filemodestring(uint MODE); //ie. for mode 0755 return string -rwxr-xr-x

    object Environ environ(); //function "Server.environ()" returns JS Object with all environment
    variables as object's properties (see example below)
    string getenv(string VARNAME); //returns specific env variable

    array argv(); //returns array of command line arguments

    /*All functions below return true if operation succeeded, false
    otherwise; If operation failed, Server.errno() will give the system
    error number:*/
    bool chdir(string DIRPATH); //change working dir to DIRPATH
    bool mkdir(string DIRPATH, uint MODE); //make new dir under filemode MODE
    bool rmdir(string DIRPATH); //remove empty dir
    bool chmod(string PATH, uint MODE); //change mode of PATH to MODE
    bool rename(string OLDPATH, string NEWPATH); //rename/move OLDPATH to NEWPATH
    bool move(string OLDPATH, string NEWPATH); //alias for rename
    bool symlink(string EXISTINGPATH, string NEWLINKPATH); //create a symlink
    bool link(string EXISTINGPATH, string NEWLINKPATH); //create a hard link
    bool unlink(string PATH); //remove a file
    bool copy(string FILEPATH, string NEWFILE [, bool APPEND]); //copy FILEPATH file to NEWFILE, if third
    arg APPEND present and non-zero then append to destination
    string readlink(string PATH); //read the contents of the symbolic link
    path in PATH and return as string. On error returns null.

    //file status
    object Stat stat(string PATH [, bool INFOABOUTSYMLINK]); //get file status; null returned on error

    uint hash(string TEXT); //create unique uint for string TEXT
    string execve(string PATHTOEXE); //run executable on location PATHTOEXE and return it's output as a string; if
    execve failed or proces unclean exit server errno is non-zero
    uint ip2n(string IPADR); //IPv4, for string "" return numeric value 23478899
    string n2ip(uint IPNUM); //IPv4, for numeric value 23478899 return string ""
    object Hostent gethostby(string NAMEORADR [, string GETHOSTBY]); //IPv4, first arg is name or IP addr; second arg
    GETHOSTBY is keyword "name" or "address" indicating lookup by name or IP address; if omitted lookup is by name

    //string-chars manipulation functions
    string chartrim(string DATA, string CHARS2TRIM, uint WHICHEND);
    //trim chars CHARS2TRIM, WHICHEND 1=leading, 2=trailing, 3=trim both ends
    //var trimmed = Server.chartrim(" abc ", "\t\r\n ", 3);
    //returns string "abc".

    string charkeep(string DATA, string CHARS2KEEP);
    //keep chars CHARS2KEEP remove all other
    //var cleared = Server.charkeep(" abc ", "ac");
    //returns string "ac", all other chars removed.

    string charremove(string DATA, string CHARSREMOV);
    //remove chars CHARSREMOV
    //var cleared = Server.charremove(" abc ", " c");
    //returns string "ab", spaces and c removed.

    string charreplace(string DATA, string CHARSFROM, string CHARSTO);
    //char by char replace, CHARSFROM change to CHARSTO
    //var changed = Server.charreplace(" abc ", " b", "_");
    //returns string "_a_c_", spaces and b changed to _.

    string charcutto1(string DATA, string WHICH);
    //cut repetitive successive chars to 1 count
    //var ccut = Server.charcutto1(" aaa bbbb ccc ", " a");
    //returns string " a bbbb ccc ", with a and spaces reduced to 1 count.

    //print localdate
    printf(Server.localdate(), "<br>");

    //file copy example:
    if ( Server.copy("myfile.txt", "myfile2.txt")==true ) {
    //operation succeded

    The "Environ" object includes a collection of environment variables.

    var environobj = Server.environ();
    //environment variables:
    environobj.REQUEST_METHOD or environobj["REQUEST_METHOD"]
    environobj.CONTENT_LENGTH or environobj["CONTENT_LENGTH"]
    .... etc etc.

    //print all environment variables ie.:
    //CONTENT_LENGTH = 123<br>
    for ( key in environobj ) {
    printf(key, " = ", environobj[key], "<br>");

    //get a single env variable:
    var contlen = Server.getenv("CONTENT_LENGTH");

    The "Stat" object provides file status information.
    object Stat {
    uint size; //size of file in bytes
    uint ta; //time of last access, in seconds
    uint tm; //time of last modified
    uint tc; //time of last file status change
    uint mode; //file mode, ie. 0644

    //bools indicating file type
    bool isreg; //true if regular file
    bool isdir; //true if file is a directory
    bool islink; //true if symlink
    bool ischar; //true if char special
    bool isblock; //true if block special
    bool isfifo; //true if named pipe (fifo)
    bool issock; //true if socket

    var statobj = Server.stat(string PATH [, bool SYMLINKINFO]); //prototype
    var statobj = Server.stat("/path/to/myfile.txt"); //get file status information
    var statobj = Server.stat("/path/to/myfile.txt", 1); //same, if file is symlink get information about link itself not
    file it points to
    if ( statobj!=null ) {
    printf("The size of myfile.txt is ", statobj.size, "<br>");

    if ( statobj.isreg ) {
    //regular file
    if ( statobj.isdir ) {
    else {
    printf("ERROR: Getting information about myfile.txt failed<br\n>");
    printf("system errno [", Server.errno(), "] ", Server.errstr(),"<br\n>");

    object Hostent {
    string name; //official name of host
    array aliases ; //string array alias list
    array addresses; //string array list of addresses from name server
    uint error; //herror (host error) number; 0 if gethostby succedded

    var Exmplhostent = Server.gethostby("", "adr");
    if ( Exmplhostent.error==0 ) {
    //operation succeded
    printf(, "<br>"); //print official name of host
    printf(Exmplhostent.aliases.join(", "), "<br>"); //print joined array of aliases
    printf(Exmplhostent.addresses.join(", "), "<br>"); //print joined array of adresses

    Built-in "Session" object provides methods for efficiently reading/storing
    variables between script executions.
    Session variables are disk based (stored on disk) and have no direct memory
    limitation ie. it is ok using a 20mb data in session variable if required.
    Variables are stored as text, meaning that numbers (or objects) must first be
    converted to string and then stored in session variable.
    When reading a numeric (or object) value from session variable, it is a reverse
    process, value is retrieved as text, then converted to it's original type.
    Each session is unique and defined by identifier sent to HTTP client/browser as
    session-id cookie.

    object Session {
    uint time([uint DURATION]); //get or set duration of variables in seconds; used with no argument returns the
    duration of session variables, otherwise argument sets session duration; setting time to 0 has effect of deleting all variables
    string get(string NAME); //get value of variable NAME; if variable is not available an empty string is
    void set(string NAME, string VALUE); //for variable NAME set value to VALUE; setting an empty string "" for VALUE has
    effect of deleting a value
    void todisk(); //optional, store session to disk (normally done at end of script execution)
    var sesdurat = Session.time(); //get current duration of session variables
    Session.time(5*60); //set duration to 5 minutes; set value is within the limit of max allowed duration
    defined in Bauk configuration script
    var mysesvar = Session.get("mysesvar"); //get value of mysesvar
    Session.set("othervar", "xyz"); //set "othervar" to value "xyz"
    Session.todisk(); //force storing session on disk and release memory (not wait for end of script
    var othervar = Session.get("othervar"); //ok to call again after storing on disk
    Session.time(10*60); //change duration
    Session.set("anothervar", "abc"); //set "anothervar" to value "abc"
    Session.todisk(); //again, to disk
    //..etc etc...

    Note: all session methods are "safe" which means that all methods can be used
    any number of times and in any desired sequence. Ie. it is ok to call get(),
    set(), time(), todisk(), then again get(), set(), time() todisk() etc. and the
    final result is always same (session is always eventually stored to disk at end
    of script execution)

    Built-in "File" class provides access to files for read/write, and additional
    functions for manipulating file data such as lock, truncate, seek, etc.
    File data access is in block (chunk) mode and "textual" (data is first converted
    to string then stored), ie. calling function reads 20 bytes from
    current file position, myfile.write("abcd") writes string "abcd" to file's
    current position. When reading numbers, value is retrieved as string and then
    converted to numeric value (ie. using parseInt() and parseFloat()).
    Additional information about file itself ie. file type, permissions, etc. can be
    obtained using Server.stat() function.
    var fileobj = new File(string FILEPATH);
    var fileobj = new File("/path/to/myfile.txt");

    class File {
    bool open(string OPENMODE [,uint CREATEMODE]); //open file by specified mode OPENMODE; see below
    bool close(); //close; also removes any lock file has set
    int write(string DATA [, string DATA2, ...]); //write to file; multiple arguments; returns number of bytes written;
    on error returns -1
    string read([uint LEN]); //read LEN bytes and return as JavaScript string; if no argument read
    all available bytes from current file position onward; on failure null returned
    int cat([uint LEN]); //cat LEN bytes to stdout, if no argument, cat all available bytes
    from current file position onward; returns number of bytes done; -1 returned on error
    uint tell(); //tell current file position
    bool seek([uint ABSPOSITION]); //seek to new absolute position within file, if no argument seek to
    end of file
    string path(); //returns file path
    bool lock(string LOCKTYPE); //lock using LOCKTYPE; see below
    bool unlock(); //release lock
    bool truncate([uint LEN]); //truncate opened file to new length; if no argument truncate to
    current file position

    Open modes:
    r = open for reading
    w = open for writing and set file position to beggining of file
    c = create file by mode CREATEMODE if not existing
    t = truncate file
    a = open for write/append and set position to end of file, excludes truncate flag

    Lock modes:
    s = set shared lock
    x = set exclusive lock
    n = non-blocking, attempt to set lock but if locked by another process and would block, return error EWOULDBLOCK

    var fileobj = new File("/path/to/myfile.txt");
    //open for RW, truncate and if not existing create mode 0644
    if ("rwtc", 0644)==true ) {
    //set exclusive lock, blocking
    if ( fileobj.lock("x")==true ) {
    //set non-blocking exclusive lock
    if ( fileobj.lock("xn")==true ) {
    //set shared lock; process blocked untill capable of setting lock
    if ( fileobj.lock("s")==true ) {

    //open and read complete file
    if ("r")==true ) {
    var fdata =; //read all
    if ( fdata!=null ) {

    Built-in "SQLite" class provides interface for using SQLite3 database.

    var databaseobj = new SQLite(string DBPATH);
    var databaseobj = new SQLite("/path/to/mydatabase.db");

    class SQLite {
    bool open(); //open database, returns true if succedded
    bool close(); //close database
    bool exec(string STATEMENT); //execute a result-less SQL statement
    bool query(string SQLQUERY); //execute SQL query SQLQUERY and create result set
    string colname(uint INDX); //for column at INDX return column name used in CREATE table statement
    string coltype(uint INDX); //for column at INDX return column data type used in CREATE statement ie. INTEGER,
    uint colcount(); //number of columns in result set
    uint rowcount(); //number of rows in result set
    bool rowhas(); //returns true if there is row under cursor available
    array rowfetch(); //from result set get single row, returned as JavaScript array of strings; null
    returned if no row available
    array array rowallfetch(); //from result set get all rows, returned as JavaScript two-dimensional array of
    uint rowlastinsertid(); //returns id created by database last insert operation
    uint lastinsertrowid(); //alias for rowlastinsertid
    bool rewind(); //move to first row of result set
    string error(); //returns SQLite3 error report string

    //BEGIN CODE-->
    //demonstrate using SQLite3 database and JavaScript interface

    var dbfilepath = "mydatabase.db";
    var databaseobj = new SQLite(dbfilepath);

    printf("<b>Opening database.</b><br>");

    if ( ) {
    printf("Executing CREATE and INSERT statement.<br>");

    var ssqlstmt = ""
    +"CREATE TABLE ttesttable (i INTEGER PRIMARY KEY, cname CHAR(255), cweight INTEGER); "
    +"INSERT INTO ttesttable (cname,cweight) VALUES ('firstuser',95); "
    +"INSERT INTO ttesttable (cname,cweight) VALUES ('anotheruser',263); "

    //if statements executed ok...
    if ( databaseobj.exec(ssqlstmt)==true ) {
    printf("Using SELECT query to fetch inserted values.<br>");
    if ( databaseobj.query("SELECT * FROM ttesttable")==true ) {
    //printing selected values in tabular form ie.
    //colname (TYPE) colname (TYPE) colname (TYPE)
    //value value value
    //value value value
    //etc etc...
    printf("Printing selected values in tabular form.<br><br>");
    printf("<table bgcolor=\"#DDDDDD\" cellspacing=1 cellpadding=4>");

    //print header row with column names and types
    printf("<tr bgcolor=\"#eeeeee\">");
    for ( var ccol=0; ccol!=databaseobj.colcount(); ccol++ ) {
    printf(" (");

    //print rows
    var nrows = 0;
    while ( (onerow=databaseobj.rowfetch())!=null ) {
    printf("<tr bgcolor=\"#FFFFFF\">");
    for ( var indx in onerow ) {



    printf("<i>number of rows in select statement [");
    else {
    //ie. table already exist etc
    printf("Error in exec, error [" ,databaseobj.error(), "]<br>");

    printf("<b>Closing database.</b><br>");
    printf("Database closed.<br>");
    else {
    //ie. invalid path, no permission etc
    printf("Error opening database, error [" ,databaseobj.error(), "]<br>");

    printf("Deleting database file.<br>");
    //delete database file
    if ( Server.unlink(dbfilepath)==true ) {
    printf("Database file deleted.<br>");
    else {
    //ie. invalid path, no permission etc
    printf("Error deleting file ",dbfilepath,", system errno [" ,Server.errno(), "]<br>");

    // <--END CODE

    Built-in "Pipe" class provides interface for using inter-process communication
    through Unix pipe, a new process is launched from specified path and
    bidirectional pipe is opened for reading/writing to new process.

    var pipeobj = new Pipe(string EXEPATH);
    var pipeobj = new Pipe("/path/to/executable"); //path to executable
    var pipeobj = new Pipe("/path/to/executable arg0 arg1 arg2"); //executable with command line arguments

    class Pipe {
    bool open(); //open bidirectional pipe, returns true if succedded
    uint close([uint WHICHEND]); //close pipe; if argument is supplied, it's either 0=read end close
    or 1=write end close; with no argument, closes both ends and returns status 0 for success; status nonzero indicates an error
    string read(); //read from pipe untill EOF and return data as a string
    int write(string ARG0 [, string ARG1 , ...]); //write to pipe; returns no of bytes written; returns -1 on error

    //BEGIN CODE-->
    //sending email using Pipe class and sendmail:
    var pipeobj = new Pipe("/usr/sbin/sendmail ");

    if ( ) {
    var smsg = ""
    +"From: \n"
    +"To: \n"
    +"Subject: Webscript test email\n"
    +"Text text text\n"
    +"more text some more text etc.\n"

    //writing ok
    if ( pipeobj.write(smsg)!=(-1) ) {
    pipeobj.close(1); //close write end
    printf(; //read and print output, if any
    else {
    printf("Failed writing to pipe [errno " , Server.errno() ,"]<br\n>");

    var xstatus = pipeobj.close(); //final close completely closes pipe and returns pipe status

    //if non-zero there was an error or process unclean exit
    if ( xstatus!=0 ) {
    printf("Closing pipe indicate failure [exit status " , xstatus ,"]<br\n>");
    printf("System status [errno " , Server.errno() ,"]<br\n>");

    else {
    printf("Opening pipe failed, system status [errno " , Server.errno() ,"]<br\n>");
    // <--END CODE

    Built-in "Dictionary" class is a hash array of unlimited length.
    Values are objects of any type and in Dictionary are stored by refference, not
    by copy. Optional argument SPEEDLEVEL (0-20) is used to increase the speed of
    array read/write by setting the size of Dictionary's hash table.

    var dictobj = new Dictionary([uint SPEEDLEVEL]); //optional argument SPEEDLEVEL 0-20 is used to increase the size of hash

    class Dictionary {
    void set(string NAME, object VALUE); //set the value in dictionary; setting new value over-writes previously set
    value; if VALUE is null effectively removes previously set value from dictionary
    object get(string NAME); //get value from dictionary; null returned if value not in dictionary
    uint len(); //number of values stored in dictionary

    var dictobj = new Dictionary(5); //create new dictionary
    var exmplobj = new Object(); //create new object to store in dictionary
    dictobj.set("name123",exmplobj); //store object in dictionary

    //now read value from dictionary
    var rdobj = dictobj.get("name123");
    if ( rdobj!=null ) {
    // ...

    GVDC, Jun 28, 2008
    1. Advertisements

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. =?Utf-8?B?Qw==?=
    Hermit Dave
    Jan 16, 2004
  2. Shaul Feldman
    Shaul Feldman
    Apr 16, 2004
  3. Guadala Harry
    Jun 15, 2004
  4. nick
    Eliyahu Goldin
    Dec 15, 2004
  5. =?Utf-8?B?bGFuZW0=?=
    Eliyahu Goldin
    Mar 30, 2005
    Jason Kester
    Oct 20, 2005
  7. Jon Clements

    Extending built-in objects/classes

    Jon Clements, Jul 3, 2006, in forum: Python
    John Machin
    Jul 3, 2006
  8. Replies: