NAME

intro - introduction to the BASIC run-time support library

SYNOPSIS

ld options files /usr/lib/basic/libbasic.a -lm -lc

INTRODUCTION

This section describes the functions, formats and symbols which implement the run-time behavior of Basmark BASIC.  BASIC resembles f77 in that complex functionality is within the bounds of the language whereas C delegates this functionality to “external” libraries of functions.  Libbasic provides this functionality along with the math and C libraries. 

The BASIC run-time support library works invisibly with basic(1) and, along with the BASIC code generator and UNIX libraries, accomplishes all the tasks possible with BASIC.  Thus one need not typically refer to this section.  However, when code written in another language is to be integrated with a BASIC program, it becomes necessary to have some knowledge of the inner workings of BASIC.  This may occur, for example, if the programmer needs to use a tightly coded assembler routine or has available a FORTRAN statistics package or perhaps wants to gain access to UNIX system functions using a C routine. 

CAVEATS

The casual user is warned that the use of the information in this section requires expertise in areas other than the BASIC language.  Competence in C programming is assumed as is familiarity with programming in a UNIX environment.  The reader who is venturing into this realm for the first time will find the example in call(stmt) to be a good introduction. 

This section should make BASIC a “good neighbor” to the other UNIX languages, but the methods described here remain trade secrets of Basmark. 

DESCRIPTION

The functions and formats described in this section are labeled for the categories of operations they implement:

(inc)

formats given by include files

(cvt)

conversion of values between types and formats

(err)

run-time errors

(io)

I/O operations

(mach)

machine dependent operations (involving absolute addresses)

(math)

mathematical functions

(misc)

chaining, terminal dependent operations, files, date and time

(str)

string functions

Naming Conventions

Libbasic function names resemble, as closely as possible, the BASIC statements and functions they implement with the following notable differences: the names are in lower case with the ‘$’ (dollar) at the end of BASIC string function names replaced by ‘S’ (capital s).  Names are limited to six characters.  Names that would collide with UNIX function names are prepended with ‘b’ (small b).  Differences also occur when a BASIC statement and BASIC function have the same name, when a BASIC function name has more than one meaning, and when functionally is embedded in BASIC without an alphabetic name.  In these cases names are chosen rationally but there is no pattern. 

Symbol Names

One must avoid collisions with symbol names used by BASIC.  One must avoid names used by the UNIX math and C libraries and this library.  Also, the names of BASIC subprograms must be avoided.  Finally, all names beginning with a capital letter are reserved; these include names beginning with a capital B used by the code generator for communication with the library, names beginning with a capital C which are COMMON block names and names beginning with INT, FLT, DBL and STR which are the transliterations of the names and types of USR functions.  If an error should occur in the code generator such that a name is used but is left undefined, the name will be made external.  If this object file is linked with a module which contains a symbol with the same name, no error will be detected and the resultant executable will be linked improperly. 

The names of the symbols defined by the code generator and the library are:

			Bargc		chain		err		lset		setalarm
			Bargv		chainy		errdisable		ltrimS		setstr
			Bcomal		chrS		exitty		main		sgn
			Bcomon		cint		field		makeaddr		shell1
			Bdata		closedir		file0		midS1		shell2
			Berror		clrstr		filed		midS2		sorter
			Bseg		cls		filel		mkbiobuf		spaceS
			L0		cmpstr		filen		mkdS		spc
			_reset		color		files		mkdmbS		sqr
			asc		comma		filptr		mkiS		stop
			asgstr		comndS		fix		mksS		strS
			atobasic		csng		genfilnam		mksmbS		strinS
			bchdir		csrlin		getalarm		name		tab
			bclose		cstring		getcol		newlin		telldir
			beep		cvd		getrow		numcvt		terment
			bend		cvdmb		hexS		octS		termflag
			bexit		cvi		ignsigs		opendir		termgoto
			bget		cvs		initio		ospeed		termnum
			bgetc		cvsmb		initrm		peek		termpad
			biofn		dateS		initsg		poke		termstr
			biotab		defseg		initty		pos		timeS
			bkill		dezomb		inkeyS		power		timer
			bload		dimd		inkmatch		print		trace
			blog		dirfiles		inline		printu		trapsigs
			bmkdir		doclose		input		random		tron
			bopen		docvt		inputS		readdir		ttyerase
			bput		doerr		instr		rembiobuf		ttykill
			bputc		doread		lcaseS		rightS		ubound
			bputs		dotrim		lclose		rnd		ucaseS
			breset		dowrite		leftS		round		unixerror
			brmdir		ehandl		len		rset		useaddr
			bsave		envir		linein		rtrimS		usenum
			btermcap		envirS		loc		run		usfnum
			bunget		eof		locate		runerr		val
			bwrite		erased		lock		runmess		varptS
			catstr		erases		lof		seekdir		varptr
			cdbl		erl		lpos		seg		width

Data Types

BASIC integers are implemented as C short integers which are 16-bit 2’s complement quantities.  BASIC single-precision and double-precision floating point numbers are handled as C floats and doubles, respectively.  Most systems implement floating point numbers according to ANSI/IEEE Standard 754-1985, but there is no guarantee of this.  A BASIC string is implemented with a C structure for the header with space allocated (except for constants and “fielded” strings) by malloc(3) (see string(inc)). 

Error Handling

Most errors that occur in the use of the functions in this library are semantic and readily detected.  These error conditions are handled with runerr (see runerr(err)) and are cataloged under the DIAGNOSTICS sub-heading on the pages of this section. 

Other errors generally can not be anticipated and are the result of error conditions detected by UNIX system calls.  These errors are handled by mapping the UNIX error number, errno (see intro(2)), into the most appropriate BASIC error number.  Although code could be written to produce the UNIX error number, the following list describes the mapping to help the user discover which UNIX error code caused the BASIC error condition:

					BASIC Error				UNIX Error
			5		Illegal function call		1		Not owner
			5		Illegal function call		13		Permission denied
			6		Overflow		34		Result too large
			7		Out of memory		12		Not enough space
			11		Division by zero		33		Math argument
			53		File not found		2		No such file or directory
			58		File already exists		17		File exists
			61		Disk full		28		No space left on device
			64		Bad file name		21		Is a directory
			70		Disk Write Protect		30		Read-only file system
			71		Disk not Ready		6		No such device or address
			72		Disk Media Error		5		I/O Error

FILES

/usr/lib/basic/libbasic.a

SEE ALSO

call(stmt), string(inc), runerr(err)
basic(1) in the Supplemental Documentation section
malloc(3), intro(2) in the UNIX Programmer’s Manual

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber