Manual: Difference between revisions

From NEOSYS Dev Wiki
Jump to navigationJump to search
No edit summary
 
(242 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=== Hello World ===
=== ICONV/OCONV PATTERNS ===


After installing Exodus, you can develop Exodus programs from any operating system command line.
==== Decimal (MD/MC) ====


Any programs you develop are stored in the same directory as their source code. They are also copied to an folder in your home directory - Exodus on Windows and bin or lib on other operating systems. These folders are added to the end of your path by the Exodus installer. This means that, as long as you are logged in as the developing user, and there is no similarly named program early on in your path (e.g. operating system commands) you can use any developed program from any command line. To make any programs available to other users you must arrange for the programs to be copied to some directory on their path.
{|class="wikitable"
!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
|-
|-1234||MD20-||1234.00-
|}


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


Use Exodus's all-in-one editor+compiler+cataloger 'edic'
{|class="wikitable"
!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
|}


edic hello1
==== Time (MT) ====


edic will give you a skeleton Exodus program which you can develop as you wish.
{|class="wikitable"
!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
|}


There must be one and only one "function main()" statement and this is run when the program is started.
==== Hex (HEX/MX) ====


By convention, main() must return an integer value. If desired, this can be used to indicate "success" with zero or "failure" with some error number.
{|class="wikitable"
!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
|}


The programinit() and programexit() lines are required and provide all the standard multivalue system variables using a simple C++ class macro.
==== Text (L/R/T) ====


<pre>
{|class="wikitable"
#include <exodus/program.h>
!input!!conversion!! (string)output
|-
|abcd||L#3||abc
|-
|ab||L#3||ab&#9251;
|-
|abcd||R#3||bcd
|-
|ab||R#3|| &#9251;ab
|-
|ab||T#3||ab&#9251;
|-
|abcd||T#3||abc&trade;d&#9251;&#9251; 
|-
|42||L(0)#5||42000
|-
|42||R(0)#5||00042
|-
|42||T(0)#5||42000
|}


programinit()
=== Dictionaries ===


function main() {
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.
        printl("hello1 says 'Hello World!'");
        return 0;
}


programexit()
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.
</pre>
 
==== Save and compile ====
 
Make any changes you want in to the skeleton and save it.
 
NB If you just want to try out the skeleton program as is then you must still explicitly save it otherwise if you just exit without saving,  edic will assume you have changed your mind and that no longer want the hello1 program, and will cancel. For the default editor (nano), explicit save is usually Ctrl+O.
 
On saving hello1, edic will compile and catalog it.


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


To run/open/execute your new hello1 program just type its name.
==== Exodus Dictionary Format ====


hello1
{|
|-
|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
|}


and the output is ...
==== Sort/Select Command ====


hello1 says 'Hello World!'
Exodus provides the classic multivalue sort/select command within any Exodus program followed by readnext().


=== Local subroutines ===
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.


To simulate classic multivalue basic's "gosub/return" in Exodus, you can add additional subroutines and functions above or below your "main" function.
The format of the select/sselect command is as follows:


Local subroutines and functions (including the "main" function) can be any order. There is no rule that functions must appear before or above the code that calls them.
<PRE>
SELECT|SSELECT


==== Simple Example ====
{max_number_of_records}


Here is hello1 modified to call a subroutine that says something.
{using filename}


The word "gosub" is just there for classical clarity. It could be omitted. It could also be replaced by "call" which is also a throwaway word. While gosub and call are interchangeable, if you are going to use them at all, it is probably a good idea to use "gosub funcx()" to indicate internal subroutines and "call funcx()" to indicate external subroutines.
filename


All functions/subroutines must fall between the programinit() and programexit() lines, and cannot be nested otherwise compilation will fail.
{datakeyvalue} ...


<pre>
{BY|BY-DSND fieldname} ...
#include <exodus/program.h>
{


programinit()
  WITH


function main() {
  {NO|ALL|ANY}
        printl("hello1 says 'Hello World!'");


        gosub subr1();
  dict_field_id


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


subroutine subr1() {
  {AND|OR}
        printl("subr1 says 'Hello'");
}


programexit()
} ...
</pre>
</pre>


output:
=== Functions and Commands ===
 
hello1 says 'Hello World!'
subr1 says 'Hello'
 
==== Functions versus Subroutines ====
 
Functions can be used anywhere an expression would be used whereas subroutines can only be used as statements.
 
The same principle applies to both internal and external subroutines/functions.
 
Both subroutines and functions can return information in any of their "out" or "io" arguments.
 
The word "call" or "gosub" before the use of a function or subroutine is optional and can be omitted.
 
===== Functions =====
 
Functions return a value so the calling program can use a function anywhere an expression is required, for example on the right hand side of an assignment.
 
var yy=funcx(xx);
 
Even though a function returns a value, it can be ignored.


call funcx(xx);
==== String Commands ====
gosub funcx(xx);
funcx(xx);


===== Subroutines =====
Most string functions like trim() that return a new modified string have a corresponding modify in place command like function like trimmer() that is is usually much faster.
So we have convert and converter, replace and replacer, insert and inserter and so on.


Subroutines do not return a value so they can only be used as statements.
Therefore by preference use


  call subrx(xx);  
  trimmer(v1);
  gosub subrx(xx); 
  // or
subrx(xx);       
  v1.trimmer()
  var yy=subrx(xx); //will not compile


=== Subroutine and Function Parameters (Arguments) ===
instead of


Parameter names must be prefixed by "in", "out" or "io" to indicate if they are inbound, outbound or both.
v1 = trim(v1);
// or
v1 = v1.trim();


Inbound parameters (prefixed with "in") cannot be amended within the function and the compiler will enforce this. This provides a guarantee to the programmer calling the subroutine or functions that their inbound parameters will not be modified by calling the function. Inbound parameters may be provided by the calling program either as a variable or as raw data like "xyz" or 123 etc.
==== Function Types ====


In/Outbound parameters ("io") must be provided by the calling program in the form of a variable and not raw data. The function can both read and write into these parameters.
{|class="wikitable"  
!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||
|-
|expr ||traditional commands that now have outputs and can be used in expressions||
|}


Outbound parameters ("out") are indicate to the programmer using the function how it works. Outbound parameters are actually no different from in/outbound parameters. There is no simple way to enforce "write only" parameters using the underlying C++ language.
==== Parameters/Argument Types ====


All the usual C++ parameters are also allowed for example "int arg1" or "const char* arg1" etc. This might be useful in special cases or where performance is critical.
{|class="wikitable"
|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"||
|-
|}


=== External functions and subroutines ===
Optional Parameters


Editing and compiling external subroutines and functions in Exodus is identical to normal programs except:
{|class="wikitable"
!Key !!Default||
|-
|= "" ||""||
|-
|= " " ||" "||
|-
|= "." ||"."||
|-
|= 1 ||1 ||
|-
|= 0 ||0||
|-
|= true ||true||
|-
|= false ||false||
|}


#the word "program" becomes "library" so we have "library.h", "libraryinit()" and "libraryexit()".
==== Field mark characters ====
#function main can have any parameters you like, for example: "function main(in arg1, in arg2, out arg3)


NB The name of the function internally must be main and NOT the name of the function so we still have "function main(...)" but this time it can have parameter names.
Exodus implements a PICK OS data structure called a "dynamic array". This is simply any string which uses six specific unprintable ASCII delimiter characters (\x1A to \x1F) to separate its various parts. The parts are referred to as records, fields, values, subvalues, text, and subtext and fall within each other.
 
==== Example ====
 
edic func1
 
<pre>
#include <exodus/library.h>
 
libraryinit()
 
function main(in arg1, in arg2, out arg3) {
        printl("func1 says 'Hello World!'");
        return 0;
}
 
libraryexit()
</pre>
 
==== Example Using External ====
 
You just need to insert an #include "func1"
 
edic prog1
 
<pre>
#include <exodus/program.h>
 
programinit()
 
#include "func1.h"
 
function main() {
        printl("prog1 says 'Hello World!'");
        return 0;
}
 
programexit()
</pre>


Dynamic arrays therefore implement sparse six dimensional arrays.


=== Differences between Exodus's Internal Subroutines and Functions and those of classic multivalue basic ===
Typical CPU caching architecture favours similar values being adjacent in memory therefore implementing them as strings of values separated by delimiter characters can have performance advantages over more complex structures.


Exodus allows some classic multivalue basic external subroutines and functions to be implemented as local subroutines/functions thereby allowing you to keep a programs source all in one file where desired. This is a major improvement in source code management. You can still make external subroutines and functions where that is the best strategy, for example to provide some feature to more than one program.
In practice the vast majority of dynamic arrays consist of "fields" separated by the FM character (\x1E) but it is very common for fields to have values separated by the VM character (\x1D) and values to have subvalues using SM (\x1D).


In classic multivalue basic, if you wanted to implement some function to be used in any expression, or you wanted to call a subroutine with parameters, or you wanted to be sure that a subroutine would not accidentally overright main program variables, you had to implement it as an external subroutine or function. Therefore a classic multivalue program would sometimes end up as a set of separately compiled source code even when the best thing would be to keep it all together in one source file.
Since the six delimiter characters fall in the unprintable character range certain other characters have been designated as usable for coding and printing. For example the FM character is represented as ^ and can be entered in source code appended with _var to indicate that the string must be converted to internal format.


Internal subroutines and functions have access to the global variables of the main program so you might want them to make them external to make sure that there is no risk that they touch any global variable.
var v1 = "f1^f2^f3"_var; // Three fields


Exodus's local subroutines and functions are rather different and arguably much better than classic multivalue local subroutines since they have their own set of variables.
var v2 = "f1^v1]v2]v3^f3"_var; // Three fields, 2nd field has 3 values. It is "multivalued".


#can be called with parameters e.g. gosub funcx(xx,yy,zz)
Anything which contains a collection of fields can be considered as a "record" and records can be stored in files with a unique primary key. The fields might represent different columns of a traditional database table. So anonymous field number 1 might be a contact name, field 2 the contact address, field 3 a multivalued list of contact points. etc.
#except for program global variables all variables are private (preventing many bugs)
#can return a result e.g. abc=funcx(xx,yy,zz)


Essentially they are identical to *external* functions and subroutines except that 1) they are written in the main program and 2) they have access to the programs global variables.
{|class="wikitable"
!Delimiter<br>name!!var||Hex!!Display!!cstr " "||char ' '
|-
|Record Mark  ||RM||\x1F|| ` || _RM || RM_
|-
|Field Mark    ||FM||\x1E|| ^ || _FM || FM_
|-
|Value Mark    ||VM||\x1D|| ] || _VM || VM_
|-
|Subvalue Mark ||SM||\x1C|| } || _SM || SM_
|-
|Text Mark||TM ||\x1B|| &#124; || _TM || TM_
|-
|Subtext Mark  ||STM||\x1A|| ~ || _STM || STM_
|}


They do not have any access to the variables of the calling program unless they are passed as parameters or are defined as global variables.
{|class="wikitable" style="text-align: center;"
|-
|align=right|<b> Delimiter Name :</b>  ||Record Mark||Field Mark||Value Mark||Subvalue Mark||Text Mark||Subtext Mark
|-
|align=right|<b>var :</b>    || RM ||FM  ||VM  ||SM  ||TM  ||STM
|-
|align=right|<b>Display :</b>||`  ||^  || ]  || }  || &#124; || ~
|-
|align=right|<b>Hex :</b>    ||\x1F||\x1E||\x1D||\x1C||\x1B||\x1A
|-
|align=right|<b>cstr " " :</b>  ||_RM ||_FM ||_VM ||_SM ||_TM ||_STM
|-
|align=right|<b>char ' ' :</b>  ||RM_ ||FM_ ||VM_ ||SM_ ||TM_ ||STM_
|}


They only have one entry point whereas in classic multivalue basic you can jump into the middle of any local subroutine. To simulate this type of coding in in Exodus you must create nested subroutines or functions.
==== Complete List of Functions ====


The old RETURN TO XYZ syntax is not supported at all and such code must be redesigned to eliminate it.
[[Functions|Complete List of Functions]]

Latest revision as of 09:13, 30 January 2025

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}

 } ...

Functions and Commands

String Commands

Most string functions like trim() that return a new modified string have a corresponding modify in place command like function like trimmer() that is is usually much faster. So we have convert and converter, replace and replacer, insert and inserter and so on.

Therefore by preference use 

trimmer(v1);
// or
v1.trimmer()

instead of 

v1 = trim(v1);
// or
v1 = v1.trim();

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
expr 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

Field mark characters

Exodus implements a PICK OS data structure called a "dynamic array". This is simply any string which uses six specific unprintable ASCII delimiter characters (\x1A to \x1F) to separate its various parts. The parts are referred to as records, fields, values, subvalues, text, and subtext and fall within each other.

Dynamic arrays therefore implement sparse six dimensional arrays.

Typical CPU caching architecture favours similar values being adjacent in memory therefore implementing them as strings of values separated by delimiter characters can have performance advantages over more complex structures.

In practice the vast majority of dynamic arrays consist of "fields" separated by the FM character (\x1E) but it is very common for fields to have values separated by the VM character (\x1D) and values to have subvalues using SM (\x1D).

Since the six delimiter characters fall in the unprintable character range certain other characters have been designated as usable for coding and printing. For example the FM character is represented as ^ and can be entered in source code appended with _var to indicate that the string must be converted to internal format. 

var v1 = "f1^f2^f3"_var; // Three fields

var v2 = "f1^v1]v2]v3^f3"_var; // Three fields, 2nd field has 3 values. It is "multivalued".

Anything which contains a collection of fields can be considered as a "record" and records can be stored in files with a unique primary key. The fields might represent different columns of a traditional database table. So anonymous field number 1 might be a contact name, field 2 the contact address, field 3 a multivalued list of contact points. etc.

Delimiter
name		 var Hex Display cstr " " char ' '
Record Mark RM \x1F ` _RM RM_
Field Mark FM \x1E ^ _FM FM_
Value Mark VM \x1D ] _VM VM_
Subvalue Mark SM \x1C } _SM SM_
Text Mark TM \x1B | _TM TM_
Subtext Mark STM \x1A ~ _STM STM_
Delimiter Name : Record Mark Field Mark Value Mark Subvalue Mark Text Mark Subtext Mark
var : RM FM VM SM TM STM
Display : ` ^ ] } | ~
Hex : \x1F \x1E \x1D \x1C \x1B \x1A
cstr " " : _RM _FM _VM _SM _TM _STM
char ' ' : RM_ FM_ VM_ SM_ TM_ STM_

Complete List of Functions

Complete List of Functions

Retrieved from "https://devwiki.neosys.com/index.php?title=Manual&oldid=1566"