SQL Relay PHP API 翻译

此文档翻译自SQL Relay官方文档的PHP API，地址为：http://sqlrelay.sourceforge.net/sqlrelay/api/php/doc.html

如果需要例子等更详细说明，见这里：http://sqlrelay.sourceforge.net/sqlrelay/programming/php.html

注意，此翻译并非严肃严谨的翻译，不保证意思明确无误。

 

注意：sqlrconref和sqlrcurref之间的细小差别，sqlrcon_ 和sqlrcur_ 之间的细小差别。

 

一个例子：

 

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);

 

 

下面就是函数了：

 

 

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

    链接到SQL Relay。使用server和port或只使用一个Unix Socket。user、password是身份认证。tries是连接失败的重连次数，0为无限次重连。retrytime是两次重连的间隔时间，0为 使用系统默认的间隔时间(不是没有间隔)。

 

02. void sqlrcon_free(int sqlrconref)

    断开连接并且使会话失效。sqlrconref为sqlrcon_alloc的返回。

 

03. void sqlrcon_endSession(int sqlrconref)

    使会话失效。

 

04. void sqlrcon_suspendSession(int sqlrconref)

    断开连接但保留会话打开，其他客户端可以用sqlrcon_resumeSession()来使用这个会话。

 

05. int sqlrcon_getConnectionPort(int sqlrconref) 

    大概的意思是获得使用"04"的客户端的端口，sqlrcon_resumeSession()会用到。

 

06. string sqlrcon_getConnectionSocket(int sqlrconref)

    大概的意思是获得使用"04"的客户端的Unix套接字，sqlrcon_resumeSession()会用到。

 

07. int sqlrcon_resumeSession(int sqlrconref, int port, string socket)

    重新使用"04"那个保留的会话，返回1为成功0为失败，这里的port和socket就是"05"和"06"获得的。

 

08. int sqlrcon_ping(int sqlrconref)

    如果数据库连接着，返回1，否则返回0。

 

09. string sqlrcon_identify(int sqlrconref)

    返回数据库类型，比如mysql等。

 

10. string sqlrcon_dbVersion(int sqlrconref)

    返回数据库的版本号。

 

11. string sqlrcon_serverVersion(int sqlrconref)

    返回SQL Relay 服务端的版本号。

 

12. string sqlrcon_clientVersion(int sqlrconref)

    返回SQL Relay 客户端的版本号。

 

13. string sqlrcon_bindFormat(int sqlrconref)

    返回一个字符串，表示绑定变量在数据库中使用的格式。不理解，试试再说。

 

14. int sqlrcon_autoCommitOn(int sqlrconref)

    让数据库在一切成功的查询之后插入一个commit。也就是自动commit开。

 

15. int sqlrcon_autoCommitOff(int sqlrconref)

    让数据库等着别人告诉它什么时候commit。也就是自动commit关。

 

16. int sqlrcon_commit(int sqlrconref)

    产生一次commit。如果成功则返回1，失败返回0，出现错误返回-1。

 

17. int sqlrcon_rollback(int sqlrconref)

    产生一次rollback。成功返回1，失败返回0，错误返回-1。

 

18. void sqlrcon_debugOn(int sqlrconref)

    收集debug数据并发送给基本输出，另一个方法是在查询后面跟上"-- debug\n"。

 

19. void sqlrcon_debugOff(int sqlrconref)

    关掉debug

 

20. int sqlrcon_getDebug(int sqlrconref)

    查看debug的状态呗。关闭的时候返回FALSE，开启的时候返回TURE。

 

21. int sqlrcur_alloc(int sqlrconref)

    sqlrconref为sqlrcon_alloc的返回，这个应该是设定一个指针吧，官方文档无解释。

 

22. void sqlrcur_free(int sqlrcur)

    官方文档无解释，看"02"吧，应该差不多意思。

 

23. void sqlrcur_setResultSetBufferSize(int sqlrcurref, int rows)

    设置结果集中每次缓存的行数。0(默认)代表缓存结果集的全部。

 

24. int sqlrcur_getResultSetBufferSize(int sqlrcurref)

    就是返回"23"的设置的数字。

 

25. void sqlrcur_dontGetColumnInfo(int sqlrcurref)

    告诉服务器不要发送任何字段的信息(名称、类型、大小)。如果你不需要这些信息可以使用这个函数来改善性能。

 

26. void sqlrcur_mixedCaseColumnNames(int sqlrcurref)

    字段的信息会按照他们在数据库的样子返回。这是默认的。

 

27. void sqlrcur_upperCaseColumnNames(int sqlrcurref)

    字段名称完全大写。

 

28. void sqlrcur_lowerCaseColumnNames(int sqlrcurref)

    字段名称权小写。

 

29. void sqlrcur_getColumnInfo(int sqlrcurref)

    让服务器发送字段信息，应该和"25"反着。

 

30. void sqlrcur_cacheToFile(int sqlrcurref, string filename)

    设置查询缓存开启。以后的查询将缓存到"filename"这个文件里。默认的10分钟的生存期也被同时设置。注意，如果这个函数被使用，所有的以后的 查询都将缓存到那个文件直到另外一次使用这个函数更换其他文件或用sqlrcur_cacheOff()关闭缓存。

 

31. void sqlrcur_setCacheTtl(int sqlrcurref, int ttl)

    设置缓存的生存期，sqlr-cachemanger将删除到期的文件。

 

32. string sqlrcur_getCacheFileName(int sqlrcurref)

    返回包含最近的结果集的缓存文件的名字。

 

33. void sqlrcur_cacheOff(int sqlrcurref)

    关闭缓存。

 

如果你不需要在你的查询中替代和绑定变量，用这两个函数。(我不知道这句为什么在这，但好像是说的函数34、35、36)

 

34. int sqlrcur_sendQuery(int sqlrcurref, string query)

    发送query并获得结果集，返回TURE为成功，返回FALSE为失败。

 

35. int sqlrcur_sendQueryWithLength(int sqlrcurref, string query, int length)

    和34一样，但如果查询里有二进制数据，就必须指定一个长度了。

 

36. int sqlrcur_sendFileQuery(int sqlrcurref, string path, string filename)

    大概是把"path"/"filename"这个文件的内容作为query发送，然后返回结果集。其余和34一样。

 

如果你需要用替代和绑定变量，在你的查询里用这些函数。看API的文档了解更多的关于替代和绑定变量的信息。

 

37. void sqlrcur_prepareQuery(int sqlrcurref, string query)

    准备执行查询。

 

38. void sqlrcur_prepareQueryWithLength(int sqlrcurref, string query, int length)

    还是在查询里有二进制的情况下。

 

39. void sqlrcur_prepareFileQuery(int sqlrcurref, string path, string filename)

    见36吧。只不过是准备执行而已。

 

40. 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)

    设定一个替代的值。如果成功返回true，负责返回false。

 

41. void sqlrcur_clearBinds(int sqlrcurref)

    清除所有绑定变量

 

42. void sqlrcur_countBindVariables(int sqlrcurref)

    解析先前准备好的查询，计算定义绑定变量的数量，并返回该数目。

 

43. 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)

    定义一个输入绑定变量，成功返回true，不成功返回false。Blob是二进制，Clob是大字符对象。

 

44. void sqlrcur_defineOutputBindString(int sqlrcurref, string variable, int length)

    定义一个字符串型输出绑定变量，"length"字节将保留用来存储这个值。

 

45. void sqlrcur_defineOutputBindInteger(int sqlrcurref, string variable)

    定义一个整数型输出绑定变量。

 

46. void sqlrcur_defineOutputBindDouble(int sqlrcurref, string variable)

    定义一个双精度浮点型输出绑定变量。

 

47. void sqlrcur_defineOutputBindBlob(int sqlrcurref, string variable)

    定义一个二进制型输出绑定变量。

 

48. void sqlrcur_defineOutputBindClob(int sqlrcurref, string variable)

    定义一个大字符对象型输出绑定变量。

 

49. void sqlrcur_defineOutputBindCursor(int sqlrcurref, string variable)

    定义一个指针型输出绑定变量。

 

50. void sqlrcur_validateBinds(int sqlrcurref)

    如果你正在捆绑到其他变量，但不是你的查询中实际用到的。使用这个函数保证数据库不会尝试捆绑除非他们的确是这次查询的。

 

51. void sqlrcur_validBind(int sqlrcurref, string variable)

    如果"variable"是查询中的有效的绑定变量，返回ture。

 

52. int sqlrcur_executeQuery(int sqlrcurref)

    执行准备好的查询。

 

53. int sqlrcur_fetchFromBindCursor(int sqlrcurref)

    从一个指针fetch，这个指针是从一个输出绑定变量返回的。

 

54. int sqlrcur_getOutputBindString(int sqlrcurref, string variable)

    返回保存的值，在先前定义的输出绑定变量里。

 

55. int sqlrcur_getOutputBindBlob(int sqlrcurref, string variable)

    同上。

 

56. int sqlrcur_getOutputBindClob(int sqlrcurref, string variable)

    同上。

 

57. int sqlrcur_getOutputBindInteger(int sqlrcurref, string variable)

    同上。

 

58. int sqlrcur_getOutputBindDouble(int sqlrcurref, string variable)

    同上。

 

59. int sqlrcur_getOutputBindLength(int sqlrcurref, string variable)

    返回保存的值的长度，在先前定义的输出绑定变量里。

 

60. int sqlrcur_getOutputBindCursor(int sqlrcurref, string variable)

    返回与先前定义的输出变量关联的指针。

 

好像终于离开替换和绑定了，不容易。

 

61. int sqlrcur_openCachedResultSet(int sqlrcurref, string filename)

    打开一个缓存的结果集，就像一个查询真正的在执行。成功返回TURE，失败返回FALSE。

 

62. int sqlrcur_colCount(int sqlrcurref)

    在结果集指针中返回字段个数。

 

63.int sqlrcur_rowCount(int sqlrcurref)

    在结果集指针中返回行数。

 

64. int sqlrcur_totalRows(int sqlrcurref)

    返回结果集里所有可以返回的行的数量。不是所有数据库都支持。如果数据库不支持则返回-1。

 

65. int sqlrcur_affectedRows(int sqlrcurref)

    返回查询中被updated、inserted或deleted的行。不是所有数据库都支持。如果数据库不支持则返回-1。

 

66. int sqlrcur_firstRowIndex(int sqlrcurref)

    返回第一个缓冲行的索引。如果同一时间缓冲只是结果集的一部分时很有用。

 

67. int sqlrcur_endOfResultSet(int sqlrcurref)

    如果结果集还有在服务器上等候的部分则返回0，否则返回1。如果setResultSetBufferSize设置的不是0，那么这个函数将至返回0。

 

68. string sqlrcur_errorMessage(int sqlrcurref)

    如果一个查询失败并返回错误，错误信息在这里可用。如果查询成功这个函数将返回FALSE。

 

69. string sqlrcur_getNullsAsEmptyStrings(int sqlrcurref)

    告诉客户端返回NULL字段并且输出绑定变量为一个空字符串。这是默认。

 

70. string sqlrcur_getNullsAsNulls(int sqlrcurref)

    告诉客户端返回NULL字段并且输出绑定变量为一个NULL。

 

71. string sqlrcur_getField(int sqlrcurref, int row, int col)

    返回指定行指定字段的值的字符串。

 

72. string sqlrcur_getFieldLength(int sqlrcurref, int row, int col)

    返回指定行指定字段的长度。

 

73. array sqlrcur_getRow(int sqlrcurref, int row)

    返回指定行的一个各个值的索引数组。

 

74. array sqlrcur_getRowLengths(int sqlrcurref, int row)

    返回指定行的一个各个值的长度组成的索引数组。

 

75. array sqlrcur_getRowAssoc(int sqlrcurref, int row)

    返回指定行的一个各个值的关联数组。

 

76. array sqlrcur_getRowLengthsAssoc(int sqlrcurref, int row)

    返回指定行的一个各个值的长度组成的关联数组。

 

77. array sqlrcur_getColumnNames(int sqlrcurref)

    返回指针结果集中所有字段的名字写入一个数组中。

 

78. string sqlrcur_getColumnName(int sqlrcurref, int col)

    返回特定字段的名字。这个col应该就是从0开始往后排吧。

 

79. string sqlrcur_getColumnType(int sqlrcurref, string col)

    string sqlrcur_getColumnType(int sqlrcurref, int col)

    返回指定字段的类型。

 

80. int sqlrcur_getColumnLength(int sqlrcurref, string col)

    int sqlrcur_getColumnLength(int sqlrcurref, int col)

    返回指定字段的长度。

 

81. int sqlrcur_getColumnPrecision(int sqlrcurref, string col)

    int sqlrcur_getColumnPrecision(int sqlrcurref, int col)

    返回指定字段的精度。精度是一个数字的总的数字位数，比如123.45的精度是5。对于非数字类型，则是字符长度。

 

82. int sqlrcur_getColumnScale(int sqlrcurref, string col)

    int sqlrcur_getColumnScale(int sqlrcurref, int col)

    返回指定字段的级别(这个词是这么翻译吗)。级别是小数点右边个数字个数。例如123.45的级别是2。

 

83. int sqlrcur_getColumnIsNullable(int sqlrcurref, string col)

    int sqlrcur_getColumnIsNullable(int sqlrcurref, int col)

    如果指定的字段可为空，则返回1，否则返回0。

 

84. int sqlrcur_getColumnIsPrimaryKey(int sqlrcurref, string col)

    int sqlrcur_getColumnIsPrimaryKey(int sqlrcurref, int col)

    如果指定的字段为主键，则返回1，否则返回0。

 

85. int sqlrcur_getColumnIsUnique(int sqlrcurref, string col)

    int sqlrcur_getColumnIsUnique(int sqlrcurref, int col)

    如果指定的字段为唯一约束，则返回1，否则返回0。

 

86. int sqlrcur_getColumnIsPartOfKey(int sqlrcurref, string col)

    int sqlrcur_getColumnIsPartOfKey(int sqlrcurref, int col)

    如果指定的字段为复合键的一部分，则返回1，否则返回0。

 

87. int sqlrcur_getColumnIsUnsigned(int sqlrcurref, string col)

    int sqlrcur_getColumnIsUnsigned(int sqlrcurref, int col)

    如果指定的字段为无符号位数字，则返回1，否则返回0。

 

88. int sqlrcur_getColumnIsZeroFilled(int sqlrcurref, string col)

    int sqlrcur_getColumnIsZeroFilled(int sqlrcurref, int col)

    如果指定的字段为零填充标志创建，则返回1，否则返回0。

 

89. int sqlrcur_getColumnIsBinary(int sqlrcurref, string col)

    int sqlrcur_getColumnIsBinary(int sqlrcurref, int col)

    如果指定的字段为二进制数据，则返回1，否则返回0。

 

90. int sqlrcur_getColumnIsAutoIncrement(int sqlrcurref, string col)

    int sqlrcur_getColumnIsAutoIncrement(int sqlrcurref, int col)

    如果指定的字段为自增字段，则返回1，否则返回0。

 

91. int sqlrcur_getLongest(int sqlrcurref, string col)

    int sqlrcur_getLongest(int sqlrcurref, int col)

    返回指定字段中最长的那个有多长。

 

92. void sqlrcur_suspendResultSet(int sqlrcurref)

    告诉服务器，保持结果集打开当连接使用suspendSession()时，然后其他连接可以用resumeResultSet()连接这个结果集当用resumeSession()再来连接的时候。

 

93. int sqlrcur_getResultSetId(int sqlrcurref)

    返回这个结果集的内部ID。这个就是让其他去用resumeResultSet()时可以连接上，见92。注意这个值只有在用sqlrcur_suspendResultSet()之后才能返回。

 

94. void sqlrcur_resumeResultSet(int sqlrcurref, int id)

    见92和93，用这个就能把用92的那个重新利用。成功返回1，失败返回0。

 

95. void sqlrcur_resumeCachedResultSet(int sqlrcurref, int id, string filename)

    继续一个结果集先前用suspendSession()保持打开的，并且继续缓存结果集到"filename"这个文件，成功返回1，失败返回0。