Manual: Difference between revisions

From NEOSYS Dev Wiki
Jump to navigationJump to search
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== Programmer's Guides ===
=== Programmer's Guides ===


Only for C++ at the moment. For all others, see some examples:
http://code.google.com/p/exodusdb/source/browse/#svn%2Ftrunk%2Fswig%2Fshare
==== [[Python]] ====
==== [[Perl]] ====
==== [[PHP]] ====
==== [[Java]] ====
==== [[C#]] ====
==== [[C++]] ====
==== [[C++]] ====


Line 9: Line 17:


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
!input!!conversion!!output
!input!!conversion (string)!!output
|-
|-
|1234||MD2||12.34
|1234||MD2||12.34
Line 33: Line 41:
|-1234||MD20-||1234.00-
|-1234||MD20-||1234.00-
|}
|}


==== Date (D) ====
==== Date (D) ====


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
!input!!conversion!!output
!input!!conversion (string)!!output
|-
|-
|12345||D||18 OCT 2001
|12345||D||18 OCT 2001
Line 74: Line 81:
|12345||DL||31
|12345||DL||31
|}
|}


==== Time (MT) ====
==== Time (MT) ====


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
!input!!conversion!!output
!input!!conversion (string)!!output
|-
|-
|234800||MT||17:13
|234800||MT||17:13
Line 101: Line 107:


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
!input!!conversion!!output
!input!!conversion (string)!!output
|-
|-
|ab||HEX||(same as HEX8 or HEX4 depending on platform)
|ab||HEX||(same as HEX8 or HEX4 depending on platform)
Line 125: Line 131:


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
!input!!conversion!!output
!input!!conversion!! (string)output
|-
|-
|abcd||L#3||abc
|abcd||L#3||abc
Line 179: Line 185:
|-
|-
|10||WIDTH||Column Width on fixed width reports
|10||WIDTH||Column Width on fixed width reports
|}
==== Exodus Dictionary Subroutines ====
"S" type file dictionary entries define table columns that are derived by calling a subroutine.
Dictionary subroutines can be executed in two cases.
# During a SSELECT command e.g. SELECT USERS WITH AGE_IN_YEARS > 10
# In any Exodus program using the Exodus's "calculate" function. e.g. calculate("AGE_IN_YEARS")
===== Dictionary Subroutine Library Format =====
Dictionary subroutines are a simplified type of Exodus external subroutine.
A dictionary subroutine is in the format "dict(xyz){...}" where xyz is the dictionary field key *without* quotes and ... is one or more lines of ordinary Exodus source code.
The source code may contain calculate() statements that obtain the results of other dictionary fields.
The source code must result in the variable ANS being set with the required result.
Return statement(s) may be placed anywhere in the code but are not required.
They are slightly different from ordinary external subroutines and do not have programinit()/programexit() clauses. In OO terms, this means that they are simple global functions and not classes, therefore:
#No global variables
#Any local subroutines or functions must be defined before (above) the dictionary subroutine.
All the subroutines related to one dictionary file go in one "external subroutine library" which can either be written manually or generated automatically from the source code in field 8 of S type dictionaries using the "compile dict_USERS" command.
The library name must be the same as the dictionary file name unless a "USING dictfilename" clause is included in the SSELECT or LIST command.
edic dict_USERS
<pre>
#include <exodus/dict.h>
dict(AGE_IN_DAYS) {
        ANS=date()-RECORD(1);
}
dict(AGE_IN_YEARS) {
        ANS=calculate("AGE_IN_DAYS")/365.25;
}
</pre>
===== Dictionary subroutine variables =====
Dictionary subroutines have access to the following variables.
When using "calculate(dictid)" the programmer is responsible for setting all these variables (with the exception of ANS) *before* the calculate() expression.
{|
!Variable!!Purpose
|-
|ID || The database record key.
|-
|RECORD || The database record
|-
|DICT|| The dictionary file name.
|-
|MV  || The required multivalue number or 0 for all.
|-
|ANS || Dictionary subroutines return their result in ANS.
|-
|}
|}


Line 602: Line 542:


===== String Functions =====
===== String Functions =====
Return new and doesnt change original.


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
Line 644: Line 586:


===== String Commands =====
===== String Commands =====
Modify original in place


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
Line 685: Line 629:


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
|var= ||oconv(instring, conversion)||
|var= ||oconv(instring, conversionstring)||
|-
|-
|var= ||iconv(instring, conversion)||
|var= ||iconv(instring, conversionstring)||
|}
|}


Line 778: Line 722:


===== Dynamic Array Functions =====
===== Dynamic Array Functions =====
Return modified, dont change original


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
Line 810: Line 756:


===== Dynamic Array Commands =====
===== Dynamic Array Commands =====
Modify original in place


{|border="1" cellpadding="10" cellspacing="0"
{|border="1" cellpadding="10" cellspacing="0"
Line 826: Line 774:
|cmd2 ||eraser(io instring, fieldno, valueno=0, subvalueno=0)||
|cmd2 ||eraser(io instring, fieldno, valueno=0, subvalueno=0)||
|}
|}
=== Troubleshooting ===
==== printl(lcaser("ABC")); //won't compile! ====
Simply use lcase instead of lcaser.
printl(lcase("ABC"));  //result is abc
lcaser is designed to modify a variable so lcaser's parameter must be a variable and not raw data like "ABC".
==== aa(10)=bb; //compiles but doesnt do anything! ====
To replace field 10 of dynamic array aa do one of the following.
replacer(aa,10,bb);
aa.replacer(10,bb);
Exodus doesnt support "aa(10)=" style syntax to replace dynamic array fields.
==== if (aa ^ bb > cc) //won't compile! ====
If the intent is to work like classic multivalue basic code then put brackets to clarify that to the compiler.
if ( (aa ^ bb) > cc)
If instead the intent is aa ^ (bb > cc) then you must pre-calculate the result of bb > cc ...
var dd=bb > cc;
if (aa ^ dd)
... or just wrap it in var()
if (aa ^ var(bb>cc) )
Exodus will not treat the direct result of a logical operation as a character "1" or "0" for the purposes of string concatenation. This is the only deliberate difference from multivalue Basic in Exodus. For why this is so, read about Exodus's concatenation operator.
==== using asserts ====
Asserts may be used to trap some errors in Exodus code.
Typical scheme to use asserts:
// near beginning of .cpp file:
#include <cassert>
...
// somewhere in the code:
assert( some_expression_that_should_be_normally_true);
If <code>some_expression_that_should_be_normally_true</code> happens to be false, the program aborts with message printed to console.
Exodus has 3 additional include files which modify or extend the functionality of standard cassert file.
<code>cassert_warn</code> - redefines all assert()s to display diagnostic message when triggered, but not to abort() the program;
<code>cassert_pause</code> - redefines all assert()s to display diagnostic message when triggered, and then pause the program until user presses a key; macro does not abort() the program;
<code>cassert_exodus</code> - defines assert() macro in the standard way, but adds 2 more macros:
<code>assert_warn( some_expression_that_should_be_normally_true)</code> - message, no abort();
<code>assert_pause( some_expression_that_should_be_normally_true)</code> - message, pause until keypress, no abort().
For simple examples - click on [[assert_examples]].

Latest revision as of 16:12, 4 November 2014

Programmer's Guides

Only for C++ at the moment. For all others, see some examples: http://code.google.com/p/exodusdb/source/browse/#svn%2Ftrunk%2Fswig%2Fshare

Python

Perl

PHP

Java

C#

C++

ICONV/OCONV PATTERNS

Decimal (MD/MC)

input conversion (string) output
1234 MD2 12.34
1234 MD20 1234.00
1234 MD20, 1,234.00
1234.5678 MD2 12.35
1234.5678 MD20 1234.57
1234.5678 MD20, 1,234.57
1234 MC2 12,34
1234 MC20 1234,00
1234 MC20, 1.234,00
1234 MD20- 1234.00

Date (D)

input conversion (string) output
12345 D 18 OCT 2001
12345 D/ 10/18/2001
12345 D- 10-18-2001
12345 D2 18 OCT 01
12345 D/E 18/10/2001
12345 DS 2001 OCT 18
12345 DS/ 2001/10/18
12345 DM 10
12345 DMA OCTOBER
12345 DY 2001
12345 DY2 01
12345 DD 18
12345 DW 4
12345 DWA THURSDAY
12345 DQ 4
12345 DJ 291
12345 DL 31

Time (MT)

input conversion (string) output
234800 MT 17:13
234800 MTH 05:13PM
234800 MTS 17:13:20
234800 MTHS 05:13:20PM
0 MT 00:00
0 MTH 12:00AM
0 MTS 00:00:00
0 MTHS 12:00:00AM

Hex (HEX/MX)

input conversion (string) output
ab HEX (same as HEX8 or HEX4 depending on platform)
ab HEX8 0000006100000062
ab HEX4 00610062
ab HEX2 6162
15 MX F
254 MX FE
255 MX FF
256 MX 100
27354234 MX 1A1647A

Text (L/R/T)

input conversion (string)output
abcd L#3 abc
ab L#3 ab␣
abcd R#3 bcd
ab R#3 ␣ab
ab T#3 ab␣
abcd T#3 abc™d␣␣
42 L(0)#5 42000
42 R(0)#5 00042
42 T(0)#5 42000

Dictionaries

Exodus dictionaries enable classic multivalue database data definition. Dictionaries are just normal Exodus multivalue files that contain one record for each data column definition. You can use Exodus's edir program to manually edit dictionaries.

Dictionary file names must start with the word "dict_". For example, if you have a "books" file, then you will probably have a "dict_books" file.

You can list the contents of a dictionary by typing "list dict_filename".

Exodus Dictionary Format

0 DICTID Field/Column Code
1 DICTTYPE "F" or "S" : "F" means use Field No (i.e. raw data) and "S" means use Source Code (i.e. a function).
2 FIELDNO Field number (0=key, 1=field 1 etc for "Fields"
3 TITLE Title on reports
4 SM S or M or Mnn : "Single Value" or "Multivalue" or "Multivalue Group nn"
5 KEYPARTNO Multipart keys are separated by * characters.
6
7 CONVERSION Conversion (MD/MT/D etc.)
8 SOURCE Source Code of a subroutine to calculate the field. Multivalues are lines and the result must be placed in a variable "ANS".
9 JUST "L" or "R" or "T" requesting left, right or text justification
10 WIDTH Column Width on fixed width reports

Sort/Select Command

Exodus provides the classic multivalue sort/select command within any Exodus program followed by readnext().

Classic multivalue select/readnext functions only provide the keys of the selected records. Exodus provides the classic select/readnext and also selectrecords/readnextrecord which provides complete records instead of just keys.

The format of the select/sselect command is as follows:

 SELECT|SSELECT

 {max_number_of_records}

 {using filename}

 filename

 {datakeyvalue} ...

 {BY|BY-DSND fieldname} ...
 
 {

  WITH

  {NO|ALL|ANY}

  dict_field_id

  {
   CONTAINING|STARTING|ENDING|LIKE|EQ|NE|NOT|GT|LT|GE|LE=|<>|>|<|>=|<= value(s)
   |
   BETWEEN value AND value
  }

  {AND|OR}

 } ...

Traditional Multivalue Functions and Statements (non-OO)

Exodus clones traditional multivalue function and statement behaviour and retains their syntax as far as possible.

  • Traditional functions are rendered as Exodus functions.
  • Traditional statements are rendered as Exodus subroutines.
PRINT OCONV(DATE(),'D')

in Exodus becomes:

printl(oconv(date(),"D"));

String Commands

The use of most of Exodus's functions will be fairly obvious to traditional multivalue programmers.

Ηοwever it is not so obvious that all the functions ending in "-er" correspond to the old string commands.

For example, the classic multivalue "modify in-place" character conversion command:

CONVERT 'ab' TO 'cd' IN ZZ

is now represented in Exodus by:

converter(zz,"ab","cd");

Exodus provides a complete set of string modification commands even where there was no specific command in classic mv basic.

To guarantee fast performance (regardless of compiler optimisation) you should always use the command instead of the old "self assign" idiom.

For example:

ZZ=TRIM(ZZ)

should appear in Exodus as:

trimmer(zz);

and not:

zz=trim(zz);

Function Types

TYPE FUNCTION TYPE
var= traditional functions that return values and can be used in expressions and be on the right hand side of assignments
if traditional conditional statements that started with "if" or ended with "then/else" (or could have)
cmd traditional commands with no outputs
cmd2 traditional commands that now have outputs and can be used in expressions

Parameters/Argument Types

in Parameters that provide data to the function. Can be variables or raw data like 1 or "X"
unspecified Same as "in". Omission of the most common type de-clutters the documentation. NB When defining your own subroutines and functions "in" cannot be omitted from the source code.
io Parameters that may provide and/or return data. Must be variables. Cannot be raw data like 1 or "X"
out Parameters that return data. Must be variables. Cannot be raw data like 1 or "X"

Optional Parameters

Key Default
="" ""
=" " " "
="." "."
=1 1
=0 0
=true true
=false false

Complete List of Functions

Environment
var= osgetenv(envname)
if osgetenv(envname, out value)
if ossetenv(envname, newvalue)
Time/Date/Sleep
var= date()
var= time()
var= timedate()
cmd ossleep(milliseconds)
var= ostime()
System File
if osopen(filename, out filehandle, in locale="")
cmd osclose(filehandle)
var= osbread(filehandle, startoffset, length)
cmd osbread(out data, filehandle, startoffset, length)
cmd osbwrite(data, filehandle, startoffset)
if osread(out data, osfilename, in locale="")
var= osread(osfilename, in locale="")
if oswrite(data, osfilename, in locale="")
if osdelete(osfilename)
if osrename(oldosdir_or_filename, newosdir_or_filename)
if oscopy(fromosdir_or_filename, newosdir_or_filename)
cmd osflush()
System Directory
var= oslist(path=".", wildcard="", mode=0)
var= oslistf(path=".", wildcard="")
var= oslistd(path=".", wildcard="")
var= osfile(filename)
var= osdir(filename)
if osmkdir(newdirname)
if osrmdir(dirname, evenifnotempty=false)
var= oscwd()
var= oscwd(newdirname)
Program Control
var= suspend(command)
var= osshell(command)
var= osshellread(command)
cmd osshellread(out commandoutput, command)
cmd osshellwrite(commandinput, command)
cmd stop(text="")
cmd abort(text)
var= perform(command)
var= execute(command)
var= chain(command)
var= logoff()
cmd debug()


Variable Control
if assigned(anyvar)
if unassigned(anyvar)
cmd2 exchange(var1,var2)
cmd2 transfer(fromvar,tovar)
Console Output
cmd print(instring)
cmd printl(instring="")
cmd printt(instring="")
Cursor
var= at(column0orcode)
var= at(column0, row0)
var= getcursor()
cmd setcursor(cursorstr)
var= getprompt()
cmd setprompt(promptchar)
Console Input
var= input()
var= input(out inputstr)
var= input(prompt, out inputstr)
var= inputn(n)
Math
var= rnd(number)
cmd initrnd(seednumber)
var= mod(dividend, divisor)
var= abs(number)
var= pwr(base, exponent)
var= exp(power)
var= sqrt(number)
var= sin(degrees)
var= cos(degrees)
var= tan(degrees)
var= atan(number)
var= loge(number)
var= integer(number)
var= floor(number)
var= round(number, ndecimals=0)
String Creation
var= chr(integer)
var= str(instring, number)
var= space(number)


String Info/Search
var= count(instring, substr)
var= dcount(instring, substr)
var= index(instring, substr, occurrenceno=1)
var= index2(instring, substr, startcharno=1)
var= len(instring)
var= length(instring)
if match(instring, matchstr, options="")
var= seq(inchar)
String Functions

Return new and doesnt change original.

var= convert(instring, oldchars, newchars)
var= crop(instring)
var= field(instring, sepchar, fieldno, nfields=1)
var= field2(instring, sepchar, fieldno, nfields=1)
var= fieldstore(instring, sepchar, fieldno, nfields, replacementstr)
var= lcase(instring)
var= ucase(instring)
var= lower(instring)
var= raise(instring)
cmd2 quote(instring)
cmd2 squote(instring)
cmd2 unquote(instring)
var= splice(instring, fromcharno, nchars, insertionstr)
var= substr(instring, fromcharno)
var= substr(instring, fromcharno, nchars)
var= swap(instring, oldstr, newstr, options="")
var= trim(instring, trimchars=" ")
var= trimb(instring, trimchars=" ")
var= trimf(instring, trimchars=" ")
String Commands

Modify original in place

cmd2 converter(io instring, oldchars, newchars)
var= cropper(io instring)
cmd2 fieldstorer(io instring, sepchar, fieldno, nfields, replacementstr)
cmd2 lcaser(io instring)
var= ucaser(io instring)
cmd2 lowerer(io instring)
cmd2 raiser(io instring)
cmd2 quoter(io instring)
cmd2 squoter(io instring)
cmd2 unquoter(io instring)
cmd2 splicer(io instring, fromcharno, nchars, insertion)
var= substrer(io instring, fromcharno)
var= substrer(io instring, fromcharno, nchars)
cmd2 swapper(io instring, oldstr, newstr, options="")
cmd2 trimmer(io instring, trimchars=" ")
cmd2 trimmerb(io instring, trimchars=" ")
cmd2 trimmerf(io instring, trimchars=" ")
iconv/oconv
var= oconv(instring, conversionstring)
var= iconv(instring, conversionstring)
Database
if connect(connectionstring="")
if disconnect()
if createdb(dbname, out errmsg)
if deletedb(dbname, out errmsg)
if createfile(filename, options="")
if deletefile(filename)
if clearfile(filename)
var= listfiles()
if createindex(filename, fieldname, usingdictfilename="")
if deleteindex(filename, fieldname)
var= listindexes(filename="")
if begintrans()
if rollbacktrans()
if committrans()
Database Files and Records
if open(filename, out filehandle)
if read(out record, filehandle, key)
if matread(out dimrecord, filehandle, key)
if readv(out record, filehandle, key, fieldnumber)
if write(record, filehandle, key)
if matwrite(in dimrecord, filehandle, key)
if writev(record, filehandle, key, fieldn)
if deleterecord(filehandle, key)
if updaterecord(record, filehandle, key) the record key must already exist
if insertrecord(record, filehandle, key) the record key must not already exist
if lock(filehandle, key)
cmd unlock(filehandle, key)
cmd unlockall()
Record Selection
if select(sortselectclause="")
cmd clearselect()
if readnext(out key)
if readnext(out key, out valueno) valueno returns multivalue numbers if your sortselectclause sorted BY-EXP on a multivalued field. Not implemented yet.
if selectrecord(sortselectclause="")
if readnextrecord(out record, out id) must be preceded by a selectrecord() not select()
Dictionary
var= calculate(fieldname)
var= xlate(filename, key, fieldno, mode)


Dynamic Array Functions

Return modified, dont change original

var= replace(instring, fieldno, replacement)
var= replace(instring, fieldno, valueno, replacement)
var= replace(instring, fieldno, valueno, subvalueno, replacement)
var= extract(instring, fieldno, valueno=0, subvalueno=0)
var= erase(instring, fieldno, valueno=0, subvalueno=0)
var= insert(instring, fieldno, insertion)
var= insert(instring, fieldno, valueno, insertion)
var= insert(instring, fieldno, valueno, subvalueno, insertion)
if locate(instring, target, out setting, fieldn=0, valuen=0)
if locateby(instring, target, ordercode, out setting, fieldn=0, valuen=0)
if locateusing(instring, target, usingchar, out setting, fieldn=0, valuen=0, subvaluen=0)
if locateusing(instring, target, usingchar)
var= remove(fromstr, io startx, out delimiterno)
var= sum(instring, sepchar=VM_)
Dynamic Array Commands

Modify original in place

cmd2 replacer(io instring, fieldno, replacement)
cmd2 replacer(io instring, fieldno, valueno, replacement)
cmd2 replacer(io instring, fieldno, valueno, subvalueno, replacement)
cmd2 inserter(io instring, fieldno, insertion)
cmd2 inserter(io instring, fieldno, valueno, insertion)
cmd2 inserter(io instring, fieldno, valueno, subvalueno, insertion)
cmd2 eraser(io instring, fieldno, valueno=0, subvalueno=0)