NicomDB Programmers Reference Manual

16-Jun-2008
By John Niclasen

Contents:

1. relative-table
1.1 Input fields
1.2 Output fields
1.3 Creation
1.4 open-relative
1.5 close-relative
1.6 read-record
1.7 write-record
1.8 rewrite-record
1.9 delete-record
2. index-table
2.1 Input fields
2.2 Creation
2.3 open
2.4 close
2.5 set-key
2.6 start-greater
2.7 start-next
2.8 read-next
2.9 start-less
2.10 start-prev
2.11 read-prev
2.12 read-first
2.13 read-last
2.14 read
2.15 write
2.16 rewrite
2.17 delete

1. relative-table

1.1 Input fields

table-name [file!]

Full name of table.

table-type [word!]

'character (default) or 'binary

fields [block!]

Name and type of data fields in a record.

1.1.1 table-type

If table-type is 'binary, the last field in each record is treated as binary data and saved that way. So records become binary data and can't be viewed by a normal text editor.

This is useful to store e.g. images, which will else take up double the amount of disk space needed, if saved as REBOL image! datatypes.

1.2 Output fields

record [block!]

Actual data record.

record-number [integer!]

Actual record number.

status [word!]

Actual status of this table.

valid [logic!]

Valid flag.

1.3 Creation

1.3.1 Example

A relative table to hold the elements of the periodic table.

elements: make relative-table [
table-name: %data/elements
fields: [
symbol word!
name word!
series word!
state word!
weight decimal!
orbits block!
]
]

1.4 open-relative

Opens a table on the relative level.

1.4.1 Arguments

No arguments

1.4.2 Return value

true

status: 'successful

1.4.3 Example

elements/open-relative

1.5 close-relative

Close a table opened on the relative level.

1.5.1 Arguments

No arguments

1.5.2 Return value

true

status: 'successful

1.5.3 Example

elements/close-relative

1.6 read-record

Read a data record.

1.6.1 Arguments

number [integer!]

The record number of the record to be read from the relative table.

1.6.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

1.6.3 Example

record: elements/read-record 42

1.7 write-record

A record is written at the next free record-number.

1.7.1 Arguments

record [block!]

Data record to be written.

1.7.2 Return value

number [integer!]

The record number of the written record.

status: 'successful

1.7.3 Example

elements/write-record [H Hydrogen nonmetal gas 1.00794 [1]]

1.8 rewrite-record

Rewrite a record previously being read.

1.8.1 Arguments

record [block!]

Data record to be rewritten.

1.8.2 Return value

number [integer!]

The record number of the rewritten record.

status: 'successful

1.8.3 Example

elements/rewrite-record [H Hydrogen nonmetal gas 1.00794 [1]]

1.9 delete-record

Delete a record.

1.9.1 Arguments

record-number [integer!]

The record number to be deleted.

1.9.2 Return value

true

status: 'successful

1.9.3 Example

elements/delete-record 42

2. index-table

2.1 Input fields

name [file! string!]

Name of table.

path [file!]

Path to table.

keys [block!]

A block of key information for the table.

2.1.1 keys

The key information for a table is held in keys. Each key has three pieces of information:

name [word!]

The name of the key.

key [block!]

A block holding the names of the fields for this key.

type [word!]

The type of the key, unique or duplicates.

2.2 Creation

2.2.1 Example

An index table to hold information for molecules.

molecules: make index-table [
name: "molecules"
path: %data/

; key-name, key-fields and key-type
keys: [
name [name] unique
formula [formula name] unique
]

; field-name and datatype
fields: [
name string!
formula string!
keywords block!
]

; The next line is optional. It's just convenient to have a default
; record, so that can be used as a basis for new records.
record: [name "" formula "" keywords []]
]

2.3 open

Opens a table on the index level.

2.3.1 Arguments

No arguments

2.3.2 Return value

The value returned from open-relative.

2.3.3 Example

molecules/open

2.4 close

Close a table opened on the index level.

2.4.1 Arguments

No arguments

2.4.2 Return value

The value returned from close-relative.

2.4.3 Example

molecules/close

2.5 set-key

Set the key to be used in later table I/O.

2.5.1 Arguments

key-name [word!]

The name of the key to set.

2.5.2 Return value

true

2.5.3 Example

molecules/set-key 'formula

2.6 start-greater

Finds a record with a key value greater than the one specified.

2.6.1 Arguments

key [block!]

The key value to check up against.

2.6.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.6.3 Example

record: molecules/start-greater ["Water"]

2.7 start-next

Finds a record with a key value equal to or greater than the one specified.

2.7.1 Arguments

key [block!]

The key value to check up against.

2.7.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.7.3 Example

record: molecules/start-next ["Water"]

2.8 read-next

Read the next record from the current file position. This function can only follow a successful retrieving of a record.

2.8.1 Arguments

No arguments

2.8.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.8.3 Example

record: molecules/read-next

2.9 start-less

Finds a record with a key value less than the one specified.

2.9.1 Arguments

key [block!]

The key value to check up against.

2.9.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.9.3 Example

record: molecules/start-less ["Water"]

2.10 start-prev

Finds a record with a key value equal to or less than the one specified.

2.10.1 Arguments

key [block!]

The key value to check up against.

2.10.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.10.3 Example

record: molecules/start-prev ["Water"]

2.11 read-prev

Read the previous record from the current file position. This function can only follow a successful retrieving of a record.

2.11.1 Arguments

No arguments

2.11.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.11.3 Example

record: molecules/read-prev

2.12 read-first

Read the first record in the table with regard to the current key.

2.12.1 Arguments

No arguments

2.12.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

If the table is empty, return value is none, and status is set to 'invalid-key.

2.12.3 Example

record: molecules/read-first

2.13 read-last

Read the last record in the table with regard to the current key.

2.13.1 Arguments

No arguments

2.13.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

If the table is empty, return value is none, and status is set to 'invalid-key.

2.13.3 Example

record: molecules/read-last

2.14 read

Finds a record with a key value equal to the one specified.

2.14.1 Arguments

key [block!]

The key value for the record being read.

2.14.2 Return value

record [block!]

If found, a data record with field names and values are returned, and status is set to 'successful.

none [none!]

Otherwise return value is none, and status is set to 'invalid-key.

2.14.3 Example

record: molecules/read ["Water"]

2.15 write

A record is written at the next free record-number, if key checks are ok for unique keys. Keys are put in the B-Tree structures.

The current table position is not modified by write.

2.15.1 Arguments

record [block!]

Data record to be written.

2.15.2 Return value

number [integer!]

If key checks are ok, the record number of the written record is returned, and status is set to 'successful.

none [none!]

If there is duplicate key for an unique key, none is returned, and status is set to 'duplicate-key.

2.15.3 Example

molecules/write [name "Water" formula "H_2O" keywords [solvent EPA]]

2.16 rewrite

Rewrite a record, if key checks are ok for unique keys. Keys are put in the B-Tree structures.

The current table position is not modified by rewrite.

2.16.1 Arguments

record [block!]

Data record to be written.

2.16.2 Return value

true [logic!]

If key checks are ok, true is returned, and status is set to 'successful.

none [none!]

If there is duplicate key for an unique key, false is returned, and status is set to 'duplicate-key.

2.16.3 Example

molecules/rewrite [name "Water" formula "H_2O" keywords [solvent EPA]]

2.17 delete

Delete a record.

The current table position is not modified by delete.

2.17.1 Arguments

key [block!]

The primary unique key value for the record to be deleted.

2.17.2 Return value

true [logic!]

If record is found, true is returned, and status is set to 'successful.

false [logic!]

Otherwise return value is false, and status is set to 'invalid-key.

2.17.3 Example

molecules/delete ["Water"]

NicomDoc - 16-Jun-2008