From ba5bd758b0767139a9bcecaa31c59387976bfa04 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20Grubbstr=C3=B6m=20=28Grubba=29?=
 <grubba@grubba.org>
Date: Mon, 13 Apr 1998 16:11:38 +0200
Subject: [PATCH] Added inline documentation.

Rev: src/modules/Mysql/mysql.c:1.18
---
 src/modules/Mysql/mysql.c | 252 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 250 insertions(+), 2 deletions(-)

diff --git a/src/modules/Mysql/mysql.c b/src/modules/Mysql/mysql.c
index 5b5ccbb1fe..a6b6e54478 100644
--- a/src/modules/Mysql/mysql.c
+++ b/src/modules/Mysql/mysql.c
@@ -1,5 +1,5 @@
 /*
- * $Id: mysql.c,v 1.17 1998/03/16 14:54:16 grubba Exp $
+ * $Id: mysql.c,v 1.18 1998/04/13 14:11:38 grubba Exp $
  *
  * SQL database functionality for Pike
  *
@@ -73,7 +73,22 @@ typedef struct dynamic_buffer_s dynamic_buffer;
  * Globals
  */
 
-RCSID("$Id: mysql.c,v 1.17 1998/03/16 14:54:16 grubba Exp $");
+RCSID("$Id: mysql.c,v 1.18 1998/04/13 14:11:38 grubba Exp $");
+
+/*
+**! module Mysql
+**! note
+**!	$Id: mysql.c,v 1.18 1998/04/13 14:11:38 grubba Exp $
+**! class mysql
+**!
+**!	Mysql.mysql is a pre-compiled Pike program. It enables
+**!	access to the Mysql database from within Pike. Mysql.mysql
+**!	is a part of the Mysql module.
+**!
+**!	Mysql is available from	www.tcx.se.
+**!
+**! see also: Mysql.result, Sql.sql
+*/
 
 struct program *mysql_program = NULL;
 
@@ -262,6 +277,22 @@ static void pike_mysql_reconnect(void)
  * Methods
  */
 
+/*
+**! method void create()
+**! method void create(string host)
+**! method void create(string host, string database)
+**! method void create(string host, string database, string user)
+**! method void create(string host, string database, string user, string password)
+**!
+**!	Connects to a Mysql database.
+**!
+**!	To access the Mysql database, you must first connect to it. This is
+**!	done with the function mysql().
+**!
+**!	If you give no argument, or give "" as hostname it will connect with
+**!	a UNIX-domain socket, which is a big performance gain.
+*/
+
 /* void create(string|void host, string|void database, string|void user, string|void password) */
 static void f_create(INT32 args)
 {
@@ -312,6 +343,12 @@ static void f_create(INT32 args)
   pike_mysql_reconnect();
 }
 
+/*
+**! method int affected_rows()
+**!
+**!	Returns the number of rows affected by the last query.
+**!
+*/
 /* int affected_rows() */
 static void f_affected_rows(INT32 args)
 {
@@ -331,6 +368,13 @@ static void f_affected_rows(INT32 args)
   push_int(count);
 }
 
+/*
+**! method int insert_id()
+**!
+**!	Returns the id of the last INSERT query into a table with
+**!	an AUTO INCREMENT field.
+**!
+*/
 /* int insert_id() */
 static void f_insert_id(INT32 args)
 {
@@ -351,6 +395,12 @@ static void f_insert_id(INT32 args)
   push_int(id);
 }
 
+/*
+**! method string error()
+**!
+**!	Returns a string describing the last error from the Mysql-server.
+**!
+*/
 /* int|string error() */
 static void f_error(INT32 args)
 {
@@ -378,6 +428,15 @@ static void f_error(INT32 args)
   }
 }
 
+/*
+**! method void select_db(string database)
+**!
+**!	The Mysql-server can hold several databases. You select which one
+**!	you want to access with this function.
+**!
+**! see also: create, create_db, drop_db
+**!
+*/
 /* void select_db(string database) */
 static void f_select_db(INT32 args)
 {
@@ -433,6 +492,19 @@ static void f_select_db(INT32 args)
   pop_n_elems(args);
 }
 
+/*
+**! method object(Mysql.mysql_result) big_query(string q)
+**!	Make an SQL query
+**! arg string q
+**!	The SQL query
+**!
+**!	This function sends an SQL query to the Mysql-server. The result
+**!	of the query is returned as a Mysql.mysql_result object.
+**!	Returns 0 if the query didn't return any result (e.g. INSERT or
+**!	similar).
+**!
+**! see also: mysql_result
+*/
 /* object(mysql_result) big_query(string q) */
 static void f_big_query(INT32 args)
 {
@@ -528,6 +600,17 @@ static void f_big_query(INT32 args)
   }
 }
 
+/*
+**! method void create_db(string database)
+**!	Create a new database
+**! arg string database
+**!	Name of the database to be created
+**!
+**!	This function creates a new database in the Mysql-server.
+**!
+**! see also: select_db, drop_db
+**!
+*/
 /* void create_db(string database) */
 static void f_create_db(INT32 args)
 {
@@ -575,6 +658,17 @@ static void f_create_db(INT32 args)
   pop_n_elems(args);
 }
 
+/*
+**! method void drop_db(string database)
+**!	Drop a database
+**! arg string database
+**!	Name of database to be dropped
+**!
+**!	This function drops a database from a Mysql-server.
+**!
+**! see also: create_db, select_db
+**!
+*/
 /* void drop_db(string database) */
 static void f_drop_db(INT32 args)
 {
@@ -622,6 +716,16 @@ static void f_drop_db(INT32 args)
   pop_n_elems(args);
 }
 
+/*
+**! method void shutdown()
+**!	Shutdown the Mysql-server
+**!
+**!	This function shuts down a running Mysql-server.
+**!
+**! see also:
+**!	reload
+**!
+*/
 /* void shutdown() */
 static void f_shutdown(INT32 args)
 {
@@ -655,6 +759,15 @@ static void f_shutdown(INT32 args)
   pop_n_elems(args);
 }
 
+/*
+**! method void reload()
+**!	Reload security tables
+**!
+**!	This function causes the Mysql-server to reload its access tables.
+**!
+**! see also: shutdown
+**!
+*/
 /* void reload() */
 static void f_reload(INT32 args)
 {
@@ -688,6 +801,23 @@ static void f_reload(INT32 args)
   pop_n_elems(args);
 }
 
+/*
+**! method string statistics()
+**!	Some Mysql-server statistics
+**!
+**!	This function returns some server statistics.
+**!
+**! 	Example:
+**!	<pre>
+**!	int main()
+**!	{
+**!	  write(mysql()->statistics());
+**!	  return(0);
+**!	}
+**!	</pre>
+**! see also: server_info, host_info, protocol_info
+**!
+*/
 /* string statistics() */
 static void f_statistics(INT32 args)
 {
@@ -710,6 +840,15 @@ static void f_statistics(INT32 args)
   push_text(stats);
 }
 
+/*
+**! method string server_info()
+**!	Give the version number of the Mysql-server
+**!
+**!	This function returns the version number of the Mysql-server.
+**!
+**! see also: statistics, host_info, protocol_info
+**!
+*/
 /* string server_info() */
 static void f_server_info(INT32 args)
 {
@@ -735,6 +874,16 @@ static void f_server_info(INT32 args)
   f_add(2);
 }
 
+/*
+**! method string host_info()
+**!	Give information about the Mysql-server connection
+**!
+**!	This function returns a string describing the connection to
+**!	the Mysql-server.
+**!
+**! see also: statistics, server_info, protocol_info
+**!
+*/
 /* string host_info() */
 static void f_host_info(INT32 args)
 {
@@ -758,6 +907,16 @@ static void f_host_info(INT32 args)
   push_text(info);
 }
 
+/*
+**! method int protocol_info()
+**!	Give the Mysql protocol version
+**!
+**!	This function returns the version number of the protocol the
+**!	Mysql-server uses.
+**!
+**! see also: statistics, server_info, host_info
+**!
+*/
 /* int protocol_info() */
 static void f_protocol_info(INT32 args)
 {
@@ -779,6 +938,18 @@ static void f_protocol_info(INT32 args)
   push_int(prot);
 }
 
+/*
+**! method object(Mysql.mysql_result) list_dbs()
+**! method object(Mysql.mysql_result) list_dbs(string wild)
+**!	List databases
+**!
+**!	Returns a table containing the names of all databases in the
+**!	Mysql-server. If an argument is specified, only those matching
+**!	wild are returned.
+**!
+**! see also: list_tables, list_fields, list_processes, Mysql.mysql_result
+**!
+*/
 /* object(mysql_res) list_dbs(void|string wild) */
 static void f_list_dbs(INT32 args)
 {
@@ -837,6 +1008,20 @@ static void f_list_dbs(INT32 args)
   push_object(clone_object(mysql_result_program, 1));
 }
 
+/*
+**! method object(Mysql.mysql_result) list_tables()
+**! method object(Mysql.mysql_result) list_tables(string wild)
+**!	List tables in the current database
+**! arg string wild
+**!	Wildcard to filter with.
+**!
+**!	Returns a table containing the names of all tables in the current
+**!	database. If an argument is given, only those matching wild are
+**!	returned.
+**!
+**! see also: list_dbs, list_fields, list_processes, Mysql.mysql_result
+**!
+*/
 /* object(mysql_res) list_tables(void|string wild) */
 static void f_list_tables(INT32 args)
 {
@@ -895,6 +1080,47 @@ static void f_list_tables(INT32 args)
   push_object(clone_object(mysql_result_program, 1));
 }
 
+/*
+**! method array(int|mapping(string:mixed)) list_fields(string table)
+**! method array(int|mapping(string:mixed)) list_fields(string table, string wild)
+**!	List all fields
+**! arg string table
+**!	Name of table to list the fields of
+**! arg string wild
+**!	Wildcard to filter the result with
+**!
+**!	Returns an array of mappings with information about the fields in the
+**!	specified table.
+**!
+**!	The mappings contain the following entries:
+**!	<pre>
+**!	 "name":	string	The name of the field.
+**!	 "table":	string	The name of the table.
+**!	 "default":	string	The default value for the field.
+**!	 "type":	string	The type of the field.
+**!	 "length":	int	The length of the field.
+**!	 "max_length":	int	The length of the longest element in this field.
+**!	 "flags":	multiset(string)	Some flags.
+**!	 "decimals":	int	The number of decimalplaces.
+**!	</pre>
+**!
+**!	The type of the field can be any of:
+**!	"decimal", "char", "short", "long", "float", "double", "null",
+**!	"time", "longlong", "int24", "tiny blob", "medium blob",
+**!	"long blob", "var string", "string" or "unknown".
+**!
+**!	The flags multiset can contain any of
+**!	 "primary_key":	This field is part of the primary key for this table.
+**!	 "not_null":	This field may not be NULL.
+**!	 "blob":	This field is a blob field.
+**!
+**! note
+**!	Michael Widenius recomends usage of the following query instead:
+**!	 show fields in 'table' like "wild"
+**!
+**! see also: list_dbs, list_tables, list_processes, fetch_fields
+**!
+*/
 /* array(int|mapping(string:mixed)) list_fields(string table, void|string wild) */
 static void f_list_fields(INT32 args)
 {
@@ -972,6 +1198,16 @@ static void f_list_fields(INT32 args)
   f_aggregate(i);
 }
 
+/*
+**! method object(Mysql.mysql_result) list_processes()
+**!	List all processes in the Mysql-server
+**!
+**!	Returns a table containing the names of all processes in the
+**!	Mysql-server.
+**!
+**! see also: list_dbs, list_tables, list_fields, Mysql.mysql_result
+**!
+*/
 /* object(mysql_res) list_processes() */
 static void f_list_processes(INT32 args)
 {
@@ -1018,6 +1254,18 @@ static void f_list_processes(INT32 args)
   push_object(clone_object(mysql_result_program, 1));
 }
 
+/*
+**! method int binary_data()
+**!	Inform if this version of mysql supports binary data
+**!
+**!	This function returns non-zero if binary data can be reliably stored
+**!	and retreived with this version of the mysql-module.
+**!
+**!	Usually, there is no problem storing binary data in mysql-tables,
+**!	but data containing '\0' (NUL) couldn't be fetched with old
+**!	versions (prior to 3.20.5) of the mysql-library.
+**!
+*/
 /*
  * Support for binary data in tables
  */
-- 
GitLab