Ruby-aci类说明¶

STACI类¶

常量¶

VERSION¶

返回ruby-aci接口的版本；

require 'staci'
puts "Ruby-aci Version :        #{STACI::VERSION}"

LIB_VERSION¶

与 VERSION 基本相同，返回版本号

require 'staci'
puts "Ruby-aci Version :        #{STACI::LIB_VERSION}"

类方法¶

.charset_id2name¶

.charset_id2name(charset_id) => String

如果id有效，则返回指定的字符集ID的字符集名称。

require 'staci'
cname=STACI.charset_id2name(854)
puts "charset name : #{cname}"

执行结果：

charset name : ZHS32GB18030

.charset_name2id¶

.charset_name2id(charset_name) => Integer

如果有效，则返回指定的字符集名称的字符集ID。

require 'staci'
cid=STACI.charset_name2id('ZHS32GB18030')
puts "charset id : #{cid}"

执行结果：

charset id : 854

实例方法¶

STACI的实例其实就是创建的连接对象，常规定义为conn。

autocommit¶

#autocommit=(autocommit_mode) => Object

设置自动提交事务状态。

直接调用autocommit方法返回当前事务模式：

irb(main):026:0> conn.autocommit => false

执行autocommit时设置事务状态：

irb(main):027:0> conn.autocommit=true => true

autocommit?¶

#autocommit? => Boolean

返回自动提交事务状态:

irb(main):027:0> conn.autocommit? => false

break¶

#break => Object

取消执行SQL

commit¶

#commit => Object

提交事务：

conn.commit

rollback¶

#rollback => Object

回滚事务：conn.rollback

database_charset_name¶

#database_charset_name => String

返回数据库的字符集名称：

conn.database_charset_name

describe_table¶

#describe_table(table_name, table_only = false) => STACI::Metadata::Table or STACI::Metadata::View

获得表或视图的信息。

describe_synonym¶

#describe_synonym(synonym_name, check_public_also = true) STACI::Metadata::Synonym

获得同义词的信息

describe_schema¶

#describe_schema(schema_name) => STACI::Metadata::Schema

获得模式的信息

describe_database¶

#describe_database(database_name) => STACI::Metadata::Database

获得数据库的信息

describe_view¶

#describe_view(view_name) => STACI::Metadata::View

获得视图的信息。

exec¶

#exec(sql, *bindvars, &block) => Object

执行SQL语句

initialize¶

#initialize(username, password, dbname = nil, privilege = nil) => STACI

连接数据库。

logoff¶

#logoff => Object

关闭数据库连接

non_blocking¶

#non_blocking=(non_blocking_mode) => Object

设置网络阻塞模式：conn.non_blocking=true

non_blocking?¶

#non_blocking? => Boolean

查询网络阻塞模式

parse¶

#parse(sql) => STACI::Cursor

返回一个prepared的语句句柄。

ping¶

#ping => Boolean

做一次客户端与数据库的交互操作，确认客户端与数据库的连接是否正常。正常返回ture，不正常返回false。

prefetch_rows¶

#prefetch_rows=(num) => Object

设置预获取数据的行数，默认16条。

recv_timeout¶

#recv_timeout => Float

获得网络接受超时时间，单位为秒

recv_timeout=¶

#recv_timeout=(timeout)

设置网络接受超时时间，单位为秒

send_timeout¶

#send_timeout => Float

获得络发送超时时间，单位为秒

send_timeout=¶

#send_timeout=(timeout)

设置网络发送超时时间，单位为秒

select_one¶

#select_one(sql, *bindvars) => Array

执行一条sql语句并返回第一条数据。

username¶

#username => Object

返回当前连接数据库的用户名

构造方法¶

initialize¶

#initialize(username, password, dbname = nil, privilege = nil) => STACI

连接数据库。

new¶

#new(username, password, dbname = nil, privilege = nil) => STACI

连接数据库。

属性¶

last_error¶

#last_error => ACIError

返回获得错误的对象

Cursor类¶

该类的实例对应于数据库术语中的游标，对应Perl/DBI的语句句柄$sth。不要通过调用“new”方法来创建实例。请通过调用STACI#exec或STACI#parse来创建它。

构造方法¶

initialize¶

#initialize(conn, sql = nil) => Cursor

返回一个cursor的新实例。

注意：不要使用此构造函数。用STACI#parse。

实例方法¶

[](key)¶

#[](key) => Object

获取绑定变量的值。当绑定变量由#bind_param显式绑定时，下标键必须与传递给#bind_param的参数键相同。当它们被STACI#exec或#exec隐式绑定时，下标键是从一开始的位置。返回绑定对应的值。

举例：

按参数名称显示绑定

cursor = conn.parse("BEGIN :out := 'BAR'; END;")
cursor.bind_param(:out, 'FOO') # bind by name
p cursor[:out] # => 'FOO'  - The subscript must be :out.
cursor.exec()
p cursor[:out] # => 'BAR'

按参数位置显示绑定

cursor = conn.parse("BEGIN :out := 'BAR'; END;")
cursor.bind_param(1, 'FOO') # bind by position
p cursor[1] # => 'FOO'  - The subscript must be 1.
cursor.exec()
p cursor[1] # => 'BAR'

按参数位置隐式绑定

cursor = conn.exec("BEGIN :out := 'BAR'; END;", 'FOO')
# 1st bind variable is bound as String with width 3. Its initial value is 'FOO'
# After execute, the value become 'BAR'.
p cursor[1] # => 'BAR'

[]=(key, val)¶

#[]=(key, val) => Object

更改绑定变量值。当绑定变量由#bind_param显式绑定时，下标键必须与传递给#bind_param的参数键相同。当它们被STACI#exec或#exec隐式绑定时，下标键是从一开始的位置。

举例如下：

# Inserts three rows whose values are 'FOO', 'BAR' and 'BAZ.'
cursor = conn.parse("INSERT INTO test(col1) VALUES(:1)")
begin
  cursor.bind_params(1, nil, String, 3)
  ['FOO', 'BAR', 'BAZ'].each do |column_value|
cursor[1] = column_value  # Change the bind value
cursor.exec               # and insert it.
end
ensure
  cursor.close()
end
# This makes same result with the following but is more efficient.
#
#  ['FOO', 'BAR', 'BAZ'].each do |column_value|
#    conn.exec("INSERT INTO test(col1) VALUES(:1)", column_value)
#  end
#

bind_param¶

#bind_param(key, param, type = nil, length = nil) => Object

显式绑定变量。当key为number时，它按位置绑定，位置从1开始。当key为string时，它按占位符的名称绑定。

举例：

cursor = conn.parse("SELECT * FROM emp WHERE ename = :ename")
cursor.bind_param(1, 'SMITH') # bind by position
# ...or...
cursor.bind_param(':ename', 'SMITH') # bind by name

要绑定为数字，请将数字intself设置为val。如果其初始值为NULL，请将nil设置为type，将Integer、Float或OraNumber设置为val。

举例如下：

cursor.bind_param(1, 1234) # 绑定一个整形，初始值为1234
cursor.bind_param(1, 1234.0) # 绑定一个浮点数，初始值为1234.0.
cursor.bind_param(1, nil, Integer) # 绑定一个整形，初始值为NULL.
cursor.bind_param(1, nil, Float) #绑定一个浮点数，初始值为 NULL.
cursor.bind_param(1, OraNumber(1234)) # 绑定一个 OraNumber,初始值为1234.
cursor.bind_param(1, nil, OraNumber) #绑定一个 OraNumber,初始值为 NULL.

在绑定字符串的情况下，将字符串本身设置为val。当绑定变量用作输出时，设置长度足以存储或设置长度的字符串。

举例如下：

cursor = conn.parse("BEGIN :out := :in || '_OUT'; END;")
cursor.bind_param(':in', 'DATA') # 绑定4个长度的字符串.
cursor.bind_param(':out', nil, String, 7) # 绑定7个长度的字符串.
cursor.exec()
p cursor[':out'] # => 'DATA_OU'
# Though the length of :out is 8 bytes in PL/SQL block, it is
# bound as 7 bytes. So result is cut off at 7 byte.

如果将字符串绑定为RAW，请将STACI::RAW设置为type,举例如下：

cursor = conn.parse("INSERT INTO raw_table(raw_column) VALUE (:1)")
cursor.bind_param(1, 'RAW_STRING', STACI::RAW)
cursor.exec()
cursor.close()

bind_param_array¶

#bind_param_array(key, var_array, type = nil, max_item_length = nil) => Object

显式绑定数组.当key为number时，它按位置绑定，位置从1开始。当key为string时，它按占位符的名称绑定。max_array_size参数必须设置在调用bind_param_array之前。

举例如下：

cursor = conn.parse("INSERT INTO test_table VALUES (:str)")
cursor.max_array_size = 3
cursor.bind_param_array(1, ['happy', 'new', 'year'], String, 30)
cursor.exec_array

close¶

#close => Object

关闭Cursor

column_metadata¶

#column_metadata => Array of STACI::Metadata::Column

获取select语句的STACI::Metadata::Column 的数组。

举例：

cursor = conn.exec('select * from tab')
puts ' Name                                      Type'
puts ' ----------------------------------------- ----------------------------'
cursor.column_metadata.each do |colinfo|
  puts format(' %-41s %s',
              colinfo.name,
              colinfo.type_string)
end

define¶

#define(pos, type, length = nil) => Object

明确指出获取值的日期类型。在parse 和exec中运行此方法。pos从1开始。当类型为String时使用lentgh。

举例：

cursor = conn.parse("SELECT ename, hiredate FROM emp")
cursor.define(1, String, 20) # 第一列用一个20个长度字符串获取.
cursor.define(2, Time)       # 第二列用一个Time类型.
cursor.exec()

exec¶

#exec(*bindvars) => Object

执行分配给游标的SQL语句。返回值的类型取决于sql语句的类型：select,insert, update delete, create, alter, drop 或PL/SQL。对于select语句，它返回查询结果的列数。对于insert、update或delete语句，它返回已处理的行数。对于create、alter、drop和PL/SQL语句，它返回true。与STACI#exec相反，即使PL/SQL也返回true。显式使用STACI::Cursor#[]获取绑定变量。

exec_array¶

#exec_array => Object

执行分配给具有数组绑定的游标的SQL语句

fetch¶

#fetch => Array

获取获取的数据作为数组。这仅适用于select语句。

举例如下：

conn = STACI.new('scott', 'tiger')
cursor = conn.exec('SELECT * FROM emp')
while r = cursor.fetch()
  puts r.join(',')
end
cursor.close
conn.logoff

fetch_hash¶

#fetch_hash => Hash

以哈希形式获取获取的数据。散列键是列名。如果给定块，则充当迭代器。

get_col_names¶

#get_col_names => Object

返回查询结果中所有列名的数组

keys¶

#keys => Array

返回绑定变量的keys数组

max_array_size¶

#max_array_size=(size) => Object

为 bind_param_array方法设置最大数组大小。

设置max_array_size时会清零掉cursor对象中的绑定对象。

max_array_size应于用户实际传入的绑定数组保存一致。

备注：所有绑定数组的大小都必须相同

prefetch_rows¶

#prefetch_rows=(rows) => Object

设置要预取的行数。这可以减少获取多行时的网络往返次数。默认值为16。

row_count¶

#row_count => Integer

返回已经处理的行数。

rowid¶

#rowid => String

获取上次插入、更新或删除的行的rowid。这不能用于select语句。

举例如下：

cursor = conn.parse('INSERT INTO foo_table values(:1, :2)', 1, 2)
cursor.execcursor.rowid # => "AAAFlLAAEAAAAG9AAA", the inserted row's rowid
#statement => String

获得只是SQL的语句字符串。

举例如下：

cursor = conn.parse("select * from country where country_code = 'ja'")
cursor.statement # => "select * from country where country_code = 'ja'"

type¶

#type => Object

获得执行SQL的语句类型,支持如下：

STACI::STMT_SELECT
STACI::STMT_UPDATE
STACI::STMT_DELETE
STACI::STMT_INSERT
STACI::STMT_CREATE
STACI::STMT_DROP
STACI::STMT_ALTER
STACI::STMT_BEGIN
STACI::STMT_DECLARE
STACI::STMT_MERGE

ConnectionPool类¶

连接池是由多个会话使用一组（池）可重用的物理连接来平衡负载。

注意，这与通常所说的连接池不同。通常，连接池在池中缓存连接。当应用程序需要新连接时，会从池中获取连接。这样可以减少建立连接的时间。然而，ruby-aci中的连接池与上述不同。

数据库的连接分为两层：一层是物理连接，如TCP/IP。另一种是应用程序使用的逻辑连接。ruby-aci中的连接池在池中缓存物理连接，而不是逻辑连接。当应用程序需要新连接时，通过物理连接创建逻辑连接，与通常称为连接池不同，物理连接需要时间来建立连接。当应用程序通过逻辑连接发送查询时，将从池中获取物理连接。查询完成后，物理连接自动返回到池。只要按顺序使用逻辑连接，就只使用一个物理连接。当应用程序一次发送查询时，它需要多个物理连接，因为一个物理连接不能一次传输多个查询。

举例如下：

# Create a connection pool.
# The number of initial physical connections: 1
# The number of maximum physical connections: 5
# the connection increment parameter: 2
# username and password are required to establish an implicit primary session.
cpool = STACI::ConnectionPool.new(1, 5, 2, username, password, database)
#   The number of physical connections: 1
#   The number of logical connections: 0
# Create a session.# Pass the connection pool to the third argument.
conn1 = STACI.new(username, password, cpool)
# One logical connection was created.
#   The number of physical connections: 1
#   The number of logical connections: 1
# Create another session.
conn2 = STACI.new(username, password, cpool)
# Another logical connection was created.
#   The number of physical connections: 1
#   The number of logical connections: 2
# Use conn1 and conn2 sequentially
conn1.exec('...')
conn2.exec('...')
# Both logical connections use one physical connection.
#   The number of physical connections: 1
#   The number of logical connections: 2
thr1 = Thread.new do
   conn1.exec('...')
end
thr2 = Thread.new do
   conn2.exec('...')
end
thr1.join
thr2.join
# Logical connections cannot use one physical connection at a time.
# So that the number of physical connections is incremented.
#   The number of physical connections: 3
#   The number of logical connections: 2
conn1.logoff
# One logical connection was closed.
#   The number of physical connections: 3
#   The number of logical connections: 1
conn2.logoff
# All logical connections were closed.
#   The number of physical connections: 3
#   The number of logical connections: 0

实例方法¶

busy_count¶

#busy_count=> Integer

返回当前在用的数据库连接数。

destroy¶

#destroy => Object

销毁连接池

incr¶

#incr => Integer

返回连接池每次增长连接的个数

max¶

#max => Integer

返回连接池的最大值

min¶

#min => Integer

返回连接池的最小值

nowait=¶

#nowait=(val) => Object

设置当使用的连接数超过最大值后创建新连接的行为。ture为不等待，返回错误；false为等待，当有空闲的连接时返回。

nowait¶

#nowait => Boolean

返回当使用的连接数超过最大值后，创建新连接的行为

open_count¶

#open_count => Integer

当前连接池中大概的连接数量

reinitialize¶

#reinitialize(min, max, incr) => Object

更改最小连接数、最大连接数和连接增量参数。

timeout¶

#timeout => Integer

空闲超过此时间值（秒）的连接将终止，以保持最佳的打开连接数。如果为零，则连接从未超时。默认值为零。

注解

只有当存在网络往返时，池才会收缩。如果没有操作，则连接保持活动状态。

timeout=¶

#timeout=(val) => Object

更改超时（以秒为单位）以终止空闲连接。

Metadata类¶

STACI具有获取数据库对象信息的方法，如表、视图、过程、函数等。获取的数据称为元数据，并作为STACI::metadata::Base的子类的实例进行检索。

举例如下：

conn = STACI.new('username/passord')
table = conn.describe_table('scott.emp')
table.columns.each do |col|
  puts "#{col.name} #{col.data_type_string}"
end

注解

Metadata类不需要开发者去实例化，而是通过其他方法返回Metadata类的实例。conn实例下有多个方法生成Metadata类的实例。

BindType模块¶

类方法¶

default_timezone?¶

.default_timezone?=> :local or :utc

返回数据库客户端时的默认时区。

default_timezone=¶

.default_timezone=(tz) => Object

设置数据库客户端时的默认时区

Base子类¶

类方法

create

.create(con, val, param, max_array_size) => Object

不显示调用。

实例方法

get

#get => Object

不显示调用。

set

#set(val) => Object

不显示调用。

BasicNumberType子类¶

实例方法

get¶

#get => Object

不显示调用。

BigDecimal子类¶

属性

bigdecimal_is_required

@@bigdecimal_is_required =false

实例方法

get

#get => Object

CLOB子类¶

类方法

create

.create(con, val, param, max_array_size) => Object

不直接调用

Date子类¶

get

#get => Object

不直接调用

set

#set(val) => Object

不直接调用

DateTime子类¶

–STACI::BindType::DateTime++这是一个助手类，用于选择或绑定数据库数据类型，例如日期、时间戳、带时区的时间戳和带本地时区的时间戳。检索到的值是DateTime。

如何选择数据时间值。

默认情况下，选择DATE, TIMESTAMP, TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE。通过显式调用STACI::Cursor#define来更改行为，如下所示：

cursor = conn.parse("SELECT hiredate FROM emp")
cursor.define(1, nil, DateTime)
cursor.exec()

否则，您可以更改所有查询的默认映射。

# Changes the mapping for DATE
STACI::BindType::Mapping[STACI::SQLT_DAT] = STACI::BindType::DateTime
# Changes the mapping for TIMESTAMP
STACI::BindType::Mapping[STACI::SQLT_TIMESTAMP] = STACI::BindType::DateTime
# Changes the mapping for TIMESTAMP WITH TIME ZONE
STACI::BindType::Mapping[STACI::SQLT_TIMESTAMP_TZ] = STACI::BindType::DateTime
# Changes the mapping for TIMESTAMP WITH LOCAL TIME ZONE
STACI::BindType::Mapping[STACI::SQLT_TIMESTAMP_LTZ] = STACI::BindType::DateTime

默认时区注释

如果检索到的值的数据类型是DATE, TIMESTAMP or TIMESTAMP WITH LOCAL TIME ZONE，则其时区由会话时区确定。

默认情况下，会话时区与本地计算机相同。它由以下SQL更改。

ALTER SESSION SET TIME_ZONE='-05:00'

实例方法

get

#get => Object

set

#set(val) =>Object

Float子类¶

所有方法都继承自BindType::Base

Integer子类¶

所有方法都继承自BindType::Base

IntervalDS子类¶

这是一个助手类，用于选择或绑定数据类型的时间间隔。检索到的值是作为浮点的两个TypeStamp之间的秒数。

注意，如果STACI::BindType::IntervalDS，则它是作为有理数的天数。单位为：天。

如何将间隔日绑定到秒

不能隐式地将绑定变量绑定为间隔日到秒。它必须由STACI::Cursor#bind_param显式绑定。

# output bind variable
cursor = conn.parse(<<-EOS)
BEGIN
    :interval := (:ts1 - :ts2) DAY TO SECOND(9);
  END;
EOS
cursor.bind_param(:interval, nil, :interval_ds)
cursor.bind_param(:ts1, DateTime.parse('1969-11-19 06:54:35 00:00'))
cursor.bind_param(:ts2, DateTime.parse('1969-07-20 20:17:40 00:00'))
cursor.execcursor[:interval] # => 10492615.0 seconds
cursor.close
# input bind variable
cursor = conn.parse(<<-EOS)
BEGIN
    :ts1 := :ts2 + :interval;
  END;
EOS
cursor.bind_param(:ts1, nil, DateTime)
cursor.bind_param(:ts2, DateTime.parse('1969-07-20 20:17:40 00:00'))
cursor.bind_param(:interval, 10492615.0, :interval_ds)
cursor.execcursor[:ts1].strftime('%Y-%m-%d %H:%M:%S') # => 1969-11-19 06:54:35
cursor.close

属性

@@hour

@@minute

@@sec

@@fsec

@@unit

类方法

unit

.unit => :second or :day

检索间隔单位。

unit=

.unit=(val) => Object

更改间隔单位：第二个是默认值。

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

IntervalYM子类¶

–STACI::BindType::IntervalYM++

这是一个助手类，用于选择或绑定数据库数据类型间隔（从年到月）。检索到的值是两个时间戳之间的月数。

该值可应用于DateTime#>>以转换月份。如果已加载ActiveSupport，则可以将其应用于时间#months_。

如何选择年到月的间隔：

IntervalYM选择为整数，比如：

conn.exec("select (current_timestamp - hiredate) year to month from emp") do |hired_months|
  puts "hired_months = #{hired_months}"
end

如何将间隔年绑定到月

不能隐式地将绑定变量绑定为年到月的间隔。它必须由OCI8：：Cursor#bind_param显式绑定。

# output bind variablecursor = conn.parse(<<-EOS)
BEGIN
    :interval := (:ts1 - :ts2) YEAR TO MONTH;
  END;
EOS
cursor.bind_param(:interval, nil, :interval_ym)
cursor.bind_param(:ts1, DateTime.parse('1969-11-19 06:54:35 00:00'))
cursor.bind_param(:ts2, DateTime.parse('1969-07-20 20:17:40 00:00'))
cursor.execcursor[:interval] # => 4 (months)
cursor.close
# input bind variable
cursor = conn.parse(<<-EOS)
BEGIN
    :ts1 := :ts2 + :interval;
  END;
EOS
cursor.bind_param(:ts1, nil, DateTime)
cursor.bind_param(:ts2, Date.parse('1969-11-19'))
cursor.bind_param(:interval, 4, :interval_ym)
cursor.execcursor[:ts1].strftime('%Y-%m-%d') # => 1970-03-19
cursor.close

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

LocalDateTime子类¶

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

LocalTime子类¶

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

NamedType子类¶

类方法

create

.create(con, val, param, max_array_size) => Object

Number子类¶

类方法

create

.create(con, val, param, max_array_size) => Object

Object子类¶

实例方法

get

#get => Object

不显示调用

get_orig

#get_orig => Object

不显示调用

set

#set(val) => Object

不显示调用

OraDate子类¶

这是一个助手类，用于将OraDate绑定为数据库的日期数据类型。

OraNumber子类¶

这是一个助手类，用于将OraNumber绑定为数据库的number类型。

RAW子类¶

这是一个助手类，用于将RAW绑定为数据库的rsw类型。

类方法

create

.create(con, val, param, max_array_size) => Object

String子类¶

属性

@@minimum_bind_length

最大绑定长度

类方法

create

.create(con, val, param, max_array_size) => Object

minimum_bind_length?

.minimum_bind_length?=> Object

minimum_bind_length

.minimum_bind_length=(val) => Object

Time子类¶

–STACI::BindType::Time++这是一个助手类，用于选择或绑定数据库数据类型，例如DATE, TIMESTAMP, TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE。检索到的值是时间。

如何查询Time值

DATE,TIMESTAMP,TIMESTAMP WITH TIME ZONE 和 TIMESTAMP WITH LOCAL TIME ZONE这些类型可以作为Time值的查询对象，可以通过显式调用STACI::Cursor#define将其作为时间进行选择，如下所示：

cursor = conn.parse("SELECT hiredate FROM emp")
cursor.define(1, nil, Time)
cursor.exec()

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

UTCDateTime子类¶

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

UTCTime子类¶

实例方法

get

#get => Object

不显示调用

set

#set(val) => Object

不显示调用

Util模块¶

属性

@@datetime_fsec_base

@@default_timezone

类方法

default_timezone

.default_timezone => Object

default_timezone

.default_timezone=(tz) => Object

Math模块¶

STACI::Math模块包含用于基本三角函数和超越函数的模块函数。其精度与OraNumber相同。

属性：¶

PI¶

圆周率

举例如下：

irb(main):008:0> STACI::Math::PI

=> #<OraNumber:3.1415926535897932384626433832795028842>

类方法：¶

acos¶

.acos(x) => OraNumber

计算x的弧余弦的主值。

asin¶

.asin(x) => OraNumber

计算x的弧正弦的主值。

atan¶

.atan(x) => OraNumber

计算其参数x的反正切主值。

atan2¶

.atan2(y, x) => OraNumber

计算y、x的反正切主值，使用两个参数的符号来确定返回值的象限。

cos¶

.cos(x) => OraNumber

计算x的余弦，以弧度为单位。

cosh¶

.cosh(x) => OraNumber

计算x的双曲余弦。

exp¶

.exp(x) => OraNumber

计算x的基e指数。

log(x)¶

.log(x) => OraNumber

计算x的自然对数。

log(x, y)¶

log(x, y) => OraNumber

计算x的基y对数。

log10¶

log10(x) => OraNumber

计算x的以10为底的对数。

sin¶

sin(x) => OraNumber

计算x的正弦，以弧度为单位。

sinh¶

sinh(x) => OraNumber

计算x的双曲正弦。

sqrt¶

sqrt(x) => OraNumber

计算x的平方根。

tan¶

tan(x) => OraNumber

计算x的切线，以弧度为单位。

tanh¶

tanh(x) => OraNumber

计算x的双曲正切。

Util模块¶

check_load_error¶

.check_load_error(exc) => Object

case RUBY_PLATFORM

dll_path¶

.dll_path => String

返回加载的aci库的路径。

比如：

STACI::Util.dll_path

执行结果：

irb(main):004:0> STACI::Util.dll_path

=> "/opt/ShenTong/bin/libaci.so"

ACIException类¶

ruby-aci引发的所有异常的超类。以下异常定义为ACIException的子类。当调用接口函数返回错误状态时，会引发这些异常。

ACIBreak
ACIError
ACISuccessWithInfo
ACINoData(他是 ACIException 的子类)
ACIInvalidHandle

Break类¶

ACIException的子类,当SQL执行被STACI#break取消时引发。

ACIError类¶

ACIException的子类,以下异常被定义为ACIERROR的子类:

ACISccessWithInfo
ACINoData（在ruby-aci 2.0之前，它一直是ACIException的子类，而不是ACIError）

当底层调用接口出现数据库错误代码（如ORA-00001）时引发。

实例方法¶

initialize¶

#initialize(message, error_code = nil, sql_stmt = nil, parse_error_offset = nil) => ACIError

按参数生成一个ACIError的一个实例，比如

ACIError.new("ORA-00001: unique constraint (%s.%s) violated", 1, 'insert into table_name values (1)', )

# => #<ACIError: ORA-00001: unique constraint (%s.%s) violated>

#<ACIError: ORA-00923: FROM keyword not found where expected>

"select sysdate"

923

14

#initialize(error_code, *params) => ACIError

创建一个新的ACIERROR对象，其中包含与指定的数据库错误代码相对应的错误消息。

ACINoData类¶

ACIError子类。在ruby-aci 2.0之前，它一直是ACIException的子类。在执行PL/SQL时返回NO_DATA_FOUND会报这个异常。

ACISuccessWithInfo类¶

ACIError子类。

ACIInvalidHandle类¶

ACIException的子类,当传递给底层调用接口的句柄无效时引发。

ACIHandle类¶

用于实现ACI处理数据类型和ACI描述符数据类型的常见行为的抽象基类。

LOB类¶

STACI::LOB是一个I/O对象。LOB内容通过关联连接从数据库读取和写入。当连接关闭时，关联的LOB也会关闭。这是大对象数据类型的抽象基类；BFILE、BLOB、CLOB。

实例方法¶

available¶

#available => true or false

大对象是否可以用，如果大对象被初始化过，则返回true。

chunk_size¶

#chunk_size => Integer

返回大对象的chunk大小。

close¶

#close => self

关闭大对象。

eof¶

#eof => true or false

返回当前是否为大对象的结束位置。

pos¶

#pos => Integer

返回当前偏移量。对于CLOB它是字符数，对于BLOB和BFILE，它是字节数。

read¶

#read => String or nil

返回读取的数据。零表示它在开始时满足EOF。当长度为零且lob为空时，它返回一个空字符串'' 作为特殊异常。

read(length)¶

#read(length) => String or nil

从当前位置读取CLOB的长度字符或BLOB和BFILE的长度字节。如果长度为零，则读取数据直到EOF。

rewind¶

#rewind => true or false

设置当前偏移为开始处。

seek¶

#seek(amount, whence = IO::SEEK_SET) => self

查找流中的给定偏移量。通过将偏移量添加到whence指定的位置来获得以字符为单位的新位置。如果whence设置为IO::SEEK_set、IO::SEEK_CUR或IO::SEEK_END，则偏移量分别相对于文件的开头、当前位置指示器或文件的结尾。

size¶

#size => Integer

返回大小。对于CLOB，它是字符数，对于BLOB和BFILE，它是字节数。

size=¶

#size=(length) => Object

将lob大小更改为给定长度。

truncate¶

#truncate(length) => self

删除指定长度的数据，对于CLOB，它是字符数，对于BLOB和BFILE，它是字节数。

write¶

#write(data) => Integer

将数据写入LOB。

CLOB类¶

处理CLOB数据的类。

实例方法¶

initialize¶

#initialize(conn, contents = nil) => STACI::CLOB constructor

当contents 不为nil时创建临时CLOB。否则，它将创建一个未初始化的lob，该lob在内部用于获取CLOB列数据。

举例如下：

# Inserts a file name and its contents as CLOB.
file_name="/opt/1.txt"
clob = STACI::CLOB.new(conn, File.read(file_name))
conn.exec('insert into file_contents values (:1, :2)', file_name, clob)

BLOB类¶

处理BLOB数据的类。

实例方法¶

initialize¶

#initialize(conn, contents = nil) => STACI::BLOB constructor

当contents 不为nil时创建临时BLOB。否则，它将创建一个未初始化的lob，该lob在内部用于获取BLOB列数据。

举例如下：

# Inserts a file name and its contents as BLOB.
blob = STACI::BLOB.new(conn,  File.read(file_name, :mode => 'rb'))
conn.exec('insert into file_contents values (:1, :2)', file_name, blob)

BFILE类¶

处理BFILE数据的类,它是只读的LOB类型，你不能更新内容。

你可以在数据库端创建BFILE的文件：

CREATE DIRECTORY file_storage_dir AS '/opt/file_storage';

/opt/file_storage目录下生成一个文件：

echo 'Hello World!' > /opt/file_storage/hello_world.txt

用ruby-aci读取bfile数据如下：

require 'staci'
# The user must have 'READ ON DIRECTORY file_storage_dir' privilege.
conn = STACI.new('username/password')
# The second argument is usually an uppercase string unless the directory
# object is explicitly created as *double-quoted* lowercase characters.
bfile = STACI::BFILE.new(conn, 'FILE_STORAGE_DIR', 'hello_world.txt')
bfile.read # => "Hello World!\n"

实例方法¶

dir_alias¶

#dir_alias => String

返回目录对象名。

dir_alias¶

#dir_alias=(dir_alias) => Object

设置目录对象名。

dir_alias¶

#dir_alias=(dir_alias) => Object

当服务器的操作系统上存在BFILE时，返回true。

filename¶

#filename => String

返回文件名。

filename¶

#filename=(filename) => Object

设置文件名。

initialize¶

#initialize(conn, directory = nil, filename = nil) => STACI::BFILE

创建BFILE对象。这对应于BFILENAME。

size¶

#size=(dummy) => Object

总是返回RuntimeError错误。因为BFILE是不可修改的。

truncate¶

#truncate(dummy) => Object

总是返回RuntimeError 错误。因为BFILE是不可修改的。

write¶

#write(dummy) => Object

总是返回RuntimeError错误。因为BFILE是不可修改的。

OraDate类¶

OraDate是与数据库DATE数据类型兼容的ruby类。范围在公元前4712年到公元9999年之间。

类方法¶

_load¶

._load(bytes) => OraDate

还原由#_dump序列化的字节流。

now¶

.now=> OraDate

返回初始化为当前本地时间的OraDate对象。

比如：

OraDate.now.to_s

执行结果：

irb(main):018:0> OraDate.now.to_s

=> "2022/07/25 18:00:07"

构造方法¶

initialize¶

#initialize(year = 1, month = 1, day = 1, hour = 0, min = 0, sec = 0) => Object

返回初始化为指定日期和时间的OraDate对象。

比如：

OraDate.new              # => 0001-01-01 00:00:00
OraDate.new(2012)        # => 2012-01-01 00:00:00
OraDate.new(2012, 3, 4)  # => 2012-03-04 00:00:00

实例方法¶

<=>¶

#<=>(other) => -1, ...

根据self是小于、等于还是大于other，返回-1、0或+1。

_dump¶

#_dump => String

序列化自身。此方法由Marshal.dump（）调用。

year¶

#year => Integer

返回日期中的年份值

year=¶

#year= => Object

设置日期中的年份值

month¶

#month => Integer

返回日期的月份

month=¶

#month= => Object

设置日期的月份

day¶

#day => Integer

返回日期的day。

day=¶

#day= => Object

设置日期的day

hour¶

#hour => Integer

返回日期的小时值

hour=¶

#hour= => Object

设置日期的小时值

minute¶

#minute => Integer

返回日期的分数值

minute=¶

#minute= => Object

设置日期的分数值

second¶

#second => Integer

返回日期的秒数

second=¶

#second= => Object

设置日期的秒数

to_a¶

#to_a => Array

返回年、月、日、小时、分钟和秒的6元素数组。

比如：

OraDate.now.to_a

to_date¶

#to_date => Object

返回表示不包含时分秒的日期对象。

OraDate.now.to_date.to_s

执行结果：

irb(main):023:0> OraDate.now.to_date.to_s

=> "2022-07-25"

to_datetime¶

#to_datetime => Object

返回表示包含年月日、时分秒的DateTime对象。

to_s¶

#to_s => OraDate

返回日志的字符串格式，年月日用[/]分割，时分秒用[:]分割。

to_time¶

#to_time => Object

返回只有时分秒的Time类型。

trunc¶

#trunc => OraDate

将小时、分钟和秒字段截断为零。

比如：

oradate = OraDate.now  # => 2008/07/17 11:07:30
oradate.trunc          # => 2008/07/17 00:00:00

OraNumber类¶

OraNumber是ACI NUMBER数据类型的ruby表示。没有精度和比例指示器。

类方法¶

_load¶

._load(bytes) => OraNumber

还原由#_dump序列化的字节流。此方法由封送处理调用。load（）对由Marshal.dump（）创建的字节流进行反序列化。

构造方法¶

initialize¶

#initialize(expr = nil, fmt = nil, nlsparam = nil) => Object

从expr 表达式中创建OraNumber的值。表达式可以是数值或字符串值。如果是字符串值，则将可选的fmt和nlsparam用作SQL函数TO_NUMBER。

比如:

# Numeric expr
OraNumber.new(123456.789)   # -> 123456.789
# String expr
OraNumber.new('123456.789') # => #<OraNumber:123456.789>
# String expr with fmt
OraNumber.new('123,456.789', '999,999,999.999') # => #<OraNumber:123456.789>
# String expr with fmt and nlsparam
OraNumber.new('123.456,789', '999G999G999D999', "NLS_NUMERIC_CHARACTERS = ',.'") # => #<OraNumber:123456.789>

实例方法¶

%¶

#%(other) => OraNumber

返回自除以其他后的模。比如：

OraNumber(13) % 5 # => #<OraNumber:3>

*¶

#*(other) => Numeric

返回self和other的乘积。当other的类是Integer时，它返回一个OraNumber值。否则，它将返回与其他类相同的值。

比如：

OraNumber(2) \* 3   # => #<OraNumber:6>
OraNumber(2) \* 1.5 # => 3.0 (Float)

**¶

#**(other) => OraNumber

指定数值的指数，比如：

OraNumber(2) \*\* 2   # => #<OraNumber:4>
OraNumber(2) \*\* 2.5 # => #<OraNumber:5.65685424949238019520675489683879231435>

+¶

#+(other) => Numeric

返回self和other的总和。当other的类是Integer时，它返回一个OraNumber值。否则，它将返回与其他类相同的值。

比如:

OraNumber(2) + 3   # => #<OraNumber:5>
OraNumber(2) + 1.5 # => 3.5 (Float)

-¶

#-(other) => Numeric

返回self和other的差。当other的类是Integer时，它返回一个OraNumber值。否则，它将返回与其他类相同的值。

比如:

OraNumber(2) - 3   # => #<OraNumber:-1>
OraNumber(2) - 1.5 # => 0.5 (Float)

-@¶

#-@ => OraNumber

OraNumber数值取负值操作。

比如:

-OraNumber(2)  # =>  #<OraNumber:-2>

/¶

#/(other) => Numeric

返回self除以other的结果。当other的类是Integer时，它返回一个OraNumber值。否则，它将返回与其他类相同的值。

比如:

OraNumber(2) / 3  # =>#<OraNumber:0.6666666666666666666666666666666666666667>
OraNumber(2) / 1.5 # => 1.3333333333333333 (Float)

<=>¶

#<=>(other) => -1, 0 or +1

根据self是小于、等于还是大于other，返回-1、0或+1。这是可比测试的基础。

比如:

OraNumber(5) <=> 3   # => 1
OraNumber(4) <=> 4   # => 0
OraNumber(2) <=> 2.5 # => 1

_dump¶

#_dump => String

序列化自身。此方法由Marshal.dump（）调用。

abs¶

#abs => OraNumber

返回绝对值。

ceil¶

#ceil => Integer

返回大于或等于self的最小整数。

比如:

OraNumber(11.1).ceil  # => 12
OraNumber(25.8).ceil  # => 26
OraNumber(-25.8).ceil # => -25

dump¶

#dump => String

返回内部表示，其格式与SQL函数转储的返回值相同。

比如:

OraNumber.new(100).dump  #=> "Typ=2 Len=2: 194,2"
OraNumber.new(123).dump  #=> "Typ=2 Len=3: 194,2,24"
OraNumber.new(0.1).dump  #=> "Typ=2 Len=2: 192,11"

floor¶

#floor=> Integer

返回小于或等于self的最大整数。

比如:

OraNumber(11.1).floor  # => 11
OraNumber(25.8).floor  # => 25
OraNumber(-25.8).floor # => -26

has_fractional_part¶

#has_fractional_part => Boolean

如果self有小数部分，则返回true。

比如:

OraNumber(10).has_fractional_part   # => false
OraNumber(10.1).has_fractional_part # => true

initialize_copy¶

#initialize_copy(obj) => Object

将self替换为obj。Object#clone和Object#dup调用此方法来复制ruby解释器未知的数据。

round¶

#round => Integer

将自身舍入到最近的整数。

比如:

OraNumber(1.49).round     # => 1
OraNumber(1.5).round      # => 2
OraNumber(-1.49).round    # => -1
OraNumber(-1.5).round     # => -2

round(decplace)¶

#round(decplace) => OraNumber

将onum舍入到指定的小数点位。

比如:

OraNumber(123.456).round(2)   # => #<OraNumber:123.46>
OraNumber(123.456).round(1)   # => #<OraNumber:123.5>
OraNumber(123.456).round(0)   # => #<OraNumber:123>
OraNumber(123.456).round(-1)  # => #<OraNumber:120>

round_prec¶

#round_prec(digits) => OraNumber

将自身舍入到指定的小数位数。

比如:

OraNumber(1.234).round_prec(2) # => #<OraNumber:1.2>
OraNumber(12.34).round_prec(2) # => #<OraNumber:12>
OraNumber(123.4).round_prec(2) # => #<OraNumber:120>

shift¶

#shift(ndigits) => OraNumber

返回按ndigit自移位的值。

比如:

OraNumber(123).shift(3)  # => #<OraNumber:123000>
OraNumber(123).shift(-3) # => #<OraNumber:0.123>

to_char¶

#to_char(fmt = nil, nlsparam = nil) => String

返回包含self表示形式的字符串。fmt和nlsparam用作SQL函数，用于TO_CHAR（number）。

比如:

OraNumber(123456.789).to_char('FM999,999,999.999')  # => "123,456.789"
OraNumber(123456.789).to_char('FM999G999G999D999',  "NLS_NUMERIC_CHARACTERS = ',.'") # => "123.456,789"

to_d¶

#to_d => BigDecimal

将self作为BigDecimal返回。

to_f¶

#to_f => Float

将self作为Float返回。

to_i¶

#to_i => Integer

将self作为Int返回。

to_onum¶

#to_onum => OraNumber

返回自己。

to_r¶

#to_r => Rational

返回Rational。

to_s¶

#to_s => String

返回字符串

truncate¶

#truncate(decplace = 0) => OraNumber

将自身截断到指定的小数点后十位。未指定deplace时返回整数。

比如:

OraNumber(123.456).truncate      # => #<OraNumber:123>
OraNumber(123.456).truncate(1)   # => #<OraNumber:123.4>
OraNumber(123.456).truncate(2)   # => #<OraNumber:123.45>
OraNumber(123.456).truncate(-1)  # => #<OraNumber:120>
OraNumber(-123.456).truncate     # => #<OraNumber:-123>
OraNumber(-123.456).truncate(1)  # => #<OraNumber:-123.4>
OraNumber(-123.456).truncate(2)  # => #<OraNumber:-123.45>
OraNumber(-123.456).truncate(-1) # => #<OraNumber:-120>

zero¶

#zero => Boolean

如果值为0，则返回true。

String类¶

实例方法¶

to_onum¶

to_onum(format = nil, nls_params = nil) => OraNumber

将string类型转换为OraNumber类型，可选format 和nls_params_参数用作SQL函数TO_NUMBER 工作。

比如：

'123456.789'.to_onum # => #<OraNumber:123456.789>
'123,456.789'.to_onum('999,999,999.999') # => #<OraNumber:123456.789>
'123.456,789'.to_onum('999G999G999D999', "NLS_NUMERIC_CHARACTERS = ',.'") # => #<OraNumber:123456.789>