********************* Claims Database V0.23 *************** PROTOCOL DOCUMENTATION Document Version 1.2 Sunday 28 June 2009 *********************************************************** Document Contents ------------------ - Global Protocol Information - insert_record_claims.sh Protocol Documentation - read_record_claims.sh Protocol Documentation - db_backup.sh Protocol Documentation * Global Protocol Information ------------------------------ When called the scripts require a number of variables to be set. It checks it's command line arguments, and if they are not present will return BADREQUEST Currently, the insertion script only supports the addition of data to the first 12 columns of a table, however this will be enhanced at a later date. If a request is made correctly, but fails for some other reason the program will return FAILED Both also return SUCCESS if the task completes successfully Both also require the variable PROGROOT to be set in /etc/claims_db.conf. This variable should point to the main Database directory. The Variable DBROOT defines the name of the Database being queried this is the name of the directory that the files for that Database are stored in The Variable TABLE defines the specific Table that is being accessed, both scripts will automatically add a .csv onto the end of the Table name. Either script can be called using the --version argument, the only output returned will be the version of the script or the words "Function Disabled". This function can be disabled in the main configuration file. Argument Differential ---------------------- There are two types of argument that can be passed to the system, the first being a parse request, the other being an information request. The first requires the system to parse information within the system, whilst the latter simply requests information that does not require access to the data. The two types can be differentiated by the way they are called. Parse requests use a single dash (-) whereas informational requests (such as version info) use a double (--). * Insert_record_claims.sh Protocol Documentation ------------------------------------------------ Program Information ------------------- The script writes to the specified Table, it performs both addition and deletion functions. Supported Arguments: -insert -delete --version Required Variables ------------------- -insert - Record insertion; The script requires the following Variables to be defined on the command line DBROOT TABLE COL1 through to COL12 A sample Record addition call would be as follows DBROOT="Sample_DB" TABLE="sample" COL1="01" COL2="Example" insert_record_claims.sh -insert -delete - Record Deletion; The following variables must be defined on the command line DBROOT TABLE whilst the -delete tag must be passed to the script followed by a line number. The line number is used to delete the data, and it is important to remember that Column Headers do count as a line, so the 1st line of data is actually row 2. An example call would be as follows DBROOT="Sample_DB" TABLE="sample" insert_record_claims.sh -delete 4 --version Returns the version of the script, subject to the requirements described in the Global Protocol Information -insert-file Should be called in the same means as -insert. The argument should then be followed by COLUMN DIR FILENAME where DIR is the directory that the file resides in, and FILENAME is the filename of the file. Text to be entered into the related record should also be specified. Column defines where the filename should be stored (can be any column except 1). Column 1 of the target table must be used for Primary key storage. The system will automatically generate a primary key once the request has been placed. An example call would be as follows DBROOT="Sample_DB" TABLE="sample" COL2="Example" insert_record_claims.sh -insert-file 3 /tmp myfile.txt * read_record_claims.sh Protocol Documentation ----------------------------------------------- Script Information ------------------- The script is intended for retrieving data only, as such it works on a copy of the Database table. The script can return all data from the table, or can execute a query. Queries are passed to the script on the command line by defining which column to search, and a texual query. Required Variables ------------------ The script requires a number of variables. Variables that must be declared on the command line are DBROOT TABLE and one of the following arguments must be given -headers -read -query -query-line -gen-PK -Table-size -select-distinct --version --gen-tbl-sig --tmp-cleanup -retrieve-document -known-databases -known-tables --Database-size -vague-query -vague-query-line Both -headers and -read require no further arguments. -read returns all data stored within the table, without the Column Headers -headers returns only the Column Headers -query requires a further two arguments, the first of which must be the Query string. This must be delimeted in quotation marks. This option will return all records matching the query data. You can optionally pass -primkey as the final argument. This should only be passed if the data you are searching is unique (i.e. a Primary Key). This will speed up the query, especially in larger tables, as the system will stop the query once it has found a match The second argument is the Column Reference, which will be an Integer. This tells the program which Column to query. All columns will be shown for matching records, it is up to the calling program to exclude any columns not wanted/needed by the user. -query and -query-line will only return exact matches where the query text makes up the entire value for that field. If you wish to query within records (for example part of a string) use -vague-query or -vague-query-line -query-line requires the same arguments as the option -query. However it will only return line numbers for matching records. You can optionally pass -primkey as the final argument. This should only be passed if the data you are searching is unique (i.e. a Primary Key). This will speed up the query, especially in larger tables, as the system will stop the query once it has found a match -gen-PK requires 1 further argument. It requires a Column Number, this number should define the column that contains the tables primary keys. The system will then return the next valid Primary Key -select-distinct requires a column number. It will then run a SELECT DISTINCT style query on the specified column and return all values contained therein, it will not return duplicate values. --version Returns the version of the script, subject to the requirements described in the Global Protocol Information --gen-tbl-sig Generates a checksum of the specified table, using whichever checksum program is used in the configuration file. -Table-size Returns the row count of the specified table, excluding the table headers --tmp-cleanup Pauses all connections and removes any surplus temporary files. Any new connections will be paused until this process has completed. -retrieve-document Requires the primary key of the Document to be specified. Then outputs the requested file directly to stdout. The front end can identify the target filename from whichever table the documents is related to. Retrieve Document queries do not require the TABLE variable to be set. -known-databases Requires no other variables to be set. This argument will cause Claims_DB to display the names of all databases currently hosted. There is no authentication on this function, as if a user has local access to Claims_DB they can quite easily ascertain which databases exist. It is expected however that projects such as Claims_DB_listener will implement steps to authenticate/prevent remote users from accessing this information unless they have authority. -known-tables Requires DBROOT to be set. The system will then output the name of all Tables stored within the named database. As with the -known-databases call there is currently no authentication on this argument. --Database-size Requires DBROOT to be set. This call will output the number of rows in the entire database, excluding table headers. -vague-query requires DBROOT and TABLE. It queries the table for any matching strings within the column that you specify. You call the -vague-query in exactly the same way as -query. The first argument should be delimited in quotation marks. You can use -primkey to only return the first record located (i.e. a Primary Key). You must then pass the Column Reference as the second argument (this will be an integer), this tells the system which field to query. All columns will be displayed so long as the query string exists in the defined column. Unlike -query if the query text exists within a string in the specified column, that record will be returned by the system. For example if you are querying column 3 for 'dog' and one record has "I have a Dog" in column 3, -query will not return that record, but -vague-query will. -vague-query-line requires the same arguments as the -vague-query, -query and -query-line arguments. An example call to receive only the headers of the Table would be DBROOT="Sample_DB" TABLE="sample" read_record_claims.sh -headers Whilst an example call to receive a dump of the tables contents would be DBROOT="Sample_DB" TABLE="sample" read_record_claims.sh -read An example query call would be DBROOT="Sample_DB" TABLE="sample" read_record_claims.sh -query "Sample Text" 4 An example query line call would be DBROOT="Sample_DB" TABLE="sample" read_record_claims.sh -query-line "Sample Text" 4 An example Document retrieval (to retrieve document 23) DBROOT="Sample_DB" read_record_claims.sh -retrieve-document 23 An example call to list all Databases stored in Claims_DB read_record_claims.sh -known-databases An example Vague Query would be DBROOT="Sample_DB" TABLE="sample" read_record_claims.sh -vague-query "Sample Text" 4 An example Vague Query for line numbers would be DBROOT="Sample_DB" TABLE="sample" read_record_claims.sh -vague-query-line "Sample Text" 4 * db_backup.sh Protocol Documentation ------------------------------------- The db_backup.sh script requires very little input from the command line. It does however require both PROGROOT and BACKUPDIR to be set in /etc/claims_db.conf The script will create a Gzipped Tar file of the entire Database directory. It is intended to allow the backing up of individual databases at a later date. As with the other protocol drivers, the script will return one of three strings FAILED SUCCESS BADREQUEST The script will return BADREQUEST if either of the variables are not set in the configuration file. Possible FAILED causes include a lack of disk space, a read only directory used for BACKUPDIR or the unavailability of Tar of Gzip. *********************************************************** DOCUMENT END ***********************************************************