util/pagetest.txt

   1 <br/><br/><br/><h2>Module:&nbsp;mysql5.lsp </h2><p>MySQL v.5 interface</p>
   2 <b>Version: </b>2.6 - addition for mysql_escape_string (Jeff)<br/>
   3 <b>Author: </b>Lutz Mueller 2003-2006, Gordon Fischer 2005, Jeff Ober 2007<br/>
   4 <p></p>
   5  This MySQL 5 interface module has been tested on version 5.0.19
   6  of mysql from <a href="http://www.mysql.com">www.mysql.com</a> <p></p>
   7  This implementation supports a maximum of 2,147,483,647
   8  rows in a database table. Now automatically adjusts row indexes to
   9  endian type of host CPU, but higher 32 bits are treated as 0 for now.
  10 <p></p>
  11  @seealso here here  here
  12 <p></p>
  13  [h3]Requirements[/h3]
  14  At the beginning of the program file include a <tt>load</tt> statment for the module:
  15  [pre]
  16  (load "/usr/share/newlisp/mysql5.lsp")
  17  [/pre]
  18 <p></p>
  19  A version of <tt>libmysqlclient</tt> for a specific platform is required:
  20 <p></p>
  21  on LINUX/UNIX: <tt>/usr/local/mysql/libmysqlclient.15.so</tt> [br]
  22  on Mac OS X:   <tt>/usr/local/mysql/libmysqlclient.15.dylib</tt>
  23 <p></p>
  24  To compile MySQL with client libraries use:
  25 <p></p>
  26  <tt>./configure --prefix=/usr/local --enable-shared</tt>
  27 <p></p>
  28  This library might be in a different location on a particular
  29  installation of MySQL or have a different name.
  30  Change accordingly in the code at the beginning.
  31 <p></p>
  32  The MySQL server itself may reside on a different machine
  33  on the network. The library <tt>libmysqlclient</tt> will communicate
  34  with that server. The correct connection is created using
  35  the <tt>MySQL:connect</tt> call.
  36 <p></p>
  37  At the bottom of the module file <tt>mysql5,lsp</tt> a test routine <tt>test-mysql</tt>
  38  is included to test for correct installation of MySQL.
  39 <p></p>
  40  In the <tt>MySQL:connect</tt> call of that test routine the correct parameters
  41  for the MySQL server location and user and password have to be inserted.
  42 <p></p>
  43  [h3]Adapting mysql.lsp to other versions of MySQL[/h3]
  44  Some of the functions like <tt>mysql_num_rows()</tt> cannot be imported
  45  because they are really macros extracting data from structures
  46  like <tt>MYSQL</tt> or <tt>MYSQL_RES</tt>. See the file <tt>mysql.h</tt> in your MySQL distribution.
  47 <p></p>
  48  The file <tt>sql.c</tt> in the newLISP distribution contains a program
  49  calculating the offsets of the most important fields in these
  50  structures. These offsets are used here to retrieve values for
  51  the number of rows in a result set, etc. Using these offsets
  52  and the information found in <tt>mysql.h</tt> and <tt>mysql_com.h</tt>, other
  53  functions can be imported and wrappers built around them.
  54  In this case one needs to install the developer's version of
  55  MySQL to get the header files mentioned.
  56 <p></p>
  57  [h3]Functions available[/h3]
  58  [pre]
  59      MySQL:init ................ get a database handle MYSQL
  60      MySQL:connect ............. connect to a database
  61      MySQL:query ............... execute a SQL statement
  62      MySQL:num-rows ............ rows in result of query
  63      MySQL:num-fields .......... columns in result of query
  64      MySQL:fetch-row ........... get row from the query result
  65      MySQL:fetch-all ........... get all rows from the last query
  66      MySQL:database ............ return all database names
  67      MySQL:tables .............. return all tables names
  68      MySQL:fields .............. return all fields in a table
  69      MySQL:data-seek ........... position in result for fetching
  70      MySQL:affected-rows ....... number of affected rows from operation
  71      MySQL:inserted-id ......... last value of auto increment id operation
  72      MySQL:escape .............. escapes SQL input string using mysql_real_escape_string
  73      MySQL:error ............... get error message
  74      MySQL:close-db ............ close database connection
  75  [/pre]
  76 <p></p>
  77  [h3]A typical MySQL session[/h3]
  78  The following code piece outlines a typical MySQL session:
  79 [p][/p][b]example:[/b][blockquote][pre] (load "mysql5.lsp) ; load the module file
  80
  81  (MySQL:init)       ; initialize
  82  (MySQL:connect "192.168.1.10" "auser" "secret" "mydb") ; logon
  83  (MySQL:query "select ...;") ; SQL query
  84  (MySQL:query "insert ...;") ; SQL query
  85         ...
  86  (MySQL:close-db)[/pre][/blockquote]
  87  The database server is listening on IP 192.168.1.10. The program
  88  connects with username <tt>"auser"</tt> password <tt>"secret"</tt> to a database with
  89  the name <tt>"mydb"</tt>. After connecting SQL statements are performed and
  90  finally the program disconnects from the server.
  91
  92
  93
  94
  95
  96
  97
  98
  99 <p></p><center>- &sect; -</center><p></p>
 100 <a name="MySQL_init"></a><h3><font color=#CC0000>MySQL:init</font></h3>
 101 <b>syntax: (<font color=#CC0000>MySQL:init</font>)</b><br/>
 102 <p><b>return: </b><tt>true</tt> on success, <tt>nil</tt> on failure.</p>
 103
 104
 105 <p></p><center>- &sect; -</center><p></p>
 106 <a name="MySQL_connect"></a><h3><font color=#CC0000>MySQL:connect</font></h3>
 107 <b>syntax: (<font color=#CC0000>MySQL:connect</font> <em>str-server</em> <em>str-userID</em> <em>str-password</em> <em>str-db</em>)</b><br/>
 108 <b>parameter: </b><em>str-server</em> - The host name or IP address or [tt]0[/tt] for localhost.<br/>
 109 <b>parameter: </b><em>str-userID</em> - The user ID for authentication.<br/>
 110 <b>parameter: </b><em>str-password</em> - The password for authentication.<br/>
 111 <b>parameter: </b><em>str-db</em> - The name of the database to connect to.<br/>
 112 <p><b>return: </b><tt>true</tt> for success or <tt>nil</tt> for failure.</p>
 113 <p></p>
 114  Connects to a database on server and authenticates a user ID.
 115  <tt>(MySQL:init)</tt> must have been called previously.
 116
 117
 118 <p></p><center>- &sect; -</center><p></p>
 119 <a name="MySQL_query"></a><h3><font color=#CC0000>MySQL:query</font></h3>
 120 <b>syntax: (<font color=#CC0000>MySQL:query</font> <em>str-sql</em>)</b><br/>
 121 <b>parameter: </b><em>str-sql</em> - A valid SQL query string.<br/>
 122 <p><b>return: </b>For <tt>insert</tt> queries rerturns the inserted ID else <tt>true</tt> </p>
 123  for success or <tt>nil</tt> for failure.
 124 <p></p>
 125  Sends a SQL query string to the database server for evaluation.
 126
 127
 128 <p></p><center>- &sect; -</center><p></p>
 129 <a name="MySQL_num-rows"></a><h3><font color=#CC0000>MySQL:num-rows</font></h3>
 130 <b>syntax: (<font color=#CC0000>MySQL:num-rows</font>)</b><br/>
 131 <p><b>return: </b>Number of rows from last query.</p>
 132
 133
 134 <p></p><center>- &sect; -</center><p></p>
 135 <a name="MySQL_num-fields"></a><h3><font color=#CC0000>MySQL:num-fields</font></h3>
 136 <b>syntax: (<font color=#CC0000>MySQL:num-fields</font>)</b><br/>
 137 <p><b>return: </b>Number of columns from last query.</p>
 138
 139
 140
 141
 142
 143 <p></p><center>- &sect; -</center><p></p>
 144 <a name="MySQL_fetch-row"></a><h3><font color=#CC0000>MySQL:fetch-row</font></h3>
 145 <b>syntax: (<font color=#CC0000>MySQL:fetch-row</font>)</b><br/>
 146 <p><b>return: </b>A list of field elements.</p>
 147 <p></p>
 148  Fetches a row from a previous SQL <tt>MySQL:query</tt>  <tt>select</tt> statement.
 149  Subsequent calls fetch row by row from the result table until the
 150  end of the table is reached.
 151
 152
 153 <p></p><center>- &sect; -</center><p></p>
 154 <a name="MySQL_fetch-all"></a><h3><font color=#CC0000>MySQL:fetch-all</font></h3>
 155 <b>syntax: (<font color=#CC0000>MySQL:fetch-all</font>)</b><br/>
 156 <p><b>return: </b>All rows/fields from the last query.</p>
 157 <p></p>
 158  The whole result set from the query is returned at once as a list of row lists.
 159
 160
 161
 162 <p></p><center>- &sect; -</center><p></p>
 163 <a name="MySQL_databases"></a><h3><font color=#CC0000>MySQL:databases</font></h3>
 164 <b>syntax: (<font color=#CC0000>MySQL:databases</font>)</b><br/>
 165 <p><b>return: </b>A list of databases.</p>
 166 <p></p>
 167  Performs a <tt>show databases;</tt> query.
 168
 169
 170 <p></p><center>- &sect; -</center><p></p>
 171 <a name="MySQL_table"></a><h3><font color=#CC0000>MySQL:table</font></h3>
 172 <b>syntax: (<font color=#CC0000>MySQL:table</font>)</b><br/>
 173 <p><b>return: </b>A list of tables in the database.</p>
 174 <p></p>
 175  Performs a <tt>show tables;</tt> query.
 176
 177
 178 <p></p><center>- &sect; -</center><p></p>
 179 <a name="MySQL_fields"></a><h3><font color=#CC0000>MySQL:fields</font></h3>
 180 <b>syntax: (<font color=#CC0000>MySQL:fields</font> <em>str-table</em>)</b><br/>
 181 <b>parameter: </b><em>str-table</em> - The name of the table.<br/>
 182 <p><b>return: </b>A list of field description lists.</p>
 183 <p></p>
 184  For each field name in the table a list of specifications
 185  for that field is returned. The list starts with the name
 186  for the field followed by the type size/precision and
 187  other optional field descriptions.
 188
 189
 190 <p></p><center>- &sect; -</center><p></p>
 191 <a name="MySQL_data-seek"></a><h3><font color=#CC0000>MySQL:data-seek</font></h3>
 192 <b>syntax: (<font color=#CC0000>MySQL:data-seek</font> <em>num-offset</em>)</b><br/>
 193 <b>parameter: </b><em>num-offset</em> - The [tt]0[/tt] based offset to position inside the data set.<br/>
 194 <p><b>return: </b>Always <tt>true</tt>. </p>
 195 <p></p>
 196  Positions in the result set at a zero based offset
 197  for a subsequent <tt>MySQL:fetch-row</tt> call. If the offset
 198  is out of the allowed range for the result set a subsequent
 199  fetch-row will return <tt>nil</tt>.
 200
 201
 202 <p></p><center>- &sect; -</center><p></p>
 203 <a name="MySQL_error"></a><h3><font color=#CC0000>MySQL:error</font></h3>
 204 <b>syntax: (<font color=#CC0000>MySQL:error</font>)</b><br/>
 205 <p><b>return: </b>Text info about the last error which occured.</p>
 206
 207
 208
 209 <p></p><center>- &sect; -</center><p></p>
 210 <a name="MySQL_affected-rows"></a><h3><font color=#CC0000>MySQL:affected-rows</font></h3>
 211 <b>syntax: (<font color=#CC0000>MySQL:affected-rows</font>)</b><br/>
 212 <p><b>return: </b>Number of affected rows by the last <tt>MySQL:query</tt> operation.</p>
 213
 214
 215 <p></p><center>- &sect; -</center><p></p>
 216 <a name="MySQL_inserted-id"></a><h3><font color=#CC0000>MySQL:inserted-id</font></h3>
 217 <b>syntax: (<font color=#CC0000>MySQL:inserted-id</font>)</b><br/>
 218 <p><b>return: </b>Last insert ID from an auto increment field.</p>
 219
 220
 221 <p></p><center>- &sect; -</center><p></p>
 222 <a name="MySQL_escape"></a><h3><font color=#CC0000>MySQL:escape</font></h3>
 223 <b>syntax: (<font color=#CC0000>MySQL:escape</font> <em>str-sql</em>)</b><br/>
 224 <p><b>return: </b>escaped string</p>
 225 <p></p>
 226  This function will escape special characters in <em>str-sql</em>, so that it
 227  is safe to place it in a MySQL query.
 228
 229 <p></p><center>- &sect; -</center><p></p>
 230 <a name="MySQL_close-db"></a><h3><font color=#CC0000>MySQL:close-db</font></h3>
 231 <b>syntax: (<font color=#CC0000>MySQL:close-db</font>)</b><br/>
 232 <p><b>return: </b>Always <tt>true</tt>.</p>
 233 <p></p>
 234  Closes database access. For new database acess, both <tt>MySQL:init</tt> and
 235  <tt>MySQL:connect</tt> functions have to be called.
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251