COBOS Small Basic
This is a short description of main performances and limitations of Small Basic language for working under COBOS. This language is generally usual Basic with some specific functions for supporting our hardware possibilities – and it will be developed in future...
Limitations
There limitations can be changed, but now we use:
· maximal amount of active numeric labels (internal/external tokenizer) 100/1000
· values for numeric labels 1-65535
· maximal nesting for FOR-NEXT 25
· maximal nesting for GOSUB-RETURN 25
· maximal nesting for recursive calculations (usually, amount of brackets) 10
· maximal amount of long variable names, including 1 & 2 D arrays 64
· maximal amount of string variables names (must be finished by $ sign) 64
· length of long & string variables names any
· amount of first recognizable chars in variable name 5
· maximal dimensions of long arrays 2
· default long variable size (i.e. value is between +/- 2147483647) 4 bytes
· default string variable size (can be changed by DIM statement) 256 bytes
· maximal amount of files/streams 5
· default size of transmitting and receiving buffers for files/streams 512 bytes
Notation
N numeric constant (decimal between +/- 2147483647 or hex up to &HFFFFFFFF)
V long variable or array element V(E [, E] )
F( ) long function, what returns long value
E long variable expression, result of arithmetic operations with N, V, and F( )
Q quoted string constant (must be less than 256 bytes)
S$ string variable (by default it uses Zero byte as terminator)
F$( ) string function, what returns string value
E$ string variable expression, result of concatenation with Q, S$, and F$( )
Operators by priority
( ) brackets
+/- unary plus/minus
^ power (exponentiation)
* / % multiplication, division, remainder of division
+ - addition or concatenation, subtraction
= > < equality or assignment, greater than, less than
Control statements
Any statements can follow each other with space, tab, line feed (LF) or new line (CRLF) delimiter, excepting comment, DIM and PRINT statements which have no a finite syntax length and must be finished only CRLF (i.e. it must be one or at least the last statement in current logical line). A logical line can contain some physical lines concatenated by “” symbol that must be the last character of physical line. Also you can use “:” symbol as traditional statement delimiter, but it is not necessary.
END end of program.
‘ blah-blah... comment, misses text after apostrophe sign until end of current line.
V=E or S$=E$ assignment, sets new value for long V or string S$ variable. If this is a new variable name, creates the new default long or string variable.
GOTO N unconditional jump to line with label N.
IF { E0 | E1 { = | > | < | >= | <= | > } E2 } THEN... [ ELSE... ]
one-line standard IF: if E0 is not equal 0 or logic condition is TRUE, continues after THEN, else (if E is equal 0 or logic condition is FALSE) goes to proper ELSE (if exist) or next line. If the nested IF-statement does not contain the same number of ELSE and THEN, each ELSE is matched with the closest unmatched THEN.
IF { E0 | E1 { = | > | < | >= | <= | > } E2 } THEN
...
[ELSE]
...
ENDIF multi-line structured IF: if E0 is not equal 0 or logic condition is TRUE, continues after THEN, else (if E is equal 0 or logic condition is FALSE) goes to proper ELSE (if exist) or to ENDIF. NB! For this IF, THEN and ELSE must be the last statement in current line.
FOR V=E1 TO E2
NEXT [V] loop, executes statements between FOR and NEXT (must be only one in each loop) and increments V by one in each loop from E1 until E2. You can change V inside loop to get any complicated loops.
GOSUB N
RETURN [N0] subroutine, executes statements between label N and RETURN with returning to position after GOSUB N or (if exist) to line with label N0.
DIM { V(N [,N] ) | S$(N) } [ , { V(N [,N] ) | S$(N) } ] ...
declares new 1 or 2 dimension long arrays or string variables with fixed length, reserves memory in heap, assigns null values to all array elements and string variables. Subscripts set maximal dimension by each direction, i.e. each direction has indexes in range [0...N]. For strings N gives the maximal size in memory (including finish Zero).
PRINT [ [ { S$ | Q | E } ] [ { , | ; } ] ] ...
prints list of arguments S$, Q, or E with delimiters. Delimiter “,” means printing the next argument from new 8-chars zone. Delimiter “;” means printing without spaces, immediately after the last value. If no finish delimiters, next printing begins from new line. *
INPUT [ { S0$ | Q } , ] { V | S$ }
prints S0$ or Q as prompt (if no, print “?” mark), waits for input from user, and sets new value for long V or string S$ variable. If this is a new variable name, creates the new default long or string variable. *
ON ERROR GOTO N
ON { TIMER{1|2|3|4} | CGI | UDP } GOSUB N
enables error handling or event trapping (for 4 timers, CGI request, or UDP receiving) to proper GOTO/GOSUB call. If N = 0, disables it. If error occurs, the error number and error line you can take from fixed variables _ERR_ and _ERL_.
TIMER E0, E sets interval E ms (0 disables) for E0 timer (1...4) of ON TIMER#... If E0 = 0, it sets “warm reboot timer”, i.e. Basic program will finish in any case when this interval will be exhausted. The current values of the increasing timers you can see in items of fixed array _TMR_(E0).
DELAY E delays program for E ms, excepting ON-calls. E = 0 means the endless delay (i.e. only ON-calls will work). DELAY will be automatically ignored in ON-call subroutine during ON-call event.
IOCTL E0, E sets E state (usually, 0 or 1) of E0 signal (HW dependant). **
SYSLOG E$ [, E] sends E$ (maximally 256 bytes) to SysLog (UDP, port 514) if fixed debug level variable _DBG_ > = E (optional, if absent, E = 0). If absent, by default, _DBG_ = 0 too. If fixed string variable _SIP_$ (SysLog IP) is absent or “x.x.x.255” SysLog and error messages are sent as broadcast, else to current _SIP_$ only. Hence, empty or wrong _SIP_$ will block SysLog and error messages.
LOCK E blocks (E=1) or unblocks (E=0) all parallel process (except Basic). NB! LOCK 1 without LOCK 0 will result in reboot after 1 sec. **
MIDSET S$, E0, E1, E
inserts E (as byte, word, or dword for E1=1, 2, or 4 respectively) into position E0 of string variable S$ (binary array). NB! Lower bytes of E are written in S$ before higher bytes (Intel format).
MIDCPY S$, E0, E1, S1$
inserts E1 bytes into position E0 of string variable S$ (binary array) from beginning of string variable S1$ (binary array). **
NB! This Basic cannot totally control all FOR-NEXT/GOSUB-RETURN stacks, therefore we do NOT recommend you to use GOTO for loop/subroutine abandoning.
NB! For string calculations this Basic uses temporary strings with size of maximal declared string variable (if it is more than default 256 byte you get the warning to SysLog). If you are sure that this string can not be used for calculations (usually it is a media buffer string), you can avoid changing a temporary string size by using “_M” prefix for this string name.
Functions
INKEY$ returns the last received chars from input buffer or empty string. *
LEN( E$ ) returns the E$ content length.
INSTR( E, E1$, E2$ ) returns the position E2$ in E1$ by searching from position E.
ISEQV( E1$, E2$ ) returns TRUE (-1) if E1$ is equivalent E2$, else returns FALSE (0).
MID$( E$, E1, E2 ) returns sub-string of E$ (i.e. E2 chars from position E1). It has a special sense if you use string variable (must be S$ instead E$) as byte array. In such case your “string” can have many zero bytes, and you can scan it byte-by-byte by using request MID$(S$, index, 1).
MIDGET( S$, E0, E1 )
extracts long variable (as byte, word, or dword for E1 = 1, 2, or 4 respectively) from position E0 of string variable S$ (binary array). NB! Order of bytes in the result (Intel format) is vice versa of S$. **
ASC( E$ ) returns ASCII code of first char in E$.
CHR$( E ) returns one-char string matching ASCII code E.
VAL( E$ ) returns long value representation of this E$ (converts E$ to V).
STR$( E ) returns string representation of this E (converts E to S$).
SPRINTF$( E$, E ) returns string representation of this E by using C-style format string E$. It can be useful for some specific purposes, for example, for hex presentation or getting own hardware address and serial number.
{L|U}CASE$( E$ ) returns lowercase or uppercase string.
SYSTIME returns time in milliseconds elapsed from the last HW reboot.
IOSTATE( E0 ) returns state of E0 signal (HW dependant). **
EXEC( S$ ) returns a result of HW dependant C-native functions. Usually it is used as Basic extension included in FW set for given HW. Common interface is like DOS command line, i.e. S$ is a string variable like "C-native_function_name/index [ <SP> par1 ] [ <SP> par2 ] ..." NB! S$ can be changed in EXEC to return indirectly results too. **
PING( E$, E ) returns a duration (in ms) of ping reply from E$ IP with maximal waiting for E ms, else (no reply or failure) returns 0. **
Logical expressions (bE) in Basic give result TRUE (-1) or FALSE (0). All logical functions below are bitwise (i.e. perform bit-by-bit calculation). If you use them only for logical expressions and logical constants (TRUE/FALSE), result will be only TRUE or FALSE as for usual logical operators. If you use long variable expressions (E) as argument, result will be long variable as for bitwise operators. NB! Just AND(bE) / OR(bE) / XOR(bE) with only one argument returns TRUE/FALSE for logical expression bE.
NOT( { E | bE } ) returns result of bitwise/logical NOT operation.
AND( { E | bE } [ , ... ] ) returns result of bitwise/logical AND operation.
OR( { E | bE } [ , ... ] ) returns result of bitwise/logical OR operation.
XOR( { E | bE } [ , ... ] ) returns result of bitwise/logical XOR operation.
SHL( E, E0 ) returns result of bitwise shift left for E by E0 bits.
SHR( E, E0 ) returns result of bitwise shift right for E by E0 bits.
For calendar calculations you can use the fixed Basic long variable _DTS_ (Date & Time in Seconds) that shows amount of seconds from 01.01.1970. If your HW has already set a value from external source it is a real Date & Time. Else _DTS_ will start from value 946684800 sec (i.e. from 01.01.2000). You can get yourself from an external source (for example, from some PC in your LAN) a real Date & Time and correct _DTS_ directly in your Basic code – firstly set _DTS_ = 0 and then assign to _DTS_ a new value. You can use also the following converting functions:
TIME$( E ) returns string “YYMMDDhhmmss” for E seconds from 01.01.1970. **
STIME( E$ ) returns seconds from 01.01.1970 for E$ string “YYMMDDhhmmss”. **
For relative calendar calculations (for example, for adding Date & Time in natural format or calculation of local time in your Time Zone) you can just convert your relative calendar string “YYMMDDhhmmss” to seconds and subtract 949276800 sec (i.e. “000000000000” string).
File and stream support
For file/stream E handler must be 0 – 4 (0 – 2 for TCP-based connections, 0 is usually used for media and has 4 kbyte receiving buffer).
OPEN S$ AS E opens S$ variable file/stream with E handler. Typical S$ is:
"TCP:0.0.0.0:port" – passive/listening TCP connection,
"TCP:x.x.x.x:port" – active TCP connection,
"UDP:0.0.0.0:port" – passive UDP receiver,
"COM:9600,N,8,1,NON:port" – serial port connection, **
"C_R://IP/Share/dir/file[@...]" – CIFS dir/file with READ access,
"C_W://IP/Share/dir/file[@...]" – CIFS dir/file with WRITE access,
"C_D://IP/Share/dir/file[@...]" – CIFS dir/file with DIR access,
NB! For "C_D:..." S$ is changed after OPEN to return first directory name.
[@...] = [@user:password] – optional CIFS authentication (else as GUEST).
"F_R:file" – parallel/serial (HW dependant) flash file reading,
"F_W:m_file" – writing from beginning into marked serial flash file,
"F_A:m_file" – appending from EOF into marked serial flash file,
NB! Marked file is any usual text file that has from first position the start marker line "<*>CRLF". To use it you must create firstly such template file and insert it in any COB file in any WEB page. Size of this file will be used as maximal size for writing. Current EOF marker (Zero byte terminator) will be inserted automatically during write/append operations. With reading the start marker line will be automatically omitted and the file will be read till current EOF marker or till end of template file. Using this feature allows you, for example, to change your HTML/DHTML files on-the-fly during run-time of your program or to save periodically your LOG/DATA files.
"BPH:" – special Kaba Benzing BPA protocol to host (only writing),
"STP:offset" – Setup “file” (256 b from offset), only one at a time.
CLOSE E closes file/stream with E handler and (for 0) flushes media buffer. For Setup “file” saves new Setup in EEPROM, if WRITE was used.