Database Server Protocol

Freedom Services 2.0 Archive Validated

$Id: db-protocol.html,v 1.3 2001/07/10 21:46:35 sam Exp $
Revision Comments
1.1 Author(s): Roger McFarlane (roger@zks.net), Philippe Boucher (philippe@zks.net); 

Initial draft. 

1.2 Author(s): Francis L'Ecuyer and Igor Stolbikov.
Revise for the implementation of 1.1 release. The connect and disconnect commands are added to initiate/terminate connection with the database server. Also the GetRecord request is replaced by ResetGet and GetNext requests.
1.3 Author: Francis L'Ecuyer
Document updated to reflect actual implementation.

Contents

Introduction

Goto : [top]
This document describes the protocol which must used to communicate with a database server. This protocol is a specialization of the Zero-Knowledge Command Protocol (ZKCP). It is therefore assumed that the reader is already familiar with the ZKCP specification.
 

Release 1.1 Note

Even though the protocol is designed for transaction based requests, it will not be done this way for release 1.1. The transaction related commands and parameters are present but will not be used.

Requirements

Goto : [top]

Commands

Goto : [top]
The following table shows the available packets types in the protocol. The ID field is the integer value which is used to represent the type. The Parameters field list the parameters which are associated with each packet type. If the parameter is enclosed in [ square brackets ], it is optional. The Source field indicates if the type is sent from a client, server or both.
 
Packet Type ID Parameters Source Description
Fetch 1 Key Client This type is used to lookup a record in the database using the specified search key. Under normal operation, the Response packet sent by the server contains a SearchResult parameter and if found, a Data parameter.
Delete 2 Key Client This type is used to delete a record in the database using the specified search key. Under normal operation, the Response packet sent by the server contains a SearchResult parameter.
Update 3 Key
Data
Overwrite
Client This type is used to create or modify an existing record in the database. You must supply the Key which will be used to store it as well as the Data to store. The Overwrite is used to indicate if overwritting is allowed in case the record already exists. Under normal operation, the server must send back a Response packet in response to this packet containing a RecordExists parameter.
ResetGet 4 None Client This packet sets a counter to the beginning of the database.
GetNext 5 None Client This packet allows you to retreive a database record using a position counter. Under normal operation, the SearchResult parameter is returned to indicate if a record was found and in that case, the Key and Data parameters are also returned.
TransactionBegin 6 Database Name Client Not implemented.
TransactionCommit 7 TransactionId Client Not implemented.
TransactionAbort 8 TransactionId Client Not implemented.
TransactionPrepareCommit 9 TransactionId Client Not implemented.
Response 10 Status
[ ErrorCode ]
[ SearchResult ]
[ Key ]
[ Data ]
[ RecordExists ]
Server This packet is used by the server to respond to packets sent from the client. Each packet sent by the client is confirmed by a response packet. The Response packet always contains a Status parameter indicating if the query was succesful. When succesful, the response contains a number of parameters, determined by the original packet. On failure, the status parameter contains an ErrorCode parameter.
Connect 20 Database  Client Initiate connection with database server. The Database parameter is sent to indicate which database is accessed. As a server only serves one database the only intent of this parameter is validatation.
Disconnect 21 None Client Terminate connection with database server.

Parameters

Parameter ID Datatype Packet Type Description
ErrorCode 1 UInt32 Response Parameter returned in a response packet when requested operation cannot be performed normally.
Status 2 UInt32 Response Returned as the first parameter of Response packets to indicate operation status. Note that this inidicates unusual problems and not, for example, a record not found when fetching. When the result is 0, operation did not execute normally and they other expected parameters (if any) are not sent but instead an ErrorCode is present in the packet.
Key 3 Binary Fetch
Delete
Update
Response
A binary of arbitrary length (but preferably short) which is used as a search key.
Data 4 Binary Create
Modify
Response
Data which is to be kept in a database record.
SearchResult 5 UInt32 Fetch
Delete
GetNext
Used in Response packet to indicates if the record was found.
Database 6 String Connect Specified only with the Connect command for validation with the server.
RecordExists 7 UInt32 Update In response to an Update query, this field indicates if the modified record exited before modification took place.
Overwrite 8 UInt32 Update When performing an Update operation, this indicates if an existing record should be overwriten.
TransactionId ? UInt32 TransactionBegin
TransactionCommit
TransactionAbort
TransactionPrepareCommit
Not implemented.

Datatypes

Datatype Format Description
Binary Byte sequence
(may contain NULs)
No interepretation is performed (or implied) on the data
UInt32 4 bytes in NBO Unsigned 32 bit value
String Byte sequence,
NUL terminated
(May not contain internal NULs)
UTF-8 encoding

Copyright © 2000 Zero-Knowledge Systems Inc.
All rights reserved.