********************* Claims Database V0.2 **************** PROTOCOL DOCUMENTATION Document Version 1.0 Wednesday 13 May 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. * Insert_record_claims.sh Protocol Documentation ------------------------------------------------ Program Information ------------------- The script writes to the specified Table, it performs both addition and deletion functions. 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 * 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 -select-distinct 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 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-line requires the same arguments as the option -query. However it will only return line numbers for matching records. -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. 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 * 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 ***********************************************************