[翻译]SQL Relay中PHP API参考手册

==================序=======================
前几天KAADA给我了这个SQL Relay的文章，想把它翻译出来。我请了双鱼大大来做主要的翻译工作，虽然他没有编程的经验，但是在这里还是要感谢双鱼大大的帮助。
由于我们才刚刚准备开始使用SQL Relay，所以这片文章的翻译还有很多我们不理解的地方，可能导致翻译上的问题，所以这篇文章只能作为一个小小的参考。也希望朋友们在看过后指出问题，让更多的人来使用它。 REDRYM by:2007-03-22 15:33

翻译： pacman
校对： 雪狼
贝贝
血色
整理： KAADA、REDRUM
MAIL： xcy_0001@hotmail.com
BY： 2007-03-22

====================正文====================

SQL-relay PHP module

PHP API

USING

FUNCTIONS

AUTHOR

 

USINGFUNCTIONSAUTHOR

You can use the module by loading it in your PHP script and calling SQL Relay functions.

你可以通过以下方式使用该module：
在你的PHP脚本中加载它，然后调用SQL Relay函数

 

For example:
例如:

=======CODE:start======
dl("sql_relay.so");
$con=sqlrcon_alloc("adasz",9000,"","user1","password1",0,1);
$cur=sqlrcur_alloc($con);
sqlrcur_sendQuery($cur,"select table_name from user_tables");
sqlrcon_endSession($con);
for ($i=0; $i<sqlrcur_rowCount($cur); $i++) {
printf("%s/n",sqlrcur_getField($cur,$i,"table_name"));
}
sqlrcur_free($cur);
sqlrcon_free($con);
=======CODE:end========

An alternative to running dl(sql_relay.so) is to put a line like:

运行dl(sql_relay.so)的另外一种方法：
在你的php.ini文件里添加如下的语句：

extension=sql_relay.so

In your php.ini file. Doing this will improve performance as the library isn't loaded and unloaded each time a script runs, but only once when the web-server is started.

这种做法能提高性能。因为这种做法下库文件(library，以下通称库文件)不是随着某脚本的运行而重复加载卸载，它只随着web-server的启而进行一次加载。

 

int sqlrcon_alloc(string server, int port, string socket, string user, string password, int retrytime, int tries)

Initiates a connection to "server" on "port" or to the unix "socket" on the local machine and authenticates with "user" and "password". Failed connections will be retried for "tries" times on interval "retrytime". If "tries" is 0 then retries will continue forever. If "retrytime" is 0 then retries will be attempted on a default interval.

发起一个连接到"server"的"port"端口，或者到本地机器的unix "socket",然后使用"user"和"password"登陆。连接失败的话会尝试重新连接，重连的次数由"tries"参数指定，重连的时间间隔由"retrytime"参数指定。
如果"tries"参数为0，则会无限的尝试重连直到成功为止。
如果"retrytime"参数为0，则使用默认值(默认值是多少原文没说)

If the "socket" parameter is nether NULL nor "" then an attempt will be made to connect through it before attempting to connect to "server" on "port".
If it is NULL or "" then no attempt will be made to connect through the socket.*/

如果"socket"参数不是NULL而且非空，那么(连接请求)就会先尝试连接该socket,然后才是"server"的"port"端口。
如果"socket"参数为NULL或者为空，则不会发出socket连接请求

 

void sqlrcon_free(int sqlrconref) Disconnects and terminates the session if it hasn't been terminated already.

断开连接，关闭尚未关闭的session

 

void sqlrcon_endSession(int sqlrconref) terminates the session

关闭session

 

void sqlrcon_suspendSession(int sqlrconref)
Disconnects this client from the current session but leaves the session open so that another client can connect to it using sqlrcon_resumeSession().

从当前session中断开客户端的连接，但是不关闭这个session，以便其它的客户端通过sqlrcon_resumeSession()函数重新连接上来

 

int sqlrcon_getConnectionPort(int sqlrconref)
Returns the inet port that the client is communicating over. This parameter may be passed to another client for use in the sqlrcon_resumeSession() command.
Note: the value returned by this function is only valid after a call to sqlrcur_suspendSession().

返回客户端通讯使用的inet port。该参数可以传递给其他的客户端用于sqlrcon_resumeSession()命令中。
注意：只有在调用sqlrcur_suspendSession()后,本函数所返回的值之才有效。

 

string sqlrcon_getConnectionSocket(int sqlrconref)
Returns the unix socket that the client is communicating over. This parameter may be passed to another client for use in the sqlrcon_resumeSession() command.
Note: the value returned by this function is only valid after a call to sqlrcur_suspendSession().

返回客户端通讯使用的unix socket。该参数可以传递给其他的客户端用于sqlrcon_resumeSession()命令中。
注意：只有在调用sqlrcur_suspendSession()之后，本函数所返回的值才有效。

 

int sqlrcon_resumeSession(int sqlrconref, int port, string socket)
Resumes a session previously left open using sqlrcon_suspendSession(). Returns 1 on success and 0 on failure.

返回sqlrcon_suspendSession()命令所挂起的session。成功则返回1，失败则返回0。

 

int sqlrcon_ping(int sqlrconref)
Returns 1 if the database is up and 0 if it's down.

如果数据库连接成功，返回1。连接失败，返回0。

 

string sqlrcon_identify(int sqlrconref)
Returns the type of database: oracle7, oracle8, postgresql, mysql, etc.

返回数据库的类型：oracle7,oracle8,postgresql,mysql,等等

 

int sqlrcon_autoCommitOn(int sqlrconref)
Instructs the database to perform a commit after every successful query.

命令数据库在每完成一次成功的query之后执行一次commit

 

int sqlrcon_autoCommitOff(int sqlrconref)
Instructs the database to wait for the client to tell it when to commit.

命令数据库等待客户端通知在什么时间进行commit

 

int sqlrcon_commit(int sqlrconref)
Issues a commit. Returns 1 if the commit succeeded, 0 if it failed and -1 if an error occurred.

发出一个commit。成功返回1，失败返回0，出错返回-1。

 

int sqlrcon_rollback(int sqlrconref)
Issues a rollback. Returns 1 if the rollback succeeded, 0 if it failed and -1 if an error occurred.

发出一个rollback。成功返回1，失败返回0，出错返回-1。

 

void sqlrcon_debugOn(int sqlrconref)
Causes verbose debugging information to be sent to standard output. Another way to do this is to start a query with "-- debug/n".

把详细的debugging信息进行标准输出。
另外一个办法是用"-- debug/n"开始一次query

 

void sqlrcon_debugOff(int sqlrconref) turns debugging off

关闭
f9f5
debugging

 

int sqlrcon_getDebug(int sqlrconref)
returns FALSE if debugging is off and TRUE if debugging is on

debugging为关闭时，返回FALSE;debugging为开启时，返回TRUE

 

int sqlrcur_alloc(int sqlrconref)

 

void sqlrcur_free(int sqlrcur)

 

void sqlrcur_setResultSetBufferSize(int sqlrcurref, int rows)
Sets the number of rows of the result set to buffer at a time. 0 (the default) means buffer the entire result set.

设定把查询结果记录集(result set)写入buffer时，每一次所写入的行数。
0(默认值)表示（一次）把整个查询结果记录集都写入buffer。

 

int sqlrcur_getResultSetBufferSize(int sqlrcurref)
Returns the number of result set rows that will be buffered at a time or 0 for the entire result set.

返回把查询结果记录集写入buffer时，每一次所写入的行数。
返回0表示（一次）把整个查询结果记录集都写入buffer

 

void sqlrcur_dontGetColumnInfo(int sqlrcurref)
Tells the server not to send any column info (names, types, sizes). If you don't need that info, you should call this function to improve performance.

让server不发送任何字段(属性)信息(名称，类型，容量)。执行此命令可以提高性能，前提是你不需要这些字段信息。

 

void sqlrcur_mixedCaseColumnNames(int sqlrcurref)
Columns names are returned in the same case as they are defined in the database. This is the default.

字段名称的大小写格式在数据库中是怎么定义的，就怎么返回。这是默认设定。

 

void sqlrcur_upperCaseColumnNames(int sqlrcurref)
Columns names are converted to upper case.

字段名称转换成大写格式。

 

void sqlrcur_lowerCaseColumnNames(int sqlrcurref)
Columns names are converted to lower case.

字段名称转换成小写格式。

 

void sqlrcur_getColumnInfo(int sqlrcurref)
Tells the server to send column info.

让server发送字段(属性)信息。

 

void sqlrcur_cacheToFile(int sqlrcurref, string filename)
Sets query caching on. Future queries will be cached to the file "filename". A default time-to-live of 10 minutes is also set.
Note that once sqlrcur_cacheToFile() is called, the result sets of all future queries will be cached to that file until another call to sqlrcur_cacheToFile() changes which file to cache to or a call to sqlrcur_cacheOff() turns off caching.

开启查询缓存(query caching)。后续查询将缓存到"filename"指定的文件中，默认情况下会设定存活时间(time-to-live)为10分钟。
注意，一旦调用了该命令，所有接下来的查询结果记录集都会缓存到指定的文件中，直到其他的sqlrcur_cacheToFile()语句把缓存文件指定为另外一个文件，或者是直到查询缓存(query caching)功能被squlrcur_cacheOFF()命令所关闭。

 

void sqlrcur_setCacheTtl(int sqlrcurref, int ttl)
Sets the time-to-live for cached result sets. The sqlr-cachemanger will remove each cached result set "ttl" seconds after it's created.

设定写入缓存中的查询结果记录集的存活时间。sqlr-cache管理器会自动在每条缓存记录生成"ttl"秒后，将其删除。

 

string sqlrcur_getCacheFileName(int sqlrcurref)
Returns the name of the file containing the most recently cached result set.

最近一次缓存记录集写到哪个文件里了？这个函数帮你找到这个文件。

 

void sqlrcur_cacheOff(int sqlrcurref)
Sets query caching off.

关闭查询缓存(query caching)。

 

If you don't need to use substitution or bind variables in your queries, use these two functions.

如果在你的查询中用不着代入(substitution)或者绑定变量(bind variables)的话，使用下面函数吧。

int sqlrcur_sendQuery(int sqlrcurref, string query) Sends "query" and gets a return set. Returns TRUE on success and FALSE on failure.

发送参数"query"描述的查询然后收到一个返回记录集。
成功返回TRUE;失败返回FALSE。

 

int sqlrcur_sendQueryWithLength(int sqlrcurref, string query, int length)
Sends "query" with length "length" and gets a result set. This function must be used if the query contains binary data.

发送一个查询，其长度由参数"length"指定，其内容在"query"中指定，然后收到一个返回记录集。
如果查询中包含二进制数据则必须使用该函数。

 

int sqlrcur_sendFileQuery(int sqlrcurref, string path, string filename)
Sends the query in file "path"/"filename" and gets a return set. Returns TRUE on success and FALSE on failure.

发送"path/filename"指定的文件中的查询。成功返回TRUE;失败返回FALSE。

 

If you need to use substitution or bind variables, in your queries use the following functions. See the API documentation for more information about substitution and bind variables.

如果你需要使用代入(substitution)或者绑定变量(bind variables)的话，在你的查询中使用下面函数吧。
关于代入和绑定变量的更多信息，参阅API文档。

void sqlrcur_prepareQuery(int sqlrcurref, string query) Prepare to execute "query".

准备执行参数中描述的查询。

 

void sqlrcur_prepareQueryWithLength(int sqlrcurref, string query, int length)
Prepare to execute "query" with length "length". This function must be used if the query contains binary data.

准备执行一个查询，其长度由参数"length"指定。如果查询中包含二进制数据则必须使用该函数。

 

void sqlrcur_prepareFileQuery(int sqlrcurref, string path, string filename)
Prepare to execute the contents of "path"/"filename".

准备执行"pathe/filename"指定的文件中的内容。

 

void sqlrcur_substitution(int sqlrcurref, string variable, string value)
void sqlrcur_substitution(int sqlrcurref, string variable, long value)
void sqlrcur_substitution(int sqlrcurref, string variable, double value, short precision, short scale)
Define a substitution variable. Returns true if the substitution succeeded or false if the type of the data passed in wasn't a string, long or double or if precision and scale weren't passed in for a double.

定义一个代入变量(substitution variable)的值。
代入成功返回true;如果传递的数据不合法则返回false。
不合法的情况是指：不是字串，也不是long类型，也不是double类型，或者没有传递double类型数值的precision和scale参数。

void sqlrcur_clearBinds(int sqlrcurref)
Clear all bind variables.

清除所有绑定的变量。

 

void sqlrcur_countBindVariables(int sqlrcurref)
Parses the previously prepared query, counts the number of bind variables defined in it and returns that number.

分析最近一个准备过(prepared)的查询，计算并返回其中定义了多少个绑定变量。

 

void sqlrcur_inputBind(int sqlrcurref, string variable, string value)
void sqlrcur_inputBind(int sqlrcurref, string variable, long value)
void sqlrcur_inputBind(int sqlrcurref, string variable, double value, short precision, short scale)
void sqlrcur_inputBindBlob(int sqlrcurref, string variable, long length)
void sqlrcur_inputBindClob(int sqlrcurref, string variable, long length)
Define an input bind variable. Returns true if the bind succeeded or false if the type of the data passed in wasn't a string, long or double or if precision and scale weren't passed in for a double.

定义一个输入绑定变量(input bind variable)。
绑定成功返回true;如果传递的数据不合法则返回false。
不合法的情况是指：不是字串，也不是long类型，也不是double类型，或者没有传递double类型数值的precision和scale参数。

 

void sqlrcur_defineOutputBindString(int sqlrcurref, string variable, int length)
Define a string output bind variable. "length" bytes will be reserved to store the value.

定义一个字串输出绑定变量。存储变量值所用的字节数由"length"参数指定。

 

void sqlrcur_defineOutputBindInteger(int sqlrcurref, string variable)
Define an integer output bind variable.

定义一个整型(integer)输出绑定变量。

 

void sqlrcur_defineOutputBindDouble(int sqlrcurref, string variable)
Define a double precision floating point output bind variable.

定义一个双精浮点(double precision floating point)输出绑定变量。

 

void sqlrcur_defineOutputBindBlob(int sqlrcurref, string variable)
Define a BLOB output bind variable.

定义一个BLOB输出绑定变量。

 

void sqlrcur_defineOutputBindClob(int sqlrcurref, string variable)
Define a CLOB output bind variable.

定义一个CLOB输出绑定变量。

 

void sqlrcur_defineOutputBindCursor(int sqlrcurref, string variable)
Define a cursor output bind variable.

定义一个cursor输出绑定变量。

 

void sqlrcur_validateBinds(int sqlrcurref)
If you are binding to any variables that might not actually be in your query, call this to ensure that the database won't try to bind them unless they really are in the query.

如果有些变量不一定会在你的查询中使用，而你却要绑定到它们，使用该函数来确保只有当这些变量确实出现在查询中时，数据库才会尝试绑定它们。

 

int sqlrcur_executeQuery(int sqlrcurref)
Execute the query that was previously prepared and bound.

执行某查询，该查询应已经准备好(prepared)，并且绑定好(bound)

 

int sqlrcur_fetchFromBindCursor(int sqlrcurref)
Fetch from a cursor that was returned as an output bind variable.
==========================译者注=================================
这句的翻译让我们很为难，因为原文解释太少，所以我们这里给出了不同的几个翻译

pacman:从某个已作为输出绑定变量而返回的cursor处进行Fetch行为。
KAADA:我的理解不知道是否正确,从cursor(数据库连接conn)取得值返回给已定义的变量..
============================================================

int sqlrcur_getOutputBindString(int sqlrcurref, string variable) Get the value stored in a previously defined output bind variable.

得到某已定义的字串(String)输出绑定变量中存储的值。

 

int sqlrcur_getOutputBindBlob(int sqlrcurref, string variable)
Get the value stored in a previously defined output bind variable.

得到某已定义的BLOB输出绑定变量中存储的值。

 

int sqlrcur_getOutputBindClob(int sqlrcurref, string variable)
Get the value stored in a previously defined output bind variable.

得到某已定义的CLOB输出绑定变量中存储的值。

 

int sqlrcur_getOutputBindInteger(int sqlrcurref, string variable)
Get the value stored in a previously defined output bind variable.

得到某已定义的整型(Integer)输出绑定变量中存储的值。

 

int sqlrcur_getOutputBindDouble(int sqlrcurref, string variable)
Get the value stored in a previously defined output bind variable.

得到某已定义的双精型(Double)输出绑定变量中存储的值。

 

int sqlrcur_getOutputBindLength(int sqlrcurref, string variable)
Get the length of the value stored in a previously defined output bind variable.

得到某已定义的输出绑定变量中存储的值的长度。

 

int sqlrcur_getOutputBindCursor(int sqlrcurref, string variable)
Get the cursor associated with a previously defined output bind variable.

得到与某已定义的Cursor输出绑定变量相关联的cursor值。

 

int sqlrcur_openCachedResultSet(int sqlrcurref, string filename)
Opens a cached result set as if a query that would have generated it had been executed. Returns TRUE on success and FALSE on failure.

==========================译者注=================================
这句的翻译让我们有点抓狂，几个人几个版本。所以我们还是在这里给出了不同的几个翻译。请大家来指正这里。

直译： 打开一个已缓存的结果集就好像可以产生该结果集的查询被执行一样，成功返回TURE，失败返回FALSE
pacman: 开启缓存文件中的记录集，假装生成该记录集的查询已经执行。
REDRUM: 将一个已执行的QUERY产生的纪录集放到一个缓冲内,成功返回TRUE
血色： 如果一个请求发出，按设定的处理结果集执行，执行成功返回“正确”否则返回“错误”。。。
雪狼： 该函数打开的是一个被缓冲的结果集，其效果和打开一个由执行查询所产生的结果集一样。当函数执行成功返回TRUE，失败返回FALSE。
============================================================

 

int sqlrcur_colCount(int sqlrcurref)
returns the number of columns in the current return set

返回当前得到的记录集中包含的列数。

 

int sqlrcur_rowCount(int sqlrcurref)
returns the number of rows in the current return set

返回当前得到的记录集中包含的行数。

 

int sqlrcur_totalRows(int sqlrcurref)
Returns the total number of rows that will be returned in the result set. Not all databases support this call. Don't use it for applications which are designed to be portable across databases. -1 is returned by databases which don't support this option.

得到结果记录集中所有要返回的行数。
不是所有的数据库都支持这个调用。对于那些设计成可在多种数据库间挂接使用的应用程序，不要使用该函数。
不支持该选项的数据库所返回的值是-1。

 

int sqlrcur_affectedRows(int sqlrcurref)
Returns the number of rows that were updated, inserted or deleted by the query. Not all databases support this call. Don't use it for applications which are designed to be portable across databases. -1 is returned by databases which don't support this option.

返回被查询所更新、插入或删除的行数。
不是所有的数据库都支持这个调用。对于那些设计成可在多种数据库间挂接使用的应用程序，不要使用该函数。
不支持该选项的数据库所返回的值是-1。

 

int sqlrcur_firstRowIndex(int sqlrcurref)
Returns the index of the first buffered row. This is useful when buffering only part of the result set at a time.

返回缓存第一行的索引(index)。当每次只保存结果记录集的一部分时，该函数很有用途。

 

int sqlrcur_endOfResultSet(int sqlrcurref)
Returns 0 if part of the result set is still pending on the server and 1 if not. This function can only return 0 if setResultSetBufferSize() has been called with a parameter other than 0.

检查查询结果记录集是否处理完了。如果还有部分在server上处理就返回0，否则返回1。
如果setResultSetBufferSize()命令曾被调用，并且参数不为0，那么本函数只会返回0。

 

string sqlrcur_errorMessage(int sqlrcurref)
If a query failed and generated an error, the error message is available here. If the query succeeded then this function returns FALSE

如果某查询失败并生成了一条错误，该函数可以查看错误信息。如果查询是成功的则返回FALSE。

 

string sqlrcur_getNullsAsEmptyStrings(int sqlrcurref)
Tells the client to return NULL fields and output bind variables as empty strings. This is the default.

让客户端把NULL fields和NULL输出绑定变量返回为空字串。默认设置就是如此。

 

string sqlrcur_getNullsAsNulls(int sqlrcurref)
Tells the client to return NULL fields and output bind variables as NULL's.

让客户端把NULL fields和NULL输出绑定变量返回为NULL's。

 

string sqlrcur_getField(int sqlrcurref, int row, int col)
returns a string with value of the specified row and column

返回指定域(field)的值。"row"参数指定行数；"column"参数指定列数。

 

string sqlrcur_getFieldLength(int sqlrcurref, int row, int col)
returns the length of the specified row and column

返回指定域(field)的值的长度。"row"参数指定行数；"column"参数指定列数。

 

array sqlrcur_getRow(int sqlrcurref, int row)
returns an indexed array of the values of the specified row

返回指定行的各值构成的索引数组(indexed array)。

 

array sqlrcur_getRowLengths(int sqlrcurref, int row)
returns an indexed array of the lengths of the specified row

返回指定行的各值的长度构成的索引数组(indexed array)。

 

array sqlrcur_getRowAssoc(int sqlrcurref, int row)
returns an associative array of the values of the specified row

返回指定行的各值构成的联合数组(associative array)。

 

array sqlrcur_getRowLengthsAssoc(int sqlrcurref, int row)
returns an associative array of the lengths of the specified row

返回指定行的各值的长度构成的联合数组(associative array)。

 

array sqlrcur_getColumnNames(int sqlrcurref)
returns the array of the column names of the current return set

得到当前返回记录集的各字段名构成的数组(array)。

 

string sqlrcur_getColumnName(int sqlrcurref, int col)
returns the name of the specified column

得到指定字段的名称。

 

string sqlrcur_getColumnType(int sqlrcurref, string col)
string sqlrcur_getColumnType(int sqlrcurref, int col)
returns the type of the specified column

得到指定字段的类型。

 

int sqlrcur_getColumnLength(int sqlrcurref, string col)
int sqlrcur_getColumnLength(int sqlrcurref, int col)
returns the length of the specified column.

得到指定字段的长度。

 

int sqlrcur_getColumnPrecision(int sqlrcurref, string col);
int sqlrcur_getColumnPrecision(int sqlrcurref, int col);
Returns the precision of the specified column. Precision is the total number of digits in a number. eg: 123.45 has a precision of 5. For non-numeric types, it's the number of characters in the string.

返回指定字段的精度(precision)。
对于数字类型的值，精度指的是数字的位数。比如 123.45的精度是5；对于非数字的值，精度指的是字串的字符数量。

 

int sqlrcur_getColumnScale(int sqlrcurref, string col);
int sqlrcur_getColumnScale(int sqlrcurref, int col);
Returns the scale of the specified column. Scale is the total number of digits to the right of the decimal point in a number. eg: 123.45 has a scale of 2.

返回指定字段的小数保留位(scale)。
小数保留位指的是小数点右边允许使用的数字的位数。比如 123.45的小数保留位是2。