Manual: Difference between revisions

From NEOSYS Dev Wiki
Jump to navigationJump to search
No edit summary
 
(229 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 so you have to reopen command lines immediately after installing Exodus.
{|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-
|}


You can use any developed program from any command line, as long as you are logged in as the developing user, and there is no similarly named program earlier on in your path (e.g. operating system commands). To make any programs available to other users you must arrange for the programs to be copied to some directory on their path.
==== Date (D) ====


==== Edit ====
{|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
|}


Use Exodus's all-in-one editor+compiler+cataloger 'edic'
==== Time (MT) ====


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


edic will give you a skeleton Exodus program which you can develop as you wish.
==== Hex (HEX/MX) ====


There must be one and only one "function main()" statement and this is run when the program is started.
{|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
|}


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.
==== Text (L/R/T) ====


The programinit() and programexit() lines are required and provide all the standard multivalue system variables using a simple C++ class macro.
{|class="wikitable"
!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
|}


<pre>
=== Dictionaries ===
#include <exodus/program.h>


programinit()
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.


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


programexit()
You can list the contents of a dictionary by typing "list dict_filename".
</pre>
 
==== Save and compile ====
 
Make any changes you fancy to the skeleton and save it.
 
NB If you just want to try out the skeleton program exactly as it is then you must 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.
==== Exodus Dictionary Format ====


==== Run ====
{|
|-
|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
|}


To run/open/execute your new hello1 program just type its name.
==== Sort/Select Command ====


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


and the output is ...
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.


hello1 says 'Hello World!'
The format of the select/sselect command is as follows:


=== Local subroutines ===
<PRE>
SELECT|SSELECT


To simulate classic multivalue basic's "gosub/return" in Exodus, you can add additional subroutines and functions above or below your "main" function.
{max_number_of_records}


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.
{using filename}


==== Simple Example ====
filename


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


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.
{BY|BY-DSND fieldname} ...
{


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


<pre>
  {NO|ALL|ANY}
#include <exodus/program.h>


programinit()
  dict_field_id


function main() {
  {
        printl("hello1 says 'Hello World!'");
  CONTAINING|STARTING|ENDING|LIKE|EQ|NE|NOT|GT|LT|GE|LE=|<>|>|<|>=|<= value(s)
  |
  BETWEEN value AND value
  }


        gosub subr1();
  {AND|OR}


        return 0;
} ...
}
 
subroutine subr1() {
        printl("subr1 says 'Hello'");
}
 
programexit()
</pre>
</pre>


output:
=== Functions and Commands ===
 
hello1 says 'Hello World!'
subr1 says 'Hello'
 
=== Subroutine and Function Parameters (Arguments) ===
 
Parameter names must be prefixed by "in", "out" or "io" to indicate if they are inbound, outbound or both.
 
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.
 
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.
 
Outbound parameters ("out") indicate to the programmer using the function how it works. However, outbound parameters do not actually prevent them being used to provide data to the subroutine or function and are therefore no different from in/outbound parameters. There is no simple way to enforce "write only" parameters using the underlying C++ language.
 
For special cases, or where performance is critical, the usual C++ parameters are also allowed for example "int arg1" or "const char* arg2" etc.
 
=== External functions and subroutines ===
 
Editing and compiling external subroutines and functions in Exodus is identical to normal programs except:
 
#the word "program" becomes "library" so we have "library.h", "libraryinit()" and "libraryexit()".
#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.
 
==== Example func1 ====
 
edic func1
 
<pre>
#include <exodus/library.h>
 
libraryinit()
 
function main(in arg1, out arg2) {
        printl("func1 says 'Hello World!'");
        arg2="arg1 was "^arg1;
        return 999;
}
 
libraryexit()
</pre>
 
==== Example prog1 using func1 ====
 
Compiling func1 created a func1.h file that is required to "glue" func1 into any program that wants to use func1.
 
To use func1 in any program or external subroutine or function, you need to insert an #include "func1.h" somewhere between "programinit()" and "programexit()" - and not within the body of any function or subroutine.
 
edic prog1
 
<pre>
#include <exodus/program.h>
 
programinit()
 
//you must "declare" that we want to use func1
#include "func1.h"
 
function main() {
        printl("prog1 says 'Hello World!'");
 
        //we print what func1 returns, and also what func1 returns in arg2
        var arg2;
        printl(  func1("myarg1",arg2)  );
        printl(arg2);
 
        return 0;
}
 
programexit()
</pre>
 
run prog1
 
prog1
 
output:
 
prog1 says 'Hello World!'
func1 says 'Hello World!'
999
arg1 was myarg1
 
=== 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.
==== String Commands ====


The word "call" or "gosub" before the use of a function or subroutine is optional and can be omitted.
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.  


==== Functions ====
Therefore by preference use


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.
trimmer(v1);
// or
v1.trimmer()


var yy=funcx(xx);
instead of


Even though a function returns a value, it can be ignored.
v1 = trim(v1);
// or
v1 = v1.trim();


call funcx(xx);
==== Function Types ====
gosub funcx(xx);
funcx(xx);


==== Subroutines ====
{|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||
|}


Subroutines do not return a value so they can only be used as statements.
==== Parameters/Argument Types ====


call subrx(xx); 
{|class="wikitable"
gosub subrx(xx); 
|in|| Parameters that provide data to the function. Can be variables or raw data like 1 or "X"||
subrx(xx);       
|-
var yy=subrx(xx); //will not compile
|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"||
|-
|}


=== Differences between Exodus's Internal Subroutines and Functions and those of classic multivalue basic ===
Optional Parameters


Exodus's internal subroutines and functions are very different from and arguably much better than classic multivalue internal subroutines since they can be called with parameters, have their own set of variables. They can also return values and therefore be used as functions.
{|class="wikitable"
!Key !!Default||
|-
|= "" ||""||
|-
|= " " ||" "||
|-
|= "." ||"."||
|-
|= 1 ||1 ||
|-
|= 0 ||0||
|-
|= true ||true||
|-
|= false ||false||
|}


Exodus Internal Subroutines and Functions:
==== Field mark characters ====


#can be called with parameters e.g. gosub funcx(xx,yy,zz)
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.
#all variables are private except for program global variables (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.
Dynamic arrays therefore implement sparse six dimensional arrays.


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


They only have one entry point whereas in classic multivalue basic you can jump into the middle of any internal subroutine. To simulate this type of coding in in Exodus you must create nested subroutines or functions.
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).


The old RETURN TO XYZ syntax is not supported at all and such code must be redesigned to eliminate it.
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.


==== Moving external subroutines and functions to internal ====
var v1 = "f1^f2^f3"_var; // Three fields


Exodus allows many classic multivalue basic external subroutines and functions to be reimplemented as internal subroutines and functions. This means that you can now, where appropriate, keep all source code related to one program in a single file. This is a major improvement in source code management.
var v2 = "f1^v1]v2]v3^f3"_var; // Three fields, 2nd field has 3 values. It is "multivalued".


In classic multivalue basic, if you wanted to implement some function to be used in expression you had to implement it as an external function requiring a separate source code file. If this function was applicable only to one program then splitting it into a separate source file is likely to be an unwanted but unavoidable outcome.
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.


In classic multivalue basic, 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.
{|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_
|}


You can still make subroutines and functions external where that is the best strategy, for example:
{|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_
|}


#to provide some common feature to more than one program
==== Complete List of Functions ====
#to compile a large program in parts
#where not all the parts of a program need to be loaded in memory immediately on startup.


NB Exodus 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.
[[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"