File: run_mysql.doc.txt

    ==================================
    # Name :               Run MySQL # 
    # Language :                 PHP #
    # Author :           Ondrej Maly #
    # e-mail : lykantrop@yahoo.co.uk #
    # Creation Date :     2003-10-08 #
    # Last Modified :     2004-12-21 #
    ==================================


    COPYRIGHT NOTICE

    Copyright (c) 2003 Ondrej Maly
    <lykantrop@yahoo.co.uk>
    Licensed under the Artistic License (see attached file)

    DO WHAT THOU WILT with this 
    piece of code as long as this 
    copyright notice remains untouched.

    If you make useful changes to
    the code, please email a copy
    to me. THAT'S THE WHOLE OF LAW.

    CURSES WILL FOLLOW !!!


    DESCRIPTION

    Run MySQL is a powerful tool for feeding the MySQL server with 
    large batches of SQL. The batch could be a string, a local file or
    a file uploaded via HTML form.

    INITIALISATION

    There are three ways how to initialise this class.

        1)  Default values are used for the initialisation. They are hard-
            coded in the class variables. Usage :

            $foo = new run_mysql ( defaults );

        2)  An existing connection is used. Supposed you have chosen the
            database before. Usage :

            $foo = new run_sql ( $link_ID );
            where the $link_ID is the resource link identifier

        3)  No connection is established. Usage :

            $foo = new run_sql ();

            You must then explicitly set up the properties :

            $foo->mysql_host, 
            $foo->mysql_username, 
            $foo->mysql_password and
            $foo->mysql_db and call the internal method
            $foo->connect(); before any usage of the class


    CLASS USAGE

    After the class is initialised it offers three methods how to pass the
    batch to the MySQL server.

        1)  run_script ( string script[, bool errors]);
            The batch is passed as string. The string is pre-parsed into
            separate commands. Please discuss the MySQL manual how the
            comments are handled by the MySQL server.

        2)  run_local_file ( string pathname[, bool errors]);
            The batch is loaded from the local file and then passed as above.
        2)  run_upload_file ( string name[, bool errors]);

            The batch is loaded from the file uploaded via HTML form. 
            The name of the input field in the form is used as na 
            argument. Then handled as above.

    Those three methods return the resource identifier of the result of the
    last SQL query in the batch (you can utilise the result then) or FALSE
    if an error occurs.
    
    2004-12-21

    New feature added. You may pass an additional parameter to thesse three
    methods. Value ERR_STOP /default/ causes script termination on error
    while ERR_IGNORE forces the class continue with execution.


    ERROR HANDLING

    If an error occurs, the error message is stored in the property error_msg
    and can be accessed using the error_msg() method then.

    If an errorneous SQL statement occurs in the batch, then everythig before
    it is of course executed. Be careful.


    SECURITY CONSIDERATIONS

    Thhere's one important thing when using SQL scripts posted via the HTML
    form.  You must be 100% sure if possible, that only authenticated persons
    could run the php script handling the form data and calling this class.
    This is out of the scope of the class presented.


    PUBLIC METHODS

    string error_msg ()
        Returns the error message if an error occures. In fact it returns the
        value of the internal property error_msg, it could be used instead.
        If no error has occured, returns FALSE.

    boolean run_mysql ([resource link_ID])
        Constructor. Read the documentation above.

    resource run_local_file ( string path[, errors])
        Runs a MySQL script from a local file.

    resource run_script ( string script[, errors])
        Runs a MySQL script stored in the string script.

    resource run_upload_file ( string name[, errors])
        Runs a MySQL script from a file uploaded via HTML form. As an
        argument the name of the input field is used.