Installation

After the full ZIM installation, copy the file zimapi.cs from the ZIM directory to wherever directory is needed to start developing your C-Sharp application.

Globals

TOP = indicate the first tuple (row or record) from a set of records
BOTTOM = indicate the last tuple (row or record) from a set of records
UTF8 = indicate a UTF8 Zim database
ANSI = indicate a ANSI Zim database
NO_ERROR = No errors

Constructors

using ZimConnection;

ZimAPI Conn = new ZimAPI();
Conn.Connect(dataBase, hostName, portNum, userName, passwd);               
System.Console(ZimAPI.State);
Conn.Close();

Alternatively:

using ZimConnection;

ZimAPI Conn = new ZimAPI(Database Name, Host Name, Port Number, User Name, Password);               
System.Console(ZimAPI.State);
Conn.Close();

The DATABASE NAME is obligatory.

The HOST NAME defaults to “localhost”, if omitted.

The PORT NUMBER is “6002” by default; if changed, it also requires changing a configuration option in the file zimconfig.srv located in the ZIM directory.

The USER NAME defaults to “ZIM”, if omitted.

The PASSWORD defaults to “”, if omitted.

Properties

int State;

The status of the last ZimAPI process executed. If zero, it was correct.

Methods

int Conn.Execute(ZIM or SQL command);

Executes a ZIM or SQL command against the connected database, returning only the status of the execution. If zero, the command was executed successfully.

Example:

if Conn.Execute("DELETE 1 Customers WHERE CustCode = 1") == 0
    System.Console("Executed successfully.");
else:
    System.Console("Error executing statement. Error Code is = " + str(zim.state) + ".");

int Conn.Transaction();

Starts an explicit transaction against the connect database. Any statements executed afterward will be within the scope of an atomic transaction until a COMMIT or ROLLBACK is executed. In ZIM, all statements are executed with an implicit transaction (that is, an automatic transaction is started, the statement is executed and then the transaction is automatically committed or rolled back in case of an error), unless an explicit transaction would be started.

int Conn.Commit();

Commits all updates occurred in the database while an explicit transaction was active and closes the transaction.

int Conn.Rollback();

Rolls back all updates occurred in the database while an explicit transaction was active and closes the transaction.

string Result[] = Conn.Callproc(procedure name);

Invokes and executes a ZIM procedure passing parameters to it. If a parameter is a “?”, that indicates an output parameter, that is, the called procedure should return a value there.

Example:

Result = zim.callproc(“MyProc(\"12\", 7, \"?\", \"?\")”);
System.Console(Result[1] + Result[2]);

RES[1] and RES[2] indicate the first and second output parameters.

int Conn.Putfile(source, destination, format);

Copies the SOURCE file located in your workstation to the DESTINATION place located in the server side using the proper FORMAT (either “/A” for text files or “/B” for binary files).

int Conn.Getfile(source, destination, format);

Gets a file from the SOURCE location on the server machine and place it in the DESTINATION place locally with the specified FORMAT (either “/A” for text files or “/B” for binary files).

string Conn.ErrorMessage();

Returns the last error message found by Zim.

int Conn.ErrorCode();

Returns the last Zim error code found by Zim.

Cursors

ZimAPI cursors allow the retrieval of records from sets created by the execution of ZIM or SQL statements through a defined cursor (see the definition of SETS below).

A cursor can be directly or indirectly created:

ZimAPI.ZimCursor.MyCursor = Conn.Cursor([ZIM command or SQL command]);

The cursor is immediately created and is ready to be used. Example:

MyCursor = Conn.Cursor("FIND 5 Customers");

or

MyCursor = Conn.Cursor();
MyCursor.Execute("FIND 5 Customers");

The cursor created by the above examples produce exactly the same results, that is, a set of up to 5 records (members) from the table (Entity Set) called CUSTOMERS.

int MyCursor.Close();

Closes the created cursor.

int MyCursor.RowCount();

Indicates how many members the indicated cursor has available for retrieval.

string MyCursor.FetchOne();

The current member of the set pointed by the cursor is fetched and made available for further processing. The member number indicator is automatically set to the next member of the set.

int MyCursor.RowNumber();

Indicates the member number (the row number) currently available to be fetched.

string MyCursor.ValueOf(field name);

Gets the value of the FIELD NAME as defined in the database repository. This value corresponds to the record (tuple or row) retrieved by the last FetchOne method.

string MyCursor.ValueOf(field index number);

Gets the value of the FIELD INDEX NUMBER as defined in the database repository. This value corresponds to the record retrieved by the last FetchOne method.

string MyCursor.GetName(field index number);

Get the name of the attribute referenced by the field index number.

int MyCursor.FieldCount();

Provides the number of fields existing in the current record.

int MyCursor.Scroll(amount);

Scrolls the set pointed the cursor in the AMOUNT of members (rows) which can be positive or negative, or the constants “TOP” or “BOTTOM” to move the current member to the beginning of the set or to the bottom of the set.

Sets

One of the most powerful features of Zim are the sets, or a logical collection of rows (records) from one or more tables. Sets are “views” of rows and persist during the whole connection or until recreated.

MyCursor = Conn.Cursor("FIND 5 Customers -> sCustomers");

This statement creates a cursor over a set of maximum 5 rows from Customers and label this set as sCustomers. You can work on this cursor and close it but the sCustomers remain available for other operations like:

MyCursor.Execute("DELETE 1 FROM sCustomers");

Which will delete the first row from the set called sCustomers.