The mysql_api library

The mysql_api library enables you to write a DB accessing application in nML, specially for MySQL database.
  • download : [zip] [tar.gz]

  • Programs that use the mysql_api library must be linked as follows:
    	[ Unix ]
    	    nmlc other options -ccopt -Lmysql system's lib directory 
           		 -cclib -lmysqlclient -cclib -lmysql_api other files
           		 
    	[ MS-Windows ]        
    	    nmlc other options -cclib -lmySQL -cclib -lmySQL_api other files
    
    Note:
    In Unix, you should set the environment variable for MySQL library directory in your path
    ex) setenv LD_LIBRARY_PATH your_lib_path:/usr/local/mysql/lib/mysql 
    
    28.1 Module Mysql_api: Mysql Database API library


    This module implements API functions for interfacing with Mysql database. These API functions are implemented based on mysql database C API functions. So, you need to read original the C API manual
    Abstract data type definitions for mysql database
    type mysql              (* MYSQL*               *)
    type mysql_res          (* MYSQL_RES*           *)
    type mysql_row          (* MYSQL_ROW            *)
    type mysql_field        (* MYSQL_FIELD*         *)
    type mysql_field_offset (* MYSQL_FIELD_OFFSET   *)
    type mysql_row_offset   (* MYSQL_ROW*           *)   
    type my_ulonglong = int (* unsigned long long   *)
    type mysql_option       (* enum mysql_option    *)
    type my_bool = int      (* char                 *)
    type lengths            (* unsigned long*       *)
    
    This is for accessing abstract data in nML
    // Get a MYSQL null pointer
    mysql_null : unit -> mysql 
    
    // Get a MYSQL_RES null pointer
    mysql_res_null : unit -> mysql_res
    
    // Get a MYSQL_ROW null pointer
    external mysql_row_null : unit -> mysql_row 
    
    // Get a MYSQL_FIELD null pointer
    mysql_field_null : unit -> mysql_field 
    
    // Check whether given MYSQL pointer is null 
    is_mysql_null : mysql -> bool 
    
    // Check whether given MYSQL_RES pointer is null 
    is_mysql_res_null : mysql_res -> bool
    
    // Check whether given MYSQL_ROW pointer is null 
    is_mysql_row_null : mysql_row -> bool
    
    // Check whether given MYSQL_FIELD pointer is null 
    is_mysql_field_null : mysql_field -> bool
    
    // Get the field name of the given mysql_field
    mysql_extract_field_name : mysql_field -> string
    
    // Get the table name of the given mysql_field
    mysql_extract_field_table : mysql_field -> string
    
    // Get the default value of the given mysql_field
    mysql_extract_field_def : mysql_field -> string
    
    // Get the type of the given mysql_field
    mysql_extract_field_type : 
    	mysql_field 
    	-> int 	(* 0 : FIELD_TYPE_TINY *)
    		(* 1 : FIELD_TYPE_SHORT *)
    		(* 2 : FIELD_TYPE_LONG *)
    		(* 3 : FIELD_TYPE_INT24 *)
    		(* 4 : FIELD_TYPE_LONGLONG *)
    		(* 5 : FIELD_TYPE_DECIMAL *)
    		(* 6 : FIELD_TYPE_FLOAT *)
    		(* 7 : FIELD_TYPE_DOUBLE *)
    		(* 8 : FIELD_TYPE_TIMESTAMP *)
    		(* 9 : FIELD_TYPE_DATE *)
    		(* 10 : FIELD_TYPE_TIME *)
    		(* 11 : FIELD_TYPE_DATETIME *)
    		(* 12 : FIELD_TYPE_YEAR *)
    		(* 13 : FIELD_TYPE_STRING *)
    		(* 14 : FIELD_TYPE_BLOB *)
    		(* 15 : FIELD_TYPE_SET *)
    		(* 16 : FIELD_TYPE_ENUM *)
    		(* 17 : FIELD_TYPE_NULL *)
    		(* 18 : FIELD_TYPE_CHAR *)
    
    // Get nth field's value of the current row 
    mysql_extract_nth_row : 
    	mysql_row -> int -> string
    
    // produce a mysql_option from the given integer 
    mysql_get_option :
    	 int 
    	 (* 0 : MYSQL_OPT_CONNECT_TIMEOUT *)
    	 (* 1 : MYSQL_OPT_COMPRESS *)
    	 (* 2 : MYSQL_OPT_NAMED_PIPE *)
    	 (* 3 : MYSQL_INIT_COMMAND *)
    	 (* 4 : MYSQL_READ_DEFAULT_FILE *)
    	 (* 5 : MYSQL_READ_DEFAULT_GROUP *)
    	 (* 6 : MYSQL_SET_CHARSET_DIR *)
    	 (* 7 : MYSQL_SET_CHARSET_NAME *)
    	 -> mysql_option 
    
    Default mysql api interface
    // returns the number of rows affected(changed) by the last UPDATE, DELETE
    // or INSERT query. May be called immediately after mysql_query().
    // For SELECT statements, it works like mysql_num_rows()
    mysql_affected_rows : mysql -> my_ulonglong 
    
    // close a previously opened connection. 
    mysql_close : mysql -> unit 
    
    // deprecated. it is preferable to use mysql_real_connect() instead
    mysql_connect : 
    	 mysql 		(* mysql *)
     	 -> string      (* const char* host  *)
    	 -> string      (* const char* user *)
    	 -> string      (* const char* passwd *)
    	 -> mysql    
    
    // create the database named by the db parameter
    mysql_create_db : 
    	 mysql 		(* mysql *)
    	 -> string	(* const char* db *)
    	 -> int		(* int : zero if success or non-zero *)
    
    // seeks to an arbitrary row in a query result set.
    mysql_data_seek :
    	 mysql_res	(* result *)
    	 -> my_ulonglong  (* unsigned long long_offset *)
    	 -> unit	(* unit *)
    
    // see the MySQL C API doc
    mysql_debug :
    	 string		(* char* debug *)
    	 -> unit	(* unit	 *)
    
    // drops the database named by the string parameter
    mysql_drop_db :
    	 mysql		(* mysql *)
    	 -> string 	(* const char* db *)
    	 -> int		(* int : zero if success, or non-zero *)
    
    
    // instruct the server to write somedebug information to the log
    // the connected user must have the process privilege for this to work
    mysql_dump_debug_info :
    	 mysql		(* mysql *)
    	 -> int 	(* int : zero if success, or non-zero*)
    
    // deprecated. mysql_errorno() or mysql_error() may be used instead	 
    mysql_eof :
    	 mysql_res	(* result*)
    	 -> my_bool	(* my_bool : zero if no error, or non-zero*)
    
    // for the connection specified by mysql parameter, mysql_errno() returns
    // the error code for the most recently invoked API function that can 
    // succeed or fail. A return value of zero means that no error occurred.
    // Client error message numbers are listed in the MySQL 'errmsg.h" header file
    // Server error message numbers are listed in 'mysqld_error.h' 	 
    mysql_errno : 
    	 mysql		(* mysql*)
    	 -> int		(* unsigned int : error code value, zero if no error*)
    
    // returns the error message for the most recently invoked API function
    // that can succeed or fail
    // an empty string ("") is returned if no error occurred
    mysql_error :
    	 mysql		(* mysql*)
    	 -> string	(* char* : error message for most recently invoked API fun,*)
    	 		(* "" if no error*)
    
    // you should use mysql_real_escape_string() instead!
    mysql_escape_string :
    	string 		(* char* to *)
            -> string 	(* char* from *)
            -> int		(* unsigned long from_length *)
            -> int 		(* unsigned long *)
    
    // returns the definition of one column of a result set as a mysql_field type
    // call this function repeatedly to retrieve information about all columns
    // in the result set.
    // returns null when no more fields are left 
    mysql_fetch_field :
    	 mysql_res	(* result*)
    	 -> mysql_field (* the mysql_field structure for the current column,*)
    	 		(* null if no columns are left*)
    
    // returns an array of all mysql_field type value for a result set.
    // each structure provides the field definition for one column of the result set
    // note : removed in nML library (use mysql_fetch_field instead!!)
    //mysql_fetch_fields :
    //	 mysql_res	(* result *)
    //	 -> mysql_field (* an array of mysql_field structures for all columns of a result set *)
    
    // given a field number for a column within a result set, returns that column's 
    // field definition as a mysql_field type. you may use this function to retrieve 
    // the difinition for an arbitrary column. the value of fieldnr should be in
    // the range from 0 to mysql_num_fields(result)-1	 
    mysql_fetch_field_direct :
    	 mysql_res	(* result *)
    	 -> int		(* unsigned int fieldnr *)
    	 -> mysql_field (* mysql_field structure for the specified column *)
    
    // returns the lengths of the columns of the current row within a result set
    // if you plan to copy field values, this length information is also useful 
    // for optimization, because you can avoid calling strlen(). in addition,
    // if the result set contains binary data, you must use this function to 
    // determine the size of the data, because strlen() returns incorrect 
    // results for any field containing null characters
    mysql_fetch_lengths :
    	 mysql_res 	(* result *)
    	 -> lengths	(* unsigned long* : an array of unsigned long integers representing the size*)
    	 		(*	of each column, null of an error occurred *)
    
    // retrieves the next row of a result set. when used after mysql_store_result(),
    // mysql_fetch_row() returns null when there are no more rows to retrieve.
    // when used after mysql_use_result(), mysql_fetch_row() returns null
    // when there are no more rows to retrieve or if an error occurred.
    mysql_fetch_row :
    	 mysql_res	(* result *)
    	 -> mysql_row	(* a mysql_row structure for next row.*)
    	 		(* null if no more rows to retrieve or if an error occurred*)
    
    // returns the number of columns for the most recent query on the connection
    mysql_field_count :
    	 mysql		(* mysql *)
    	 -> int	 	(* unsigned int : the number of fields in a result set *)
    
    // set the field cursor to the given offset. the next call to mysql_fetch_field()
    // will retrieve the field definition of the column associated with that offset
    mysql_field_seek :
    	 mysql_res	(* result*)
    	 -> mysql_field_offset (* offset*)
    	 -> mysql_field_offset (* previous value of the field cursor*)
    
    // returns the position of the field cursor used for the last mysql_fetch_field().
    // this value can be used as an argument to mysql_field_seek()
    mysql_field_tell :
    	 mysql_res	(* result *)
    	 -> mysql_field_offset	(* = unsigned int *)
    	    (* position of field cursor used for the last mysql_fetch_field *)
    	    (* can be used as an argument to mysql_field_seek *)
    
    // frees the memory allocated for a result set by mysql_store_result(),
    // mysql_use_result(), mysql_list_dbs(), etc. when you are done with a result set,
    // you must free the menory it uses by calling mysql_free_result()	    
    mysql_free_result :
    	 mysql_res	(* result *)
    	 -> unit	(* () *)
    
    // returns a string that represents the client library version
    mysql_get_client_info :
    	 unit		(* unit *)
    	 -> string	(* char* : the mysql client library version *)
    
    // returns a string describing the type of connection in use, including
    // the server host name
    mysql_get_host_info :
    	 mysql		(* mysql *)
    	 -> string	(* char* : the server host name and the connection type *)
    
    // returns the protocol version used by current connection
    mysql_get_proto_info :
    	 mysql 		(* mysql *)
    	 -> int		(* unsigned int : protocol version used by the current connection *)
    
    // returns a string that represents the server version number
    mysql_get_server_info : 
    	 mysql		(* mysql *)
    	 -> string	(* char* : the server version number *)
    
    // retrives a string providing information about the most recently executed query.
    // see MySQL C API manual page for detailed information.
    mysql_info :
    	 mysql		(* mysql *)
    	 -> string	(* char* : additional information about the most recently executed query. *) 
    	 		(* 	null if no information is available for the query *)
    
    
    	 
    // allocates or initializes a MYSQL object suitable for mysql_real_connect().
    // if mysql is a NULL pointer(get this from mysql_null() function), 
    // the function allocates, initializes and returns a new object.
    // otherwise the object is initialized and the address of the object is returned.
    // if mysql_init() allocates a new object, it will be freed when mysql_close() is 
    // called to close the connection.	 		
    mysql_init :
    	 mysql		(* mysql : usually null. get this from c function*)
    	 -> mysql	(* mysql *)
     
    // returns the ID generated for an AUTO_INCREMENT column by the previous query.
    // use this functin after you have performed an INSERT query into a table that 
    // contains an AUTO_INCREMENT field
    mysql_insert_id :
    	 mysql		(* mysql*)
    	 -> my_ulonglong  (* the value of the AUTO_INCREMENT field that was updated by the previous query.*)
    	 		  (* returns zero if there was no previous query on the connection *)
    	 		  (* or if the query didn't update an AUTO_INCREMENT value*)
    
    
    // asks the server to kill the thread specified by pid
    mysql_kill : 
    	 mysql		(* mysql*)
    	 -> int		(* unsigned long pid *)
    	 -> int		(* int : zero for success, or non-zero*)
    
    // returns a result set consisting of databse names on the server that match the simple
    // regular expression specified by the wild parameter. wild may contain the wildcard
    // characters '%' or '_', or may be "" to match all databases.
    // calling mysql_list_dbs() is similar to executing the query SHOW database [LIKE wild]
    mysql_list_dbs :
    	 mysql
    	 -> string	(* const char* wild*)
    	 -> mysql_res	
    
    // returns a result set consisting of field names in the given table that match the simple
    // regular expression specified by the wild parameter. wild may contain the wildcard
    // characters '%' or '_', or may be "" to match all fields.
    // calling mysql_list_fields() is similar to executing the query 
    // SHOW COLUMNS FROM tble_name [LIKE wild]
    mysql_list_fields :
    	 mysql
    	 -> string	(* const char* table*)
    	 -> string	(* const char* wild*)
    	 -> mysql_res	 
    
    // returns a result set describing the current server threads. this is the same kind of
    // information as that reported by mysqladmin processlist or a SHOW PROCESSLIST query
    mysql_list_processes :
    	 mysql
    	 -> mysql_res
    	 
    // returns a result set consisting of table names in the current database that match the 
    // simple regular expression specified by the wild parameter. wild may contain the wildcard
    // characters '%' or '_', or may be "" to match all fields.
    // calling mysql_list_tables() is similar to executing the query SHOW tables [LIKE wild]
    mysql_list_tables :
    	 mysql
    	 -> string	(* const char* wild *)
    	 -> mysql_res
    
    // returns the number of columns in a result set
    mysql_num_fields : 
    	 mysql_res 
    	 -> int		(* unsigned int*)
    
    // returns the number of rows in the result set
    mysql_num_rows :
    	 mysql_res
    	 -> my_ulonglong 
    
    // can be used to set extra connect options and affect behavior for a connection.
    // this function may be called multiple times to set several options
    mysql_options :
    	 mysql
    	 -> mysql_option  (* obtained by mysql_get_option function *)
    	 -> string 	(* const char* arg  *)
    	 -> int 	(* int : zero fo success, or non-zero *)
    
    // checks whether or not the connection to the server is working
    // if it has gone down, an automatic reconnections is attempted
    mysql_ping : 
    	 mysql
    	 -> int		(* int : zero if the server is alive, or non-zero *)
    
    // executes the SQL query pointed to by the string
    // the query must consist of a single SQL statement.
    // you should not add a terminating semicolon(':') or \g to the statement	 
    mysql_query :
    	 mysql
    	 -> string 	(* const char* query *)
    	 -> int		(* int : zero if the query was successful,  *)
    
    
    // attempts to establish a connection to a MySQL database engine running on the specified host
    // mysql_real_connect() must complete successfully before you can execute any of the other
    // API functions, with the exception of mysql_get_client_info
    // for detail information, see the MySQL C API documentation in the manual
    mysql_real_connect : (* if MYSQL_VERSION_ID >= 32200 *)
    	 mysql
    	 -> string	(* const char* host  *)
    	 -> string	(* const char* user *)
    	 -> string	(* const char* passwd *)
    	 -> string 	(* const char* db *)
    	 -> int 	(* unsigned int port *)
    	 -> string	(* const char* unix_socket *)
    	 -> int		(* unsigned int client_flag *)
    	 -> mysql
    
    // executes the SQL query pointed to by query, which should be a string length bytes long.
    // the query must consist of a single SQL statement. you should not add ad terminating
    // semicolon(':') or \g to the statement
    // Note : for queries that contain binary data. in addition, it is faster than mysql_query()
    mysql_real_query : 
    	 mysql
    	 -> string	(* const char* query *)
    	 -> int		(* unsigned int length *)
    	 -> int		(* int : zero if success *)
    
    // asks the MySQL server to reload the grant tables. 
    // the connected user must have the reload privilege
    mysql_reload :
    	 mysql
    	 -> int		(* int : zero for success *)
    
    // sets the row cursor to an arbitrary row in a query result set.
    // this require that the result set structure contains the entire result of the query,
    // so mysql_row_seek() may be used in conjunction only with mysql_store_result(),
    // not with mysql_use_result() 
    mysql_row_seek :
    	 mysql_res
    	 -> mysql_row_offset
    	 -> mysql_row_offset 		(* int : zero for success  *)
    
    // returns the current position of the row cursor fo the last mysql_fetch_row().
    // this value can be used as an argument to mysql_row_seek()
    mysql_row_tell :
    	 mysql_res
    	 -> mysql_row_offset   (* = MYSQL_ROW* *)
    
    // causes the database specified by the string parameter to become the default(current) DB
    // on the connection specified by mysql. in subsequent queries, this database is the default 
    // for the table reference that do not include an explicit database specifier
    mysql_select_db :
    	 mysql
    	 -> string	(* const char* db  *)
    	 -> int		(* int : zero for success *)
    
    // asks the database serve to shutdown. the connected user must have shutdown privileges
    mysql_shutdown :
    	 mysql
    	 -> int		(* int : zero for success *)
    
    // returns a string containing information similar to that provided by the mysqladmin status
    // command. this includes uptime in seconds and the number of running threads, questions,
    // reloads and open tables
    mysql_stat :
     	 mysql
     	 -> string	(* char*  : a character string describing the server status *)
     	 		(*  	null if an error occurred *)
    
    // you must call mysql_store_result() or mysql_use_result() for every query which successfully 
    // retrieves data(SELECT, SHOW, DESCRIBE, EXPLAIN)
    // for detail information, see the MySQL C API documentation in the manual 
    mysql_store_result :
    	 mysql
    	 -> mysql_res	
    
    // returns the thread ID of the current connection. 
    // this value can be used as an argument to mysql_kill() to kill the thread	 	 
    mysql_thread_id :
    	 mysql
    	 -> int		(* unsigned long *)
    
    // you must call mysql_store_result() or mysql_use_result() for every query 
    // which successfully retrieves data (SELECT ,SHOW, DESCRIBE, EXPLAIN)
    // for detail information, see the MySQL C API documentation in the manual 
    mysql_use_result :
    	 mysql
    	 -> mysql_res
    
    removed library due to no definition
    mysql_slave :
    mysql_stop_slave :	 
    mysql_thread_save :
    mysql_change_user : 
    mysql_character_set_name :
    mysql_real_escape_string :
    
    Refined function definitions
    // refined mysql_real_connect function 
    mysql_refined_real_connect : 
    	 mysql
    	 -> string	(* const char* host  *)
    	 -> string	(* const char* user *)
    	 -> string	(* const char* passwd *)
    	 -> string 	(* const char* db *)