SnowCron

.COM


SnowCron.com








Learn Touch Typing

SLANG: Built-in Scripting Language

Programmer's reference

Contents




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);


String Operations

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");
}

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.




CHARTS Implemented as Plug-In

This is a new approach to charting, that will replace the old built-in charting functions with time. To implement it, we used SLANG's Plug-ins. This is also an example of a third-party's software working with Cortex.

For usage hints, see an example below.

Currently, only a pie chart is supported.

void CHART_SET_TYPE(double nChartType);

Sets the type of a chart, currently, only 0 (pie chart) is supported.

CHART_ADD_SERIES(array arr);

Add data series to the chart. For a pie chart, a single array of doubles is used.

CHART_RESET()

Clears the charting tool, to make it ready for a next, different chart.

CHART_SAVE_PIE(strFileName, nWidth, nHeight);

Creates a .PNG file on disk with a Pie Chart. Pie chart is always based on the first array passed to CHART_ADD_SERIES()

CHART_ADD_LEGENDS(arr_s);

Same way you add data arrays to a chart, you can add an array of legends for this data.

CHART_LEGENDS_STYLE_PIE(nType);

Affects the way legends are displayed. It can be:

0: no labels displayed
1: numbers od data elements are displayed, like 1., 2. ...
2: text labels, ones passed to CHART_ADD_LEGEND(), are displayed
4: actual values for data are displayed, those passed to CHART_ADD_SERIES
8: percents are displayed.

It is also possible to combine flags, to display more than one type of legnds: CHART_LEGENDS_STYLE_PIE(1+2+4+8);

The following example displays all legend info:

Let's take a look at code that produced this image (data\samplas\sample_plugin_chart.tsc).

// First, we need to include a plugin for charting.
#plugin "CortexChartsPlugin.dll"

void main()
{
	// Set a chart type to Pie Chart
	CHART_SET_TYPE(0);

	// ---
	
	// Create and fill and array of data to plot

	array arrData = CREATE_ARRAY(0);
	arrData[0] = 15;
	arrData[1] = 1;
	arrData[2] = 1;
	arrData[3] = 1;
	arrData[4] = 1;
	arrData[5] = 1;
	arrData[6] = 1;
	arrData[7] = 1;
	arrData[8] = 4;
	arrData[9] = 0.5;
	arrData[10] = 2;
	arrData[11] = 4;

	// Register the data array with charting tool

	CHART_ADD_SERIES(arrData);
	
	// ---

	Create and fill an array with legends to use

	array_s arrLegends = CREATE_ARRAY_S(0);
	arrLegends[0] = "Food";
	arrLegends[1] = "Gas";
	arrLegends[2] = "Rent";
	arrLegends[3] = "Food and services";
	arrLegends[4] = "Gas";
	arrLegends[5] = "Rent";
	arrLegends[6] = "Food";
	arrLegends[7] = "Gas and services";
	arrLegends[8] = "Rent";
	arrLegends[9] = "Food";
	arrLegends[10] = "Gas";
	arrLegends[11] = "Rent and services";
		
	// Register the legends array with charting tool

	CHART_ADD_LEGENDS(arrLegends);

	// Set a style for legenas. It will look like Number. Text; Value; Percent (1. Gas; 4; 5%)

	CHART_LEGENDS_STYLE_PIE(8 + 4 + 2 + 1);
		
	// ---

	/ Create an image file on disk. 

	CHART_SAVE_PIE("H:\\S_Projects\\CortexPro\\data\\samples\\images\\pie.png", 800, 600);

	// Not mandatory here, use if you are not going to draw more charts
	CHART_RESET();
}


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.







  • (C) snowcron.com, all rights reserved

    Please read the disclaimer