It is possible to force INKEY$ to behave exactly like in ANSI BASIC by specifying the option -I at the compile time. In that case there is no loop and INKEY$ simply reads the first character from the keyboard buffer and exits immediately.

According to QB, when a key is pressed, INKEY$ returns a string which corresponds to the key. Most keys return a string of length one (single character). Extended keys are represented with a string of length 2. Key codes of ordinary keys are emulated by QB2C exactly as they are in QuickBASIC whereas codes of extended keys are (hopefully insignificantly) different. The only difference is that the first code is 1 instead of 0.

Here is the list of extended keys and their ASCII codes:

  Key   QB2C   QBASIC     Key     QB2C   QBASIC     Key          QB2C  QBASIC  
  F1    1 59   0 59       F9      1 67   0 67       End          1 79  0 79
  F2    1 60   0 60       F10     1 68   0 68       Page Down    1 81  0 81
  F3    1 61   0 61       F11     1 133  0 133      Cursor Up    1 72  0 72
  F4    1 62   0 62       F12     1 134  0 134      Cursor Left  1 75  0 75
  F5    1 63   0 63       Insert  1 82   0 82       Cursor Down  1 80  0 80
  F6    1 64   0 64       Home    1 71   0 71       Cursor Right 1 77  0 77
  F7    1 65   0 65       Page Up 1 73   0 73
  F8    1 66   0 66       Delete  1 83   0 83

This is not all ! As different implementations of screen codes in UNIX are not unique, it is necessary to 'calibrate' your keyboard in some way. If you are going to use INKEY$ function you should definitely do this by running program calib. The program will ask you to press extended keys listed above and will create the file .kbcalib in your $HOME directory.

Constant numbers may be represented with or without leading and/or trailing zeros, and in exponential notation. For example the following are equivalent:
0.001
.001
000.001
0.001000
Exponential notation allows more convenient and compact writing of very large or very small numbers:
1000000000 is equivalent to: 1E9, 1e9, 1E+9 or 1e+9 .
.000000001 is equivalent to: 1E-9 or 1e-9 .

Numbers, whether in ordinary or in exponential notation *must be written without any spaces*. For example, the following is invalid:
a = 1 000 000
b = 1E 9
etc.

When associated to a variable, constant numbers is always automatically converted to the variable type. For example:
a = 1
or
a = 1
is equivalent to:
a = ((float) 1)
in C.

Like in C (but unlike BASIC) one can write constant numbers both in decimal and hexadecimal notation. Hexadecimal numbers are in the form of "0x" followed immediately with a hex number of appropriate length. For example:

  hex           decimal
  0xf           15
  0xa0          160
  0x378         888
  0x3e8         1000

See also: CONST, HEX$

At compilation time every "constname" is replaced by appropriate "expression". An expression consists of literals (such as 1.0), other constants, or any of the arithmetic and logical operators except exponentiation (^). You may also use a single literal string such as "Error on input". You cannot use string concatenation, variables, user-defined functions, or intrinsic functions like SIN or CHR$ in expressions assigned to constants.

Example:

  CONST ONE = 1, TWO = ONE + ONE

The following example produces an error because the constant ONE is not defined before it is used to define TWO (constants are defined from left to right and from up to down):

  CONST TWO = ONE + ONE, ONE = 1

In a program, nothing can be assigned to a constant and no variable can have the same name. Length of the name of a constant is limited to 80 characters.

A special case of CONST usage is to redefine the default string length.

Example:

  CONST LMAX=32000

defines the default length of string variables to 32000 characters. Minimum value of LMAX is 1, maximum is 1048576 (1024x1024 bytes). If you attempt to set LMAX less than the minumum or more than the maximum it will be redefined to fit this range.

See also: -L option

Names of variables can be composed of the alphanumeric characters and the underscore character, more precisely of: 'a' to 'z', 'A' to 'Z', '0' to '9' and '_'. Variable name may not coincide with any name of the BASIC library or user-defined function or subroutine.

Variable name may not coincide an array name. For example, if you defined the array 'DIM a(100)' you may not use variable name 'a', but you still may use variable or array name a#, a%, a&, a? and a$.

Variables' precision and length in memory.

Type of a variable is defined by its name, more precisely by a suffix of a variable name. A space in memory occupied by
a numeric variable of some type is somewhat dependent of a machine and C compiler in question. For Linux and gcc compiler for Intel X86 processors (and rather generally) the situation is summarized in the following table:

Type	range	length	suffix	example
integer	-2 147 483 648	4 bytes	%	a%
	+2,147,483,647
long integer	-2 147 483 648	4 bytes+	&	a#
	+2,147,483,647
long long int	-18446744073709551616	8 bytes	&&	a&&
	+18446744073709551615
short integer	-32768 to 32767	2 bytes	_%	a_%
byte	0 to 255	1 byte	?	a?
float	(see below)	4 bytes	none	a
double	(see below)	8 bytes	#	a#
char (string)		1024 bytes*	$	a$

The same suffix convention applies also to array names and return values of functions (see DIM and FUNCTION).

+ On some machines long integer may be 8 bytes long.
* This default can be changed via -L option or CONST statement.

PREPROCESSING

The bcpp preprocessor allows for conditional compilation by the use of "REM #if defined label", "REM #else" and "REM #endif" preprocessor directives similar to the C language syntax.
An example program (sample.bas):

REM #if defined Linux
    SCREEN (100,100), 300, 200
REM #endif
REM #if defined DOS
    SCREEN 12
REM #endif
    LINE (10,10)-(100,100), 1
END

It is necessary that preprocessor directives start at the beginning of the line and follow exact spacings as in this example. At preprocessor level, lines enclosed in the label which is not defined are skipped and do not appear in the .bcp file.

To obtain a Linux source, type:

  bcpp -define Linux sample

and to obtain a DOS source type:

  bcpp -define DOS sample

In both cases a file named 'sample.bcp' is the desired BASIC source. You can compile the sample program for Linux this way:

  bcc sample -define Linux

If either Linux or DOS labels must be used, the above example could as well be written as:

REM #if defined DOS
    SCREEN 12
REM #else
    SCREEN (100,100), 300, 200
REM #endif
    LINE (10,10)-(100,100), 1
END

In this example, by specifying no label (bcc sample) one obtains the Linux source whereas specifying the "DOS" label (bcc sample -define DOS) one obtains the DOS source.

Preprocessor statement that literally includes a specified QB2C file into the place where it appears.

Syntax:

  REM #include filename

where filename is a name of a single file containing QB2C code which is to be included at this place.
It is necessary that preprocessor directive starts at the beginning of the line and follow exact spacings as in this example.

IMPORTANT NOTICE:
There may be any number of #include statements in the code. However, only the first layer of directives will be unfolded. That is if there are any #include directives in the included file they will be ignored unless they are C code.

See also: #cinclude

Preprocessor statement that literally includes a specified C source into the place where it appears.

Syntax:

  REM #cinclude filename

where filename is a name of a single file containing C code which is to be included at this place. This functions as follows: each line of text in the 'filename' is prepended with "C " and written at this place in the order of appearance.

See also: #include

Supported logical operators are: NOT, AND, OR, XOR. By default, they operate as logical operators and not as bitwise operators.

Bitwise operators are: ~ (bitwise complement), & (bitwise and), | (bitwise or), @ (bitwise xor) >> (right byte translation, division by 2^n) and << (left byte translation, multiplication by 2^n).

For more details, refer to a manual section for every operator.

LIMITS to QB2C NUMBERS, STRINGS AND NAMES

  What                                 Maximum               Minimum
  variable or function name length     40 characters         1 character
  string length                        1024  characters      0 characters
  integers                             32767                -32768
  long integers                        2 147 483 647        -2 147 483 648
  float numbers (positive)             3.402823 E+38         1.401298 E-45
  float numbers (negative)            -1.401298 E-45        -3.402823 E+38
  long float    (positive)
                          Maximum:     1.797693134862315 D+308
                          Minimum:     4.940656458412465 D-324
  long float    (negative)
                          Maximum:    -4.940656458412465 D-324
                          Minimum:    -1.797693134862315 D+308

Limit to a line length in QB2C is 1023 characters (i.e 1024 including newline character). This can be changed by specifying CONST LMAX to a different value, or by use of the -L option to qb2c at compile time. Possible value is between 1 and 1048576.

SPECIAL NAMES

Special names that may be defined in some C languages are a tricky question. It is important to avoid using any names which may be defined in include files or you will get compile errors or unexpected program behavior. Following "usual" names are defined in the math.h header file and you should definitely avoid their use as variable or function names:

name	meaning
PI	Ludolf's number 3.14...
y0	Bessel function Y(0,x)
y1	Bessel function Y(1,x)
yn	Bessel function Y(n,x)
j0	Bessel function J(0,x)
j1	Bessel function J(1,x)
jn	Bessel function J(n,x)
asin	Inverse sine function
acos	Inverse cosine function

File math.h is automatically included by QB2C if there is a need. Be careful.

CONTROLLING IMPLICITE VARIABLE TYPES

A few statements to controll implicite variable types according to a first letter in their names, are supported in the QB2C. These are:

Syntax:

  DEFINT letterrange [,letterrange]...
  DEFDBL letterrange [,letterrange]...
  DEFSTR letterrange [,letterrange]...

parameter	meaning
letterrange	letterrange has the form: letter1[-letter2]
	where letter1 and letter2 are any of the uppercase or
	lowercase letters of the alphabet. The case of the letters
	in letterrange is not significant. If more than one
	letters appear in the letter1 or letter2 only the leftmost
	character counts.

Names beginning with the letters in
letterrange have the type specified by the last three letters of the statement: integer (INT), double precision (DBL), or string (STR).

Example:

  ...
  DEFSTR A-e
  ...

All variables starting with letters A-E will be treated as strings, in addition to the normal implicite rules (for example z$ will also be a string).

In collision with default implicite names, the default ones are stronger, for example A% will nevertgeless be an integer, not a string.

Examlpe:

All of the following statements are equivalent:

 DEFINT A-e
 DEFINT a-E
 DEFINT auxc-ebic

This is equivalent of: FUNCTION name(parameterlist)
name = expression
END FUNCTION

See also: FUNCTION

Syntax:

  FUNCTION name(parameterlist)
      [statements]
    name = expression
      [statements]
  END FUNCTION

Part	Description
name	The name of the function. FUNCTION names follow the
	same rules as QB2C BASIC variable names and can include
	a type-declaration character (%, &, #, _%, ? or $).
	The type of the name determines the type of
	value the function returns. For example, to create a
	function that returns a string, you would include a
	dollar sign in the name or give it a name defined as
	a string name by a DEFSTR statement.
parameterlist	The list of variables, separated by commas, passed
	to the FUNCTION. The parameters other than arrays
	are passed by value, so any change to a parameter's
	value inside the function has no effect to its value
	in the calling program. Arrays, however are passed
	as pointers, therefore any change to an array
	value in the subprogram also changes its value in
	the calling program. See below for a complete
	description of the syntax. It is only possible to
	pass 1-dimensional string arrays whose element length
	is equal to the default (LMAX).
expression	The return value of the function. Depending on the
	type of function expression may be numeric or string.
	If no value is assigned to the FUNCTION name, the
	FUNCTION returns a default value: a numeric
	function returns a value of zero, and a string
	function returns the null string ("").

It is not a good idea that a QB2C FUNCTION calls itself, because because all implicitly declared variables are static.

If you define any SUBroutine or FUNCTION, then the main program must end up with the statement END.

EXAMPLE:

  DIM f(100)
  .....
  z = 0
  x = Integral(dx, f(), n%)
  .....
  END

  FUNCTION Integral(dx, f(), max%)
   s = 0
   FOR i% = 0 TO max%
    s = s + f(i%)
   NEXT
   func = dx * (s - (f(0) + f(max%)) / 2)
  END FUNCTION

See also: DEF, SUB

Syntax:

  SUB name[(parameterlist)] [STATIC]
    [statements]
  [EXIT SUB]
    [statements]
  END SUB

Part	Description
name	A subroutine name up to 40 characters long. This name
	cannot appear in any other FUNCTION or SUB
	statement in the same program or the user library.
parameterlist	Contains the names of simple variables and arrays
	passed to the subprogram when the SUB is invoked.
	Each name is separated from the preceding name by
	a comma. Note that these variables and arrays are
	passed by reference, so any change to an argument's
	value in the subprogram also changes its value in
	the calling program. See below for a complete
	description of the syntax. It is only possible to
	pass 1-dimensional string arrays whose element length
	is equal to the default (LMAX).

A subprogram is a separate procedure, like a FUNCTION. However, unlike a FUNCTION, a SUB cannot be used in an expression. SUB is uniquely executed by a CALL statement.

Subroutine name has no type because a subroutine returns nothing itself.

SUB and END SUB mark the beginning and end of a subprogram. You may also use the optional EXIT SUB statement to exit a subprogram.

If you define any SUBroutine or FUNCTION, then the main program must end up with the statement END.

EXAMPLE:

  DIM b(100)
  ...
  a = ...
  c% = ...
  CALL Sub(a, b(), c%)
  ...
  END

  SUB Sub(z, bc(), c%) 
   z = bc(0) + bc(10) - c%
  END SUB

In this example, a subroutine Sub is called with three input/output parameters. Note that the local parameters names may differ from the names used in the calling statement. What is actually passed to the subroutine are the addresses in memory of the variables "a", "c%" and of the first array element "b(0)". The subroutine Sub identifies the array "bc" with "b". It is important to understand that the array "bc" actually does not exist as a separate location in memory. It is the same array "b" just it is referred to by another name. That is "bc(0)" is actually "b(0)", "bc(1)" is actually "b(1)" etc. The same goes for the simple variables "s" and "c%".

Therefore, if a value of a parameter is changed within a subroutine, the change affects the parameter's value in the calling program.

When passing an array to a subroutine, it is possible to make a shift in index. For example in the syntax:

  ....
  CALL Sub(a, b(10), c%)
  ....

  SUB Sub(z, bc(), c%) 
   z = bc(0) + bc(10) - c%
  END SUB

the subroutine Sub sets the address of the local array element bc(0) to the address of b(10) which means that "b(0)" becomes "b(10)", "bc(1)" becomes "b(11)", etc.
This syntax should be used with care: one should keep in mind that the subroutine expects an array rather than just an array element, as is suggested by the calling statement.

See also: CALL, FUNCTION

If the COMMAND$ has been used anywhere in the main program, then an array of strings argv$() and integer number n_arg% are defined automatically by the QB2C compiler. The argv$() contains the list of arguments to the program which is being executed, while n_arg% says how many arguments there are. For example, your executable has the name "myprog" and is called with a three arguments:

  myprog -a 3 abc

In this case n_arg% = 3, and argv$(1) equals "-a", argv$(2) equals "3" and argv$(3) equals "abc".

If there is no arguments n_arg% is equal to zero. The argv$(0) contains the name with which the program has been run, in our example it would contain string "myprog".

Example:

  ...
  c$ = COMMAND$
  ...

An array of strings called the `environment' is made
available to your program when it is run.

ENVIRON$ function returns the environment string associated with the name name$ or an empty string if the name cannot be found.
The argument name$ must be a string variable or a string constant.

Common examples of environment names in UNIX are:

USER	The name of the logged-in user (used by some BSD-
	derived programs).
LOGNAME	The name of the logged-in user (used by some Sys-
	tem-V derived programs and Linux).
HOME	A user's login directory
PATH	The sequence of directory prefixes that shell and
	many other programs apply in searching for a file
	known by an incomplete path name. The prefixes are
	separated by `:'
PWD	The current working directory. Set by some shells.
SHELL	The file name of the user's login shell.
TERM	The terminal type for which output is to be pre-
	pared.
OSTYPE	Short name of the operating system, such as "Linux".

Example:

  pwd$ = ENVIRON$("PWD")

returns the full path of the current directory on most UNIX systems.

See also: ENVIRON

ENVIRON statement sets the system environment string variable.

stringexpression must have the form:

  name$ = value$

where name$ is the name of the environment variable and value$ is a string to be associated with the variable. Everything to the left of the equal sign or space is assumed to be a variable name, and everything to the right its new value which replaces the old one.

For example:

  ENVIRON "DISPLAY" = "darkstar.linux.ch:0.0" 

associates the environment variable DISPLAY to string "darkstar.linux.ch:0.0". The same could be, for example, obtained with:

  disp$ = "DISPLAY": ENVIRON disp$ = "darkstar.linux.ch:0.0"

If the environment variable has not previously existed in the environment string table, it is appended to the end of the table. If the variable exists in the table when the ENVIRON statement is executed, it is deleted and the new variable is appended to the end of the table.

See also: ENVIRON$

STRING PROCESSING FUNCTIONS

Function that returns a string of length n% whose characters all have given asc% ASCII code.

See also: SPACE$

SPACE$ is a string processing function that returns a string of spaces of length n%.

See also: STRING$

LEFT$ is a string processing function that returns a string consisting of the leftmost n% characters of the string a$.

The argument n% is a numeric expression in the range 0-1024 indicating how many characters are to be returned. Natural limit to the number n% is 1024 since in QB2C the default storage for strings amounts 1024 characters. However, this can be overridden by the option -L at translation time (see the OPTIONS section of the manual).

If n% is greater than the number of characters in stringexpression, the entire string is returned. To find the number of characters in a$ use LEN(a$).

If n% is zero, the null string (length zero) is returned.

See also: RIGHT$, MID$, CONST

RIGHT$ is a string processing function that returns a string consisting of the rightmost n% characters of the string a$.

The argument n% is a numeric expression in the range 0-1024 indicating how many characters are to be returned. Natural limit to the number n% is 1024 since in QB2C the default storage for strings amounts 1024 characters. However, this can be overridden by the option -L at translation time (see the OPTIONS section of the manual).

If n% is greater than the number of characters in stringexpression, the entire string is returned. To find the number of characters in a$ use LEN(a$).

If n% is zero, the null string (length zero) is returned.

See also: LEFT$, MID$, CONST

Syntax 1 (function):
MID$(a$, start%[, length%])

MID$ is a string-processing function that returns a substring of a string.

This function returns a string containing length% characters starting from start%-th character in the string a$.

If the third argument (length) is omitted or start%+length% exceeds the length of the string a$, then function returns a string which starts at start%-th and goes to the end of the a$.

Syntax 2 (statement):
MID$(a$, start%[, length%]) = stringexpression

MID$ is a string processing statement that replaces a portion of a string variable with another string.

Argument	Description
stringvariable	The string variable being modified.
start	A numeric expression giving the position in
	stringvariable where the replacement starts.
length	The length of the string being replaced. The
	length is a numeric expression.
stringexpression	The string expression that replaces part of the
	stringvariable.

The arguments start and length are integer expressions. The argument stringvariable is a string variable, but stringexpression can be a string variable, string constant, or string expression.

The optional length refers to the number of characters from the argument stringexpression that are used in the replacement. If length is omitted, all of stringexpression is used. However, regardless of whether length is omitted or included, the replacement of characters never goes beyond the original length of stringvariable.

NOTE:
Natural limit to start% and length%, both for function and statement, is 1024 since in QB2C the default storage for strings amounts 1024 characters. However, this can be overridden by the option -L at translation time (see the OPTIONS section of the manual).

Related topics: LEFT$, RIGHT$, INSTR, CONST

The arguments string1 and string2 can be string variables
or string constants but not string expressions.

The value returned by INSTR depends on the following conditions:

Condition	Value Returned
string2$ found in string1$	The position at which the string2$ is found
start% > length of string1$	0
string1$ is null string	0
string2$ is null string	start (if given); otherwise, 1

Related topics: MID$

Syntax:

  variable$ = LCASE$(stringexpression)

stringexpression may be a string constant, string variable, or string expression. It may refer to a fixed- or variable-length string.

See also: UCASE$

Syntax:

  variable$ = UCASE$(stringexpression)

stringexpression may be a string constant, string variable, or string expression. It may refer to a fixed-length or variable-length string.

See also: LCASE$

Syntax:

  a$ = LTRIM$(z$)
  b$ = LTRIM$(z$, " ")

See also: RTRIM$, TRIM$

Syntax:

  a$ = RTRIM$(z$)
  b$ = RTRIM$(z$, " ")

See also: LTRIM$, TRIM$

Syntax:

  u$ = TRIM$(z$)
  u$ = TRIM$(z$, white$)

See also: LTRIM$, RTRIM$

Argument	Description
w$	- a string to be scanned through;
n%	- number of tokens found in w$;
tok$()	- array to which tokens are copied;
sep$	- a string of character separators according to which a$
	is separated into tokens;

TOKENS is a string processing function. It scans string w$ for tokens delimited by any of the characters found in the sep$ and save the n% resulting tokens in tok$(i) 1 <= i <= n%. Separators ',' and '\t' (comma and tab) are special: two adjacent will give an empty token. For example: "a,,b" gives 3 tokens: "a", "", "b". Parts of the string w$ placed within double quotes or in brackets () are not tokenized.

Example:

  DIM tok$(10)
  ....
  w$ = " +abCd  ef, ,&,(b+c)d"
  TOKENS w$, n%, tok$(), " +"
  FOR i% = 1 TO n%
   PRINT i%, ":"; tok$(i%); ":"
  NEXT

The result is:

 1             :abCd:
 2             :ef:
 3             ::
 4             :&:
 5             :(b+c)d:

See also: SSCAN

ASC is a string processing function that returns a numeric value that is the ASCII code of the first character in a string.

See also: CHR$

CHR$ is a string processing function that returns a one-character string whose ASCII code is the argument.

CHR$ is commonly used to send a special character to the file or printer. For example, the "form feed" character CHR$(12)
tells the printer or some editors editor to skip to a new page.

CHR$ can also be used to include a double quote (") in a string:

  a$ = CHR$(34) + "Quoted string" + CHR$(34)

This line adds a double-quote character to the beginning and the end of the string.

See also: ASC

LEN returns the number of characters in the string a$.

STR$ is a string function that returns a string representation of the value of a numeric expression.
If numeric_expression is positive, the string returned by the STR$ function contains a leading blank.

See also: ASTR$, VAL

ASTR$ is a string function that returns a string representation of the value of a numeric expression.
If numeric_expression is positive, the string returned by the ASTR$ function does not contain a leading blank, ie. the first character is either '-' or a digit.

See also: STR$, VAL

VAL is a string-processing function that returns the numeric value of a string of digits. It returns a value of the maximum leftmost characters recognizable as a number. Return value is of the type double. Examples:

  x = VAL("123.456")        x = 123.456
  x = VAL(" 12A13B")        x = 12
  x = VAL("R34.56")         x = 0
  x = VAL(-1.23.45.67")     x = -1.23

See also: STR$, HEXVAL&, OCTVAL&

HEXVAL& is a string-processing function that returns the numeric value of a hexadecimal string of digits. The argument a$ is a string representing a nonnegative integer in the hexadecimal notation. Character-valued digits (A-F) may be in any case (upper, lower or mixed).
HEXVAL& acts as the inverse of the HEX$ function.
Return value is of the type long integer.
Example:

  x = HEXVAL&("a0ef")       x = 41199

See also: HEX$

OCTVAL& is a string-processing function that returns the numeric value of a hexadecimal string of digits. The argument a$ is a string representing a nonnegative integer in the octal notation.
OCTVAL& acts as the inverse of the OCT$ function.
Return value is of the type long integer.
Example:

  x = OCTVAL&("015")       x = 13

See also: OCT$

HEX$ is a string function that returns a string that represents the hexadecimal value of the decimal argument expression.

The argument expression is a numeric expression or a number. It is converted to a long integer by truncating a non-integer part before the HEX$ function evaluates it. Leading zeros are omitted.

A string consists of only numbers and upper case letters. You may convert to lower case using LCASE$ function.

See also: OCT$

OCT$ is a string function that returns a string that represents the octal value of the decimal argument expression.

The argument expression is a numeric expression or a number. It is converted to a long integer by truncating a non-integer part before the OCT$ function evaluates it. Leading zeros are omitted.

A string consists of only numbers and upper case letters. You may convert to lower case using LCASE$ function.

See also: HEX$

SIN is a math function that returns the sine of an angle given in radians. Argument can be of any type. Value of the SIN is calculated to a double precision. Return type is the "signed double precision", which corresponds to a variable with suffix '#'.

See also: COS, TAN, ATN

COS is a math function that returns the cosine of an angle given in radians. Argument can be of any type. Value of the COS is calculated to a double precision. Return type is the "signed double precision", which corresponds to a variable with suffix '#'.

See also: SIN, TAN, ATN

TAN is a math function that returns the tangent of an angle given in radians. Argument can be of any type. Value of the TAN is calculated to a double precision. Return type is the "signed double precision", which corresponds to a variable with suffix '#'.

See also: SIN, COS, ATN

ATN is a math function that returns the angle, measured in radians, tangent is the numeric_expression. Said in a words of a mathematician, ATN returns "arcus tangent" of its argument. The argument can be of any type. Value of the ATN is calculated to a double precision. Return type is the "signed double precision", which corresponds to a variable with suffix '#'.

ATN is the only inverse trigonometric function in BASIC and can be used to perform other inverse functions using the following formulae:

asin(x) = atn(x/SQR(1-x*x))
acos(x) = atn(SQR(1-x*x)/x)

See also: SIN, COS, TAN

EXP is a math function that calculates the exponential function (that is Euler's number e=2.7182818284... raised to the power of a numeric expression). Inverse function of EXP is LOG.

See also: LOG

LOG is a math function that returns the natural logarithm of a numeric expression, ie. the logarithm with the base e=2.7182818284... Argument can be of any type and the return value is a double float.

To convert to logarithm with base 10 simply divide with LOG(10). For example, the following function calculates the logarithm with base 10:

  FUNCTION log10(x)
   log10 = LOG(x) / LOG(10)
  END FUNCTION

See also: EXP, FUNCTION

The absolute value function returns the unsigned magnitude of its argument. For example, ABS(-1.23) and ABS(1.23) are both 1.23 Argument can be of any type and the return value is a double float.

See also: SGN

RND is a math function that returns a single-precision random number between [0, 1) ie. 0 included, 1 excluded.
If the argument is omitted, the RND function returns the next number in the pseudorandom number sequence. The argument 'n' is a numeric expression of any type. The value of n determines how RND generates the next random number:

Argument	Return value
0 or n omitted	returns the next random number in the sequence
n <> 0	returns the last number generated

A tip:
To produce random integers in a range between n1% and n2% both included, use the formula:

  INT((n2% - n1% + 1)*RND + n1%)

For example, to simulate throwing a dice use n1% = 1, n2% = 6:

  INT(6 * RND) + 1

NOTE:
This implementation of RND uses C library function rand() to generate random numbers using the following formula:

  RND = rand()/((double) RAND_MAX))

See also: RANDOMIZE

RANDOMIZE is a math statement that initializes (reseeds) the random-number generator. The expression may be any integer
number between 0 and 65535. If not specified, the default
value of 32767 is taken.

If a number smaller than 0 or larger than 65535 is specified, then this number modulo 65536 is taken as a seed.

If the random-number generator is not reseeded, the RND function returns the same sequence of random numbers each time the program is run. To change the sequence of random numbers every time the program is run, place a RANDOMIZE statement at the beginning of the program and change the argument with each run.

A convenient way to initialize the random-number generator is to use the TIMER function as follows:
RANDOMIZE TIMER
Using TIMER ensures a new series of random numbers each time you run the program.

INT is a math function that returns the largest integer less than or equal to a numeric-expression. In other words, the INT function removes the fractional part of its argument. INT returns long integer, therefore the expression parameter must be in the range of the long integer i.e. -2 147 483 648 ... +2,147,483,647.

See also: CINT

CINT is a conversion function that converts a numeric expression to a long integer by rounding the expression. It is equivalent to INT(0.5 + expression).

See also: INT

The modulus or "remainder" operator. Divides one number by another (real values are rounded to integers) and returns the remainder. For example, 18 MOD 6.7 equals four.

Diagnostics of syntax and other errors at the translation time is not one of the greatest thing about QB2C but should be good enough in most cases. However, some errors are only detected at compilation time of the C translate. In that case, there is usually a very large number of errors complained by your C compiler. Errors detected at that level can be hard to back-trace to the original BASIC code. The tip is that you should always look only at the first error reported by the C compiler and correct for it before looking at any other error reports. Often the first reported error is the only error.

Reserve space in memory for arrays of variables. Array list is a list of arrays with specified dimensions delimited with comma. An array can be specified as a static or dynamic block of memory.

Array dimensioned with statement DIM DYNAMIC occupy a dynamic block of memory. Space for such array is allocated at run time and can be freed (see ERASE) or redimensioned (see REDIM) at the run time.

On the other hand, an array dimensioned with DIM statement occupy a static block of memory. Space for such array is predetermined at compile time and cannot be freed or change its size at the run time.

The DIM DYNAMIC statement can occur anywhere in the program, and the space required by array(s) is requested from the system at the momen when the program execution encounters the statement.
This is opposed to the DIM (static) statement which absolutely MUST be stated at the very beginning of the program (possibly after the CONST statement(s)), and which reserves the required array space immediately at the beginning of the program and does not free it until the program has stopped.

Initial contents of both static and dynamic arrays are set to zero.

KNOWN BUG:
A line with two or more DIM statements is not correctly logged if non-first array is SHARED:
DIM a(10): DIM b(10)
REMEDY. use only one DIM statement per physical line:
DIM a(10), b(10)

See also: ERASE, REDIM

Changes the size of the memory block pointed to by a dynamic array. The contents of the block will be unchanged to the minimum
of the old and new sizes. Newly allocated memory will be
uninitialized.
NOTE: REDIM works correctly only for 1-dimensional arrays of numbers. Example:

  DIM DYNAMIC a(10)
  ...
  REDIM a(20)

See also: DIM, ERASE

Clear and free the memory associated with dynamic arrays in the list. Arraylist is a list of bare array names separated by a comma. ERASEd can be only dynamic arrays previously created by the DIM DYNAMIC command.
When an array is ERASEd, it's name cannot be reused in another DIM DYNAMIC command. This limitation may disappear in the future versions of QB2C.
Example:

  DIM DYNAMIC a(10), b(100, 10)
  ...
  ERASE a, b

See also: DIM, REDIM

Call a user defined subroutine. Length of the name of the subroutine is limited to 80 characters, and it can not begin with a number (digit).

Example.

  CALL Sub(100, a%, x(8)) 

See also: SUB, FUNCTION

DATA is a non-executable statement that defines an unique data block of numeric and/or string constants.

Argument to DATA is the list of numeric or string data separated by comma. If a string constant contains commas, colons, or leading or trailing spaces you want to preserve in your program, you must enclose the string in double quotes.

Names of symbolic constants (defined in a CONST statement) appearing in DATA statements are interpreted as strings, rather than names of constants. For example:

  CONST PI=3.141593
  .
  .
  .
  DATA 2.20, PI,45,7

in this example, PI is interpreted as string "PI" rather than the number 3.141593.

A DATA statement may contain as many constants as will fit on a line. A whole line including the DATA statement must not exceed 1023 characters (see LIMITS section).
Several DATA lines add up data to the block in the order in which they appear in the program.

Data from the DATA block are visible from the MAIN and all subroutines in the program file.

See also: READ, RESTORE

READ is an I/O statement that reads values from the DATA block and assigns the values to variables

Argument variablelist is made up of one or more variables, separated by commas, which are to receive the data. The variables may be string or numeric.

When a READ statement is
called for the first time, it reads data from the DATA block starting from the first one. It reads as many items as there are in the valiablelist. Every new call starts reading from the next item in the DATA block. To reset the reading to the first element, use RESTORE.

During the READ, data are converted to the type as required/specified in the variablelist.

See also: DATA, RESTORE

RESTORE is an I/O statement that allows DATA block to be reread from a specified item. Items are counted from 1. If no argument is specified then DATA are reread from the first item.

See also: DATA, READ

INP is a device I/O function that returns a byte read from an I/O port.

port_number	is a numeric-expression which has an integer value between
	0 and 1023 (hexadecimal 0x000 to 0x3ff). It identifies the
	hardware address of the I/O port to read from.

You must run the program as the superuser or have your program given suid permissions ("chmod u+s program_name", which again can be given only by the superuser) in order to use INP function.

For example 889 is the address of 5 input lines of the parallel PC port.

The INP function complements the OUT statement.

See also: OUT

IMPORTANT NOTICE:
If you use either INP or OUT functions you must compile with bcc4, brun4 or run4 versions of the scripts.

OUT is a device I/O statement that sends a byte to a machine I/O port.

port_number	is a numeric-expression which has an integer value between
	0 and 1023 (hexadecimal 0x000 to 0x3ff). It identifies the
	hardware address of the I/O port to write to.
data	is a numeric expression that has an integer value between
	0 and 255, and is the data to be sent out the port.

You must run the program as the superuser or have your program given suid permissions ("chmod u+s program_name", which again can be given only by the superuser) in order to use OUT statement.

The OUT function complements the INP statement.

The INP and OUT statements give a program direct control over the hardware in a system through the I/O ports. These statements must be used with care because they directly manipulate the system hardware.

For example 888 is the address of 8 output lines of the parallel PC port. Address 890 contains 4 more output lines of the parallel port.

Summary of the other base addresses:

     DOS        Linux          Address Hex     Dec
  +--------------------------------------------------+
  |             /dev/lp0               0x3bc   956   |
  |  LPT1       /dev/lp1               0x378   888 * |
  |             /dev/lp2               0x278   632   |
  |  COM1       /dev/ttyS0             0x2f8   760 * |
  |  COM2       /dev/ttyS1             0x3f8   1016* |
  |  COM3       /dev/ttyS2                           |
  |  COM4       /dev/ttyS3                           |
  +--------------------------------------------------+

*- most common ports installed on PC's

See also: INP

IMPORTANT NOTICE:
If you use either INP or OUT functions you must compile with bcc4, brun4 or run4 versions of the scripts.

INPUT is a device I/O statement that reads input from the keyboard during program execution and stores it into a list of variables.

variablelist - is one or more variables separated by commas

Argument	Description
promptstring	A string constant printed before the prompt character.
	If used, is displayed on the screen to tell the user of
	the program what to enter at the keyboard
;	Print a question mark at the end of the promptstring
,	Print the promptstring without a question mark
variablelist	A list of variables, separated by commas, to accept
	the input values.

The INPUT statement causes the program to pause and wait for data. You can then enter the required data at the keyboard.

This implementation of input expects input numeric tokens to be delimited with "," and string tokens with ", ". In any case, there may be more white spaces. This allows you to pass strings which contain comma character. However, if input string contains white space it must be enclosed in double quotes. Example of a valid input:

  INPUT "Give one string and two numbers:"; a$, a, b, b$
  ....

Execution looks like this:
Give one string and two numbers: aa,bb ,2,3,"k l"

Result: a$ = "aa,bb", a = 2, b = 3, b$ = "k l"

Argument	Description
a$	- a string to be scanned through;
sep$	- a string of character separators according to which a$
	is separated into tokens;
variablelist	- a comma-separated list of variables (numeric and/or string).
	Each variable from this list is assigned a token found
	in a$ at the order of appearance.

SSCAN is a string processing function. It scans string a$ for tokens delimited by any of the characters fount in the sep$. Each token is converted in the type of the corresponding variable from the variablelist and assigned to it. SSCAN operates on the string a$ in the similar way as READ operates on the DATA block. If variablelist contains more variables than there are tokens in a$, the overhead variables are left with their prevous values, and a run-time warning is isseed. At the exit, a$ and sep$ are not changed.

Example 1:

  a$ = "Abcd, 12.34, efGh, -2" 
  SSCAN a$; ","; b$, x, c$, i%
  PRINT b$
  PRINT x
  PRINT c$
  PRINT i%

scans a$ for string, real numnber, string and integer separated by comma and writes four results. The output will be:

  Abcd
  12.34
  efGh
  -2

Example 2:
If you want to scan a string according to either a tab or comma for example, do this:

  tab$ = ",_": MID$(tab$, 2, 1) = CHR$(9)
  SSCAN string$; tab$; .....

Tip: in the above example you could also have defined tab$ like this:

  tab$ = "  "
C tab_S[0]=','; tab_S[1]='\t';

NOTE. You should use SSCAN when number and type of tokens are known. If the number of tokens is not known in advance, use TOKENS command.

Related topics: TOKENS, TRIM$, LTRIM$, RTRIM$

OPEN - a file operation statement that enables input and/or output to a file.

Argument	Description
filename$	a string or a string expression denoting the file to be
	opened
filenumber	a small positive integer: 0 is invalid, must be >=1.
	This number is used to identify an opened file to I/O
	commands like CLOSE, PUT #, GET #, etc.
mode	one of the following keywords: (C equivalent)
INPUT	Opens file for reading only. File is not changed. (r)
OUTPUT	Creates a new file and opens it for writing. If file of the
	same name exists, it is replaced with the new file. (w)
APPEND	Opens an existing file for writing at the end of the file.
	If the file does not exist, it is created. (a)
RANDOM	Opens a file for binary
BINARY
ACCESS
READ
WRITE
READ WRITE

Mode	Description	C equivalent
INPUT	Opens file for reading only. File is not changed.	(r)
OUTPUT	Creates a new file and opens it for writing. If file
	of the same name exists, it is replaced with the new
	file.	(w)
APPEND	Opens an existing file for writing at the end of the
	file. If the file does not exist, it is created.	(a)
RANDOM	Opens a file for binary
BINARY
ACCESS
READ
WRITE
READ WRIT	TE

NOTE. Full syntax is:

  OPEN filename$ FOR mode [ACCESS access] AS [#]filenumber [LEN=reclen]

See also: CLOSE, SEEK, PUT, GET, INPUT, PRINT, EOF, LOF

The association of a file with a file number ends when a CLOSE statement is executed. You may then reopen the file using the same or a different file number. Once you close a file, you may use that file's number for any unopened file.

A CLOSE for a file or device that was opened for sequential output writes the final buffer of output to that file or device.

CLOSE releases all buffer space associated with the closed file or files.

The END statement closes all files automatically.

See also: OPEN, EOF, LOF

LOF function returns file length in bytes.

See also: DOF$

DOF$ function returns a character which represents time of last modification of the file 'filename$'.

See also: LOF

EOF is a file I/O function that tests for the end-of-file condition.

The EOF function returns TRUE (nonzero integer) if the end of a sequential file open for read has been reached or passed.
IF EOF returns TRUE, further file reading by INPUT # or GET # commands is not possible and will produce an error. You may
use EOF to prevent such error to occur.
EOF recognizes 'stdin' as a special file descriptor: EOF(stdin).

See also: stdin

GET is file I/O statement that reads from an opened file into a variable.

Argument	Description
filenumber	- The number used in the OPEN statement to open the file.
recordnumber	- the number of the record to be read.
	The first record or byte position in a file
	corresponds to the recordnumber 1.
	For a numeric variable or array, length is the number
	of records to be read. If omitted, then length equals 1.
	For string variable or array, length is the number of bytes
	to be read in. If omitted, length equals the length of the
	string (see the function LEN).
	If you omit recordnumber, the next record or byte
	(the one after the last GET # or PUT #, or the one
	pointed to by the last SEEK) is read into the buffer.
	Each time something is read by GET #, the file pointer
	points to the next unread byte, or the end-of-file marker
	and the next GET # starts with that byte.
	The largest possible record number is 2^31 -1, or
	2,147,483,647.
variable	- A numeric variable used to receive input from the file,
	it can be single variable or element of an array.
length	- the number of records to be read in by the GET command.
	If omitted, the default is one record (see above).
	In case that a variable is a string, length is a number
	of bytes to be read in or, if omitted, the (current) length
	of the string as would be returned by the function LEN.

Example.

  DIM b(10)       :REM Dimension an array of real numbers
  OPEN "file" FOR INPUT AS #2  :REM Open a file for reading
  ...
  GET #2,,i%      :REM Read one integer number (four bytes) into variable i%
  GET #2,,a?      :REM Read next byte into variable a?
  GET #2,,b(5)    :REM Read one real number into the array element b(5)
  GET #2,,b(6),5  :REM Read 5 real numbers into elements b(6)...b(10)
  ...
  CLOSE #2

See also: PUT, SEEK, EOF

PUT is a file I/O statement that writes from a variable to an opened file.

Arguments description is the sam as for the GET # statement except that the variable is written to the file rather than read from it.

See also: GET, SEEK, EOF

SEEK command sets the position of the pointer for file I/O to a specified position.

The filenumber is an integer number used in the OPEN statement to open the file.

The position is a numeric expression indicating the byte where the next read or write is to be done. The position must be in the range 1 to 2,147,483,647 (equivalent to 2^31 -1).
The first byte in a file is 1. After a SEEK, the next file I/O operation starts at that byte in the file.

Note: Record numbers specified in GET # or PUT # will override the file positioning done by SEEK.

Example: see the GET # example.

See also: PUT, GET

When a C program (or a QB2C program) is started the operating system also opens three special files: standard input (stdin), standard output (stdout) and standard error output (stderr). There is nothing you must do to open them: they are already opened and ready fo use. There is probably nothing you can do th close them either: they are automatically closed on program exit.

Currently QB2C supports writing to the standard output via PRINT command, writing to the standard error output vita the EPRINT command, and reading from the standard input using the file descriptor 'stdin' in the following commands/functions/statements: INPUT, INPUT #stdin, LINE INPUT #stdin, GET #stdin, EOF(stdin).

Examples:
...
WHILE NOT EOF(stdin)
LINE INPUT #stdin, a$
INPUT #stdin, a, b, c
PRINT a$, a, b, c
WEND
...

Redirecting standard output to the file:
myprog > file

Redirecting both standard output and std. error to the file: myprog >& file

Redirecting content of a file into the std. input:
myprog < file
or:
cat file | myprog -

Redirecting string into the standard input:
echo "This goes into the standard input of the program myprog" | myprog

See also: PRINT, EPRINT, INPUT, INPUT, LINE, GET, EOF()

Inline:

   IF bool THEN expr
   IF bool THEN expr ELSE expr
   IF bool THEN expr ELSE IF expr THEN expr
   IF bool GOTO 100
   IF bool GOSUB 100

   IF a = b THEN 100 ELSE 200

Multiline:

   IF bool THEN
    expr
   [[ELSEIF bool THEN
    expr]
   [ELSE
    expr]]
   END IF

In multiline IF statements you may add a remark in the form: REM ... only after the keywords THEN and ELSE and in that case the remark must not be separated by a colon ":".
Example:

  IF a = 1 THEN REM Remark no. 1
   ...
  ELSE REM Remark no. 2
   ...
  END IF

See also: SELECT

SELECT CASE is a control flow statement that executes one of several statement blocks depending on the value of the test expression.

Syntax:

  SELECT CASE testexpression
  [CASE expressionlist1]
    [statementblock-1]
  [CASE expressionlist2
    [statementblock-2]] ...

  [CASE ELSE
    [statementblock-n]]
  END SELECT

testexpression	is any numeric or string expression;
expressionlist	contains one or more expressions of the same type as
	testexpression;
statementblock	consists of any number of statements on one or more
	lines;

row	The number of a row on the screen; row is a numeric
	expression returning an integer. If row is not specified,
	then the line (row) does not change.
column	The number of a column on the screen; column is a numeric
	expression returning an integer. If column is not
	specified, then the column location does not change.

For normal text-mode screen the usefull ranges are:
1<= row <= 80
1<= column <= 25

LOCATE is usually used just before the PRINT command in order to print the output starting at the specified position on the window. See also: PRINT, COLOR

A line may be labeled so that "GOSUB label" or "GOTO label" may jump to the line. Labels must be numbers only unless option "-lab" is not specified at compile-time in which case labels may additionally be alphanumeric. Non-numeric labels must contain a colon ":" at ther right end.
It is not necessary that a label defined must be used, but a label used (by GOTO, GOSUB) must be defined or compile-time error will occur.

Label examples:

Good label:	1000
Good label:	A1000:
Bad labels:	A1000 1000A Abcd 10A00

Labeling examples:

     GOTO 10
     ...
  10 PRINT "This is line labeled 10"

or:

     GOTO 10
     ...
  10
     PRINT "This is line after the line labeled 10"

or:

     GOTO A10
     ...
  A10:
     PRINT "This is line after the line labeled A10"

or:

     GOTO start
     ...
  start: PRINT "This is line labeled start"

See also: GOTO, GOSUB

GOTO performs unconditional jump to a line labeled with 'label'. This line must be in the same procedure or subroutine as the GOTO statement. GOTO may be used to exit from loops.

See also: LABELS, GOSUB

GOSUB...RETURN are a control flow statements that jumps to, and returns from a local subroutine. A local subroutine is a piece of code within the sam subroutine or the main program. GOSUB unconditionally jumps to a line labeled with 'label'. When a program flow enounters the RETURN statement for the first time it returns to the line immediately after the GOSUB statement.

You may call a local subroutine any number of times in a program. You may also call a local subroutine from within another local subroutine. In QB2C the terminal GOSUB depth is 16 levels. Local subroutines that call themselves (recursive subroutines) can easily run out of stack space.

GOSUB is very versatile because you may jump to different parts of a piece of code, which can contain more than one RETURN statements, returning from the first one that happens to be executed. However, this style of programming may be made very unclear and hard to debug even to its creator.

See also: RETURN, LABELS, GOTO

Return from a local subroutine.

See also: GOSUB

Syntax

  a = TIMER
  z# = TIMER

TIMER returns a number of seconds down to a microsecond, i.e. 6 decimal places. However true timing accuracy is machine dependent and can be less than that.

The TIMER function can be used with the RANDOMIZE statement to generate a random number. It can also be used to time programs or parts of programs.

BASIC COMMANDS

PRINT is a device I/O statement that outputs data to the screen.

Print a string, string expression or number.
IF outputlist is omitted then print an empty line.

See also: PRINT, EPRINT

PRINT USING is a device I/O statement that outputs formatted data to the screen.

Print a string, string expression or number, under a control of format. Format may contain only characters "#" and/or ".". For example: PRINT USING "###.##"; a
will print a as a float number which occupy exactly 6 places, and is print with precision to two decimal places.
Example:

  i% = 123: j% = 123456: k% = 1
  h$ = "#####"
  PRINT USING h$; i%; j%; k%

will print the string 15 characters wide, in which each of integer numbers i%, j%, k% will occupy at most 5 characters, other characters will be blank:

    12323456    1 

See also: PRINT, EPRINT

  $ program > file

However, the output of EPRINT will still appear on the screen. Thus, EPRINT is suitable for printing error messages. If you want to redirect both PRINT and EPRINT output use >& :

  $ program >& file

If you want to redirect output of PRINT to file1 and EPRINT to file2:

  $ program > file2 2>&1 > file1

See also: PRINT

EXAMPLE:

  1 + 2 * 19 MOD 6.7 + .5
  is equivalent to:
  1 + (CINT(2 * 19) MOD CINT(6.7)) + .5

EXAMPLE:

   name$ = "myfile.dat"
   IF EXISTS("~/" + name$) THEN
    ...
   END IF

GRAPHICS COMMANDS

Set of graphics commands to work under X11 windows system is included. They are similar in syntax to the original Quick Basic commands, except for some intrinsic differences between DOS and X11 graphics display. For example, the 'SCREEN 10' command will open an 820x485 pixel X-window to which subsequent graphics will be sent. Both text and graphics screens live at the same time, so there is no need to switch between two modes ('SCREEN 0' is obsolete).

There is a small demo program 'graphic.bas' included in this package. Try to compile it and understand how it works:
bcc graphic
graphic

Below is the short review of syntax.

SCREEN command establishes connection to the X server, initializes graphics (colors, fonts, etc.) and opens an X11 graphic window with identifier ID = 0 at the position (x, y) pixels. It has two supported syntaxes.

SCREEN 10
Initializes graphics and opens an X11 graphic window of the size width=820; height=485 pixels using default title and font.

SCREEN (x, y)[, width, height[, title$[, Xfont_name$]]]
Initializes graphics and opens X11 graphic window with identifier ID = 0 at the position (x, y) pixels. The window ID number is used in commands like: XSELWI, XCLS etc.
The optional width and height of the window are specified in pixels. If not specified, the default is: width=820, height=485.
The default background color is white and foreground black. These may be changed (individually for each window) via SET BG or XCLS. The default global font is:
"-misc-fixed-medium-r-normal-*-20-140-*-100-c-100-iso8859-1" and it fits exactly 80 rows and 25 columns in the default window size. Initial title for the window can be set via title$ parameter. By default title will be written in the form: title@hostname. To avoid printing of the hostname, start the title with "-". Title of an already open window can be redefined via XTITLE command, which behaves the same way.

SCREEN must be the first graphics command and must be executed exactly once. If more than one X-windows are needed they may be opened via XWINDOW command.

The background color of an already opened window can be changed via XCLS command.

See also: XCLS, SET, XTITLE, BACKINGSTORE

From the early days of the QB2C its graphics has been relying on so called "backing store" feature of the XFree86 servers. The backing store means that the content of every window is kept in a memory and that it can be pulled out when needed automatically, by the X-window server. For example if a window gets obscured by another window it is clear that the obscured part of its content isn't present anymore in the video memory. When the obscured part became exposed again, its content can be restored if a copy of the window content is kept at hand. The "backing store" feature means that such refreshing of a window content is done automatically: programmer does not have to bother with it. However, since XFree86 version 4.0.0 it has been decided that such a system creates too big a load for X server and the backing store is OFF by default ever since. Some server modules still allow to switch ON the backing store, but some window managers (notably KDE, KDM) do not behave properly when the backing store is ON.
To switch ON the backing store on a typical Linux X-window system:

startx -- -depth 16 +bs

Note that "-depth 16" sets the color depth to 16 bits per pixel, which is the maximal color deepth for proper functioning of screen capturing commands such as: SAVEGIF, SAVEPS etc. The "+bs" option switches ON the backing store.

The QB2C (since version 4.91) supports its own internal backing store which is invoked at time when program execution reaches the command BACKINGSTORE. It works well with all window managers.

BACKINGSTORE is equivalent to switching ON the XBUF buffer for all currently active and future active windows.

Example. See the program xbutton.bas which is a part of the QB2C package.

See also: XBUF, XRMBUF

The background color of an already opened window can be changed via XCLS command.

See also: XCLS, SET, XTITLE, SCREEN, BACKINGSTORE

See also: XWINDOW

See also: SET, PGET, LINE

See also: PSET

  LINE (x1, y1)-(x2, y2)[, [color%][, [B[F]][,style%]]]
  LINE [[STEP] (x1,y1)]-[STEP] (x2,y2) [,[color][,[B[F]][,style]]]
  LINE - [STEP] (x, y)[, color%[, B[F]]

LINE Statement Details

Syntax

  LINE [[STEP] (x1,y1)]-[STEP] (x2,y2) [,[color][,[B[F]][,style]]]

The coordinates (x1,y1) and (x2,y2) specify the endpoints of the line; note that the order in which these endpoints appear is unimportant, since a line from (10,20) to (120,130) is the same as a line from (120,130) to (10,20).

The STEP option makes the specified coordinates relative to the most recent point, instead of absolute, mapped coordinates. For example, if the most recent point referred to by the program is (10,10), then

  LINE -STEP (10,5)

draws a line from (10,10) to the point with x coordinate equal to 10 + 10 and y coordinate equal to 10 + 5, or (20,15).

You may establish a new most recent point by initializing the screen with the CLS and SCREEN statements. Using the PSET, PRESET, CIRCLE, and DRAW statements will also establish a new most recent point.

Variations of the STEP argument are shown below. For the following examples, assume that the last point plotted was (10,10):

Statement	Description
LINE -(50,50)	Draws from (10,10) to (50,50)
LINE -STEP(50,50)	Draws from (10,10) to (60,60); that
	is, to 10 plus offset 50
LINE (25,25)-STEP(50,50)	Draws from (25,25) to (75,75); that
	is, to 25 plus offset 50
LINE STEP(25,25)-STEP(50,50)	Draws from (35,35) to (85,85); that
	is, from 10 plus offset 25 to that
	point plus offset 50
LINE STEP(25,25)-(50,50)	Draws from (35,35) to (50,50); that
	is, from 10 plus offset 25 to
	absolute 50

The color is the number of the color in which the line is drawn. (If the B or BF options are used, the box is drawn in this color.) See the PALETTE statement details for information about how to specify a color.

The B option draws a box with the points (x1,y1) and (x2,y2) specifying diagonally opposite corners.

The BF option draws a filled box. This option is similar to the B option; BF also paints the interior of the box with the selected color.

The style is a 16-bit integer mask used to put pixels on the screen. Using the style argument is called "line styling." With line styling, LINE reads the bits in style from left to right. If a bit is 0, then no point is plotted; if the bit is 1, a point is plotted. After plotting a point, LINE selects the next bit position in style.

Because a 0 bit in style does not change the point on the screen, you may want to draw a background line before using styling so you can have a known background. Style is used for normal lines and boxes, but has no effect on filled boxes.

When coordinates specify a point that is not in the current viewport, the line segment is clipped to the viewport.

See also: SET, PALETTE, PSET, PLINE

See also: PMARKER, SET

See also: SET, SET

  (x0, y0) -> (array_%(0, 0), array_%(0, 1))
  (x1, y1) -> (array_%(1, 0), array_%(1, 1))
  (x2, y2) -> (array_%(2, 0), array_%(2, 1))

Examples.
See also: SET

Draw a circle of radius 20, with the center at x=150, y=100 :

   CIRCLE (150, 100), 20, 1

Draw an elipse with horizontal radius 20, vertical radius 10, and the center at x=150, y=100 :

   CIRCLE (150, 100), 20, 1, 0, 6.3, .5

Related topics: SET, XLEN

Related topics: SET, XTEXT, LEN

This command affects the following drawing commands:
LINE, PLINE, PSET, MARKER, PMARKER, FAREA, CIRCLE, XTEXT.

See also: XROT, XSCAL, MRESET

This command affects the following drawing commands:
LINE, PLINE, PSET, MARKER, PMARKER, FAREA, CIRCLE (aspect=1 only), XTEXT.

See also: XTRAN, XSCAL, MRESET

This command affects the following drawing commands:
LINE, PLINE, PSET, MARKER, PMARKER, FAREA, CIRCLE, but not XTEXT.

See also: XTRAN, XROT, MRESET

Graphics transformations (XTRAN, XROT and XSCAL) are done using the following formula:

  x' = xT + cos(phi) * scalex * (x - xR) + sin(phi) * scaley * (y - yR)
  y' = yT - sin(phi) * scalex * (x - xR) + cos(phi) * scaley * (y - yR)

where:

(xT, yT)	= new origin set by XTRAN
(xR, yR)	= rotation central point by XROT
phi	= rotation angle set by XROT
scalex, scaley	= scaling factors set by XSCAL

That is, the object is first moved to the origin (xO, yO), then scaled by (scalex, scaley) and then rotated by an angle phi with respect to the origin (xO, yO).

This command affects the following drawing commands:
LINE, PLINE, PSET, MARKER, PMARKER, FAREA, CIRCLE, XTEXT.

See also: XTRAN, XROT, XSCAL

The answ% contains button information:

answ% = 1	( 1) left button pressed
11	(-1) left button released
2	( 2) middle button pressed
12	(-2) middle button released
3	( 3) right button pressed
13	(-3) right button released.
-1	( 0) motion
-1	( 16) window entered
-2	(-16) window left
25	6*(ascii + 256*keycode) key pressed
-25	6*(ascii + 256*keycode) key released

Values in brackets are in case that bit number 1 (2^1) of mode% is set. Sensityvity to keyboard is in the case that bit number 4 (2^4) of mode% is set (see below).

Input parameters are:

typ% (mouse type) =	0 previous type	mode% (request mode) =	1 Request mouse only
	1 Tracking cross		17 Request mouse or keyboard
	2 Cross-hair	(default mode = 1)
	3 Rubber circle
	4 Rubber band
	5 Rubber rectangle.
(default type = 0)

In Request modes the GCGET statement blocks until an event
(associated with the window where the mouse is placed) is received then removes it from the queue and returns the result.

If a keyboard key is pressed answ% equals
to +char_ascii_code (key pressed) or -char_ascii_code (key depressed) multiplied by 256.

NOTE: User should normally use this mouse-reading function only if the program uses not more than one X-window, because GCGET can read only one window at a time. If more than one X-window is opened, XPOINTER should be used instead.

OBSOLESCENCE NOTE. As of the version 4.92, function GCGET is obsolete. It is no longer mantained and is kept only for backwards compatibility. Users are strongly encouraged to use XEVENT function instead.

See also: XEVENT, XPOINTER, XCURSOR

Output parameters:

(x%, y%) =	the position of of the pointer;
win% =	window on which the pointer is logically positioned;
answ% =	1 ( 1) left button pressed
	11 (-1) left button released
	2 ( 2) middle button pressed
	12 (-2) middle button released
	3 ( 3) right button pressed
	13 (-3) right button released.
	-1 ( 0) motion
	-1 ( 16) window entered
	-2 (-16) window left
	0 ( 32) window resized
	0 ( 64) window obscured or exposed
	256*(ascii + 256*keycode) key pressed
	-256*(ascii + 256*keycode) key released

Values in brackets are in case that bit number 1 (2^1) of mode% is set. Sensityvity to keyboard is in the case that bit number 4 (2^4) of mode% is set (see below).

Input parameters are:

typ% (mouse type)	1 Tracking cross	mode% (report mode)
	2 Cross-hair	bit 2^0	0=Request 1=Sample
	3 Rubber circle	bit 2^1 set	motion=0
	4 Rubber band	bit 2^4 set	keyboard on
	5 Rubber rectangle	bit 2^5 set	resize, expose on
	(default = 1)	(default = 19)

In Request mode the XPOINTER statement blocks until an event (associated with the window where the mouse is placed) is received then removes it from the queue and returns the result.

In Sample mode it checks for an event in the queue (associated with the window where the mouse is placed) and if one is there removes it and return the result whereas if there is no such event it returns code 128. This makes possible further execution of the program.

OBSOLESCENCE NOTE. As of the version 4.92, function XPOINTER is obsolete. It is no longer mantained and is kept only for backwards compatibility. Users are strongly encouraged to use XEVENT function instead.

See also: XEVENT, GCGET, XCURSOR

Output parameters short summary:
x%, y%= pointer coordinates
win% = window to which the event referes; -1 if neither
but% = code of (de)pressed mouse (-)(1,2,3)
key or Enter/Leave +/-16 event
window resized event +32
window obscured/exposed event +64
asc% = ascii code of (de)pressed keyboard key
key% = keyboard code of the (de)pressed key
(usefull for function or other non-alphanumeric keys)

Input parameters short summary:

typ% (mouse type)	1 Tracking cross	mode% (report mode)
	2 Cross-hair	bit 2^0	0=Request 1=Sample
	3 Rubber circle	bit 2^1 set	motion=0
	4 Rubber band	bit 2^4 set	keyboard on
	5 Rubber rectangle	bit 2^5 set	resize, expose on
	(default = 1)	(default = 19)

X server generates certain events and fills a special buffer called "X-event queue". XEVENT reads one event from the queue and removes it. XEVENT is aware of the following events: mouse button press/release, pointer motion, window resize, window obscure/expose, keyboard key press/release. Not all of these events are reported by XEVENT. Details of what gets reported are controled by mode% parameter.

The mode% is an integer input parameter whose bits are seen as flags. Each flag can be set (1) or not set (0). Currently active bits are: 0, 1, 4, and 5.

Bit 0 determins whether XEVENT operates in Sample (set) or Request (not set) mode. In Request mode the XEVENT statement blocks until an event (associated with the window where the mouse is placed) is received, then removes it from the queue and returns the result. In Sample mode it checks for an event in the queue (associated with the window where the mouse is placed) and if one is there removes it and return the result whereas if there is no such event it returns code 128. This makes possible further execution of the program.

Bit 1 controls the way events are reported. This is summarized in the table below:

window leaved => answ% =	-16	-2
window entered => answ% =	16	-1
window resized => answ% =	32	0
window obscured/exposed => answ% =	64	0
mouse moved within the window => answ% =	0	-1
button 1 pressed/released => answ% =	1/-1	1/11
button 2 pressed/released => answ% =	2/-2	2/12
button 3 pressed/released => answ% =	3/-3	3/13

Bit 4 controls whether XEVENT reports keyboard events (bit set) or not (bit not set).

Bit 5 controls whether window resized and window obscured/exposed events are reported (bit set) or not (bit not set).

If a keyboard key is pressed, XEVENT returns a window number of the active window (active window s recognized by its border color) and answ% equals to +char_ascii_code (key pressed) or -char_ascii_code (key depressed) multiplied by 256. This is only efective if bit 4 of mode% is set. For example in mode 17 XEVENT will lock and wait for any mouse or keyboard or window event to happen.

Table of codes of some keys:

Key	asc%	key%
A-Z	97-122	38-52
a-z	65-90	38-52
@	64	11
F1	0	67
F2	0	68
F3	0	69
F4	0	70
F5	0	71
F6	0	72
F7	0	73
F8	0	74
F9	0	75
F10	0	76
F11	0	95
F12	0	96
Insert	0	106
Home	0	97
PageUp	0	99
Delete	0	107
End	0	103
PageDn	0	105
Cursor Up	0	98
Cursor Left	0	100
Cursor Down	0	104
Cursor Right	0	102
Shift (Left)	0	50
Ctrl (Left)	0	37
Alt (Left)	0	64
Shift (Right)	0	62
Ctrl (Right)	0	109
Alt (Right)	0	113
MSWin (Left)	0	115

NOTE. Window enter and leave events are sometimes not
detected by the X11 system. Other events may be corrupted with some window managers (notably KDE).

NOTE ON PERFORMANCE
Modes with keyboard are some 60 percent slower than pure mouse modes.

See also: XCURSOR

Saves contents of the current graphics window into a PostScript file. Figure is resized proportionally in width and height to fit the A4 paper.

Saves contents of the current graphics window into the file in Encapsulated PostScript format.
Figure is resized proportionally in width and height to fit the A4 paper. SAVEPSL creates the same picture in Landscape orientation, also to fit the paper.

See also: READGIF

It is recommended to use byte-type array (suffix "?") if some kind of picture manipulation is intended by the user, since in this case one element of the array corresponds to exactly one pixel of image.

NOTE: See the PUT and GETCOL commands and the example program getput.bas.

Related topics: PALETTE, GET, PUT

Related topics: PUT, GET, PALETTE, GETCOL, SET

NOTE:	See the GET and GETCOL command for the additional information.
NOTE:	In order to produce correct image, color palette must not be
	changed between GET and PUT commands, since `array?' only contains
	color codes of pixels.
NOTE:	Using multiple PUT commands it is possible to achieve animation.
	However, simpler and faster way is to use XANIM command.