SLANG: Built-in Scripting Language
Programmer's reference
(C) S Projects. Any distribution of any parts
of this site is strictly prohibited,
unless explicitly stated in text.
Please read the disclaimer
|
|
Introduction
The SLANG is a general purpose scripting language. It can be used to
perform data processing, charting, to do input and output
operations and so on.
It can also access the functionality of a program that is
using it, giving you the interface to program's functions, in automatic
mode, without the need for user input.
The functions are implemented in few DLLs, each group covering
certain area. This Reference Guide follows the same structure.
SP_BASIC.DLL
This DLL contains set of functions implementing a BASIC-like language.
Arithmetics
The language supports a traditional set of operations:
+, -, *, /, % (remainind part after division), ^(power)
Logical operations
Used as "condition" part in "if" and "for".
Supported logical operations are:
&& (AND), || (OR), == (equal), != (not equal),
< (less than), > (greater than), <=, >=
Types of variables
There are four types of variables in SLANG: number, string, array of
numbers and array of strings. We need to declare them, before we use
them:
double x;
double y = 0;
string str = "Hello";
array arr = CREATE_ARRAY(0);
array_ arr_s = CREATE_ARRAY_S(0);
Notice, that we can create numeric or string variables, and later
assign the values to them.
As for arrays, they have to be created by calling the CREATE_ARRAY or
CREATE_ARRAY_S functions. The reason for it is rather simple - in
our scripting language we have three different types of arrays:
not sorted, sorted and sorted with no duplicated values. We create
them by passing 0, 1 and 2 to the CREATE_... function.
Be careful with the sorted arrays - there are things you can not do
with them. Let's say, you want to alter 5th element of an array:
arr[5] = 3;
It is OK if an array is not sorted, but what if it was sorted?
For example, what if it had 10, 20, 30, and 40? By inserting "3" into
the 5th array's element, you will ruin the sorting!
To avoid these sort of problems, use the following approach. If the array
is unsorted (0 was passed when it was created), you can assign values to
its elements using assignment, like in
arr[5] = 3;
If an array is sorted, you have to use built-in functions of the scripting
language. For example, you can add an element to the sorted array
by calling
double nPos = ARRAY_ADD(arr, dValue);
This function will add dValue to the correct (according to sorting)
position, and return the index of a new element in array. For example,
if we want to insert 3 into the sorted array that already has elements
2, 4, 5, the resulting array will be 2, 3, 4, 5 and the nPos, returned by
the ARRAY_ADD function will be equal 1 (indices in arrays are zero-based,
0, 1, 2...).
An important advantage of using arrays is the fact that you can use them in cycle,
using the cycle variable as an array index.
for(i = 0; i < 10; i = i + 1)
{
arr[i] = 2 * i;
}
Comments
The // is used to comment code to the
end of line.
The /*...*/ is a block comment.
User-defined functions
The program exacution begins with "main" function. All other functions are
called from "main", and when "main" code is over, the script stops.
The "main" function is an example of "user-defined" functions. Other functions
can be created as well, provided that they don't use names, that are reserved
for built-in functions.
A user-defined function can return value, using the
return operator, in this case, it can be used in expressions:
x = UserFunction(y);
Note, that all control paths of a function must return the same type:
double MyFunc(double x)
{
if(x == 3)
{
return 3;
}
return "Hello"; //WRONG !
}
A user-defined function can receive parameters:
double MyFunc(double x, array arr, ...)
if(condition) ... else ...
Check the logical condition and execute or skip corresponding
code.
if(x > 3 && y < 5)
{
... do something ...
}
else
{
... do something else ...
}
The "else" block is not mandatory.
for...continue...break...
The cycle works as follows:
for(i = nInitialValue; condition; i = nNewValue)
{
...
break i; // break from the (nested) cycle(s)
...
continue i; // go back to the beginning of the cycle
...
}
The initial value should be assigned, it can not be a call to a function,
that sets the value, but an explicit assignment.
The cycle continues for as long as the Condition is true.
Assignment of a new value of a cycle variable can increase or decrease
its value, for example i = i + 1.
"break i" directive is used to BREAK from the cycle (to pass control to the
next operator after the cycle's body) that has the specified cycle variable.
"continue i" directive is used to move to the next cycle, ignoring
whatever code is after the "continue".
LESS_SQUARE
arrCoefs = LESS_SQUARE(arrX, arrY, nFirst, nLast);
Returns an array, containing two elements. The first element contains
a, the second element contains b, where Y = a*X + b.
CREATE_ARRAY,
CREATE_ARRAY_S
array arr = CREATE_ARRAY(0);
array arr_s = CREATE_ARRAY_S(0);
Variables of array and array_s types have to be declared, as any other types.
In addition, arrays have to be created by calling the CREATE_ARRAY or
CREATE_ARRAY_S functions. The reason for it is rather simple - in
SLANG we have three different types of arrays:
not sorted, sorted and sorted with no duplicated values. We create
them by passing 0, 1 and 2 to the CREATE_... function.
Be careful with the sorted arrays - there are things you can not do
with them. Let's say, you want to alter 5th element of an array:
arr[5] = 3;
It is OK if an array is not sorted, but what if it was sorted?
For example, what if it had 10, 20, 30, and 40? By inserting "3" into
the 5th array's element, you will ruin the sorting!
To avoid these sort of problems, use the following approach. If the array
is unsorted (0 was passed when it was created), you can assign values to
its elements using assignment, like in arr[5] = 3;
If an array is sorted, you have to use built-in functions of the scripting
language. For example, you can add an element to the sorted array
by calling double nPos = ARRAY_ADD(arr, dValue);
This function will add dValue to the correct (according to sorting)
position, and return the index of a new element in array. For example,
if we want to insert 3 into the sorted array that already has elements
2, 4, 5, the resulting array will be 2, 3, 4, 5 and the nPos, returned by
the ARRAY_ADD function will be equal 1 (indices in arrays are zero-based,
0, 1, 2...).
An important advantage of using arrays is the fact that you can use them in cycle,
using the cycle variable as an array index.
for(i = 0; i < 10; i = i + 1)
{
arr[i] = 2 * i;
}
PAUSE
PAUSE(nTimeout);
Suspends a program for the specified number of milliseconds.
WRAP_CREATE
hVarList = WRAP_CREATE();
The way SLANG works with arrays (array, array_s) makes it impossible
to have, say, array of arrays, or array of variables. However,
it is often necessary.
Example: In
Stock Downloader script, we need to perform two different
tasks. The first time we run the script, we need to load the previously
saved stock or Forex quotes from disk. We do not know in advance, how many
arrays it will create, because it depends on the number of stock / forex
symbols the user specified.
The second time we run the script, and every next time (it is called by
the timer), we only need to add new quotes to already existing arrays,
without spending time on downloading the same data again.
Therefore, we need an "array of arrays", or array of wariables.
In SLANG, we use the concept of a wrapper. Working with wrappers is
similar to working with files: you need to get a handle.
A handle represents an array of variables, for example, arrays (you can
mix variables of different types in a single array).
If we used copies of variables, then, especially in case of arrays,
accessing the data would be slow. To make the process faster, we use
so called references. Please read the explanations below, to avoid
frustrations.
1. When we create a wrapper using WRAP_CREATE, we create an empty array
of a special type.
2. To add a variable to this array, you need to call WRAP_ADD, to remove it,
call WRAP_REMOVE. The variable in the array is a COPY of the original
variable.
3. To "get" the element of a wrapper, you need to call WRAP_GET. The
way it works is by making the data (for example, an array) of the
new variable to point to the data, that a wrapper holds. When you
change the variable (for example, by adding an element to an array, or
changing its value), the data in a wrapper are changing as well.
Therefore, by calling the WRAP_GET, you are creating an alias for an
element of a wrapper.
4. What if you are trying to create an alias for an element of a
wrapper, that already have an alias? Then the previous alias is "released".
Its value will be reset to a default. For example, if you have an array
(arr), and you call WRAP_ADD(handle, arr), the wrapper, that is
referred to by a handle "handle" will be added a copy of "arr".
Then, if you create an alias, by calling WRAP_GET(handle, arr1, nPos), then
the arr1 will POINT to the data, that the wrapper's element contains.
Finally, if you call WRAP_GET(handle, arr2, nPos), then arr2 will
point to the wrapper's element, while arr1 will contain an empty
array, and not a "pointer".
WRAP_ADD
nPos = WRAP_ADD(hList, var);
Adds a copy of the variable "var" to the wrapper. For details, see
the WRAP_CREATE
WRAP_REMOVE
WRAP_REMOVE(hList, nPos);
Removes an element from the wrapper. if there is a variable, pointing
to this element, its value will be reset. For details, see
the WRAP_CREATE
WRAP_GET
WRAP_GET(hList, var, nPos);
Create an alias for the element (with the index nPos) of a wrapper.
After the call, "var" points to the element of a wrapper.
For details, see the WRAP_CREATE
WRAP_CLOSE
WRAP_CLOSE(hVarList);
Delete a wrapper, reset all variables that were pointing on it.
For details, see the WRAP_CREATE
#include
#include "strFileName"
Includes file (containing SLANG code) in the current script.
This approach allows to use same external "library",
instead of pasting the same code in every script
that need it.
The file is included in the exact place where #include
directive is located, so if it uses variables, defined
in the parent file, you need to make sure they are
already defined.
The path is either a full path ("c:\s_projects\cortex...")
or a path relative to the location of Cortex.exe
("..\CortexPro\data\samples\scripts\myscript.tsc").
SCRIPTMATH.DLL
This DLL contains mathematical functions and some data conversion
routines.
ARRAY_SIZE(array)
double nSize = ARRAY_SIZE(arr);
Returns the size of an array.
This function can take both array and array_s types of parameters.
ARRAY_ADD
nPos = ARRAY_ADD(arr, dValue);
or nPos = ARRAY_ADD(arr_s, strValue);
Add a new element to an array, according to a sorting rules. If
successfull, return the index of a new entry, if failed (for example,
the elemetn already present and array allows no duplication)
returns -1.
ARRAY_REMOVE
dValue = ARRAY_REMOVE(arr, nIdx);
or strValue = ARRAY_REMOVE(arr_s, nIdx);
Removes an element, and returns it.
ARRAY_FIND
nPos = ARRAY_FIND(arr, dValue);
or nPos = ARRAY_FIND(arr_s, strValue);
Returns an index of the array's element, or -1, if not found.
ARRAY_INSERT
nPos = ARRAY_INSERT(arr, dValue, nIdx);
or nPos = ARRAY_INSERT(arr_s, strValue, nIdx);
Insert an element in the specified position. Returns an index.
If an array is sorted, a new element will be inserted according
to a sort order, and nIdx will be ignored.
ARRAY_TRUNCATE
ARRAY_TRUNCATE(arr, nIdxFirst, nIdxLAst);
or ARRAY_TRUNCATE(arr_s, nIdxFirst, nIdxLAst);
Truncates an array.
ARRAY_SUM
double dSum = ARRAY_SUM(arr, nFirst, nLast);
Returns sum of elements of an array, nFirst is the first index,
nLast is the last index. For example, to calculate sum of first 10
elements, use dSum = ARRAY_SUM(arr, 0, 9);
Use -1 for max and min indexes (same applies to all
functions of this kind, like ARRAY_MIN etc)
ARRAY_SUMSQ
double dSum = ARRAY_SUMSQ(arr, nFirst, nLast);
Returns sum of squared elements of an array: x[i]^2 + x[i + 1]^2...
ARRAY_SUMXMY2
dSumXmY2 = ARRAY_SUMXMY2(arr1, arr2, nFirst, nLast);
Returns sum of (arr1[i] - arr2[i])^2
ARRAY_AVG
dAverage = ARRAY_AVG(arr, nFirst, nLast);
Returns sum of array elements divided by the number of elements.
ARRAY_MAX
dMax = ARRAY_MAX(arr, nFirst, nLast);
Returns maximum value of an array element (for the given interval of
indices).
ARRAY_MIN
dMax = ARRAY_MIN(arr, nFirst, nLast);
Returns minimum value of an array element (for the given interval of
indices).
ARRAY_MIN_MAX
arrMinMax = ARRAY_MIN_MAX(arr, nFirst, nLast);
Returns an array of four elements, first containing minimum value
of an array elements (for the given interval of indices), the second
one containing the maximum, third containing the index of the minimum
element, fourth containing the index of the maximum element.
Note: if there are more than one min. or max. values in the selected range
(more then one point has min or max value), the index contains the location
of the first occurence.
MV_AVG, EXP_MVAVG, MV_MAX,
MV_MIN, MV_SUM
arrResult = MV_XXX(arrSrc, nInterval);
Returns an array, containing moving average, exponential moving
average, moving maximum, moving minimum, or moving sum.
NEXT_EXP_MA
dNextExpMa = NEXT_EXP_MA(arrMa, dMaInterval, dValue);
Often, data arrive one record in a time, and to process it in real time,
we cannot call EXP_MV_AVG every time. This function takes an array
of previously calculated MA values, the next number, and calculates
next MA. Note, that the new value is not added to the array - you
have to do it yourself.
MAX, MIN
dMax = MAX(dX, dY);
dMin = MIN(dX, dY);
Returns larger or smaller of two numbers.
Math. functions
y = F(x);, where F can be:
CEIL - closest integer above x
FLOOR - closest integer below x
SIN, COS, TAN, ASIN, ACOS, ATAN, COSH, SINH, TANH
ABS, EXP, LOG (e), LG (10)
DEGREES - converts radians to degrees
RADIANS - converts degrees to radians
FACT - factorial
RAND - random number between 0 and x
REAL_TO_DATE,
DATE_TO_REAL
strDate = REAL_TO_DATE(nDate);
nDate = DATE_TO_REAL(strDate);
Dates and time are processed as numbers. Dates are in days,
time - in minutes. To convert these numbers between the form
that scripting engine understands and human-readable form,
we use these two functions.
List of supported formates: 15-01-99, 01-Jan-1999, 01-Jan-99,
10/7/2003, 10/7/03, 10.07.2004, 15-01-1999, 2002.08.15
REAL_TO_TIME,
TIME_TO_REAL
strTime = REAL_TO_TIME(nTime);
nTime = TIME_TO_REAL(strTime);
S_FILE.DLL
F_MAKEDIR
bResult = F_MAKEDIR(strDirName);
Creates a directory. This function can create only one new
directory per call, it means that only one (last) subdirectory
or the path can be a new directory.
F_OPEN
handle = F_OPEN(strFileName,
strMode, bIsPathRelative = 0);
Open the file, return a file handle, number that is used by
other file accessing functions, or -1 if failed.
strMode can be "w" - write, "r" - read, "a" - append, also it may
be text "t" or binary "b".
Third argument can be omitted, default value is 0
(full path is used). 1 stands for path, relative to
the location of EXE file (BIN folder).
handle = F_OPEN("work.txt", "w+b");
For a complete list of file access modes, see fopen function in
online C or C++ tutorials.
PRINT, F_PRINT
F_PRINT(hFile, strFormat, xArgument, ...);
PRINT(strFormat, xArgument, ...);
PRINT function is used to perform text output to the window, called
Output Panel. F_PRINT can either print to file, or - if you pass
it -1 as a file handler - to the same window as PRINT.
strFormat is a format string. For strings, you need to use "%s",
for numbers - "%f". It is possible to add extra text to the format
string, for example:
PRINT("x = %f", x, ", y = %f", y);
Format strings follow the C language specs, full description of
all details can be found in online articles about printf function
of C or C++ language. Here we only list the most useful things.
Number of decimal places to be printed: "%2.2f" means that 2 digits
will be printed before decimal point and 2 - after. "%.0f" prints
integer, no decimals.
\t prints tabulation.
\r\n prints a new line: PRINT("x = %f\r\n", x);
"%00.0f" prints two digits, for example 05, it can be useful, when
you print time or dates.
F_EOF
bIsEof = F_EOF(hFile);
Returns 1 if the file cursor is at the end of file, 0 otherwise.
F_GETS
str = F_GETS(hFile);
Reads a string from the file, until finds end of file, or
a new line.
F_READ
bResult = F_READ(hFile, strBuffer, nLen);
Reads up to nLen bytes from hFile to strBuffer variable. Returns
number of bytes actually read.
F_WRITE
bResult = F_WRITE(hFile, strBuffer);
Writes data (string) from the strBuffer variable to file.
Returns 1 if successful, 0 otherwise.
F_SEEK
bResult = F_SEEK(hFile, nOffset, nSeekType);
Moves the file cursor. The distance to move is set by nOffset.
Depending on nSeekType, cursor moves:
if 0 - relative to the current position,
if 1 - relative to the end of file
if 2 - relative to the beginning of file
F_RENAME
bResult = F_RENAME(strOldName, strNewName);
Renames the file, returns 1 if successful, 0 if failed.
F_COPY
bResult = F_COPY(strOldName, strNewName);
Creates a copy of a file, returns 1 if successful, 0 if failed.
F_GETPOS
nPos = F_GETPOS(hFile);
Returns a position of the file cursor.
F_UNLINK
bResult = F_UNLINK(strFileName);
Deletes the file from disk, returns 0 if failed, 1 - if successfull.
F_CLOSE
F_CLOSE(hFile);
Close file, previously opened by F_OPEN. It is strongly recommended
to close files that are not used, to free system resources. Also,
until you close file, there is no guarantee, that the writing
into this file is completed.
F_EXE
bResult = F_EXE(strFileName);
Runs an external executable file (including .BAT files).
Returns 0 if failed, 1 if succeded.
The function waits for the EXE to finist its work, before
it continues. For example, if you run an external .BAT
file, that processes 10000 photos, the script will
resume only after photos are processed (or command window
is manually closed).
TABLE_LOADER
nNumOfRecords = TABLE_LOADER(strFullPath,
bIsRelative, bReverse, strStartPattern, strSkipAfterStartPattern,
strEndPattern, nCol_1, arr_1, ...);
Used to load data from a disk file to the set of arrays, one array per
column.
Return value: number of records that was successfully processed. or
-1, if failed (for example, no such file).
Arguments:
strFullPath - location of the file to be loaded
bIsRelative - 0, if it is a complete path, and 1 if the path is
relative to the location of the program's executable. For example:
c:\\s_projects\\CortexPro\\data\\samples\\stocks\\msft.txt
..\\CortexPro\\data\\samples\\stocks\\msft.txt
bReverse - should arrays that we loaded, be reversed, for example, if
the stock quotes file contains newest data first, and we want them last.
strStartPattern - a line, AFTER which meaningfull data begin. Used,
if we need to skip the file's header. "" (empty string) if none.
strSkipAfterStartPattern - number of lines to skip AFTER the startPattern
(or beginning of file, if start pattern is "".
strEndPattern - string, where to stop, "" if we want to go till the
end of file.
nCol_1 - the first column to load
arr_1 - array (a variable, previously declared) that will get data
from the first column.
... there can be more nCol_i, arr_i pairs, if we want to load more
than one column.
LOAD_FILE
strBuffer = LOAD_FILE(strFilName);
Loads file to a string buffer.
GET_FULL_PATH
Get full path from relative (to Cortex's Bin directory).
string strFullPath = GET_FULL_PATH(strRelativePath);
GET_TOKEN
strToken = GET_TOKEN(strSrc, strDelimiters);
Returns a substring, from the beginning of a string, to the
end, or to the first occurence of one of the symbols from the
strDelimiters. The strSrc gets shorter after this operation, as
the string read is being removed from it.
For example:
string str = "Hello, World!";
strToken = GET_TOKEN(str, ",;-");
After this operation, strToken contains "Hello" and str contains " World!"
GET_DIR
arrFileNames = GET_DIR("c:\\S_Pojects\\Tmp",
bRecurse, strMask);
Returns an array, containing list of file names.
bRecurse specifies, if subdirectories should be scanned as well.
Example of strMask: "*.htm; *.txt;"
Example of the code:
array_s arrDirList =
GET_DIR("c:\\s_projects\\CortexPro\\data", 0, "*.*");
for(double n = 0; n < ARRAY_SIZE(arrDirList); n = n + 1)
{
PRINT("%s\r\n", arrDirList[n]);
}
STR_STR
strFoundString = STR_STR(strString, strSubstring,
bSecondPart);
If bSecondPart equals 1, returns a sub-string, that begins with
the strSubString, empty string ("") if not found.
If it is 0, returns the first part.
For example, for the string "Hello, World!", a call to the function, with
a strSubString equal "Wo", will return "Hello, " and "World!",
corrispondingly.
STR_CHR
strResult = STR_CHR(strString, strCharacter,
bReverse);
Returns string, that begins with first or last (if bReverse is 1)
occurrence of a character. Empty string, if character not found.
STR_CMP
nResult = STR_CMP(strString1, strString2,
nLen = -1, bCaseSensitive = 0);
Returns a result of lexicographic comparison of two strings.
nLen represents the length of comparison (for example, the first 3
characters), bCaseSensitive determines, if the comparison
is case sensitive (1) or not (0).
nLen and bCaseRelative can be omitted, in this case, the default
value is used.
STR_REPLACE
nNumOfReplacements = STR_REPLACE(strLine,
strOld, strNew);
Replaces all occurrences of strOld with strNew, returns number
of replacements made.
STR_LEN
nLen = STR_LEN(strVariable);
Returns length of a string.
SUBSTRING
strSubString = SUBSTRING(strString, nFirst, nLast);
Returns a substring of a string, between nFirst and nLast characters.
TIME
arrTime = TIME(nHoursDif);
Returns an array containing DayOfWeek,Year,Month,Day,Hour,Minute,Second.
OUT_CLEANUP
OUT_CLEANUP();
Deletes all the text in the Output Panel.
STR2NUM
x = STR2NUM(str);
Converts string to number.
NUM2STR
x = NUM2STR(str, "%f");
Converts number to a string, according to format sperifier.
REGEXP_IGNORE_CASE
REGEXP_IGNORE_CASE(bIgnoreCase);
For the processor of regular expressions, sets the
"ignore case" flag to 1 or 0.
REGEXP_GLOBAL
REGEXP_GLOBAL(bIsGlobal);
For the processor of regular expressions, sets the
"global" flag to 1 or 0. If the flag is set to global,
replace operation handles all matches, otherwise, only
the first match will be replaced.
REGEXP_MATCH
bHasMatch =
REGEXP_MATCH(strSource, strPattern);
Searches the strSource string against the match pattern.
Returns 0 if nothing found, or 1 if at least one
match found.
For an example of use, see sample_regexp.tsc script
file, included with the Cortex archive.
REGEXP_REPLACE
strResult =
REGEXP_REPLACE(strSource, strPattern,
strReplaceWith);
Replaces one (if "global" flag is set to 0) or all
(if set to 1) matches in the strSource with
strReplaceWith.
Returns a resulting string.
For an example of use, see sample_regexp.tsc script
file, included with the Cortex archive.
REGEXP_EXECUTE
listOfMatches = REGEXP_EXECUTE
(strSource, strPattern);
Returns a string list containing matches.
For an example of use, see sample_regexp.tsc script
file, included with the Cortex archive.
DATABASES
DB_OPEN
hDb = DB_OPEN(string strFileName,
double bIsPathRelative);
Opens the sqlite database, returns a database handle.
This handle will be passed to other functions,
that work with that database.
DB_CLOSE
DB_CLOSE(double hDb);
Closes a database, that was previously opened with DB_OPEN.
After the database is closed, handle becomes invelid and
cannot be used.
DB_SQL_RUN
double nNumOfRecords =
DB_SQL_RUN(double hDb, string strSql,
array (or array_s) arrColumn_1, ...);
Executes the SQL statement.
hDb - database handle, obtained by DB_OPEN()
strSql - SQL statement. For supported syntax, see
home page of SQLite in the Internet.
Example:
"SELECT ImageLocation, rights_id FROM Images;"
arrColumn1, ... arrColumnN - arrays, created with
CREATE_ARRAY or CREATE_ARRAY_S, that will receive
corresponding field, returned by SQL.
DB_GET_FIELD_NAMES
array_s arrFieldNames =
DB_GET_FIELD_NAMES(double hDb, string strTableName);
Returns string list, containing field names for given table
in a database.
IMAGE
PROCESSING
IMAGE_PROCESS
void IMAGE_PROCESS(strSrcFileMame,
strImageType, bGrayScale, nBrightness, nContrast,
bKeepAspect, nWidth, nHeight);
Used to convert image file, altering its size and
some attributes.
strSrcFileMame - name of a source fize
strImageType is one of: auto, bmp, jpg, jpeg, gif,
png, ico, tif, tiff, tga, pcx
If "auto" is specified, a file with the same extension
(and name) is created, overwriting the source file.
Note: to preserve original file, copy it from other
directory, and only then call IMAGE_PROCESS.
bGrayScale: 0 to preserve original colors, 1 to
convert image to grayscale.
nBrightness - increase or decrease image brightness
nContrast: -1 to blur, 0 to leave as is, 1 to sharpen
bKeepAspect: 0 to use only width and height, 1 to
preserve aspect ratio
nWidth, nHeight - bounding rectangle for the target image.
If bKeepAspect is 1, the actual image can be smaller.
USING HTML FORMS
HTML_FORM
bOkCancel = HTML_FORM(nWidth, nHeight,
strTemplate, strFieldName1, varFieldValue1, ...);
This function creates a modal dialog, based on HTML (or XML)
template, and waits for the user to take an action.
Return value: 0 if the user clicks CANCEL, 1 if the user
clicks OK.
nWidth, hHeight are width and height of the window, in
screen pixels.
strTemplate is the name of HTML (or XML) file, that the
form uses.
pairs strFieldName, varFieldValue are used to retrieve
the data from the form. strFieldName is a name of the
field in the form, while varFieldValue is the variable
(previously declared, and in case of arrays, initialized by
calling ARRAY_CREATE or ARRAY_CREATE_S) that will receive
the value of that field.
If the field contains multiple values (list box with
multiple selection), you should pass a variable of list
type, that will be filled, one value per array element.
To close the dialog, you can use either Cancel or OK:
<input type="submit" name="cancel" value="Cancel">
<input type="submit" name="ok" value="OK">
Note, that the name of OK button must be 'ok'.
To simulate the form submit via the html link, use JavaScript,
for example:
<script type="text/javascript">
function LinkSelected(control)
{
document.forms.form.what.value = 'Link was clicked';
document.forms.form.ok.click();
}
</script>
...
<a href="#" OnClick=LinkSelected(this)>link</a>
HTML_FORM_EX
bResult = HTML_FORM_EX(nWidth,
nHeight, strTemplate, arrsFieldNames, arrsFieldValues);
Fills two arrays, one for field names, and one for field
values. Note, that fields allowing multiple selection
are not supported by this function.
CHARTS
This DLL handles charting.
See SAMPLE_07.TSC for example of a script that uses charting.
SET_AXE
SET_AXE(nWhichAxe, nSubTickNo, nTextDirection, nDateX);
Configures the axe that will be used later for charting.
Parameters:
nWhichAxe - 1 - X axe at the bottom of a chart,
2 - Y axe at the left side of a chart,
4 - X axe at the top of a chart
8 - Y axe at the right side of a chart
For example: SET_AXE(1 + 4 + 8, ...
nSubTickNo - number of subticks between ticks on axe(s), also
used to draw the grid.
nTextDirection - text directions for labels, 0 - horizontal, 1 -
vertical.
nDateX - 0 if X axe is numeric, 1 - if it represents dates.
Dates (SEE REAL_TO_DATE and DATE_TO_REAL functions) can be
passed as numeric array, but labels will show them in human-readable
form.
ADD_SERIES_STYLE
ADD_SERIES_STYLE(nMarkerType, nConnectorType);
Each dataset is displayed using its own connector and marker.
Marker is a symbol, that is shown at the point of a chart,
while connector is a line, connecting these points.
Markers:
0: NON (no symbol)
1: RECTANGLE
2: CIRCLE
3: TRIANGLE
4: STAR5
5: STAR6
6: R_CROSS
7: X_CROSS
8: DIAMOND
9: TRIANGLE2
10: BAR2
11: CIRCLE2
12: ARROW_UP
13: ARROW_DN
14: BAR
15: BAR3D
16: STACKED_BAR,
17: STACKED_BAR3D
Note, that BAR, BAR_3D, STACKED_BAR and STACKED_BAR3D are TYPES of
a chart, too.
Connectors:
0: No connector
1: LINE_GRAPH
2: BAR_GRAPH
3: STACKED_GRAPH
SET_CHART_CLIP
SET_CHART_CLIP(xmin, ymin, xmax, ymax);
Set the rectangle to fit the chart into, all dimensions are in screen
pixels.
SET_CHART_SCALE
SET_CHART_SCALE(double xmin, double ymin, double
xmax, double ymax);
Set the min. and max. values to be displayed on the axes.
GET_STACKED
GET_STACKED(double* pdData, int nNumOfPoints,
double* pdBase);
When we draw the first dataset on a stacked bar chart, we pass
an array (pdBase), containing zeros. The function will set
array elements to the heights of bars.
When we draw the second dataset, the bars will be stacked on top
of existing bars, using this array, and then the array elements
will be adjusted, again.
DRAW_CROSS
DRAW_CROSS();
Draw the "cross" - two lines, crossint at 90 degrees in the 0,0
point.
CALC_SCALE
CALC_SCALE(arrArray, nWhichAxe, bIsFirstTime,
nResizeMethod, arrDelta);
As an alternative to manually setting the min and max values for the
axes using SET_CHART_SCALE, we can call CALC_SCALE to do it
automatically.
Parameters:
arrArray - an array (data from tataset, for this axe) to add to
a chart. To plot more than one dataset, call this function for
each dataset.
nWhichAxe: 0 - X axe, 1 - Y axe
bIsFirstTime - 1 if this is the first time we call the function
(for THIS chart, for THIS axe), 0 otherwise.
nResizeMethod: 0 - if it is not bar or stacked bar graph,
1 otherwise.
arrDelta: used by bar and stacked bar charts. Create an array,
fill it with 0, and pass to the function. It will fill it with
numbers automatically.
DRAW_AXES
DRAW_AXES(nAxesColor, nLegendsColor, nGridStyle,
nGridColor, nLineWidth, nTickWidth, nAxesSet);
Draws axe(s) on screen.
Parameters:
nAxesColor - color of axe(s).
Colors are:
| black = 0 |
|
|
blue = 1 | |
| green = 2 | |
|
cyan = 3 | |
| red = 4 | |
|
magenta = 5 | |
| brown = 6 | |
|
lightgray = 7 | |
| darkgray = 8 | |
|
lightblue = 9 | |
| lightgreen = 10 | |
|
lightcyan = 11 | |
| lightred = 12 | |
|
lightmagenta = 13 | |
| yellow = 14 | |
|
white = 15 | |
nLegendsColor - color of text labels
nGridStyle - style of a grid;
solid = 0; dash = 1; dot = 2; dashdot = 3; dashdotdot = 4;
nGridColor - color of the grid lines
nLineWidth - width if the lines on chart.
nTickWidth - width of ticks
nAxesSet - which axes to draw
1 - X axe at the bottom of a chart,
2 - Y axe at the left side of a chart,
4 - X axe at the top of a chart
8 - Y axe at the right side of a chart
PLOT
PLOT(nSeriesNumber, arrX, arrY, arrShifts);
arrShifts parameter is optional, it is only required
for bar and stacked bar charts.
Array of shifts is 2 times larger than x and y arrays. It contains
information about shifts of bars in BAR_GRAF or BAR_3D_GRAF.
s[2*i] contains negative and s[2*i+1] - positive shifts.
After every call to this function shifts[] will be modified.
Initial values of array elements at first call should be 0.
In the case of the stacked bar graphs, the arrDelta array is provided.
It is 4 times bigger than the size of data. It can also be used in
the case of the chart with deviations (deltax1, deltay1, deltax2,
deltay2)
Parameters:
nSeriesNumber - number of a dataset, zero-based.
arrX, arrY - X and Y data to plot.
arrShifts - create this array, fill it with 0 and pass to the
function. See SAMPLE_07.TSC for an example.
MARKER_SET_COLOR
MARKER_SET_COLOR(nColor16, nBack16, bFill);
Set color, background color and fill flag for the dataset's marker.
CONNECTOR_SET_COLOR
CONNECTOR_SET_COLOR(nColor16, nBack16, bFill);
Set color, background color and fill flag for the dataset's connector.
SAVE_CHART
strXML = SAVE_CHART(dWidth, dHeight, bDateX,
strFileName, arrX, arrY_1, ...optional arr 2, ...);
Creates the line chart and saves it on disk. Returns XML code that
can be used to create a web page containing this chart (or can be
ignored, it not required).
Parameters:
dWidth, dHeight - dimensions of the chart, pixels.
bDateX - 0 if X axe is numeric, 1 if it contains numbers that should
be converted to dates.
strFileName - name of the file to create.
arrX_1, arrY_1, ...optional arr 2, ...
First is an X array, then one or more Y arrays sharing the same
X array.
SAVE_CHART_EX
strXML = SAVE_CHART(dWidth, dHeight, bDateX,
strFileName, arrX_1, arrY_1, ...optional arrX_2, arrY_2...);
Similar to SAVE_CHART, except X arrays are different for each
dataset.
SAVE_CHART_INTRADAY
strXML = SAVE_CHART_INTRADAY(dWidth, dHeight,
strFileName, nNumOfDaysToShow, nMinutesInTheDay,
nStartTime, arrDate1, arrTime1, arr1, ...optional arrDate2,
arrTime2, arr2, ...);
Creates a PNG file, containing intraday (minutes) chart. The dates array
contains one date per each time:
01-Jan-2003, 10:00 ...
01-Jan-2003, 10:01 ...
Dates and times are converted to numbers using DATE_TO_REAL
and TIME_TO_REAL functions.
Creates the line chart and saves it on disk. Returns XML code that
can be used to create a web page containing this chart (or can be
ignored, it not required).
Parameters:
dWidth, dHeight - dimensions of a chart, pixels.
strFileName - file name to create
nNumOfDaysToShow - allows you to display only last few days,
which can be useful, if the chart is too long.
nMinutesInTheDay. Used for situations, when we only need part of the day. For example,
stock market closes at 5 pm, so we don't need to plot anything
between 17.00 and 24.00
nStartTime - same as with nMinutes in the day. For example,
the market may open in 9.00.
arrDate1, arrTime1, arrY1, ...optional arrDate2, arrTime2, arrY2, ...
- data to plot
strXML = SAVE_CHART_SMOOTH(arrColors, dWidth, dHeight, bDateX, strFileName,
// arrDate, arr_1, ...optional arr 2, ...);
Similar to SAVE_CHART, except, it draws the first line, using
colors from arrColors. It allows to create a chart, where
color changes smoothly - think of marking trends on the stock
price chart.
Colors are in RGB form.
SAVE_XML
SAVE_XML(strFullPath, "xml_file_name",
"xsl_file_name", "root", strXML);
As we are saving charts, using SAVE_CHART... functions,
we get XML strings, each can be used to show the chart at the Web
page. Then we can add these strings, to create a code for a web page,
that has more than one chart on it:
void Chart()
{
string strXML = "";
strXML = strXML + "<stocks>";
string strPath =
"c:\\S_Projects\\CortexPro\\data\\samples\\images\\";
string strStockName = "genz";
string strFullPath = strPath + strStockName + ".png";
string strNeuralPath = strPath + strStockName +
"_neural.png";
strXML = strXML + "<symbol>";
strXML = strXML + "<symbol>";
strXML = strXML + strStockName;
strXML = strXML + "</symbol>";
strXML = strXML + SAVE_CHART(400, 200, 1, strFullPath,
arrDate, arrClose);
strXML = strXML + SAVE_CHART(400, 200, 1, strNeuralPath,
arrDate, arrNN);
strXML = strXML + "</symbol>";
strXML = strXML + "</stocks>";
SAVE_XML(strPath, "chart_dayend", "chart_dayend",
"root", strXML);
SHOW_XML(strPath + "chart_dayend.xml");
}
(To get more information about XML, visit
Free online XML tutorial
Finally, to get a complete, working, XML file we need to add some
decorations to the string we created. That is what the SAVE_XML does.
Parameters:
strFullPath - path to the file to be created, without file name (see
the example above).
"xml_file_name" - name of the xml file to create.
"xsl_file_name" - name of the XSL file that XML file is using.
"root" - name of the root of the XML tree
strXML - the string we created.
END_DRAWING
END_DRAWING();
Finish the drawing session and show the result in Drawing Pane.
INTERNET
This DLL takes care of the Internet access via HTTP protocol.
OPEN_HTTP_SESSION
bResult = OPEN_HTTP_SESSION();
Opens HTTP session. Returns 1 if successfull, 0 otherwise.
GET_HTTP
bResult = GET_HTTP(strURL, strFileName);
Downloads a file from the Internet via HTTP protocol and saves it to
strFileName file.
bResult is 0 if failed, 1 if successful.
CLOSE_HTTP_SESSION
CLOSE_HTTP_SESSION();
Closes a previously opened HTTP session.
Neural Networks
SHOW_XML
SHOW_XML(strFullPath);
Opens a file (XML, HTML, text...) in Internet Explorer.
SHOW_XML_EX
strPageSource = SHOW_XML_EX(strFullPath);
Opens a file (XML, HTML, text...) in Internet Explorer,
and waits (i.e. pauses the script) until the page is
fully loaded.
Returns the HTML source for the target page.
RUN_JSCRIPT
RUN_JSCRIPT(strJScript, strArg1, ...);
If there is a Java Script function on the HTML page,
then you can run it, after the page is opened
(say, using a call to SHOW_XML).
The first argument refers to a function name,
optional second etc arguments contain arguments
to be passed to a function.
HTML_GET_ELEMENT
strValue = HTML_GET_ELEMENT
(strAttributeName, strId);
Retrieves a value for a given element of HTML form
(of HTML file, opened in IE window, by calling SHOW_XML).
The first element contains the element name (say, "value"),
the second argument contains element name or ID.
Example:
strValue = HTML_GET_ELEMENT("value", "given_name")
HTML_SET_ELEMENT
HTML_SET_ELEMENT(strValue, strAttributeName, strId);
Sets the value for a form element (of HTML file,
opened in IE window, by calling SHOW_XML).
The first argument refers to the value to be set,
the second contains the property name (say, "value"),
the third one contains form element's id or
name.
Example:
HTML_SET_ELEMENT("Hello", "value", "given_name");
HTML_CLICK
HTML_CLICK(strId, nTimeout = -1);
Simulates a click on an element (of HTML file,
opened in IE window, by calling SHOW_XML),
specified by strId (id or name).
Sometimes (usually, when Java Script in one frame
is trying to open web pages in the other, the
function hangs, which means, the "Working..."
dialog does not disappear. To fix the problem, you
can use the second argument, providing maximum
wait time, in milliseconds.
FTP_OPEN
FTP_OPEN(strSite, strLogin, strPassword,
nIsBinary, bIsPassive, nPort);
Opens FTP session.
Port is usually 21.
FTP_UPLOAD
FTP_UPLOAD(strFileName, strTargetDir);
Uploads a file from local disk to FTP location.
strFileName is the full path, a file with same
name will be created at destination.
If we want to copy file to the root, pass an empty string
("") as strTargetDir, otherwise the program will
try to create this dir and to copy file there.
FTP_CLOSE
FTP_CLOSE();
Terminates the FTP session.
OPEN_NN
hNN = OPEN_NN(strPath, bIsPathRelative);
Returns the handle of Cortex Neural Network, -1 if failed.
Handles of opened Neural Networks are used in a way, similar to
the use of file handles.
Parameters:
strPath - name of the NN file.
bIsRelative. Specifies if the strPath contains full path to the
file (0) or if this path is relative to the location of program's
EXE file. For example:
hNN = OPEN_NN("..\Cortex\data\jaco.nn", 1);
SAVE_NN
SAVE_NN(hNn, strPath);
Saves NN to disk file. Note, that this function ONLY
writes the NN description, not the information for
UI dialogs used by Cortex (like number of lines to
skip in data file etc). It means, that you will only
be able to open this file using script OPEN_NN, but not
from the Cortex UI.
For Cortex UI compatible NNs, use SAVE_NN_EX.
SAVE_NN_EX
SAVE_NN_EX(hNn, strFileName,
strLagDataFile, nSkipBefore, nSkipAfter,
strStartLine, strEndLine, bReverseArrays,
pnlistInputs, pstrlistInputs,
pnlistOutputs, pstrlistOutputs, nExtract,
bExtractRandom, dStopError, nStopEpoch, nLayer1,
nLayer2, nLayer3, nLayer4, nNumOfLayers,
nActivationType, dAdjustRange, bShowEpochs,
bShowEpochsSince, bShowLearningError, bShowTestingError,
strApplyDataFile, nApplySkipBefore, nApplySkipAfter,
strApplyStartLine, strApplyEndLine, bApplyReverseArrays,
plistApplyInputs, pstrlistApplyInputs, plistApplyOutputs,
pstrlistOutputs, strOutputDataFile, nOutputSkipBefore,
nOutputSkipAfter, strOutputStartLine, strOutputEndLine,
bOutputReverseArrays, plistOutputInputs,
pstrlistOutputInputs, plistOutputOutputs,
pstrlistOutputOutputs);
Save NN, associated with the handle (hNn) to the file
(strFileName). This function creates the file, that is
fully compatible with Cortex UI. If you only plan to use
the resulting NN from scripting language (no UI dialogs),
use SAVE_NN instead.
CLOSE_NN
CLOSE_NN(hNN)
Close the previously opened NN.
APPLY_NN
APPLY_NN(hNnHandle, nNumOfRecords, dExtendRange,
nNumOfInputArrays, arrInput_1, arrLags_1, ...,
nNumOfOutputArrays, arrOutput_1, ...);
Applies (see NN theory) the NN.
The following sequence of actions is performed:
For the list of inputs and list of lag numbers (5, 6...) generate the
lags, together with the input data, it will be fed to the network,
pattern by pattern.
Normalize the data WITHIN THE RANGE of first nNumOfRecords records.
The network was trained on this range, so whatever data we send to it,
it should be normalized to the same range.
For example, we have learning data: 1, 2, 3. We normalize the data
to the range 0 - 1, by dividing by 2 (3 - 1). Now, if we have the
testing data, 3.25, we will still divide it by 2.
The range can be changed, by providing the dExtendRange coefficient,
if we expect new data to be outside the range. Generally, whatever
parameters we used when teaching the NN, should be passed here.
Each lags array corresponds to an input array.
See sample_nn_01.tsc, sample_nn_02_tsc, sample_nn_03.tsc for a code,
that works with Neural Networks.
Parameters:
hNnHandle - handle of a previously opened NN.
nNumOfRecords - number of records in learning set. Used to normalize the
data. Usually, whatever number was used during teaching of a network,
should be passed here.
dExtendRange - If test data are outside the range of the learning data,
we can use this scaling coefficient. Usually, whatever number was
used during teaching of a network, should be passed here.
nNumOfInputArrays - number of inputs.
arrInput_1, arrLags_1, ... - Pairs of the input array and array of
lags to be applied to it.
nNumOfOutputArrays - number of outputs
arrOutput_1, ... - output arrays
TEST_NN
dError = TEST_NN(hNnHandle, nNumOfRecords,
dExtendRange, nNumOfInputArrays, arrInput_1, arrLag_1, ...,
nNumOfOutputArrays, arrOutput_1, ..., );
Tests the NN using provided data, returns the testing error.
dError calculated using testing data only (start at nNumOfRecords).
For example, we have an array of stock data, 10000 records long. The
learning was performed using 8000 records as a learning set, and 2000
records as a testing set. In order to estimate how good the resulting
NN is, we need to test it using the same 2000 records. We can do it,
by providing original arrays (10000 records) and specifying nNumOfRecords
equal 8000.
Parameters:
hNnHandle - handle of a previously opened NN.
nNumOfRecords - number of records in learning set. Used to normalize the
data. Usually, whatever number was used during teaching of a network,
should be passed here.
dExtendRange - If test data are outside the range of the learning data,
we can use this scaling coefficient. Usually, whatever number was
used during teaching of a network, should be passed here.
nNumOfInputArrays - number of inputs.
arrInput_1, arrLags_1, ... - Pairs of the input array and array of
lags to be applied to it.
nNumOfOutputArrays - number of outputs
arrOutput_1, ... - output arrays
PATTERN_NN
PATTERN_NN(hNnHandle, arrPattern, dExtendRange);
Run the network against a single pattern. Note that arrPattern contains
both inputs (first) and outputs (last), the NN will take inputs and
fill the outputs.
For example, if we have a stock price predicting network (1 output),
that expects 10 inputs, we need to fill arrPattern[0] through
arrPattern[9] with inputs. After we call PATTERN_NN, the arrPattern[10]
will contain the output of the NN.
OPEN_NN_FILE
OPEN_NN_FILE(strNnFileName, bIsPathRelative,
bStartLearning, bResumeScript, bReset);
Brings up a modal dialog, containing the NN parameters.
The first parameter is a path to the NN file, the second specifies,
if the path is relative (to the location of the Cortex executable),
or absolute.
If the bStartLearning parameter equals 0, the NN is waiting for the user
input (for example, the user can press the "Run" button), if it is 1,
the learning begins automatically.
The bResumeScript parameter (0 or 1) specifies, if the dialog should be
closed automatically and script execution to continue. For example, you
may set the "min. testing error" to some value, and when it is reached,
the dialog will close.
The bReset parameter specifies, if the NN should be reset to the
untrained state before the learning begins.
CREATE_LAG_FILE
CREATE_LAG_FILE(srcFileName, bIsPathRelative,
dstFileName, bIsPathRelative, nSkipBefore, nSkipAfter, strStartLine,
strEndLine, strSeparator, bReverseArrays, arrInputColumns,
arrInputColumnNames, arrLags, nNumOfInputColumns);
Creates lag (.lgg) file for a network to use.
Parameters:
srcFileName - name of the source file, for example, file containing
stock quotes
bIsPathRelative - is it a full path or if it is relative to the
location of the program's executable.
dstFileName - lag file to be created
bIsPathRelative - is it a full path or if it is relative to the
location of the program's executable.
nSkipBefore - number of lines to skip before the start line.
nSkipAfter - number of lines to skip after the start line.
strStartLine - the line in the source file, after which meaningfull
data begin.
strEndLine - the line, at which data loading should stop.
strSeparator - list of characters, used to separate data, for example,
",;"
bReverseArrays - we need newest data LAST. If the source file contains
newest data FIRST, we need to reverse arrays, after we have loaded
them.
arrInputColumns - array, containing numbers of input columns
arrInputColumnNames - array, containing names of input columns,
these names will be displayed in the corresponting list box of the
dialog.
arrLags - array, containing lags.
nNumOfInputColumns - number of input columns.
CREATE_NN
CREATE_NN(strNnFileName, bIsPathRelative,
strInputFile, bIsPathRelative, nSkipBefore, nSkipAfter,
strStartLine, strEndLine, bReverseArrays, arrInputColumns,
arrInputColumnNames, arrOutputColumns, arrOutputColumnNames,
nExtractRecords, dStopError, nStopEpoch, nNeuronsLayer1,
nNeuronsLayer2, nNeuronsLayer3, nNeuronsLayer4, nLayers,
nActivation, nAdjustRange, arrOutTabInputColumns,
arrOutTabInputColumnNames, arrOutTabOutputColumns,
arrOutTabOutputColumnNames);
Creates a new NN on disk, parameters are the same as in the
NN dialog tabs.
Parameters:
strNnFileName - name of the network file
bIsPathRelative - is this path absolute, or relative to the
location of the program's executable.
strInputFile - input (lag) file with data
bIsPathRelative - is this path absolute, or relative to the
location of the program's executable.
nSkipBefore - number of lines to skip before the start pattern.
nSkipAfter - number of lines to skip after the start pattern.
strStartLine - start pattern, meaningfull data begin after this line.
Empty string ("") if not used.
strEndLine - the line, at which the data loading should stop.
bReverseArrays - should data arrays be reversed. Make sure this
parameter is correct. For example, if we have already reversed arrays
during the call to CREATE_LAG_FILE, we don't want to reverse
them again.
arrInputColumns - numbers of input columns
arrInputColumnNames - names of input columns
arrOutputColumns - number of output columns
arrOutputColumnNames - names of output columns
nExtractRecords - record extraction method, see
Cortex tutorial for details.
dStopError - error at which to stop learning. 0 if not used.
nStopEpoch - epoch number to stop calculations. 0 if not used.
nNeuronsLayer1 - number of neurons in layer 1
nNeuronsLayer2 - number of neurons in layer 2
nNeuronsLayer3 - number of neurons in layer 3
nNeuronsLayer4 - number of neurons in layer 4
nLayers - number of layers
nActivation - type of the activation function
(0, 1... corresponds to selection in combo box).
nAdjustRange - scaling coefficient
arrOutTabInputColumns - numbers of input columns for "Output" tab
of the dialog.
arrOutTabInputColumnNames - names of input columns for "Output" tab.
arrOutTabOutputColumns - numbers of output columns for "Output" tab
of the dialog.
arrOutTabOutputColumnNames - names of output columns for "Output" tab.
GET_NN_WEIGHTS
array arrWeights = GET_NN_WEIGHTS(hNn, nLayer);
Returns an array, containing weights for all neurons of a given
layer.
Let's say, we are retrieving weights for the 1st layer, and there are
5 neurons in the previous, 0th layer. Then array elements 0 - 4
will contain weights for the 1st neuron, and so on.
GET_NN_DESCRIPTION
array arrDescription = GET_NN_DESCRIPTION(hNn);
Returns an array, containing description of a network.
Array elements:
0 - num of layers
1-4 - num. of neurons in the corresponding layer
5 - Activation type (0 - sigmoid, 1 - tangent)
MUTATION_NN
hNnCopy = SCRIPT_MUTATION_NN
(nNn, nCopyWeights, dRange, bDeterministic);
nCopyWeights = 0 - exact copy,
1 - uniformly distributed, 2 - Gauss distributed
dRange - range weights are distributed in,
centered at weight value of source NN
bDeterministic. Used only with nCOpyWeights not equal
zero. If 0, we vary weights randomly. If 1, ve vary
OUTPUTS randomly, which, in some situations (of genetic
learning) can speed up the learning signifficantly.
Shortly, if 1, we get a random DIRECTION we want the output
to change, and then vary inputs on a neuron in the same direction.
Creates a copy of the NN, whose handle is passed as a
first parameter. Weights of a resulting NN are distributed
around the corresponding weight of a source NN,
in the given range. Uniform and Gaussian distributions
are supported.
SELF ORGANIZING MAPS
CREATE_SOM
CREATE_SOM("..\Cortex\data\test.kh", bIsPathRelative,
nNumOfInputs, nIterations, dimX, DimY, nRedrawEvery);
Parameters 1 and 2 are path to a SOM to create (existing file will be
replaced without a warning) and type of a path - absolute (0) or
relative to Cortex's Bin folder.
nNumOfInputs - number of inputs SOM will expect.
nIterations - default number of iterations. It will be displayed in a
dialog box, when we call OPEN_SOM_DLG.
dimX, DimY - number of cells in a SOM grid
nRedrawEvery - as redrawing picture during SOM training is a slow operation, we
can choose to do it only once per few cycles.
OPEN_SOM_DLG
bOkCancel = OPEN_SOM_DLG("..\Cortex\data\jaco.kh", bIsPathRelative,
"..\Cortex\data\jaco.txt", bIsPathRelative,
strStartLine, nSkipBefore, strEndLine, arrColNumbers,
bStartLearning);
Brings up SOM training dialog.
Parameters 1 and 2 are path to a SOM description file and type of a path - absolute (0) or
relative to Cortex's Bin folder.
Parameters 3, 4 are for data file.
strStartLine, nSkipBefore, strEndLine are used same way as in TABLE_LOADER
arrColumns is an array with number of columns to load (for example, we may want to
skip the 0th column, that contains the row number.
bStartLearning, if set to 1, tels the dialog box to start learning immediately
and to continue the script after the specified number of epochs is reached.
OPEN_SOM
hSom = OPEN_SOM("..\Cortex\data\jaco.kh", bIsPathRelative);
Open SOM and return its handle.
Parameters 1 and 2 are path to a SOM description file and type of a path - absolute (0) or
relative to Cortex's Bin folder.
CLOSE_SOM
CLOSE_SOM(hSom);
Closes SOM when it is no longer needed.
PATTERN_SOM
arrResult = PATTERN_SOM(hNnHandle, arrPattern);
Takes SOM handle and an array of data, one element per expected input.
returns an array with the following elements: number of a winner neuron, red, green, blue colors,
X and Y coordinates of a winner neuron in a SOM's grid.
Note, that input is expected to be in 0 - 1 range.
GET_SOM_WEIGHTS
array arrWeights = GET_SOM_WEIGHTS(hNn);
Returns an array of weights for the SOM:
for each neuron N
for each weight W
This function can be used to export SOM information, for example, in order to recreate
the trained SOM using some other programming language.
GET_SOM_COLORS
// array arrColors = GET_SOM_COLORS(hSom);
Returns an array of m_dWin values that can be used to calculate BLUE colors for the SOM, one color per neuron. The way we handle
colors is explained in APPLY_SOM section.
GET_SOM_INFO
// array arrResult = GET_SOM_INFO(hSom);
Returns an array with SOM information.
arrResult[0] contains SOM size (number of neurons)
arrResult[1] contains number ofneurons in a row (SOM is a square, X by Y, rows by columns)
arrResult[2] contains number ofneurons in a column
GET_SOM_WINNERS
GET_SOM_WINNERS(hSom, strDataPath, bIsPathRelative,
strStartLine, nSkipBefore, strEndLine, arrColNumbers, nStep);
Loads the data from file same way TABLE_LOADER does, except
column numbers to load are provided as an array.
If you look at the C++ code sample in APPLY_SOM section, you
will see pNode->m_dWin and pNode->m_dMaxWin, first value is for the current neuron,
the second is the maximum value for all neurons. These values are calculated
during the SOM training, so technically, you do not have to call GET_SOM_WINNERS.
However, if you run an already trained network against set of patterns, you will
get different values, so it is better to do it this way.
If you run SOM against ALL patterns you have (37,000 patterns in FOREX history file,
for example), it will take very long time. Instead, you can specify a step (nStep variable),
for example, if nStep equals 100, we will only have 370 patterns, and result still will be
reliable.
APPLY_SOM
arrResult = APPLY_SOM(strSomFileName, bIsPathRelative,
strDataFileName, bIsDataPathRelative,
strStartLine, nSkipBefore, strEndLine, arrColNumbers);
Processes multiple input patterns. Takes input from the data file, loading it the same way
TBLE_LOADER does.
Returns an array of colors, 3 colors (red, green, blue) per each pattern and
its position in a grid. The following C++ code is used to calculate the color (though
you do not need to know it in order to use it):
void CortexSlang::GetSomColor(int& red, int& green, int& blue, CNode* pNode)
{
red = (int)((double)pNode->m_nCol / pNode->m_nCellsX * 128);
green = (int)((double)pNode->m_nRow / pNode->m_nCellsY * 128);
blue = (int)(255.0 * pNode->m_dWin / pNode->m_dMaxWin);
}
Here, the red and green colors are related to neuron's coordinates, and blue color
is based on the strength of its signal.
Note: the arrColors is 3 times the size of the data array, per each pattern,
we receive 3 numbers: r, g, b.
Trading
TRADE_INIT
TRADE_INIT("arrOpen, arrHigh, arrLow, arrClose,
&dAdviceMax, &dAdviceMin,
arrNnAdvice, arrNnBuyStopLoss, arrNnBuyTakeProfit,
arrNnSellStopLoss, arrNnSellTakeProfit,
arrNnLotSizes, dSpread, dMinStop, dMaxStop,
dLeverade,
&arrBalance, &arrBalanceBuy, &arrBalanceSell,
&dSuccessRatio, &dBuyToSellRatio,
&nWinTrades, &nLooseTrades
&nCurrentTradeType, &dMaxDrawDown,
&nNumberOfTrades, &nNumberOfTradesBuy,
&nNumberOfTradesSell,
&dStopLoss, &dTakeProfit");
Initialization for the later calls of TRADE and TRADE_CURRENT
functions. The function takes a string with names of parameters
to be passed to TRADE and TRADE_CURRENT and to be returned from
them. If a parameter is to be modified by the function, it
is prefixed (in this description only) with an & character.
For example, after we call TRADE(), it fills an array called
arrBalance with values. Therefore, this variable is
prefixed with &. On the other hand, arrOpen is only used to
pass values to the function, but it will not be modified
by it.
Note, that all variables must be created before passing their names
to the function.
Parameters:
arrOpen, arrHigh, arrLow, arrClose: price of a security
(like EURUSD) we trade
&dAdviceMax, &dAdviceMin: max. and min. values of the
signal, produced by NN (or of some other signal - whatever
we feed to the TRADE function). It is sometimes convenient
to know this range, so we return it.
arrNnAdvice, arrNnBuyStopLoss, arrNnBuyTakeProfit,
arrNnSellStopLoss, arrNnSellTakeProfit,
arrNnLotSizes: arrays (one value for each bar) with
trading signal, stop loss value, and so on. The TRADE function will
use them to make trade decisions and to calculate profits.
Note, that we used NN produced signals in this example, which,
strictly speaking, is not the only option we have. There are
some details to be aware of. Let's say, we used NN to generate
signals: one output for signal, one - for stop loss, one for
take profit... In this case, all signals will be confined to 0-1
range, however, the true range can be smaller. You need to
keep this in mind, when using the values.
First of all, the signal (arrNnAdvice) will be normalized, to
fill the 0-1 range. It means, that if your NN produced a signal in
0.3-0.4 range, it will be extended to 0-1, then 0-0.25 will be
considered a BUY signal, 0.25-0.5 - a CLOSE_SELL signal,
0.5-0.75 a CLOSE_BUY signal and 0.75-1 a SELL signal.
Second, here is the way we handle stop loss and take profit
values.
Stop loss: the range, returned by NN is 0-1, so we expect
values to be inside this interval. If not (say, you are
trading stocks), make sure you normalize your data
before passing them to TRADE or TRADE_CURRENT.
The value of a stop loss will be calculated, using the
following formula:
dStopLoss = arrNnStopLoss[nBar] * (dMaxStopLoss - dMinStopLoss)
+ dMinStopLoss;
Take profit: Unlike stop loss, take profit range is not
necessarily used. Therefore, we need to use it, if the signal is small,
and if the signal is large, it will not be used, because it is never
reached. To do it, we use
dTakeProfit = arrNnTakeProfit[nBar] * 10 * (dMaxStopLoss - dMinStopLoss)
+ dMinStopLoss;
It means, that we artifficially compressed the range 10 times.
dSpread, dMinStop, dMaxStop, dLeverade: common parameters used to
calculate profit.
&arrBalance, &arrBalanceBuy, &arrBalanceSell:
arrays, containing profit values, one per bar.
&dSuccessRatio, &dBuyToSellRatio,
&nWinTrades, &nLooseTrades:
see code sample. These are values
containing some statistics about trades we made.
&nCurrentTradeType: BUY = -2, CLOSE_SELL = -1,
CLOSE_BUY = 1, SELL = 2
&dMaxDrawDown, &nNumberOfTrades, &nNumberOfTradesBuy,
&nNumberOfTradesSell: additional statistics
&dStopLoss, &dTakeProfit: values returned by
TRADE_CURRENT, containing information about parameters of a
current (this bar) trade.
For example, this is how we call this function:
...
// arrays are initialized and filled with data first
array arrDate = CREATE_ARRAY(0);
array arrTime = CREATE_ARRAY(0);
array arrOpen = CREATE_ARRAY(0);
array arrHigh = CREATE_ARRAY(0);
array arrLow = CREATE_ARRAY(0);
array arrClose = CREATE_ARRAY(0);
TABLE_LOADER(strDataFileName, bIsPathRelative,
0, "", 0, "", 0, arrDate, 1, arrTime, 2, arrOpen, 3, arrHigh, 4, arrLow, 5, arrClose);
// Variables to be returned are created first
double dSuccessRatio;
double dBuySellRatio;
double dMaxDrawDown;
// Some values must be initialized, use this
// sample as a guide
double dMinStop = 0.0030; // 30 points
double dMaxStop = 0.0250; // 250 points
double nNumberOfTradesBuy = 0;
double nNumberOfTradesSell = 0;
double nNumberOfTrades = 0;
double nCurrentTradeType;
// Arrays to keep NN output
// filled (in this example) by ApplyNN, used in Test
array arrNnAdvice = CREATE_ARRAY(0);
array arrNnBuyStopLoss = CREATE_ARRAY(0);
array arrNnBuyTakeProfit = CREATE_ARRAY(0);
array arrNnSellStopLoss = CREATE_ARRAY(0);
array arrNnSellTakeProfit = CREATE_ARRAY(0);
array arrBalance = CREATE_ARRAY(0);
array arrBalanceBuy = CREATE_ARRAY(0);
array arrBalanceSell = CREATE_ARRAY(0);
double nWinTrades = 0;
double nLooseTrades = 0;
double dSpread = 0.0005;
double dAdviceMax;
double dAdviceMin;
array arrNnLotSizes = CREATE_ARRAY(0);
double dStopLoss;
double dTakeProfit;
TRADE_INIT("arrOpen, arrHigh, arrLow, arrClose,
dAdviceMax, dAdviceMin,
arrNnAdvice, arrNnBuyStopLoss, arrNnBuyTakeProfit,
arrNnSellStopLoss, arrNnSellTakeProfit,
arrNnLotSizes, dSpread, dMinStop, dMaxStop,
arrBalance, arrBalanceBuy, arrBalanceSell,
dSuccessRatio, dBuySellRatio,
nWinTrades, nLooseTrades
nCurrentTradeType, dMaxDrawDown,
nNumberOfTrades, nNumberOfTradesBuy, nNumberOfTradesSell,
dStopLoss, dTakeProfit");
TRADE
TRADE(nFirstRecordNum, nLastRecordNum,
nProcessTrades <1 - buy, 2 - sell, 3 - both>);
nFirstRecordNum - first bar
nLastRecordNum - last bar - trades are performed between
first and last bars, for example, if we have 10000 bars, and
pass 100, 1000, then we only trade between 100th and 1000th bars,
and ignore the rest.
nProcessTrades <1 - buy, 2 - sell, 3 - both>):
parameter, specifying, if we trade longs, shorts or both.
Return value (returned by changing the value of a corresponding
variable, passed to TRADE_INIT): CLOSE_BUY = 1, BUY = 2,
CLOSE_SELL = 4, SELL = 8
Note: it is not a signal, but info about what we did. Say,
we have BUY position, and we got a CLOSE_SELL signal. Return
value will be 0, as no action was taken.
Note: returned trade type for last bar in the range ONLY.
Say, 10 bars ago, BUY position opened. Then the return
value was -2 10 bars ago, but now (10 bars after the position
was opened) it is 0.
Few words about the reasons we use this function. In the
code sample you can find a similar
functionality, implemented as SLANG code. However, using
TRADE() function instead of coding it in SLANG is much
faster, you can double speed of your script this way.
The reason we moved initialization to TRADE_INIT is simple:
we only call it once, outside any cycles, and therefore, we
improve speed, by not passing all these parameters over and
over again.
TRADE_CURRENT
nTradeType = TRADE_CURRENT(nRecordNum);
Returns BUY = -2, CLOSE_SELL = -1, CLOSE_BUY = 1, SELL = 2.
These are values for current bar ONLY. Say, 10 bars ago,
BUY position opened. Then the return
value was -2 10 bars ago, but now (10 bars after the position
was opened) it is 0.
Timer
Cortex can call script one time after another, by timer. Select
Timer from the main menu, set timer interval and specify a script
file to run.
Script file, instead of "main" function, should contain two
functios: "init" and "timer""
void init()
{
double nTimerCounter = 1;
PRINT("%s\r\n", "Initializing");
}
void timer()
{
PRINT("%.0f\r\n", nTimerCounter);
nTimerCounter = nTimerCounter + 1;
}
init() is only called once, when the timer starts for the first
time. Timer is called every time (including the first time,
it is called after init()).
PLUGINS
#plugin
This is a preprocessor directive, that allows you to load your own (or third party)
functions from DLLs.
The detailed description on how to create Cortex plugins:
plugins tutorial
The source code for a sample plugin: \CortexPro\Plugins\Sample
The use (see CortexPro\data\samples\script\sample_plugin.tsc)
#plugin "sample.dll"
Here, sample.dll is a third party plugin. The path to plugins is relative to
the Bin directory.
To get fully enabled version of the Cortex Built-in Scripting engine, you need
to
register.
Free Stock trading Course
The course consists of five E.mails and covers
all essentials of Technical Analysis approach to Stock Trading.
Compare to $$$ that you will have to pay elsewhere. All you need to do is
to enter your name (nickname will do) and E.mail address in the form
below.
|