1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
//! OCI environment
#[cfg(feature="blocking")]
#[cfg_attr(docsrs, doc(cfg(feature="blocking")))]
mod blocking;
#[cfg(feature="nonblocking")]
#[cfg_attr(docsrs, doc(cfg(feature="nonblocking")))]
mod nonblocking;
use std::{ptr, sync::Arc};
use crate::{Error, Result, oci::*, types::Ctx};
/// Represents an OCI environment.
pub struct Environment {
err: Handle<OCIError>,
// `OCIEnv` handle must be behind Arc as it needs to survive the Environment drop,
// so that `OCIEnv` is still available to async-drop used, for example, in `Session`.
env: Arc<Handle<OCIEnv>>,
}
impl AsRef<OCIEnv> for Environment {
fn as_ref(&self) -> &OCIEnv {
&*self.env
}
}
impl AsRef<OCIError> for Environment {
fn as_ref(&self) -> &OCIError {
&*self.err
}
}
impl Ctx for Environment {
fn try_as_session(&self) -> Option<&OCISession> {
None
}
}
impl Environment {
/**
Returns a new environment handle, which is then used by the OCI functions.
# Example
```
use sibyl::Environment;
let oracle = Environment::new()?;
# Ok::<(),sibyl::Error>(())
```
*/
pub fn new() -> Result<Self> {
let mut env = Ptr::<OCIEnv>::null();
let res = unsafe {
OCIEnvNlsCreate(
env.as_mut_ptr(), OCI_OBJECT | OCI_THREADED,
ptr::null(), ptr::null(), ptr::null(), ptr::null(), 0, ptr::null(),
AL32UTF8, UTF8
)
};
if res != OCI_SUCCESS {
return Err( Error::new("Cannot create OCI environment") );
}
let env = Handle::from(env);
let err = Handle::<OCIError>::new(&env)?;
let env = Arc::new(env);
Ok(Self { env, err })
}
pub(crate) fn get_env(&self) -> Arc<Handle<OCIEnv>> {
self.env.clone()
}
fn get_attr<V: attr::AttrGet>(&self, attr_type: u32) -> Result<V> {
self.env.get_attr(attr_type, self.as_ref())
}
fn get_attr_into<V: attr::AttrGetInto>(&self, attr_type: u32, into: &mut V) -> Result<()> {
self.env.get_attr_into(attr_type, into, self.as_ref())
}
fn set_attr<V: attr::AttrSet>(&self, attr_type: u32, attr_val: V) -> Result<()> {
self.env.set_attr(attr_type, attr_val, self.as_ref())
}
/**
Returns the maximum size (high watermark) for the client-side object cache
as a percentage of the optimal size.
# Example
```
let oracle = sibyl::env()?;
let max_size_percentage = oracle.max_cache_size()?;
assert_eq!(max_size_percentage, 10);
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn max_cache_size(&self) -> Result<u32> {
self.get_attr(OCI_ATTR_CACHE_MAX_SIZE)
}
/**
Sets the maximum size (high watermark) for the client-side object cache as a percentage
of the optimal size. Usually, you can set this value at 10%, the default, of the optimal size.
Setting this attribute to 0 results in a value of 10 being used. The object cache uses the
maximum and optimal values for freeing unused memory in the object cache.
If the memory occupied by the objects currently in the cache reaches or exceeds the maximum
cache size, the cache automatically begins to free (or ages out) unmarked objects that have
a pin count of zero. The cache continues freeing such objects until memory usage in the cache
reaches the optimal size, or until it runs out of objects eligible for freeing. Note that the
cache can grow beyond the specified maximum cache size.
The maximum object cache size (in bytes) is computed by incrementing `optimal_size` by the
`max_size_percentage`, using the following algorithm:
```
# fn example(optimal_size: u32, max_size_percentage: u32) -> u32 {
let maximum_cache_size = optimal_size + optimal_size * max_size_percentage / 100;
# maximum_cache_size }
```
# Parameters
* `size` - The maximum size for the client-side object cache as a percentage of the cache optimal size.
# Example
```
let oracle = sibyl::env()?;
oracle.set_cache_max_size(30)?;
let max_size_percentage = oracle.max_cache_size()?;
assert_eq!(max_size_percentage, 30);
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn set_cache_max_size(&self, size: u32) -> Result<()> {
self.set_attr(OCI_ATTR_CACHE_MAX_SIZE, size)
}
/**
Returns the optimal size for the client-side object cache in bytes.
# Example
```
let oracle = sibyl::env()?;
let optimal_size = oracle.optimal_cache_size()?;
assert_eq!(optimal_size, 8*1024*1024);
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn optimal_cache_size(&self) -> Result<u32> {
self.get_attr(OCI_ATTR_CACHE_OPT_SIZE)
}
/**
Sets the optimal size for the client-side object cache in bytes. The default value is 8 megabytes (MB).
Setting this attribute to 0 results in a value of 8 MB being used.
# Parameters
* `size` - The optimal size of the client-side object cache in bytes
# Example
```
let oracle = sibyl::env()?;
oracle.set_cache_opt_size(64*1024*1024)?;
let optimal_size = oracle.optimal_cache_size()?;
assert_eq!(optimal_size, 64*1024*1024);
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn set_cache_opt_size(&self, size: u32) -> Result<()> {
self.set_attr(OCI_ATTR_CACHE_OPT_SIZE, size)
}
/**
Returns the name of the language used for the database sessions created in the current environment.
See [Database Globalization Support Guide / Locale Data / Languages][1]
[1]: https://docs.oracle.com/en/database/oracle/oracle-database/19/nlspg/appendix-A-locale-data.html#GUID-D2FCFD55-EDC3-473F-9832-AAB564457830
# Example
```
let oracle = sibyl::env()?;
let lang = oracle.nls_language()?;
assert_eq!(lang, "AMERICAN");
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn nls_language(&self) -> Result<String> {
let mut lang = String::with_capacity(32);
self.get_attr_into(OCI_ATTR_ENV_NLS_LANGUAGE, &mut lang)?;
Ok(lang)
}
/**
Sets the language used for the database sessions created in the current environment.
# Parameters
* `lang` - The name of the language used for the database sessions
# Example
```
let oracle = sibyl::env()?;
oracle.set_nls_language("ENGLISH")?;
let lang = oracle.nls_language()?;
assert_eq!(lang, "ENGLISH");
# Ok::<(),Box<dyn std::error::Error>>(())
*/
pub fn set_nls_language(&self, lang: &str) -> Result<()> {
self.set_attr(OCI_ATTR_ENV_NLS_LANGUAGE, lang)
}
/**
Returns the name of the territory used for the database sessions created in the current environment.
See [Database Globalization Support Guide / Locale Data / Territories][1]
[1]: https://docs.oracle.com/en/database/oracle/oracle-database/19/nlspg/appendix-A-locale-data.html#GUID-550D6A25-DB53-4911-9419-8065A73FFB06
# Example
```
let oracle = sibyl::env()?;
let territory = oracle.nls_territory()?;
assert_eq!(territory, "AMERICA");
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn nls_territory(&self) -> Result<String> {
let mut territory = String::with_capacity(24);
self.get_attr_into(OCI_ATTR_ENV_NLS_TERRITORY, &mut territory)?;
Ok(territory)
}
/**
Sets the name of the territory used for the database sessions created in the current environment.
# Parameters
* `territory` - The name of the territory used for the database sessions
# Example
```
let oracle = sibyl::env()?;
oracle.set_nls_territory("CANADA")?;
let territory = oracle.nls_territory()?;
assert_eq!(territory, "CANADA");
# Ok::<(),Box<dyn std::error::Error>>(())
```
*/
pub fn set_nls_territory(&self, territory: &str) -> Result<()> {
self.set_attr(OCI_ATTR_ENV_NLS_TERRITORY, territory)
}
}