Skip to content

Commit c827bd9

Browse files
vikramkhatrivikramkhatri
committed
Changes to the README from a new user perspective
1 parent ef70914 commit c827bd9

File tree

1 file changed

+126
-116
lines changed

1 file changed

+126
-116
lines changed

‎README.md‎

Lines changed: 126 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -6,121 +6,152 @@ Interface for Rust to DB2 for z/OS, DB2 for LUW, DB2 for i with support for Conn
66

77
> For complete list of rust_ibm_db APIs refer to this link: https://docs.rs/ibm_db/1.0.5/ibm_db/
88
9-
## Prerequisite
9+
## Testing IBM_DB driver on Linux
1010

11-
> RUST should be installed(Rust version should be >=1.45)
12-
Confirm by typing below in command prompt:
11+
### Prerequisites
1312

14-
```
15-
>rustc --version
16-
17-
```
18-
> GIT should be installed
19-
Confirm by typing below in command prompt:
13+
We tested the following steps on an AWS EC2 instance rrunning AL2.
2014

15+
#### Install dependencies
2116
```
22-
>git --version
17+
# yum -y install gcc unixODBC git openssl-devel
2318
```
2419

25-
## How to Install If CLI Driver is not installed:
20+
#### Install Rust
2621

27-
> Download the ibm_db crate from crates.io using the below link:
28-
```
29-
https://crates.io/api/v1/crates/ibm_db/1.0.5/download
30-
```
31-
> Once done, unzip the .crate file which is actually a .tar.gz.
32-
>
33-
> Copy the setup.rs from "examples" folder to your RUST project under examples folder.
34-
>
35-
> Add the below dependencies in case not present:
36-
```
37-
[build-dependencies]
38-
cc = "1.0"
39-
winapi = "0.2"
40-
user32-sys = "0.2"
41-
sys-info = "0.7.0"
42-
bitness = "0.4.0"
43-
error-chain = "0.12.4"
44-
tempfile = "3.1.0"
45-
reqwest = "0.10.10"
46-
tokio = { version = "0.2", features = ["full"] }
47-
futures = "0.3.8"
48-
zip = "0.5"
49-
flate2 = "1.0"
50-
tar = "0.4"
51-
52-
[dependencies]
53-
winapi = "0.2"
54-
user32-sys = "0.2"
55-
sys-info = "0.7.0"
56-
bitness = "0.4.0"
57-
error-chain = "0.12.4"
58-
tempfile = "3.1.0"
59-
reqwest = "0.10.10"
60-
tokio = { version = "0.2", features = ["full"] }
61-
futures = "0.3.8"
62-
zip = "0.5"
63-
flate2 = "1.0"
64-
tar = "0.4"
65-
odbc-safe = "0.5.0"
66-
odbc-sys = "0.8.2"
67-
log = "0.4.1"
68-
encoding_rs = "0.8.14"
69-
prettytable-rs = "^0.8"
70-
lazy_static = "1.0"
71-
r2d2 = "0.8"
7222
```
73-
>
74-
> Now, run the below command once you have followed the above steps and CLI Driver will be installed:
75-
```
76-
cargo run --package <package name i.e. ibm_db or <your package name>> --example setup
23+
$ curl https://sh.rustup.rs -sSf | sh
24+
$ source ~/.bashrc
25+
26+
$ cargo --version
27+
$ rustc --version
28+
$ git --version
7729
```
7830

79-
> Then you can do "cargo install --path ." from ibm_db crate or "cargo install ibm_db" or simply include the "ibm_db" driver in your cargo.toml depending on your convenience.
31+
#### Install **clidriver**.
8032

81-
#### NOTE:
33+
<pre>
34+
<b>$ cargo install ibm_db --example setup</B>
8235

83-
In order for the test/db program to run, DSN needs to be configured.
84-
Update the db2dsdriver.cfg file(present in /clidriver/cfg folder under CLI driver path) with the requisite details.
36+
... more ...
37+
Finished release [optimized] target(s) in 1m 40s
38+
Installing /home/admin/.cargo/bin/setup
39+
Installed package `ibm_db v1.0.5` (executable `setup`)
8540

86-
Example as follows:
87-
```
88-
e.g.
89-
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
90-
<configuration>
91-
<dsncollection>
92-
<dsn alias="dashdb4" host="[email protected]" name="FOO" port="0000"/>
93-
</dsncollection>
94-
95-
<databases>
96-
<database host="[email protected]" name="FOO" port="0000"/>
97-
</databases>
98-
99-
</configuration>
100-
```
41+
<b>$ /home/admin/.cargo/bin/setup</b>
42+
</pre>
43+
44+
#### Add entries to profile
10145

102-
Include ibm_db in your cargo.toml with latest version from [Crates.io](https://crates.io/crates/ibm_db)
46+
<pre><b>
47+
$ echo "export IBM_DB_HOME=$HOME/clidriver" >> ~/.bashrc
48+
$ echo 'export LD_LIBRARY_PATH="${IBM_DB_HOME}/lib"' >> ~/.bashrc
49+
$ echo 'export PATH="${IBM_DB_HOME}/bin":$PATH' >> ~/.bashrc
50+
$ source ~/.bashrc
51+
</B></pre>
10352

104-
OR
53+
#### Install **ibm_db**.
10554

106-
Simply include this project in your RUST project.
55+
<pre><b>
56+
$ cargo install ibm_db
57+
</b></pre>
10758

108-
#### NOTE:
59+
#### Create a Rust package
60+
61+
<pre><b>
62+
$ cargo new testdb
63+
</b></pre>
64+
65+
#### Add ibm_db as a dependency to Cargo.toml
66+
67+
<pre><b>
68+
$ cd testdb
69+
$ echo 'ibm_db = "1.0.5"' >> Cargo.toml
70+
</b></pre>
71+
72+
#### Create connection properties using db2cli command
73+
74+
> Note: Change connection properties as per your database endpoints
75+
76+
<pre><b>
77+
$ cd ~/clidriver/bin
78+
$ ./db2cli writecfg add \
79+
-dsn MYDB \
80+
-database TESTDB \
81+
-host database-1.xxxxxxx.us-east-1.rds.amazonaws.com \
82+
-port 50000
83+
</b></pre>
84+
85+
#### Check db2dsdriver.cfg file
86+
87+
<pre><b>
88+
cat ~/clidriver/cfg/db2dsdriver.cfg
89+
</b></pre>
90+
91+
#### Replace ~/testdb/src/main.rs with the following program
10992

110-
In case it is not already set, add the path of the CLI Driver downloaded as above to your Path on
111-
Windows/LINUX/MACOS environment variable i.e. IBM_DB_HOME, PATH and LD_LIBRARY_PATH or DYLD_LIBRARY_PATH depending on Windows/LINUX/MACOS
112-
e.g:
11393
```
114-
set PATH = C:/IBM/IBM_DATA_SERVER_DRIVER/clidriver/bin
115-
set IBM_DB_HOME = C:/IBM/IBM_DATA_SERVER_DRIVER/clidriver
116-
(or)
117-
export LD_LIBRARY_PATH = /IBM/IBM_DATA_SERVER_DRIVER/clidriver/bin
118-
export IBM_DB_HOME = /IBM/IBM_DATA_SERVER_DRIVER/clidriver
119-
(or)
120-
export DYLD_LIBRARY_PATH = /IBM/IBM_DATA_SERVER_DRIVER/clidriver/bin
121-
export IBM_DB_HOME = /IBM/IBM_DATA_SERVER_DRIVER/clidriver
94+
use ibm_db::{safe::AutocommitOn,Statement,create_environment_v3, Connection,ResultSetState::{NoData, Data}};
95+
use std::error::Error;
96+
97+
fn main() {
98+
match connect() {
99+
Ok(()) => println!("Success."),
100+
Err(diag) => println!("Error: {}", diag),
101+
}
102+
}
103+
104+
fn connect() -> Result<(), Box<dyn Error>> {
105+
106+
let env = create_environment_v3().map_err(|e| e.unwrap())?;
107+
let conn = env.connect("MYDB", "admin", "password").unwrap();
108+
println!("Connection successful.");
109+
execute_statement(&conn)
110+
}
111+
112+
fn execute_statement<'env>(conn: &Connection<'env, AutocommitOn>) -> Result<(),Box<dyn Error>> {
113+
let stmt = Statement::with_parent(conn)?;
114+
115+
let sql_text = "select current server from sysibm.dual";
116+
117+
match stmt.exec_direct(&sql_text)? {
118+
Data(mut stmt) => {
119+
let cols = stmt.num_result_cols()?;
120+
while let Some(mut cursor) = stmt.fetch()? {
121+
for i in 1..(cols + 1) {
122+
match cursor.get_data::<&str>(i as u16)? {
123+
Some(val) => print!(" {}", val),
124+
None => print!(" NULL"),
125+
}
126+
}
127+
println!();
128+
}
129+
}
130+
NoData(_) => println!("Query executed, no data returned"),
131+
}
132+
133+
Ok(())
134+
}
122135
```
123136

137+
#### Build and run the program
138+
139+
<pre>
140+
<b>$ cd ~/testdb
141+
$ cargo build</b>
142+
... more ...
143+
Compiling testdb v0.1.0 (/home/admin/testdb)
144+
Finished dev [unoptimized + debuginfo] target(s) in 0.44s
145+
146+
<b>$ ./target/debug/testdb</b>
147+
148+
Connection successful.
149+
TESTDB
150+
Success.
151+
</pre>
152+
153+
You successfully tested the Rust program for connecting to the RDS Db2.
154+
124155
### <a name="Licenserequirements"></a> License requirements for connecting to databases
125156

126157
rust_ibm_db driver can connect to DB2 on Linux Unix and Windows without any additional license/s, however, connecting to databases on DB2 for z/OS or DB2 for i(AS400) Servers require either client side or server side license/s. The client side license would need to be copied under `license` folder of your `clidriver` installation directory and for activating server side license, you would need to purchase DB2 Connect Unlimited for System z® and DB2 Connect Unlimited Edition for System i®.
@@ -131,29 +162,8 @@ To know more about server based licensing viz db2connectactivate, follow below l
131162
* [Activating the license certificate file for DB2 Connect Unlimited Edition](https://www.ibm.com/developerworks/community/blogs/96960515-2ea1-4391-8170-b0515d08e4da/entry/unlimited_licensing_in_non_java_drivers_using_db2connectactivate_utlility1?lang=en).
132163
* [Unlimited licensing using db2connectactivate utility](https://www.ibm.com/developerworks/community/blogs/96960515-2ea1-4391-8170-b0515d08e4da/entry/unlimited_licensing_in_non_java_drivers_using_db2connectactivate_utlility1?lang=en.)
133164

134-
### How to run sample program:
135-
136-
To run the sample i.e. **main.rs** simply execute:-
137-
138-
```
139-
cargo run
140-
```
141-
#### You can also run other Sample Programs under examples folder using:
142-
```
143-
cargo run --package ibm_db --example <example_name i.e. connect or list_tables etc.>
144-
e.g. cargo run --package ibm_db --example connect
145-
```
146-
## NOTE for MACOS:
147-
If you get an error i.e. "dyld: Library not loaded: libdb2.dylib"
148-
Run the following command(Where replace the <RUST_CRATE_LIB> with the path of your rust program root folder):
149-
150-
```
151-
install_name_tool -change libdb2.dylib $IBM_DB_HOME/lib/libdb2.dylib <RUST_CRATE_LIB>/target/debug/ibm_db
152-
153-
```
154165

155-
<a name='contributing-to-the-ibm_db-RUST-project'></a>
156-
## Contributing to the ibm_db RUST project
166+
## Contributing to the <a name='contributing-to-the-ibm_db-RUST-project'>ibm_db</a> RUST project
157167

158168
See [CONTRIBUTING](https://github.com/ibmdb/rust-ibm_db/blob/main/CONTRIBUTING.md)
159169

0 commit comments

Comments
 (0)