dBasic Function Table of Contents

 Alphabetic list of Functions

 Functions by Catagory


Function List
dBasic Function Index

DBMS Functions

ADD.KEY	ADD.RECORD	CLOSE.FILE
DBMS.DEFINE	DBMS.EXIT	DELETE.KEY
DELETE.MEMO	DELETE.RECORD	FIELD.INFO
FILEBASE	FILE.INFO	FIND.KEY
GET.FIELD	GET.MEMO	GET.RECORD
GET.TAG.FIELD	INITIALIZE.FILE	LOCK.CONTROL
LOCK.FILE	LOCK.RECORD	LOCK.TO.SSD
NEXT.KEY	OPEN.FILE	OPEN.KEY.FILE
OPEN.MEMO.FILE	OPEN.TAG.FILE	PREVIOUS.KEY
PUT.FIELD	PUT.MEMO	PUT.RECORD
READ.RECORD	READ.UNLOCKED	UNLOCK.CONTROL
UNLOCK.FILE	UNLOCK.RECORD	WRITE.CONTROL
WRITE.EXCLUSIVE	WRITE.RECORD

BASIC Functions & Compiler Directives

ABOUT	ABS	ACCEPT.FIELD
ACS	AFTER	AGAIN
AGE	ALLOCATE	ASC
ASN	ATN	AUTOCAP
BAR.INPUT	BEFORE	BIN
BINARY	BREAK	BYTE
CALL	CASE	CENTER
CHAIN	CHR	CLOSE
CONTAINS	COS	CVTBIN
CVTHEX	CVTOCT	DATA
DATE	DATN	DAYNUMBER
DECHR	DEF	DFREE
DIAGNOSTIC 	DIM	DISPLAY.FIELD
DO	DRAW.FORM	DRAWBOX
DUAL.PRINT	DUPSTR	ELSEIF
END	ENDDO	ENDFORM
ENDFUNC	ENDIF	ENDSTRUCTURE
ENTRY.POINT	EOF	ERF
ERR	ERRMSG	EVAL
EXECUTE	EXP	EXPAND.MACRO
EXTERNAL	FACT	FILESPEC
FLOAT	FOR	FORM.DEFINE
FORM.ORIGIN	FORM.PRINT	FORM.PUT
FRAC	FUNCTION	GET
GETKEY	GOTO	HEX
HOTKEY	HRDEC	IF
IFDEF	IFEQUDEF	IFEQUNOTDEF
IFFALSE	IFLABELDEF	IFLABELNOTDEF
IFNOTDEF	IFTRUE	IFVARDEF
IFVARNOTDEF	INCLUDE	INPUT
INPUT.FIELD	INSTR	INT
IO	JULIAN	JULIANTODATE
KILL	LCS	LEFT
LEN	LIKE	LJUST
LOAD.MASK	LOG	LOG.ERRORS
LONG	LOOKUP	LTRIM
MACRO	MACRO.FILE	MAP
MATCH	MEM	MENUEXIT
MERGE	MID	MOVE.FIELD
NEW.FORM	NEXT	NEXT.DIRECTORY
NO.EXPAND.MACRO	NTOW	NULL
NUMFIELDS	OCT	ON
ON.OR.AFTER	ON.OR.BEFORE	OPEN
OPERATOR	PAGE.SIZE	PARSE
PICK.LIST	PLURAL	POP
PRINT	PROGRAM	PUSH
PUT	PUT.MASK	RAD50
RANDOMIZE	READ	RENAME
REPEAT	RESET	RESTORE
RESUME	RETURN	RIGHT
RJUST	RND	RTRIM
RUNDOS	SET	SET.PARAMETER
SEVAL	SGN	SIGNIFICANCE
SIN	SLEEP	SORT.MEMORY
SOUNDSLIKE	SPACE	SQR
SQUEEZE	STATUS.LINE	STOP
STOP.MACRO	STR	STRING
STRIP	STRSIZ	STRUCTURE
SUBPROGRAM	SWITCH	SYSOPR
TAN	TIME	TRIM
UCS	UNTIL	USING
VAL	VDATE	VUE.WINDOW
WEND	WHEN	WHILE
WIPEBOX	WORD	WRITE
XCALL


Functions by Catagory
Function Catagories

   DBMS Interface

   Conditional Compilation Directives

   Macro Operations

   String Functions

   Math Functions

   Conversion Functions

   Date & Time Functions

   Execution/Control Operators

   I/O Functions

   Screen Interface Functions

   Error handling

   CRT/TCRT codes

   System Variables

   Miscellaneous Operators

   User defined functions


Generic DBMS Interface Functions
Generic DBMS Interface Statements

ADD.KEY	ADD.RECORD	CLOSE.FILE
DBMS.DEFINE	DBMS.EXIT	DELETE.KEY
DELETE.MEMO	DELETE.RECORD	FIELD.INFO
FILEBASE	FILE.INFO	FIND.KEY
GET.FIELD	GET.MEMO	GET.RECORD
GET.TAG.FIELD	INITIALIZE.FILE	LOCK.CONTROL
LOCK.FILE	LOCK.RECORD	LOCK.TO.SSD
NEXT.KEY	OPEN.FILE	OPEN.KEY.FILE
OPEN.MEMO.FILE	OPEN.TAG.FILE	PREVIOUS.KEY
PUT.FIELD	PUT.MEMO	PUT.RECORD
READ.RECORD	READ.UNLOCKED	UNLOCK.CONTROL
UNLOCK.FILE	UNLOCK.RECORD	WRITE.CONTROL
WRITE.EXCLUSIVE	WRITE.RECORD


DBMS Packet
Structure of DBMS packet
        1 BUFFER
                2 RECDNO,B,4
                2 FLAG1,B,4
                2 FLAG2,B,4
                2 FLAG3,B,4
                2 FLAG4,B,4
                2 FLAG5,B,4
                2 ERTN,B,4
                2 PORT,B,2
                2 FILLER,X,330
                2 FIELDS(128)
                        3 FNAME,X,6
                        3 FTYPE,B,1
                        3 FSIZE,B,1


Memo Pad Packet
Structure of Memo PAD packet
        1 BUFFER
                2 RECDNO,B,4
                2 FLAG1,B,4
                2 FLAG2,B,4
                2 FLAG3,B,4
                2 FLAG4,B,4
                2 FLAG5,B,4
                2 ERTN,B,4
                2 PORT,B,2
                2 FILLER,X,330


Key Packet
Structure of key packet
        1 BUFFER
                2 RECDNO,B,4
                2 FLAG1,B,4
                2 FLAG2,B,4
                2 FLAG3,B,4
                2 FLAG4,B,4
                2 FLAG5,B,4
                2 ERTN,B,4
                2 PORT,B,2
                2 FILLER,X,330


Tag Packet
Structure of tag packet
        1  TAGBUF
                2  NUMRECDS,b,4
                2  TAGRECNUM,b,4
                2  FIELDTYPE,b,4
                2  FIELDSIZE,b,4
                2  NUMFIELDS,b,4
                2  RECORDSIZE,b,4
                2  WHO,s,12
                2  TIME,s,6
                2  DATE,s,6
                2  FIELDNAME,s,10
                2  SUM(8)
                        3  SUMNAME,s,10
                        3  SUMVALUE,f,6
                2  INTERNAL,x,900


add.key
ADD.KEY Statement

     Syntax:  add.key {to} buffer {using} strexp {of} buffer2
Description:  Adds a key to a DBMS key file
    Example:  add.key to KEY'FILE_BUFFER using KEY'STRING of SALES'FILE_BUFFER

This statement causes the key strexp to be added to the DBMS key file specified by buffer.  buffer2 specifies the data file that the key belongs to and its RECDNO variable must contain the current record number.

Returns:  flag1  - 0 if successful


add.record
ADD.RECORD Statement

     Syntax:  add.record {to} buffer
Description:  Allocates a record from a DBMS file
    Example:  add.record to MAIL'LIST_BUFFER

This statement will cause a new record to be allocated from the DBMS file specified by buffer.  The new record will be cleared to zeroes and locked for exclusive use.  The RECDNO field of buffer will contain the record number of the new record.  If there are no more free records in the file, then the RECDNO field will be set to zero.


close.file
CLOSE.FILE Statement

     Syntax:  close.file buffer
Description:  Closes a DBMS file
    Example:  close.file cusmas_BUFFER

Closes the DBMS file specified by buffer.


dbms.define
DBMS.DEFINE Statement

     Syntax:  dbms.define name
Description:  Defines the GENERIC DBMS interface module to use.
    Example:  dbms.define ANDI

This statement defines the DBMS interface package to be used by d/BASIC for the processing of generic DBMS calls.  name is the one to six character name of the program to be used for the interface.  The actual program to be used will have an extension of ".SYS".

This example above will result in the ANDI.SYS interface package being used by the run time system.  The interface package is responsible for the conversion of parameters used in the d/BASIC program to those required by the file management software that you'll be using.  It is also responsible for error output.  The interface package must be located in memory before use by d/BASIC.

This is the only generic DBMS statement that does not require a memory buffer area as defined before.


dbms.exit
DBMS.EXIT Statement

     Syntax:  dbms.exit buffer
Description:  Performs any required clean-up functions for DBMS
    Example:  dbms.exit CUSMASTER_BUFFER

This statement performs any clean-up functions required by the DBMS when a program exits.


delete.key
DELETE.KEY Statement

     Syntax:  delete.key {from} buffer {using} strexp {of} buffer2
Description:  Deletes a key from a DBMS key file
    Example:  delete.key from KEY_BUFFER using KEY1 of TRX_BUFFER

This statement causes the key strexp to be deleted from the DBMS key file specified by buffer.  buffer2 specifies the data file that the key belongs to and its RECDNO variable must contain the current record number.

Returns:  flag1  - 0 if key not found, else non-zero


delete.Memo
DELETE.MEMO Statement

     Syntax:  delete.memo {from} buffer
Description:  Deletes a memo from a memo pad file
    Example:  delete.memo from CUSMAS_BUFFER

This statement causes the memo whose starting record number is in the RECDNO field of buffer to be deleted from the memo pad file described by buffer.


delete.record
DELETE.RECORD Statement

     Syntax:  delete.record {from} buffer
Description:  Deletes a record from a DBMS file
    Example:  delete.record from AR_BUFFER

This statement will cause the record whose record number is specified in the RECDNO field of buffer to be deleted from the DBMS file specified by buffer.  The record must have been locked by a previous READ.UNLOCKED or LOCK.RECORD statement.


field.info
FIELD.INFO Statement

     Syntax:  field.info {in} buffer {about} strexp
Description:  Retrieves information about a DBMS field
    Example:  field.info in NAMES_BUFFER about "ZIPCODE"

This statement causes the information about the DBMS field named strexp to be returned in the flag variables of buffer.  buffer specifies the name of the DBMS file which contains the field in which you have an interest.

Returns:
         flag2  - 0 if not found, else non-zero
         flag3  - length of field (unpacked)
         flag4  - field type:
                     1 - alphanumeric
                     2 - numeric
                     3 - floating point
                     4 - digits only
                     5 - alpha only
                     6 - binary
                     7 - RAD50
         flag5  - field number in record


filebase
FILEBASE Statement

     Syntax:  filebase exp
Description:  Sets the file access record number base offset
    Example:  filebase 1

The FILEBASE statement is used to set the value of the first record number of random access files.  This value defaults to zero.  Therefore, zero is normally the first record's number, one the second's, etc.  exp will set the new value for the file base value.  The example shown above sets it to one.  When this statement is executed the first record number of files will have a value of one.


file.info
FILE.INFO Statement

     Syntax:  file.info {about} buffer
Description:  Returns file statistics about a DBMS file
    Example:  field.info TRANACTIONS

Returns information about the DBMS file specified by buffer.

Returns:
         flag1  - number of allocated records (includes deleted)
         flag2  - number of unallocated records
         flag3  - number of records in active use
         flag4  - record size


find.Key
FIND.KEY Statement

     Syntax:  find.key {in} buffer {using} strexp
Description:  Searches for a key in a DBMS key file
    Example:  find.key in KEY_BUFFER using KEY'STRING

This statement causes strexp to be searched for in the DBMS key file specified by buffer.  Note that this statement will only return the first of any duplicate keys.  The NEXT.KEY statement must be used to locate the others.

Returns:
         flag1  0 = key not found,
                else key's data record #


get.field
GET.FIELD Statement

     Syntax:  get.field {of} buffer {named} strexp {into} variable
Description:  Retrieves a named field from a DBMS record
    Example:  get.field of NAMES_BUFFER named "ADDRESS" into INBUF

This statement causes the contents of the DBMS field named strexp to be transferred from the current record into the d/BASIC variable variable. buffer specifies the name of the DBMS file from which the data is to be retrieved.

Returns:
         flag2  - 0 if not found, else non-zero
         flag3  - length of field (unpacked)
         flag4  - field type:
                     1 - alphanumeric
                     2 - numeric
                     3 - floating point
                     4 - digits only
                     5 - alpha only
                     6 - binary
                     7 - RAD50
         flag5  - field number in record


get.memo
GET.MEMO Statement

     Syntax:  get.memo {from} buffer {into} variable
Description:  Retrieves a memo from a memo pad file
    Example:  get.memo from CUSMAS_BUFFER into MEMO'TEXT

This statement causes the contents of a memo whose starting record number is specified in the RECDNO field of buffer to be loaded into variable. buffer specifies the memo pad file from which the memo is to be retrieved. Each line of the memo will be terminated with a RETURN character.  The entire memo will be terminated by a null byte or the end of the variable.

Returns:
         flag1  - number of chars returned in variable
         flag2  - amount of unused space in variable


get.record
GET.RECORD Statement

     Syntax:  get.record {from} buffer {into} variable
Description:  Transfers data to variable(s) from DBMS memory
    Example:  get.memo from CUSMAS_BUFFER into REC'BUF

This statement will cause the data located in the internal DBMS record buffer to be transferred into the variable named variable in the d/BASIC program.  The DBMS file is specified by buffer.  The amount of data transferred is equal to the DBMS record size.


get.tag.field
GET.TAG.FIELD Statement

     Syntax:  get.tag.field buffer #exp {into} variable
Description:  Retrieves d/QL file field into local variable
    Example:  get.tag.field cusmas_BUFFER #2 into CUST'NAME

This statement retrieves one of three types of fields from the currently read tag record of the d/QL generated tag file specified by buffer.

The field number to retrieve is specified by exp.  If exp resolves to zero, the record number of data record from which the tag file record was created will be returned.  Otherwise it corresponds to the one of the fields in the EXTRACT statement in the d/QL program that generated the tag file.  The first field in the EXTRACT statement is field 1, the second is field 2, etc.

variable is the name of a variable which will receive the returned data.  The data that can be returned will either be of type string, float, or a four byte binary DBMS record number.

After the statement has been executed, various fields in buffer will contain information to help you figure what you have.

The FIELDTYPE field in buffer will contain the type of data returned in variable as follows:
         1 - string
         2 - floating point
         3 - DBMS record number

The FIELDNAME field of buffer will contain the name of the field that was retrieved.

The FIELDSIZE field of buffer will contain the maximum size of the data returned in variable.  Note that string fields will always be terminated by a null byte.


initialize.file
INITIALIZE.FILE Statement

     Syntax:  initialize.file buffer
Description:  Initializes a DBMS file
    Example:  initialize.file SALES_BUFFER

Initializes the file specified by buffer.  The interface must figure out the type of file being initialized.


lock.control
LOCK.CONTROL Statement

     Syntax:  lock.control buffer
Description:  Locks the control record for a DBMS file
    Example:  lock.control TRX_BUFFER

This statement will cause the control record to be read from the DBMS file specified by buffer.  It will then be locked for the exclusive use of the job doing the locking.  It can only be unlocked by a UNLOCK.CONTROL or WRITE.CONTROL statement.  Control record manipulation will rarely be transportable between DBMS's.


lock.file
LOCK.FILE Statement

     Syntax:  lock.file buffer
Description:  Locks a DBMS file for exclusive use
    Example:  lock.file TRX_BUFFER

Locks the DBMS file specified by buffer for the exclusive use of the job performing the call.


lock.record
LOCK.RECORD Statement

     Syntax:  lock.record {from} buffer
Description:  Reads and locks data record from a DBMS file
    Example:  lock.record sales_BUFFER

This statement is used to read a data record from the DBMS file specified by buffer.  The record will be locked for exclusive use by your job.  If it is currently locked by another job, your job will be put in a wait state until the record is available.  The RECDNO field in buffer must have been previously set.  Valid record numbers start at 1.

The LOCK.RECORD call only causes the record to be read into memory.  It does not transfer the contents of the data record into any d/BASIC variables.  It is necessary to perform a GET.RECORD call to perform this function.

 Returns:
         flag1  - 0 if deleted, 2 if at or past end of file
         flag2  - 0 if record successfully locked


lock.to.ssd
LOCK.TO.SSD Statement

     Syntax:  lock.to.ssd n
Description:  Requires a particular SSD to be installed
    Example:  lock.to.ssd 263

This directive is used to require the installation of a particular Software Security Device (SSD) in the machine before the program will be allowed to continue past the point of the LOCK.TO.SSD statement.

n in the statement is the SSD serial number.  Note that it must be a numeric constant (which can be defined using the DEF directive).  It is not a standard d/BASIC expression.

The serial number n covers a range of SSD's from different manufacturers as follows:

1 to 5000
Devices with serial numbers in this range are MCSDs as shipped with d/OS, ANDI, or SuperVUE.

501001 to 549999
Devices with serial numbers in this range are Alpha Micro SSD's as shipped already installed in their computers.  To convert your SSD number to a d/BASIC SSD number merely requires that you add 500000 to your SSD number.

The following example program demonstrates an easy way to make use of this statement:

         def SSDNUMBER=SWITCHVALUE
         lock.to.ssd SSDNUMBER

The program would then be compiled using the "/V" switch to specify an SSD number as in:

                 ) compil armenu/v:263

This is a hassle for a single program.  When only a single program is involved, it is easier to simply hardcode the SSD number in the program. The use of the definition and SWITCHVALUE really makes things easy when you have multiple programs that you want locked to the same SSD.


next.key
NEXT.KEY Statement

     Syntax:  next.key buffer {using} variable
Description:  Returns next sequential key in a DBMS key file
    Example:  next.key in KEY_BUFFER using KEY'STRING

This statement causes the next sequential key after variable to be returned in variable as well as its record number in flag1. buffer specifies the DBMS key file to be searched.  Set variable equal to "" to return the first key in the file.

 Returns:
         flag1  0 = no more keys in file
                key's data record #


open.file
OPEN.FILE Statement

     Syntax:  open.file buffer {named} strexp
Description:  Opens a DBMS data file
    Example:  open.file cusmas_BUFFER named "CUSMAS"

This statement opens a DBMS file using the memory area buffer.  The name of the file to open is specified by the string expression strexp.


open.key.file
OPEN.KEY.FILE Statement

     Syntax:  open.key.file buffer {named} strexp
Description:  Opens a DBMS key file
    Example:  open.key.file keys_BUFFER named "CUSTKEY"

This statement opens a DBMS key file using the memory area buffer.  The name of the file to open is specified by the string expression strexp.

 Returns:
         flag1  0 = duplicate keys allowed
                otherwise non-zero.


open.memo.file
OPEN.MEMO.FILE Statement

     Syntax:  open.memo.file buffer {named} strexp
Description:  Opens a memo pad file for processing
    Example:  open.memo.file CUSMAS_BUFFER named "CUSMAS"

This statement opens a memo pad file for processing using the buffer area specified by buffer.  The name of the file to open is specified by the string expression strexp.  The extension of the file is ".PAD".

The structure of buffer is standard with the exception that no field definitions are used.


open.tag.file
OPEN.TAG.FILE Statement

     Syntax:  open.tag.file buffer {named} strexp
Description:  Used to open a d/QL tag file for processing
    Example:  open.tag.file ORDREC_BUFFER named "ORDREC"

This statement opens a d/QL generated tag file using the memory area named buffer.  The name of the file to open is specified by the stringexpression strexp.  The default extension of the file is ".Dnn" where nn is your job number.

The TAGRECNUM field is the relative record number of the tagfile.  It can range in value from 1 to the value in the NUMRECDS field.  Information is retrieved from the tag file using the GET.TAG.FIELD statement.

If the file cannot be found or is in an incorrect format, the RECORDSIZE field will be set equal to zero.


Previous.key
PREVIOUS.KEY Statement

     Syntax:  previous.key {in} buffer {using} variable
Description:  Returns next previous key in a DBMS key file
    Example:  previous.key in KEY_BUFFER using KEY'STRING

This statement causes the next previous key before variable to be returned in variable as well as its record number in flag1.  buffer specifies the DBMS key file to be searched.

 Returns:
         flag1  - 0 = no more keys in file
                  record number of data record
                  belonging to the new key.


Put_Field
PUT.FIELD Statement

     Syntax:  put.field {to} buffer {named} strexp {from} variable
Description:  Stores a named field in a DBMS record
    Example:  put.field to NAMES_BUFFER named "CITY" from INBUF

This statement causes the contents of the DBMS field named strexp to be loaded from the d/BASIC variable variable.  buffer specifies the name of the DBMS file for which the data is to be stored.  The record must be locked for exclusive use before using this statement.


Put_Memo
PUT.MEMO Statement

     Syntax:  put.memo {to} buffer {from} variable
Description:  Outputs a memo to a memo pad file
    Example:  put.memo to CUSMAS_BUFFER from MEMO'TEXT

This statement causes the contents of variable to be written to the memo pad file specified by buffer.  If the RECDNO field of buffer is non-zero, it must be the starting record number of an existing memo.  Otherwise the memo will be added as a new memo to the file and the record number of the new memo will be returned in the RECDNO field.

Each line of the memo must be terminated with a RETURN character.  The entire memo must be terminated by a null byte or the end of the variable. If the memo text consists of only "white space" (blanks or RETURN characters), it will be deleted by the PUT.MEMO call.

 Returns:
         flag1  - 0 if the file is full and couldn't add
         flag2  - 1 if the memo was deleted by the call


Put_Record
PUT.RECORD Statement

     Syntax:  put.record {to} buffer {from} variable
Description:  Transfers data from variable(s) to DBMS memory
    Example:  put.record to MAIL'LIST_BUFFER from INTERNAL'RECORD

This statement will cause the data named by variable in the d/BASIC program to be transferred into the internal DBMS record buffer.  The record must be locked for exclusive use by your job.  The DBMS file is specified by buffer.  The old contents of the record will be overwritten by the contents of variable which is typically a STRUCTURE definition or a mapped variable list.  The amount of data transferred is equal to the DBMS record size.


read.record
READ.RECORD Statement

     Syntax:  read.record {from} buffer
Description:  Reads a data record from a DBMS file
    Example:  read.record GL'LEDGER

This statement is used to read a data record from the DBMS file specified by buffer.  The RECDNO field in buffer must have been previously set. Valid record numbers start at 1.  This call does not perform any exclusive use locking.

The READ.RECORD call only causes the record to be read into memory.  It does not transfer the contents of the data record into any d/BASIC variables.  It is necessary to perform a GET.RECORD call to perform this function.

 Returns:
         flag1  0 if deleted, 2 if at or past end of file


read.unlocked
READ.UNLOCKED Statement

     Syntax:  read.unlocked {from} buffer
Description:  Reads & locks unlocked data record
    Example:  read.unlocked sales_BUFFER

This statement is used to read a data record from the DBMS file specified by buffer.  The record will only be read if it is not locked for exclusive use by another job.  If read successfully, it will then be locked for exclusive use for your job.  The RECDNO field in buffer must have been previously set.  Valid record numbers start at 1.

The READ.UNLOCKED call only causes the record to be read into memory.  It does not transfer the contents of the data record into any d/BASIC variables.  It is necessary to perform a GET.RECORD call to perform this function.

 Returns:
         flag1  - 0 if deleted, 2 if at or past end of file
         flag2  - 0 if record successfully locked


unlock.control
UNLOCK.CONTROL Statement

     Syntax:  unlock.control buffer
Description:  Unlocks the control record for a DBMS file
    Example:  unlock.control TRX_BUFFER

This statement will cause the control record locked by a previous LOCK.CONTROL statement to be unlocked and made available for access by other jobs.  The DBMS file whose control record is to be unlocked is specified by buffer.


unlock.file
UNLOCK.FILE Statement

     Syntax:  unlock.file buffer
Description:  Unlocks a DBMS file previously locked using lock.file
    Example:  unlock.file aropen'buffer

Unlocks the DBMS file specified by buffer which has previously been locked by a LOCK.FILE statement.


unlock.record
UNLOCK.RECORD Statement

     Syntax:  unlock.record {of} buffer
Description:  Unlocks a DBMS data record
    Example:  unlock.record TRX_BUFFER

This statement is used to release the exclusive use record lock specified for the DBMS file named by buffer.  The record must have been locked by a previous READ.UNLOCKED or LOCK.RECORD statement.  The RECDNO field in buffer must have been previously set to the number of the record being unlocked.  Valid record numbers start at 1.  This call does not result in any file reads or writes.


write.control
WRITE.CONTROL Statement

     Syntax:  write.control buffer
Description:  Writes the control record for a DBMS file
    Example:  write.control TRX_BUFFER

This statement will cause the control record locked by a previous LOCK.CONTROL statement to be written back to the DBMS file specified by buffer.  The control record will then be unlocked.


write.exclusive
WRITE.EXCLUSIVE Statement

     Syntax:  write.exclusive {to} buffer
Description:  Writes the current data record to a DBMS file
    Example:  write.exclusive TRX_BUFFER

This statement is used to write the current data record to disk for the the DBMS file specified by buffer.  The record must have been locked by a previous READ.UNLOCKED or LOCK.RECORD statement.  The RECDNO field in buffer must have been previously set.  Valid record numbers start at 1.

The WRITE.EXCLUSIVE call only causes the record to be written from memory to the DBMS file.  It does not transfer the contents of the data record from any d/BASIC variables.  It is necessary to perform a PUT.RECORD call first to perform this function.  Unlike the WRITE.RECORD call, this call does not release the record lock.


write.record
WRITE.RECORD Statement

     Syntax:  write.record {to} buffer
Description:  Writes the current data record to a DBMS file
    Example:  write.record TRX_BUFFER

This statement is used to write the current data record to disk for the the DBMS file specified by buffer.  The record must have been locked by a previous READ.UNLOCKED or LOCK.RECORD statement.  The RECDNO field in buffer must have been previously set.  Valid record numbers start at 1.

The WRITE.RECORD call only causes the record to be written from memory to the DBMS file.  It does not transfer the contents of the data record from any d/BASIC variables.  It is necessary to perform a PUT.RECORD call first to perform this function.


Conditional Compilation Directives

 ELSEIF	ENDIF	IFDEF	IFEQUDEF
 IFEQUNOTDEF	IFFALSE	IFLABELDEF	IFLABELNOTDEF
 IFNOTDEF	IFTRUE	IFVARDEF	IFVARNOTDEF

     Syntax:  IFcond exp/name
Description:  Used to determine compilation action.
    Example:  IFtrue FLAG1

d/BASIC supports conditional compilation directives.  These directives can be used to control the production of code.  They are very useful in macro definitions.  As a matter of fact, some can only be used in macro definitions.  The standard formats for a conditional compilation directive are:

         IFcond exp/name,statement
 or:
         IFcond exp/name
                 statements
         {ELSEIF
                 statements}
         ENDIF

Where cond is the condition to be tested for.  exp is the expression or macro parameter that is used to determine the truth or falsity of the test. It may consist of numbers, DEF equates, and the operators *, +, -,  /, and % (modulus).  name is a variable, label, or equate name that can be tested for existance.

The condition is assumed to be true if exp evaluates to a non-zero value. If true, the statements in the first format will be compiled.  In the second format (multi-line), the first group of statements will be compiled and the second set ignored.  If the condition is false, then any optional ELSEIF statements will be compiled and the first group of statements will be ignored.

The various conditions that may be specified are:

TRUE.

Results in a true condition if exp evaluates non-zero.

FALSE.

Results in a true condition if exp evaluates zero.

DEF.

Can only be used in a macro.  It is used to determine if a macro parameter is defined in the statement that invokes the macro.  If the parameter is defined, a TRUE condition will result.

NOTDEF.

Can only be used in a macro.  It is used to determine if a macro parameter is defined in the statement that invokes the macro.  If the parameter is not defined, a TRUE condition will result.

NOTDEF varname.

Evaluates TRUE if the variable "varname" has been defined earlier in the program.

LABELDEF labelname.

Evaluates TRUE if the program label "labelname" has been defined earlier in the program.

VARNOTDEF varname.

Evaluates TRUE if the variable "varname" has not been defined earlier in the program.

LABELNOTDEF labelname.

Evaluates TRUE if the program label "labelname" has not been defined earlier in the program.

EQUDEF defname.

Evaluates TRUE if the equate defined as "defname" has been defined earlier in the program.

EQUNOTDEF varname.

Evaluates TRUE if the equate defined as "defname" has not been defined earlier in the program.

Examples:

         DEF AMOS=0

           ...

         iftrue AMOS

                 print "AMOS system"

         elseif

                 print "d/OS system"

         endif

Generates: print "d/OS system"

         iftrue AMOS-1,DEF sys=d/OS

When AMOS=0

Generates: DEF sys=d/OS

         IFvardef CUSTOMER, ++include CUSMAP

If the variable CUSTOMER is defined previously in the program, the file CUSMAP.BSI will be included in the compilation.

        macro type %sexp

                ifnotdef 0,print

                ifdef 0,print %0

        endmacro

        type

Generates: print

TYPE "Hi there"

Generates: print "Hi there"

The first example is a multi-line conditional construct.  The second is a single line.  And the last is two single line constructs that can only appear in a macro since they determine if a macro parameter has been defined.  Note that the last example could have been coded with a multi-line IF block, it just wasn't.

Note that the IFcond, ELSEIF, and ENDIF directives cannot be part of a multi-line statement.  They must appear on a line by themselves without labels or line numbers.  This restriction is true of all directives.


Macro Operations
dBasic Macro Operators

     Syntax:  macro text
Description:  Used to define user instructions.
    Example:  macro hithere %sexp

d/BASIC allows you to define your own instructions using its macro facility.
For example:

Definition:
  macro load mask %sexp INTO %var
        ifnotdef 1,set.parameter 1=INMAP
        xcall crt,1,%0,%1

  endmacro

Usage:
  load mask "OE" into INMAPB

Results:
  xcall crt,1,"OE",INMAPB

This macro defines a call to an XCALL assembly language subroutine.  The use of a macro can usually make the source code easier to read and maintain, especially when dealing with cryptic XCALLs.

All macros have a name which can consist of letters, digits, and the "." character.  Macros are defined in separate files from your d/BASIC source files.  The default extension of the macro source files is ".MSC" (for Macro Source Code).

A macro definition consists of two parts.  The first part is the definition of the statement's syntax.  This is called the template.  The second part of the macro definition consists of the actual d/BASIC instructions that will be compiled when the macro is used.  This second part is referred to as the macro body.

The macro syntax is a mixture of key words or parameter type definitions. Optional items in the syntax are enclosed within braces ("{}").  The type definitions of the parameters may be one of the following:

      %exp     - general expression (numeric or string).
      %sexp    - string expression.
      %nexp    - numeric expression.
      %rsexp   - string expression required.
      %rnexp   - numeric expression required.
      %const   - numeric constant required.
      %sconst  - string constant
      %var     - variable of any type required.
      %svar    - variable of string type (S or X) required.
      %nvar    - variable of numeric type (B or F) required.
      %fvar    - variable of floating point type (F) required.
      %xvar    - variable of unformatted type (X) required.
      %bvar    - variable of binary type (B) required.
      %bvar1   - variable of binary type (B) size 1 required.
      %bvar2   - variable of binary type (B) size 2 required.
      %bvar3   - variable of binary type (B) size 3 required.
      %bvar4   - variable of binary type (B) size 4 required.
      %bvar5   - variable of binary type (B) size 5 required.
      %varlist - variable list (eg, v1,v2,v3)
      %label   - program label/function name

You now need a way to reference the passed parameters in the macro body.  This is done using macro parameter references which are numbered:%0, %1, ..., %9 (ten of them).  "%0" corresponds to the first defined parameter in the macro template, "%1" refers to the second, etc.
What if you want to use the "%" character in statement in the macro body?  Simple.  Just use two in a row as in: "%%".

When the d/BASIC compiler processes the macro body, it will replace any parameter references with the actual parameter used by the programmer in the source code.  Example:

Macro definition in ".MSC" file:
     macro type2 %sexp %nexp
           print %0,%1
           print "50%%"
     endmacro

Usage in your ".BAS" file:
     type2 "Hello" 2*3

Results in the following lines being compiled:
     print "Hello",2*3
     print "50%"

In this macro example there are two parameters.  "%0" is a string expression type (%sexp).  "%1" is a numeric expression type (%nexp).  When the macro is invoked above, "%0" is replaced by "Hello" and "%1" is replaced by "2*3".  The generated text that actually gets compiled is "print "Hello",2*3".

You should be aware that macros may appear within other macros (to a level of 16 deep).  The parameters (and their definitions) will not interfere with one another.

Normally you will not see what the macros expand to listing your programs with either the "/T" or "/L" switches.  The same goes for the debugger.  You must use the new switch "/X" to produce the expanded macros.  The "/X" switch will be ignored if any of the macro files you are using are SSD encoded.

Conditional compilation IFcond blocks can be very useful in generating the actual statements to be compiled.  Keep in mind that a macro is really a template or pattern for your own instruction.

You can define the value of macro parameters using the SET.PARAMETER directive

Using the MACRO File Compiler

The macro compiler program is named MC.LIT and is used to compile macro source code files into files usable by the d/BASIC compiler.  The format of the MC command is:

    .mc filespec/s:n

Where filespec is the name of the input source file (default extension ".MSC") and /s is an optional switch.  If defined, n is the number of the MCSD or SSD which the macro file will be locked to.  n must conform o the d/BASIC conventions of numbering SSDs and MCSDs (see LOCK.TO.SSD  ).  Examples:

     .mc test
     .mc oe/s:509001

The lines of text within a macro program may be one of the following:

A comment line.

This is any line beginning with a "!" character.

A blank line.

MACRO syntax

This line defines the beginning of a macro template.  "syntax" is the syntax of the macro.

END MACRO

This line defines the end of macro definition.

SSD n

This line defines the SSD or MCSD that the macro file will be locked to (same as the "/S" switch).

VERSION x

Defines the version number for the file header of the output ".MAC" file.  "x" is the version number in the standard AMOS format.

END

This optional line defines the end of the file.

The MC program compiles the ".MSC" file into a ".MAC" file which is then used by the d/BASIC compiler (COMPIL.LIT) when defined by the programmer using the MACRO.FILE directive.

See also:

expand.macro 	macro.file 	no.expand.macro 	set.parameter 	stop.macro


macro.file
MACRO.FILE Statement

     Syntax:  macro.file filespec
Description:  Used to load a macro file to use.
    Example:  macro.file CRTMAC

This directive is used to load a compiled d/BASIC macro file  (as compiled using the MC program).  filespec is the file specification of the macro file which has a default extension of .MAC.  Multiple macro.file directives may appear in the same program.  Note that if you define a macro with the same name in more than one file (or the same file for that matter), only the first one will be recognized.  filespec must be a constant and not a string expression as macro.file is a compiler directive.


expand.macro
EXPAND.MACRO Statement

     Syntax:  expand.macro
Description:  Used to re-enable macro recognition and expansion
    Example:  expand.macro

Use of this directive reenables macro recognition.  This is the default case and this directive is only needed if the NO.EXPAND.MACRO directive has been used previously.


no.expand.macro
NO.EXPAND.MACRO Statement

     Syntax:  no.expand.macro
Description:  Used to disenable macro recognition and expansion
    Example:  no.expand.macro

Use of this directive disables all macro recognition and stops the expansion of any currently active macros.


set.parameter
SET.PARAMETER Statement

     Syntax:  set.parameter n=text
Description:  Used to define macro parameter text.
    Example:  set.parameter 0="Account"

This directive is used to define the text for macro parameter n as text. This is usually used in conjunction with the IFNOTDEF directive to define default parameters.

     set parameter n=text

Where n is the number of the parameter to set equal to text.  This directive is frequently paired with conditional compilation statements as in the following example:

     macro load mask %sexp {INTO} %xvar
           ifnotdef 1, set.parameter 1=INMAP
           xcall crt,1,%0,%1
     end macro

If the "%1" variable is not defined ("%xvar"), the SET.PARAMETER directive will set it equal to "INMAP".  This is a handy way to default parameter values.  Note the optional "INTO" keyword.

We did not specify the special parameter lead-in character in either the IFNOTDEF or SET.PARAMETER directives since we do not want macro parameter expansion to occur in these directives.


stop.macro
STOP.MACRO Statement

     Syntax:  stop.macro
Description:  Used to stop the current macro from further expansion
    Example:  stop.macro

Use of this directive causes the immediate end to the expansion of the current macro.  It does not affect any other macros that the current macro is contained in.


dBasic date functions
Date and Time Functions

Date Relational Operators

Age
Date
Daynumber
Julian
Juliantodate
Vdate

Time functions
dechr
hrdec
Time


Date Relational Operators

Syntax: exp1 RELOP exp2

The four date relational operators (RELOP) are:

         exp1 AFTER exp2
         exp1 BEFORE exp2
         exp1 ON.OR.AFTER exp2
         exp1 ON.OR.BEFORE exp2

return TRUE if after comparing the two expressions exp1 and exp2 meet the relational test.  Both expressions are assumed to be numeric dates in the format MMDDYY.  Examples:

         110954 before 100467    <- returns TRUE
         100467 after 101989     <- returns FALSE


About
The ABOUT Operator

Syntax: exp1 ABOUT exp1

Relational operator that returns TRUE if the exp1 is within + or - 10% of the second.  Example: 9 about 10 is TRUE.  2 about 5 is not.


Age()
The AGE Function

Syntax: age(exp1,exp2)

AGE returns the number of days between date exp1 and date exp2.  AGE assumes that exp1 and exp2 are in the format MMDDYY or DDMMYY depending on whether or not european date format is being used.  Note that the ".date" variable returns the date in the correct format and the d/BASIC function "date" does not.  Example:

   today's date is: 021488
   age(.date,022188)    ! returns 7
   age(120188,112988)   ! returns 2


System Functions

There are a number of what are known as "system functions" that may be used in d/BASIC programs.  They are not like other functions although their use can be similar.

System functions can appear as part of an expression or on the left side of the equal sign.  They do not all require parameters or parentheses as do normal functions.

The d/BASIC system functions are:

TIME

Returns the system time as a totally useless number.  This function is only provided for compatibilty with older programs.  Use the system variables for more usable formats of the system time.  You must have system operator privileges for TIME to appear on the left side of the equal sign (which will change the system time).

DATE

Returns the system date as a totally useless number.  This function is only provided for compatibilty with older programs.  Use the system variables for more usable formats of the system date.  You must have system operator privileges for DATE to appear on the left side of the equal sign (which will change the system date).

IO(x)

Allows you to read or write directly to I/O location x.  You must have system operator privileges to use this function.  The location is read when IO(x) appears in an expression.  The location is written when it appears on the left side of the equal sign.

BYTE(x)

Allows you to read or write the byte at memory address x.  You must have system operator privileges to use this function.  The byte is read when BYTE(x) appears in an expression.  The byte is written when it appears on the left side of the equal sign.

WORD(x)

Allows you to read or write the word at memory address x.  You must have system operator privileges to use this function.  The word is read when WORD(x) appears in an expression.  The word is written when it appears on the left side of the equal sign.

LONG(x)

Allows you to read or write the long word (32 bits) at memory addressx.  You must have system operator privileges to use this function.  Thelong word is read when LONG(x) appears in an expression.  The long word iswritten when it appears on the left side of the equal sign.


Daynumber()
The DAYNUMBER Function

Syntax: daynumber(exp)

This function returns the day number of the year for the date specified by exp.  The date format of exp is mmddyy or ddmmyy depending on system date format.  Example:

   daynumber(052589)  ! returns 145


Julian()
The JULIAN Function

Syntax: julian(exp)

JULIAN returns a numeric value which is the Julian date number of exp which is a date in the format "MMDDYY".  Examples:

    julian(110954)     ! returns 2435056
    julian(100467)     ! returns 2439768


JuliantoDate()
The JULIANTODATE Function

Syntax: juliantodate(exp)

JULIANTODATE returns a numeric value which is the normal date representation of the julian day number specified by exp.  The date is returned in the format "MMDDYY".  Examples:

   juliantodate(2435056) ! returns 110954
   juliantodate(2439768) ! returns 100467


VDate()
The VDATE Function

Syntax: vdate(strexp)

The VDATE function will validate the six character string expression strexp as a date in either the format "MMDDYY" or "DDMMYY" depending on the date format recognized by your system.  It will return zero if the date is not a valid date, otherwise it will return a floating point number representing the date.  The format of the returned number will be "YYMMDD" for easy comparison.  Examples:

   vdate("110954")   ! returns 541109
   vdate("130188")   ! returns 0 - not a valid date


Dechr()
The DECHR Function

Syntax: dechr$(exp)

DECHR$ reverses the action of the HRDEC function.  The numeric expression exp will be converted to a string in the format "hh:mm:ss" in 24 hour format (no AM or PM).  exp represents a number of seconds.  Examples:

    dechr$(43200)     ! returns "12:00"
    dechr$(64800)     ! returns "18:00"


Hrdec()
The HRDEC Function

Syntax: hrdec(strexp)

HRDEC converts the time of day string strexp (format: hh:mm:ss xM) into a value representing a fraction of a day.  Multiple by 86400 to determine the exact second.  Examples:

    hrdec("12:00")   ! returns .5
    hrdec("6:00 PM") ! returns .75


SysVars
System Variables

.account	(string)  logged in account number

.applevelnn	(float)   Logged in application levels (nn = 00-19)

.branch	(string)  logged in branch code

.companycode	(string)  logged in companycode

.companyname	(string)  logged in company name

.date	(float)   today's date as MMDDYY (or DDMMYY)

.day	(string)  name of the day of the week

.device	(string)  logged in device

.division	(string)  logged in division code

.dosversion	(string)  OS version number

.dow	(float)   the day of the week number (1-7)

.experience	(float)   experience level

.initials	(string)  logged in initials

.jobname	(string)  job name

.jobnumber	(float)   relative job number

.lastlogon	(float)   last logon date in YYMMDD format

.length	(float)   terminal length in rows

.level	(float)   user level

.logondate	(float)   date logged in

.logontime	(float)   time logged in

.month	(string)  name of the current month

.newmail	(float)   new mail flag (1 = new mail avaialable)

.options	(string)  The rest of the comand line when RUN was invoked (switches etc..)

.osname	(string)  returns "d/OS", "AMOSL", or "AMOS32" depending upon the OS currently running

.pgmname	(string)  name of your program

.pgmversion	(string)  version number of your program

.rootaccount	(string)  home account

.rootdevice	(string)  home device

.securitylevel	(float)   logged in security level

.serialnumber	(string)  System serial number

.systemname	(string)  name of system

.terminal	(string)  terminal name

.time	(float)   current time as HHMMSS

.username	(string)  logged in user name

.width	(float)   terminal width in columms

.yymmdd	(float)   todays date in YYMMDD format


String Functions

 ASC	AUTOCAP	CENTER
CHR	CONTAINS	DUPSTR
EVAL	FILESPEC	INSTR
LCS	LEFT	LEN
LIKE	LJUST	LTRIM
MATCH  	MERGE  	MID
NTOW  	NULL	PARSE
PLURAL	RIGHT	RJUST
RTRIM  	SEVAL  	SOUNDSLIKE
SPACE	SQUEEZE  	STRIP
STRSIZ  	TRIM  	UCS


Asc
The ASC Function

Syntax: asc(strexp)

ASC returns the ASCII value of the first character of the string expression strexp.

    asc("A")        ! returns 65
    asc("a")        ! returns 97


Autocap
The AUTOCAP Function

Syntax: autocap$(strexp)

The AUTOCAP$ function will return strexp with the first letter of each word capitialized as well as letters preceeded by a period (".").  All other letters will be made lower case.  Example:

    autocap$("IM A. HOGG")  ! returns "Im A. Hogg"
    autocap$("hi there")    ! returns "Hi There"


Center
The CENTER Function

Syntax: center$(strexp,exp)

CENTER$ will center the string expression strexp in a window of size exp.  Sufficient space characters will be added to the beginning of strexp to effect this.  If the length of strexp is larger than exp, strexp will be truncated to fit.

    center$("Hi",6)  ! returns "  Hi"
    center$("A",7)   ! returns "   A"


Chr
The CHR Function

Syntax: chr$(exp)

CHR$ converts its numeric expression exp to a single character string.

    chr$(13)        ! returns a RETURN character
    chr$(65)        ! returns "A"


Contains
The CONTAINS Operator

Syntax: sexp1 CONTAINS sexp2

Relational operator that returns TRUE if the string expression sexp1 contains the substring represented by the string expression sexp2.  Example:

    "abcdef" contains "bcd"

returns TRUE as "bcd" is found in the first string.


Dupstr
The DUPSTR Function

Syntax: dupstr$(strexp,exp)

DUPSTR$ returns the string expression strexp duplicated exp number of times.  Examples

   dupstr$("-+",4)   ! returns "-+-+-+-+"
   dupstr$("-",6)    ! returns "------"


EVAL
The EVAL Function

Syntax: eval(strexp)

The EVAL function is used to evaluate the string expression strexp which represents a standard d/BASIC expression.  It will return either the result of the evaluation or zero if an error in the processing of the expression is detected.  The code of any detected error is retrieved using the ERR(4)  function.  Example:

   input line "Expression:",a$
   print eval(a$)
   if err(4)<>0 goto got'an'error

All standard elements of a normal d/BASIC expression may be used with the following two exceptions:

The functions EVAL and SEVAL cannot be used in the processed expression.  EVAL and SEVAL are not recursive.

You do not have access to the variables in the program running.

EVAL supports its own variable structure.  Variables that may be used in expressions are named with a single letter optionally followed by a number from 0 to 1023.  Letter case is ignored.  Examples:

   A0
   A  (same as A0)
   Z120

A variable may be either a string or floating point type.  A string variable is specified by following the name of the variable with a $ character as in D40$ or F$.  String variables may by 1-32 characters in size.

Variables are defined and initialized to zero when you use a variable in an expression to be evaluated by the EVAL function.  Note that when you use a variable such as A4; A0, A1, A2, and A3 are automatically created also.  The number in the variable name is really an array subscript.

Variables can be set to values using the format:

   varname = expression

Which is the standard assignment statement of d/BASIC.  The "+=" type of convenience operators are also allowed.

EVAL() function now allows you to specify an IF operator as part of the expression being evaluated.

The format is: if exp1 then exp2 else exp3.  The value of the expression exp2 will be returned as the value of the function if exp1 evaluates true (using standard d/BASIC IF statement rules).

Otherwise the value of the exp3 expression will be returned if it is defined, if not defined - zero or the null string will be returned.  Example:

   if a>10 then b=b/a else b=1


Filespec
The FILESPEC Function

Syntax: filespec$(sexp1,sexp2)

The FILESPEC$ function validates the string expression sexp1 as an AMOS file specification with the possible default file name extension defined as expression sexp2.  It returns the resultant string as its result or the null string if an error occurred.  If sexp2 is a null string, then no default extension will be used.  Examples:

   filespec$("ABC","LST")  ! returns "ABC.LST"
   filespec$("ABC","")     ! returns "ABC"


Instr
The INSTR Function

Syntax: instr(exp,strexp1,strexp2)

The INSTR function is used to determine if the string expression strexp2 occurs within the string expression strexp1.  INSTR starts its search in strexp1 at position exp.  Examples:

   instr(1,"ABC","BC")    ! returns 2
   instr(2, "ABCDEF, "D") ! returns 4


Lcs
The LCS Function

Syntax: lcs(strexp)

LCS converts the string expression strexp to its lower case equivalent string.  Examples:

    lcs("HI BOZO")   ! returns "hi bozo"
    lcs("YES")       ! returns "yes"


Left
The LEFT Function

Syntax: left$(strexp,exp)

LEFT$ returns the leftmost exp characters of the string expression strexp.  Note that this is the equivalent of the sub-string strexp[1,exp]. LEFT$ is provided primarily for compatibility with other dialects of BASIC. Examples:

   left$("ABC",2)   ! returns "AB"
   left$("ABC",1)   ! returns "A"


Len
The LEN Function

Syntax: len(strexp)

LEN returns the length of the string expression strexp.  It is recommended that you use the LEN function to determine if a string is empty (length equal to zero) rather than comparing it to spaces or the null string (""). Examples:

   len("")          ! returns 0
   len("ABC")       ! returns 3


LIKE
The LIKE Operator

Syntax: sexp1 LIKE sexp2

Relational operator that returns TRUE if the string expression sexp1 "sounds like" the string expression sexp2.  The two expressions will be converted to a Soundx-like code which will then be compared for equality.

Example:

   if "Smith" like "Symthe" goto pretentious

see also SOUNDSLIKE


Ljust
The LJUST Function

Syntax: ljust$(strexp,exp)

LJUST$ will left justify the string expression strexp in a window of size exp.  Sufficient space characters will be added to the end of strexp to effect this.  If the length of strexp is larger than exp, strexp will be truncated to fit.  The resulting string expression's length will always be exp.

   ljust$("Hi",6)      ! returns "Hi    "
   ljust$("There",6)   ! returns "There "


Ltrim
The LTRIM Function

Syntax: ltrim$(strexp)

The LTRIM$ function strips leading spaces from the string expression strexp.  Examples:

   ltrim$("   1234")   ! result is "1234"
   ltrim$(" ABC")      ! returns "ABC"


Match
The MATCH Operator

Syntax: sexp1 MATCH sexp2

Relational operator that returns TRUE if the possibly wildcarded string expression sexp1 matches the string expression sexp2.  The special wildcard characters that may appear in sexp1 are:

  ? This character will match any character in the corresponding position of   the second string.

  # This character will only match a numeric digit in the second string in the   same position.

  @ This character will only match an alphabetic character in the second string  in the same position.

  SPACE This character will match one or more spaces and tabs in the second string.

  * This character will match the rest of the second string.

Any other character in the first string must match the character in the corresponding position of the second string.  Example:

     if "AB*" match a$ goto we'got'it

This will be true if a$ starts with the characters AB.


Merge
The MERGE Function

Syntax: merge$(strexp1,strexp2)

MERGE$ will merge strexp1 and strexp2 and return the resulting string as a the value of the function.  strexp1 is considered the controlling mask.  Every instance of the character "#" in strexp1 will be replaced by a character in strexp2 working from left to right.  Characters other than "#" will be passed directly to the output string.  Examples:

   merge$("###-##-####","137232786")  ! returns "137-23-2786"
   merge$("##/##/##", "110954")       ! returns "11/09/54"


Mid
The MID Function

Syntax: mid$(strexp,exp1,exp2)

MID$ returns a sub-string of the string expression strexp starting at position exp1 for a length of exp2 characters.  Note that this is the equivalent of the sub-string strexp[exp1;exp2].  MID$ is provided primarily for compatibility with other dialects of BASIC.  Examples:

   mid$("ABCDEF",2,3)   ! returns "BCD"
   mid$("ABCDEF",3,2)   ! returns "CD"


Ntow
The NTOW Function

Syntax: ntow$(exp)

NTOW$ (numbers to words) returns a string which represents the value of exp in words.  NTOW$ will not process any decimal values (101 and 101.5 will be processed as 101).  Negative values will be treated as positive ones.  Examples:

   ntow$(101)     ! returns "one hundred one"
   ntow$(15)      ! returns "fifteen"


Parse
The PARSE Function

Syntax: parse$(strexp)

PARSE$ returns the first "word" of the string expression strexp.  The first word is defined as the first group of non-blank characters followed by a blank, tab, punctuation character (",.!?;:"), or end of string.  Examples:

   parse$("ab cd")          ! returns "ab"
   parse$("Emmet T. Frog")  ! returns "Emmet"


Plural
The PLURAL Function

Syntax: plural$(strexp,exp)

PLURAL$ is used to avoid that idiotic lazy programmer statement  "1 errors detected".  PLURAL$ returns a string which is exp followed by strexp which will be properly pluralized.  Example:

   plural$("copy",x)

   x = ?    Returned string
       0    No copies
       1    1 copy
       2    2 copies


Right
The RIGHT Function

Syntax: right$(strexp,exp)

RIGHT$ returns the rightmost exp characters of the string expression strexp.  Note that this is the equivalent of the sub-string strexp[-1;-exp].  RIGHT$ is provided primarily for compatibility with other dialects of BASIC.  Examples:

   right$("ABC",2)   ! returns "BC"
   right$("ABC",1)   ! returns "C"


Rjust
The RJUST Function

Syntax: rjust$(strexp,exp)

RJUST$ will right justify the string expression strexp in a window of size exp.  Sufficient space characters will be added to the beginning of strexp to effect this.  If the length of strexp is larger than exp, strexp will be truncated to fit.  The resulting string expression's length will always be exp.

   rjust$("Hi",6)      ! returns "    Hi"
   rjust$("There",6)   ! returns " There"


Rtrim
The RTRIM Function

Syntax: rtrim$(strexp)

RTRIM$ returns the string expression strexp minus any ending space characters.  Examples:

    rtrim$("  Emmet  ")   ! returns "  Emmet"
    rtrim$("   ")         ! returns ""


Seval
The SEVAL Function

Syntax: seval$(strexp)

The SEVAL function is used to evaluate the string expression strexp which represents a standard d/BASIC expression.  It will return either the result of the evaluation or a null string if an error in the processing of the expression is detected.  The code of any detected error is retrieved using the ERR(4) function.  Example:

   input line "Expression:",a$
   print seval(a$)
   if err(4)<>0 goto got'an'error

All standard elements of a normal d/BASIC expression may be used with the following two exceptions:

The functions EVAL and SEVAL cannot be used in the processed expression.  EVAL and SEVAL are not recursive.

You do not have access to the variables in the program running.

SEVAL supports its own variable structure.  Variables that may be used in expressions are named with a single letter optionally followed by a number from 0 to 1023.  Letter case is ignored.  Examples:

    A0
    A  (same as A0)
    Z120

A variable may be either a string or floating point type.  A string variable is specified by following the name of the variable with a $ character as in D40$ or F$.  String variables may by 1-32 characters in size.

Variables are defined and initialized to zero when you use a variable in an expression to be evaluated by the EVAL function.  Note that when you use a variable such as A4; A0, A1, A2, and A3 are automatically created also.  The number in the variable name is really an array subscript.

Variables can be set to values using the format:

    varname = expression

Which is the standard assignment statement of d/BASIC.  The "+=" convenience operator is also allowed.

SEVAL$() function now allows you to specify an IF operator as part of the expression being evaluated.

The format is: if exp1 then exp2 else exp3.  The value of the expression exp2 will be returned as the value of the function if exp1 evaluates true (using standard d/BASIC IF statement rules).

Otherwise the value of the exp3 expression will be returned if it is defined, if not defined - zero or the null string will be returned.  Example:

    if a>10 then b=b/a else b=1


Soudslike
The SOUNDSLIKE Function

Syntax: soundslike$(strexp)

SOUNDSLIKE$ will return the compressed "Sound's-like" code of strexp as a 1 to 4 digit string.  Examples:

   soundslike$("Smith")    ! returns "S23"
   soundslike$("Mike")     ! returns "M2"
also LIKE


Space
The SPACE Function

Syntax: space$(exp)

SPACE$ returns a string expression of exp space characters.  Examples:

    space$(4)   ! returns "    "
    space$(1)   ! returns " "


Squeeze
The SQUEEZE Function

Syntax: squeeze$(strexp)

SQUEEZE$ returns the string expression strexp stripped of multiple blank characters.  That is, all multiple blank characters are made into a single space.  Examples:

    squeeze$("a   b     c")  ! returns "a b c"
    squeeze$(" 1   2 ")      ! returns " 1 2 "


Strip
The STRIP Function

Syntax: strip$(strexp)

STRIP$ is will remove all non-numeric characters from the string expression strexp.  Examples:

    strip$("11/09/54")      ! returns "110954"
    strip$("Im A. Hogg")    ! returns ""


Strsiz
The STRSIZ Function

 Syntax:      strsiz n
 Description: Defines size of unmapped string variables
 Example:     strsiz 20

The STRSIZ directive is used to define the size of any variables that are not defined using the MAP directive.  The size of the variables is defined by n.  n is an integer that can range in value from 1 to 32767.  The default string size is 32.


Trim
The TRIM Function

Syntax: trim$(strexp)

TRIM$ returns the string expression strexp minus any beginning and ending space characters.  Examples:

    trim$("  Emmet  ")   ! returns "Emmet"
    trim$("Hi  ")        ! returns "Hi"


Ucs
The UCS Function

Syntax: ucs(strexp)

UCS converts the string expression strexp to its upper case equivalent string.  Examples:

    ucs("hi bozo")   ! returns "HI BOZO"
    ucs("yes")       ! returns "YES"


NULL
The NULL Statement

Syntax: null$(exp)

NULL$ returns a string of exp null characters.  This function is primarily used to clear unformatted variables to zero byte values.  Examples:

   null$(10)      ! returns 10 null bytes
   null$(a+1)     ! returns a+1 null bytes


Math functions
Math & Artithmetical Funcions

ABS	ACS	ASN
ATN	COS	DATN
EXP	FACT	FIX
FRAC	INT	LOG
RND	SGN	SIN
SQR	TAN


ABS
The ABS Function

Syntax: abs(exp)

The ABS function returns the absolute value of exp.  The net effect of ABS is to return as its value the positive equivalent of exp.  Examples:

   abs(1)          ! returns 1
   abs(-2)         ! returns 2


ACS
The ACS Function

Syntax: acs(exp)

ACS returns the inverse cosine of exp in radians.  Examples:

   acs(.5)     ! returns 1.0471975512
   acs(.75)    ! returns .72273424781


ASN
The ASN Function

Syntax: asn(exp)

ASN returns the inverse sine of exp in radians.  Examples:

   asn(.5)     ! returns .5235987756
   asn(.75)    ! returns .84806207898


ATN
The ATN Function

Syntax: atn(exp)

ATN returns the inverse tangent of exp in radians.  Examples:

    atn(.5)     ! returns .463647609
    atn(.75)    ! returns .64350110879


COS
The COS Function

Syntax: cos(exp)

COS returns the cosine of exp in radians.  Examples:

    cos(45)     ! returns .52532198881
    cos(75)     ! returns .92175126973


DATN
The DATN Function

Syntax: datn(exp1,exp2)

DATN returns the value ATN(exp1/exp2) if exp2 does not equal zero. Otherwise it will return SGN(exp1)*(pi/2).  Examples:

   datn(10,20)   ! returns .463647609
   datn(90,135)  ! returns .58800263335


EXP
The EXP Function

Syntax: exp(exp)

EXP returns the value of e^exp.  Examples:

   exp(1)      ! returns 2.7182818285
   exp(2)      ! returns 7.3890560989


FIX
The FIX Function

Syntax: fix(exp)

FIX returns the integer part of exp.  Examples:

   fix(1.23)   ! returns 1
   fix(-3.141) ! returns -3


FRAC
The FRAC Function

Syntax: frac(exp)

FRAC returns the fractional part of exp.  Examples:

    frac(1.23)       ! returns .23
    frac(-3.141)     ! returns -.141


FACT
The FACT Function

Syntax: fact(exp)

FACT returns the factorial of exp.  The factorial of 3 is 6 (1x2x3).  The factorial of 4 is 24 (1x2x3x4).  Examples:

   fact(5)          ! returns 120
   fact(2)          ! returns 2


INT
The INT Function

Syntax: int(exp)

INT rounds exp to the next lowest integer.  It is similar in operation to the FIX function except in regards to negative expressions.  Examples:

   int(1.23)        ! returns 1
   int(-3.141)      ! returns -4


RND
The RND Function

Syntax: rnd(exp)

RND is used to return the next number from the d/BASIC pseudo-random number generator.  If exp is negative, it will be used as the new random number seed before returning the next number in sequence.  d/BASIC will always return the same sequence of numbers from the same seed.  The number returned is always between 0 and 1.  The RANDOMIZE statement should be used to randomly generate a new seed.  Examples:

   rnd(0)   ! returns a number
   rnd(-1)  ! sets seed and returns #


SGN
The SGN Function

Syntax: sgn(exp)

SGN returns as its value the sign of exp.  It will return -1 if exp is negative, 0 if exp is 0, or 1 if exp is positive.  Examples:

    sgn(4.2)      ! returns 1
    sgn(-231)     ! returns -1


SIN
The SIN Function

Syntax: sin(exp)

SIN returns the sine of exp in radians.  Examples:

   sin(45)     ! returns .85090352454
   sin(75)     ! returns-.38778163541


SQR
The SQR Function

Syntax: sqr(exp)

SQR returns the square root of exp.  Examples:

    sqr(2)          ! returns 1.4141
    sqr(36)         ! returns 6


TAN
The TAN Function

Syntax: tan(exp)

TAN returns the tangent of exp in radians.  Examples:

   tan(45)     ! returns 1.6197751906
   tan(75)     ! returns-.42070095062


LOG
The LOG Function

Syntax: tan(exp)

Syntax: log(exp)

LOG returns the natural logarthimic value of exp (ln x).  Examples:

   log(50)     ! returns 3.9120230054
   log(100)    ! returns 4.605170186


Conversion Functions
String/Numeric Conversion Functions

BIN	CVTBIN	CVTHEX
CVTOCT	HEX	OCT
RAD50	STR	VAL


Bin$()
The BIN Function

Syntax: bin$(exp)

BIN$ converts its numeric expression exp to its binary equivalent string.  Examples:

    bin$(5)         ! returns "101"
    bin$(127.23)    ! returns "1111111"


Cvtbin()
The CVTBIN Function

Syntax: cvtbin(strexp)

CVTBIN is used to return the value of the string expression strexp which represents a binary number.  Examples:

    cvtbin("101")      ! returns 5
    cvtbin("10000")    ! returns 16


Cvthex()
The CVTHEX Function

Syntax: cvthex(strexp)

CVTHEX is used to return the value of the string expression strexp which represents a hexadecimal number.  Examples:

   cvthex("1A")       ! returns 26
   cvthex("D")        ! returns 13


Cvtoct()
The CVTOCT Function

Syntax: cvtoct(strexp)

CVTOCT is used to return the value of the string expression strexp which represents an octal number.  Examples:

   cvtoct("377")      ! returns 255
   cvtoct("40")       ! returns 32


Hex$()
The HEX Function

Syntax: hex$(exp)

HEX$ converts its numeric expression exp to its hexadecimal equivalent string.  Examples:

   hex$(15)        ! returns "F"
   hex(127)        ! return "7F"


Oct$()
The OCT Function

Syntax: oct$(exp)

OCT$ converts its numeric expression exp to its octal equivalent string.  Examples:

   oct$(15)        ! returns "17"
   oct$(127.23)    ! returns "177"


Rad50$()
The RAD50 Function

Syntax: rad50$(exp)

RAD50$ returns the ASCII three character string represented by the numeric expression exp.  Examples:

   rad50$(&h1C03)    ! returns "DSK"
   rad50$(1)         ! returns "A"


Str$()
The STR Function

Syntax: str$(exp)

STR$ returns the expression exp converted to a string.  This is generally unnecessary in d/BASIC since d/BASIC automatically converts between string and numeric expressions as needed.  STR$ is provided primarily for compatibility with other dialects of BASIC.  Examples:

   str$(123)         ! returns "123"
   str$(-23.12)      ! returns "-23.12"


Val()
The VAL Function

Syntax: val(strexp)

VAL returns the numeric value of strexp.  This is actually done automatically whenever d/BASIC needs a numeric expression and a string is supplied.  Note that VAL allows the numbers in the strings to be specified in other bases in the same manner that d/BASIC constants are defined (using the & character).  Examples:

   val("45")         ! returns 45
   val("&b101")      ! returns 5


Execution Functions
Program Execution/Control Functions

AGAIN	BREAK	CALL
CASE	CHAIN	DO
END	ENDDO	ENTRY.POINT
EXECUTE	FOR	GOTO
IF	MENUEXIT	NEXT
ON	POP	PUSH
REPEAT	RESET	RESUME
RETURN	RUNDOS	SET
SIGNIFICANCE	SLEEP	STOP
SUBPROGRAM	SWITCH	UNTIL
VUE.WINDOW	WEND	WHEN
WHILE	XCALL


AGAIN
The AGAIN Statement

     Syntax:  again
Description:  Used to start another loop cycle or SWITCH
    Example:  again

The AGAIN statement causes the current loop interation to be made again. In a WHILE or DO loop the expression will be reevaluated.  In other loops, execution will continue with the UNTIL statement.  In effect, these statements will cause the rest of the loop body to be ignored.  In a SWITCH statement, AGAIN will cause the SWITCH statement to be re-evaluated.


BREAK
The BREAK Statement

     Syntax:  break
Description:  Used to exit a loop or SWITCH statement
    Example:  break

The BREAK statement causes the current loop or SWITCH statement to be exited and control of the program to continue with the statement following the end of the loop.  This is the best way out of a loop or SWITCH statement.  It is recommended highly that you do not GOTO or RETURN out of a loop or SWITCH statement.


CALL
The CALL Statement

     Syntax:  call label or call @exp
Description:  Used to execute a subroutine
    Example:  call read'record

The CALL statement is used to transfer control to the subroutine named in the statement.  There are two ways to define where execution is to continue. One is the traditional syntax of a CALL statement as in "call LABEL".  The other method allows you to use the result of an expression as the address to transfer to.  The syntax for this type of call is:

   call @routine'address

The value of the expression must point to the start of a d/BASIC statement. Usually this address is derived from the use of the "*" unary operator which returns the value of the following label as its value.  Example:

        routine'address=*CUSTOMER'LOOKUP
        call @routine'address

The address CALLed must be greater than zero and less than the size of the program.  In other words, it must be a location within the location, but not the first location in the program.

MEGA-IMPORTANT-NOTE:  Incorrect usage of this very powerful feature may result in crashing of the system or other extremely nasty things.  If you vector to the middle rather than the start of a d/BASIC statement, all sorts of wonderful and wacky things are possible.

Regardless of the method used to call a subroutine, program execution will continue in that routine until a RETURN statement is executed.  At that point, execution will continue with the statement after the CALL statement.


CHAIN
The CHAIN Statement

     Syntax:  chain {same} strexp {to strexp2}
Description:  Used to link to another program or command
    Example:  chain "ARMENU"

The CHAIN statement is used to transfer control to another d/BASIC program, command file, or assembler language program.  What to link to is specified by the string expression strexp.  strexp is typically the file spec of what you want to execute.  The default extension is ".RUN".

When the CHAIN statement begins execution it will close all open files.  If the file extension of strexp is ".RUN", strexp will be executed as a d/BASIC program.  If it is ".LIT", then it will be run as a assembler program as if you had entered it from command level.  If the extension is anything else, d/BASIC will attempt to run it as a command file.

If strexp is other than a d/BASIC program, you can specify additional lines.  In effect, building a temporary command file.  You can specify multiple programs to run or provide the input to another program.  Examples:

   chain "ARMENU"
   chain "sys:time.lit"+crlf+"date"
   chain ":T"+crlf+"SYS:DOIT"+CRLF+"Y"+CRLF+"DSK0:"
   chain "SYS:RUN.LIT INP"+crlf+"ABC.TMP"+crlf+"2"
   chain same "MENU"
   chain "OE" to "ADD'A'CUSTOMER"


DO
The DO Statement

     Syntax:  do {statement} until exp
Description:  Defines the beginning of a DO loop
    Example:  do i+=1 until i>j

The DO statement defines a loop construct of statements that is executed zero or more times.  All statements after the UNTIL clause and the ending ENDDO statement are part of the loop body.

The basic form of the DO loop is:

   do {statement} until exp
       {loop body}
   enddo

statement is executed at least once.  After it is executed the UNTIL exp is checked for truth.  If true, then the loop body is skipped and execution of the program resumes with the statement following the ENDDO statement.

Examples:

     do until I>10
           call make'a'move
     enddo

     do input line #IN'LINE,LIN until eof(IN'LINE)
           print #OUT'CHANNEL,LIN
     enddo

     do call GET'A'RECORD until name="]]]]]]"
           call total'up
           call process'record
     enddo


END
The END Statement

     Syntax:  end
Description:  Ends a program's execution
    Example:  end

The END statement causes the d/BASIC program to stop and exit to the operating system monitor level.  All open files will be closed first after their buffers are flushed.


ENTRY.POINT
The ENTRY.POINT Statement

     Syntax:  entry.point lable
Description:  Defines an entry point for chaining to a lable
    Example:  entry.point DEL'CUST

The ENTRY.POINT statement is used to define an entry point into the program so that other programs can chain to a program label within the program. The label to chain to is defined by label.  A special form of the CHAIN  statement is used to chain to a label (it will have the optional TO clause).

All statements prior to the ENTRY.POINT statement which defines the label to be chained to will be executed.  For this reason, the ENTRY.POINT statement should be placed after the MAP statements in the program.  All other statements you wish executed should also be placed before the ENTRY.POINT statement.

You may have multiple ENTRY.POINT statements in a program in any order.


EXECUTE
The EXECUTE Statement

     Syntax:  execute text
Description:  execute an AMOS level program or command file
    Example:  execute STAT

The EXECUTE directive is used to execute text as any AMOS program or command file during the compilation of the program.  This is frequently done when programs generate code for inclusion in the compilation.  Example:

   execute mapgen CUSMAS
   ++include CUSMAS.MAP


FOR
The FOR Statement

     Syntax:  for var=exp1 to exp2 {step exp3}
Description:  Defines the beginning of a FOR/NEXT loop
    Example:  for i=1 to 10

The FOR statement is the start of the traditional BASIC looping construct. It is less than wonderful for most applications when compared to the WHILE,  DO, or REPEAT loops.  It does have one minor feature - it is a little faster than the other loops since it is not so generalized and flexible.

The basic form of the FOR loop is:

   for var=exp1 to exp2 step exp3
       statements
   next var

var is the loop control variable.  It must be a floating point variable. exp1 is the initial value of var.  exp1 will only be evaluated once at the top of the loop.  exp2 is the ending value of the loop.  Once var is greater than or equal to exp2 when the NEXT statement is encountered, the loop will terminate.

The default value to increment var on each pass through the loop is 1. The optional STEP clause allows you to change this increment to exp3. This expression will be evaluated when the NEXT statement is encountered.

The body of a FOR/NEXT loop will be executed at least once.  You cannot use the AGAIN and BREAK statements to exit a FOR/NEXT loop.

Examples:

   for i=1 to 10
       print i
   next i

   for j=2 to 100 step 2
       print even'numbers(i)
   next j

   for little=1.5 to 0 step -.25
       call do'something
       if widget=1 then little=0
   next little

FOR/NEXT loops may be nested to any level allowed by available memory. However, the complete FOR/NEXT loop must exist within the higher level one.


GOTO
The GOTO Statement

     Syntax:  goto lable or goto @exp
Description:  Used to change the order of program execution
    Example:  goto print'totals

The GOTO statement is used to transfer control to some other location in the program.  There are two ways to define where execution is to continue. One is the traditional syntax of a GOTO statement as in "goto LABEL".  The other method allows you to use the result of an expression as the address to transfer to.  The syntax for this type of call is:

    goto @routine'address

The value of the expression must point to the start of a d/BASIC statement. Usually this address is derived from the use of the "*" unary operator which returns the value of the following label as its value.  Example:

    routine'address=*CUSTOMER'LOOKUP
    goto @routine'address

The address GOTOed must be greater than zero and less than the size of the program.  In other words, it must be a location within the location, but not the first location in the program.

MEGA-IMPORTANT-NOTE:  Incorrect usage of this very powerful feature may result in crashing of the system or other extremely nasty things.  If you vector to the middle rather than the start of a d/BASIC statement, all sorts of wonderful and wacky things are possible.

Regardless of the method used to define where to go to, program execution will continue sequentially with statements at that point in the program until another GOTO or CALL statement is executed.


IF
The IF Statement

     Syntax:  if exp1 relop exp2 {then} statement1 {else statement2}
Description:  Used to conditionally execute statements
    Example:  if a<0 then goto error'out else b=a/2

The IF statement is used to determine the truth of the relational expression exp1 relop exp2 and execute one of possibly two statements passed on that truth factor.  exp1 and exp2 are standard d/BASIC expressions and relop is one of the valid relational operators.

If the relational expression is true, statement1 will be executed and any ELSE clause will be ignored.  Otherwise if the relational expression is false statement2 will be executed if the ELSE clause is defined.  Examples:

    if a=b then print "a=b"
    if a<>b then call AB:goto LINK
    if a>b call AGB else call ALEB
    if a=b+1 goto link else a+=1:b-=1

As you should have figured out, you can have multiple statements in place of statement1 or statement2.  The statements must of course be separated by a colon character.


MENUEXIT
The MENUEXIT Statement

     Syntax:  menuexit
Description:  Used to return to a menu shell as required
    Example:  menuexit

The MENUEXIT statement is used to exit the program and return to either the d/SHELL or MCL menu programs if they called the program.  If not, processing will resume with the next statement after the MENUEXIT statement which is usually an END statement.  Note that MENUEXIT will cause all open files to be closed as necessary.


NEXT
The NEXT Statement

     Syntax:  next {var}
Description:  Used to mark the end of a FOR loop
    Example:  next i

The NEXT statement is used to mark the end of a FOR loop.  If var is defined it marks the end of the FOR/NEXT loop whose control variable is var.  Otherwise it marks the end of the last FOR/NEXT loop.


ON
The ON Statement

     Syntax:  on condition GOTO/CALL label1{,label2,labeln}
Description:  Used to vector off somewhere based on a condition
    Example:  on error goto error'handler

The ON statement is really three different statements as follows:

on error goto label

This version of the statement will cause the normal d/BASIC error processor to be bypassed and control transferred to the routine specified by label. Once in the error handling routine your program can determine how to handle the error.  You exit the error handler using the RESUME statement.  If another error occurs before a RESUME statement is encountered, the normal d/BASIC error processor will be invoked and error trapping will be disabled

on exp goto label1,label2,etc.

 This version of the statement will cause exp to be evaluated.  If it is equal to 1, then execution control will be transferred to label1.  If it is equal to 2, then control will be transferred to label2.  This will continue for as many labels are defined on the statement line.  If exp is a value not represented by a program label entry, execution will resume with the next program statement following the ON GOTO statement.  Example:

  top:
      input "Which routine",vector
      on vector goto rou1,rou2,rou3
      print "Pick 1, 2, or 3"
      goto top
  rou1:
      ...

on exp call label1,label2,etc.

This statement is almost identical in operation to the ON GOTO statement with the exception that the label entries represent the starting labels of subroutines which will be called by this statement.  They return to the caller using the normal RETURN statement.  When they return, execution resumes with the first statement after the ON CALL statement.

In many cases the ON GOTO/CALL statement can be replaced by the much more modern and readable SWITCH statement.


POP
The POP Statement

     Syntax:  pop error
Description:  Used to restore a saves ON ERROR address
    Example:  pop error

The POP statement is used to restore the most recently saved ON ERROR goto address.  This address is saved using the PUSH ERROR statement.  Addresses are saved in an internal 64 level stack for this purpose.  This means that 64 PUSH statements may be executed before a POP statement must be executed.

PUSH and POP are most likely to be used within subroutines or functions where the caller is not known.  The subroutine would save the caller's ON ERROR address using the PUSH statement and set a local one using a new ON ERROR statement.  Before the subroutine ended, it would restore the caller's error goto address using the POP ERROR statement.  Example:

    my'routine:
        push error
        on error goto LOCAL'ERROR
        <<< do some stuff >>>
        pop error
        return


PUSH
The PUSH Statement

     Syntax:  push error
Description:  Used to save an ON ERROR goto address
    Example:  push error

The PUSH statement is used to save the current ON ERROR goto address for later restoration by the POP statement.  There is an internal 64 level stack for this purpose.  This means that 64 PUSH statements may be executed before a POP statement must be executed.

PUSH and POP are most likely to be used within subroutines or functions where the caller is not known.  The subroutine would save the caller's ON ERROR address using the PUSH statement and set a local one using a new ON ERROE statement.  Before the subroutine ended, it would restore the caller's error goto address using the POP ERROR statement.  Example:

    my'routine:
        push error
        on error goto LOCAL'ERROR
        <<< do some stuff >>>
        pop error
        return


REPEAT
The REPEAT Statement

     Syntax:  repeat
Description:  Defines the beginning of a REPEAT loop
    Example:  repeat

The REPEAT statement defines a loop construct of statements that is executed at least one time.  All statements after the REPEAT statement and the ending UNTIL statement are part of the loop body.

The REPEAT statement has a number of different formats:

   repeat {statements}
        {<loop body>}
   until exp

   repeat {statements} until exp

   repeat until exp

Examples:

   repeat
        call output'line
        call total'up
        call get'next'record
   until record'flag="]]]]]]"

   repeat call PROCESS'A'RECORD until eof(1)

   repeat until getkey(-1)=65


RESET
The RESET Statement

     Syntax:  reset condition
Description:  Used to reset an environment condition
    Example:  reset echo

The RESET statement is used to clear a d/BASIC environment condition such as input echoing.  condition in the statement defines what is to be reset. It can be one of the following:

sysopr

Controls access to functions normally allowed only for system operators (such as BYTE or WORD).  RESET SYSOPR disables access to the functions if the operator is not normally a system operator.

echo

Disables terminal input echoing.

image

Disables image mode input and returns to normal line input mode.

uplowcase

Disables lower case input.  When used, all lower case input will be folded to upper case.

ctrlcok

Disables ^C inputs.  If a RESET CTRLCOK statement is used, you must provide some other method besides the reset button or power cord to exit your program.

funkey

Disables special key translation.

crtonoff

Disables the blanking of the terminal's video when using the PUT.MASK statement.  Resetting CRTONOFF is typically done when outputting multiple masks at the same time, thus avoiding a strobe effect.

The SET statement is used to set these conditions.


RESUME
The RESUME Statement

     Syntax:  resume {lable}
Description:  Defines where to resume execution after an error
    Example:  resume end'it

The RESUME statement is used to resume the execution of a program after an error has been trapped using the ON ERROR GOTO statement.  When RESUME is executed, ^C program interrupt recognition (if enabled) is active and execution resumes at label if defined in the RESUME statement.  Otherwise execution resumes at the statement that caused the error condition.  In either case, the error flag will be cleared.

Never use a GOTO instruction to exit an error recovery routine.  GOTO does not clear the error condition and further errors will result in the program being ended.  Examples:

  error'handler:
       if err(1)=1 resume    ! ^C error?
       call print'error
       resume end'it         ! all other errors


RETURN
The RETURN Statement

     Syntax:  return
Description:  Returns to the caller of a subroutine
    Example:  return

The RETURN statement is used to end execution of a subroutine and return to the caller of the subroutine.  CALLs and RETURNs may be nested to the depth of available memory.


RUNDOS
The RUNDOS Statement

     Syntax:  rundos strexp
Description:  Used to execute an O/S command as a subroutine
    Example:  rundos "DIR DIRECT=*.*/D/V/H"

The RUNDOS statement is used to call an operating system level command strexp as if the user had entered strexp from the monitor command prompt.  When the program being called completes execution, it returns to the d/BASIC program where execution resumes with the statement following the RUNDOS statement.  strexp will be forced to upper case.


SET
The SET Statement

     Syntax:  set condition
Description:  Used to set an environment condition
    Example:  set image

The SET statement is used to set a d/BASIC environment condition such as input echoing.  condition in the statement defines what is to be set.  It can be one of the following:

sysopr

Controls access to functions normally allowed only for system operators (such as BYTE or WORD).  SET SYSOPR enables access to the protected functions if the operator is not normally a system operator.

echo

Enables terminal input echoing.  (Normal default).

image

Enables image mode input.  d/BASIC will accept only a single character at a time when SET IMAGE is used as opposed to waiting for a RETURN character.

uplowcase

Enables lower case input.  (Normal default).

ctrlcok

Enables ^C inputs.  (Normal default).

funkey

Enables special key translations using the d/SOFT ".FNK" files.  The special key translation files must be preloaded into memory for translation to take place.  Usually these keys are function keys.

When a SET FUNKEY statement is executed, the GETKEY() function, the BAR.INPUT statement, and the ACCEPT.FIELD statement will return the following valuesfor the special keys on the keyboard:

    Key            Returned Value
    F1-F16         128-143 (unshifted function keys)
    sF1-sF16       144-159 (shifted function keys)
    Next page      160
    Prev page      161
    Delete char    162
    Delete line    163
    Insert char    164
    Insert line    165
    Clear line     166
    Toggle insert  167
    Next word      168
    Prev word      169
    Delete word    170
    Execute        171
    Print          172
    Help           173

The ACCEPT.FIELD statement will not return codes 162-170 as these are used in the editing of the input.

crtonoff

Enables the blanking of the terminal's video when using the PUT.MASK statement.

The RESET statement is used to clear these conditions.


SIGNIFICANCE
The SIGNIFICANCE Statement

     Syntax:  significance n
Description:  Defines number of significant digits to display
    Example:  significance 8

The SIGNIFICANCE directive is used to define the number of digits to display when unformatted numbers are output.  n must be an integer between 1 and 11.  The significance value defaults to 11.


SLEEP
The SLEEP Statement

     Syntax:  sleep exp{,var}
Description:  Used to put your job to sleep
    Example:  sleep 20000

The SLEEP statement is used to cause the execution of your job to pause for exp clock ticks.  Each "tick" is 1/10 of a millisecond (10000 make a second).  The optional variable var will be set equal to zero if the job was awakened before the sleep count had expired.  Example:

   do sleep 10000,wakeup until wakeup=0
       print "."
   enddo


STOP
The STOP Statement

     Syntax:  stop
Description:  Pauses the execution of the program
    Example:  stop

The STOP statement is used to cause the execution of the program to pause until the operator presses the RETURN character.  They will be prompted with the message:

    Press RETURN to continue:


UDF
User Defined Functions

     Syntax:  {external} function name{$}(parameters)
Description:  Used to define a user function.

d/BASIC supports internal and external user defined functions.  The format of a user defined function is:

   function name$(parm1,parm2,...,parm16)
        statements
   endfunc

or:

   function name$(parm1,parm2,...,parm16)=expression

name is the user name of the function and is a standard d/BASIC label (you cannot have a variable of the same name).  The trailing $ specifies that the function is to return a string value, else it will return a numeric value.  All functions must return a value.

parm1 - parm16 are the up to 16 parameters that can be passed to the function.  The number defined and the number actually used when the function is called must be the same.  The expressions used to call the function will replace these when used in any statement within the function.

The first format of the FUNCTION directive shown above is for multiple lines, the second is a single line function definition.  Examples:

    function dectime(x)=x/86400

    function ageit(date1,date2)
         d1=julian(date1)
         d2=julian(date2)
         if d2>d1 return d2-d1 else return d1-d2
    endfunc

    print dectime(timer+elapsed)
    print ageit(.date,082787)

Functions return values using the RETURN instruction as follows:

    RETURN exp

where exp is a standard d/BASIC expression.

It is possible for user functions to be external to your program.  For example, let's say all your programs use a common SSD checker or error processor written in BASIC.  Currently you must include the source code in each and every program that needs it.  If you change it, all the programs that call it must be recompiled.  d/BASIC has a method of calling BASIC subprograms from within your program.  It does this through the external user function interface.

First you must define the function name and format using the following statement:

     external function fspec name$(parms)

Where: fspec is the up to full file specification of the subprogram containing the function.  (The default extension is .FUN).  The remaining information on the line is identical to a normal function definition.

In the subprogram file, the first program line should be:

    subprogram

Which identifies the module as a subprogram.  The function is defined in the subprogram exactly as a normal function.  Note that there is a limitation of one function per subprogram.

You may share common variables between the subprogram and the main program if the MAP definitions of all variables used are identical in layout and type in the two programs.  Subprograms may not have unmapped variables.

Notes about user function usage:

Parameters cannot be used on the left side of the "=" or as the variable that receives a value (as in the SLEEP statement).

You cannot GOTO or CALL a label in a function.  However, there is nothing to prevent you from GOTOing out of a function and never returning.  Don't do it!  It will cause all sorts of nasties.

There is no limit on the number of functions that may be defined in a program.  Functions can also call other functions.


SWITCH
The SWITCH Mechanism

     Syntax:  switch {on} exp
Description:  Conditionally executes statements
    Example:  switch on vector'number

The SWITCH statement defines a program structure used to select one out of exp cases for execution.  The format of the SWITCH structure is:

   switch {on} cexp
       case exp1 {to exp2}
            {statements}
       endcase

       {case exp3 {to exp4}
             {statements}
       endcase}

       {default case
             {statements}
       endcase}
   endswitch

When executed, d/BASIC will compare the expression cexp to each of the expressions specified in the CASE statements (exp1, exp2, etc.).  When it finds one that matches, it will execute that statement block until an ENDCASE or a BREAK statement.  When the ENDCASE or BREAK statement is
encountered, processing will continue at the statement following the ENDSWITCH statement.

If no expressions match cexp and a DEFAULT CASE block is defined, it will be executed.  The DEFAULT CASE block of statements must be the last CASE block.

The CASE statement also allows you to specify a range of values that cexp can match.  This is done using the TO clause and specifying a second expression after it.  cexp must be a value in the range between the two expressions (inclusive) for that case to be selected for processing.

The use of the BREAK statement in any CASE goes to the ENDSWITCH statement. The AGAIN statement causes control to resume at the SWITCH ON statement.

Example:
   input "Enter the case number: ",a
   switch on a
        case 1
            print "case 1"
        endcase
        case "2"
            print "case 2"
            input "Enter case letter: ",a$
            if ucs(a$)="B" break
            print "No B entered"
            a=1
            again
        endcase
        case 3 to 10
            print "case 3-10"
        endcase
        default case
            print "Default case"
        endcase
   endswitch

Do not GOTO or CALL a label within a SWITCH ON structure from out of the structure if you hope to see your program alive again.  Also do not GOTO a label outside of your switch structure from within the structure.


VUE.WINDOW
The VUE.WINDOW Statement

     Syntax:  vue.window svar {at} exp1,exp2,exp3,exp4,rvar
Description:  Multi-screen freeform editing of text
    Example:  vue.window TEXT'BUFFER at 1,1, 23,79,TEXT'SIZE

This statement causes the text in the string or unformatted variable svar to be edited using a d/VUE-like screen editor.  Multiple screens of text can be edited in the "window" specified by exp1 - exp4.

The upper left-hand corner of the window is defined to be on row exp1 starting in column exp2.  The lower right-hand corner of the window is defined to by on the row exp3 ending in column exp4.

The vue.window statement allows most d/VUE editing commands including many of the ^S commands.  The notable exceptions are draw mode and macros.

Each line in svar is terminated with a RETURN character and the end of text is specified as a NULL byte.

rvar receives the status of the editing session.  If a negative number, the operator aborted the edit, otherwise it contains a count of the number of characters currently in svar.  rvar must be a floating point variable.

Example:

   vue.window TEXT'BUFFER at 5,2, 23,79, EDIT'RESULT
   when EDIT'RESULT>=0
        call put'text'to'disk
   wend

The VUE.WINDOW statement uses the EDTWIN.SYS subprogram for its operation.  This module must be preloaded into either system or user memory first.


WHEN
The WHEN Statement

     Syntax:  when exp statements {else statements} wend
Description:  Conditionally executes statements
    Example:  when a<b

The WHEN statement defines a conditional execution program structure, a multi-line IF statement if you will.  The general formats of the WHEN statement are:

   when exp {statements} wend

   when exp else {statements} wend

   when exp {statements} else {statements} wend

   when exp {statements}
      {when body}
   wend

   when exp {statements}
      {when body}
   else {statements} wend

   when exp {statements}
      {when body}
   else {statements}
      {when body}
   wend

   when exp else {statements}
      {when body}
   wend

Unlike a multi-line IF statement (using the "&" character), the WHEN statement is not limited to 510 characters in length.

Examples:

   when a=b c=1 wend
   when a<>c
      call do'c
   else
      a=c
   wend


WHILE
The WHILE Statement

     Syntax:  while exp
Description:  Defines the start of a WHILE loop
    Example:  while eof(1)=0

The WHILE statement is used to define a loop construct that is executed zero or more times.  All statements between the WHILE and WEND statements are part of the loop.  The expression in the WHILE statement is not required to be numeric.  The possible formats of the WHILE statement are:

   while exp
      {statements}
   wend

   while exp {statements}
      {loop body}
   wend

   while exp {statements} wend

   while exp wend

Example:

   while a<>b
      call process'record
      b=b+1
   wend


XCALL
The XCALL Statement

     Syntax:  xcall name{,parm1,parm2,parmn}
Description:  Calls an assembly language subroutine
    Example:  xcall spool,"REPORT.LST"

The XCALL statement is used to call the assembly language program named name (extension is always .SBR).  The optional parameters that are passed to the subroutine are separated from each other by commas.  If the parameter passed is a variable, it can be modified by the XCALL routine. String constant parameters are not guaranteed to be null terminated.

When the XCALL statement is executed, d/BASIC uses it's standard search order for the subroutine as follows:

In system memory.
In the user memory partition .
In the currently logged into account.
In the ",0" account of the project on the same disk as you are looged in on.
In the BAS: account (DSK0:[7,6]).

Note that d/BASIC will load the subroutine into memory if it's on disk each time it is called.  This can result in considerable program speed degradation if the subroutine is called more than once.


IO Functions

ALLOCATE
CLOSE
DATA
DFREE
EOF
GET
GETKEY
INCLUDE
INPUT
KILL
LOOKUP
NEXT.DIRECTORY
OPEN
PRINT
PUT
READ
RENAME
RESTORE
WRITE


CLOSE
The CLOSE Statement

     Syntax:  close #exp
Description:  Used to close an open file channel
    Example:  close #1

The CLOSE statement is used to close the open file on channel exp.  This will cause all buffers to be flushed as necessary.  Any further I/O to the closed channel will result in an error condition.  Once a channel has been closed, it can be re-opened as the same or as a different file.

All channels are automatically closed when the program ends with either an END statement, MENUEXIT statement, a CHAIN statement, or when an error occurs.


DATA
The DATA Directive

     Syntax:  data item, item, ...
Description:  Defines data items for READ statement
    Example:  data "String 1", 1.23, 3.14, "String 2"

The DATA directive is used to define items of data that can be read into variables using the READ statement.  One or more items of data can be defined on the DATA directive line if they are separated by commas.  Both floating point and string data may be defined.  Multiple DATA directives may appear in a program to create a larger data pool than can be defined on a single line.

The items in the DATA directive must be constants and not expressions.  This is because the items are resolved at compile time and not run time.

Everytime an item of data is read, the internal data pointer is advanced to the next item.  The RESTORE statement may be used to restore the data item pointer to the first DATA item.  Example:

    do i+=1 until i>4
           read name(i),value(i)
    enddo

    data "Johnny Rotten", 0.23, "Prince", 0.98
    data "Chris Squire", 7.89, "Peter Gabriel, 15.32
    data "Cher", 0.12, "Madonna", 1.20
    data "Bryan Ferry", 7.56, "Megatron", 11.20

If you attempt to read data when none is left, you will be given an obvious error message.


GET
The GET Statement

     Syntax:  get byte/word/long #exp,var
Description:  Used to read raw data from disk files
    Example:  get byte #1,IN'CHAR

The GET statement is used to read the raw data bytes, words, or long words from the file open on channel exp into the variable var.  No editing of the data will be performed with the exception of type conversion if var is not the same type and size as specified in the word after GET.

Unlike the INPUT statement, the GET statement will return the exact contents of the file.  Therefore the GET statement can be used to read and process files containing any data.  Example:

  map1 char,b,1

   open #1,"SYS:TIME.LIT",input
   do get byte #1,char until eof(1)
      print hex$(char);
      check'sum+=hash
   enddo
   print check'sum

This example opens up the file SYS:TIME.LIT, reads it in one byte at a time, and outputs the bytes in hexadecimal to the terminal screen.


GETKEY
The GETKEY Function

Syntax: getkey(exp)

The GETKEY function is used to return the next available character from the terminal's input buffer.  GETKEY is a little different than your normal function in that it can result in getting input from the user.

exp determines how GETKEY will act.  If exp is 0, then the value of the first character in the terminal's input buffer will be returned if one is available.  If one is not available, -1 will be returned.  If exp is negative, then the program will be placed into a terminal input wait state until a character is typed if none are available.  Examples:

   getkey(0)      ! returns -1 or char, no waiting
   getkey(-1)     ! returns char only since it waits

GETKEY will recognize special key input (i.e., F1) if the SET FUNKEY  statement has been executed and the special key translation table for the terminal is in memory (extension ".FNK").

The values of the special keys are:

   Key            Returned Value
   F1-F16         128-143 (unshifted function keys)
   sF1-sF16       144-159 (shifted function keys)
   Next page      160
   Prev page      161
   Delete char    162
   Delete line    163
   Insert char    164
   Insert line    165
   Clear line     166
   Toggle insert  167
   Next word      168
   Prev word      169
   Delete word    170
   Execute        171
   Print          172
   Help           173


INCLUDE
The INCLUDE Directive

     Syntax:  ++include fspec1{+fspec2+fspecn}
Description:  Defines source files for inclusion in the compilation
    Example:  ++include maps

The INCLUDE directive is used to include other source files in the compilation of your program.  One or more files can be included.  The files are specified by the file specifications fspec1, fspec2, etc.  The default file extension is ".BSI".  The included files will be inserted into the compilation at the INCLUDE directive's location in the program.

The INCLUDE directive is particularly useful in the management of multiple program applications.  The programs in these applications tend to share the same record structures, subroutines, etc.  You can place the common MAP  declarations in a single MAP file for all the programs.  You can also place your common subroutines in an "include" file also.  This way if something changes, you need only change one source file (you will still be stuck recompiling everything).


INPUT
The INPUT Statement

     Syntax:  input {line} {#exp}{"text"},varlist
Description:  Used to input data from a file or the terminal
    Example:  input "Enter your name: ",name$

The INPUT statement is the primary means of inputting data from the operator or a sequential access disk file.

When used to get information from the terminal, the INPUT statement will first prompt the operator with "text" if it's defined.  If text isn't defined, you will be prompted with a ? character.  d/BASIC will expect an input for each variable in varlist.  The input must be separated by commas if you are responding with string information.  You can use blanks or commas for numeric data.  If you should fail to supply the proper number of inputs, you will be prompted with "??" for the missing inputs.  Example:

   input "Enter age and sex",years,sex$
     Enter age and sex? 33,M

When you specify LINE after the word INPUT, the execution of the statement changes.  The entire line of input will be processed as a single unit rather than chopped up between commas into different variables.  Therefore, varlist must be a single variable rather than a list of variables.  Example:

   input line "Enter your name please: ",name$
     Enter your name please: Lizard, Godzilla

The main two differences between the file input version of the INPUT statement and what we've discussed so far is that you specify a file channel number as shown by exp in the statement's syntax rather than the input prompt.  (Note that the input prompt is always optional).  Also, obviously, the input items come from a file open for input.  Example:

   open #1,"TEST.DAT",input
   input line #1,line'buffer

In this example the first line terminated by a RETURN character will be returned in the variable line'buffer.  LINEFEED characters are ignored by the INPUT statement.


KILL
The KILL Statement

     Syntax:  kill strexp
Description:  Used to erase a disk file
    Example:  kill "TEMP.DAT"

The KILL statement is used to erase a file from the disk.  It does this by removing its name from the file directory and deallocating all the disk space belonging to the file.  The name of the file to erase is specified by strexp which has a default extension of ".DAT".


LOOKUP
The LOOKUP Statement

     Syntax:  lookup strexp,var
Description:  Used to determine if a file exists
    Example:  lookup "SYSDAT",result

The LOOKUP statement is used to determine if the file specified by strexp exists (default extension of ".DAT").  If not, var will be set equal to zero.  Otherwise if the file is a sequential file, it will be set equal to a positive non-zero number.  If it is a random access file, var will be set equal to the negative size of the file in blocks.  Example:

   lookup "bas:sysdat",result
   if result=0 goto FILE'NOT'FOUND
   if result>0 goto FILE'NOT'RIGHT'TYPE


NEXT.DIRECTORY
The NEXT.DIRECTORY Statement

     Syntax:  next.directory #exp matching strexp into strvar
Description:  Used to process directory channels
    Example:  next.directory #1 matching "*.lit" into a$

This statement is used to return the next matching entry for file channels opened as directories (using the OPEN #x,"",DIRECTORY statement).  exp is the channel number of the open directory.  The MATCHING clause, if defined, specifies a wildcard string ("strexp") that the scanned directory entries must match.

The string variable strvar will receive the next directory item in sequence, if any are available, otherwise the null string will be returned.

The special characters that may appear in the wildcard string are:

?  - match any character
*  - match to next character or end of string
@  - match any alphabetic character
#  - match any numeric character
{} - match the characters within the curly braces.  You can use the "-" character to denote a range as in "a-z".

The wildcard string may have multiple specifications as in:

     "*.bas; roldex.*"

The default extension is "*". When the wildcard specification is for a "p,pn" (when scanning for directory entries), the defaults are "*,*".  Do not specify the "[" and "]" characters in the wildcard specification.  Note that the wildcard specifications are separated by the ";" character and not the comma.

Example:
   map1 file'names(40),s,30
   map1 filler,b,1

   input line "Directory specification? ";a$
   open #1,a$,directory

   do i+=1 until i>40
      next.directory #1 into file'names(i)
      if file'names(i)="" break
   enddo


OPEN
The OPEN Statement

     Syntax:  open #exp1,strexp,how{,recsize,var{,span'blocks}}
Description:  Used to open a file channel for access
    Example:  open #1,"TEST",input

The OPEN statement is used to locate a file and open it for access on the file channel specified by exp.  File channels are integer numbers starting at 1.  The name of the file to be opened is defined by the string expression strexp.  (The default extension is ".DAT").

how determines how access to the file is to be performed.  It may be one of the following:

input

The file must be a sequential access file (such as a text file).  INPUT  and GET statements are used to read from the file.

output

The file will be opened as a sequential output file.  Any file of the same name will be erased by this statement.  PRINT and PUT statements are used to output data to the file.

append

The file will be opened as a sequential output file.  Any existing output file will not be erased.  Rather the data output in append mode will be added to the start of the file.  PRINT and PUT statements are used to output data to the file.

hotkey

The file will be opened for hot key access only using the HOTKEY  statement.  Hot keys are a form of on-line help.  The same mechinism is used in the d/VUE editor when ^S^N is entered.  Unlike other files, the default extension of files open for HOTKEY access is ".HOT".

random

The file will be opened as a random access file.  When opened in this mode two additional parameters are required.  The first is recsize which is the logical record size of each record in the file.  This can range in value from 1 to 512 or 1 to 65,536 if span'blocks is specified.

The second parameter is the name of the variable that will be used to contain the current record number for READ and WRITE statements.  This variable must be a floating point variable.  You would use the READ and WRITE statements to access data in the file.

d/BASIC is responsible for mapping the logical to physical records.  It will not split records over block boundaries unless the clause span'blocks is specified.  It will only place as many logical records as can fit completely on a 512 byte block.  Anything else in the block will be wasted.  If you have a logical record size of 257, you're looking at some serious disk space wastage.  Try to use a record size that is a power of 2 for zero wastage. Failing that, shoot for the one that results in the minimum space wastage.

If you do specify span'blocks in the open statement there will be no space wastage because records will be split over one or more blocks as needed.

directory

This will open up channel exp as a directory channel.  Currently only the NEXT.DIRECTORY statement may be used on these types of channels.

strexp determines what kind and which directory to open as follows:

[]

Open the current user directory and return the names of files in the directory.

[p,pn]

Open the specified ("p,pn") user directory and return the names of files in the directory.

devn:

Open the master directory of device "devn:" and return the account numbers in the directory.

devn:[p,pn]

Open the specified directory on the specified device and return the names of files in the directory.

ersatz-name

Open the device and user directory specified by the AMOS ersatz name "ersatz-name" and return the names of files in the directory.

mnemonic

Open the device and user directory specified by the TSASS mnemonic "mnemonic" and return the names of files in the directory.

Example:

   map1 file'names(40),s,30
   map1 filler,b,1

   input line "Directory specification? ";a$

   open #1,a$,directory

   do i+=1 until i>40
      next.directory #1 into file'names(i)
      if file'names(i)="" break
   enddo


PRINT
The PRINT Statement

     Syntax:  print {#exp,} explist
Description:  Outputs data to the screen or sequential file
    Example:  print "This is a very simple PRINT statement"

The PRINT statement is used to output human readable data to either a terminal's screen or a file open for output or append operations.

#exp determines the difference between the two types of PRINT statement. If non-zero and positive, it will be the number of the file channel to output the results of the statement.  If zero or non-defined, the results will be output to the terminal.  If negative, an error will occur.

explst is what will be output.  It can consist of numeric and string expressions separated by commas or semi-colons.

Numeric expressions will be output with a trailing blank.  The number will be preceeded by either a blank if it is positive or a - character if it is negative.

String expressions are output exactly as they are defined with no leading or trailing blanks added.

Each item to be output in the PRINT statement is separated from its neighbors by either a comma or a semi-colon.  If a comma is used, the cursor will be moved to the start of the next print zone.  A print zone starts every 16 character positions.  Use of the semi-colon between items will cause no cursor action to be taken.

If the PRINT statement does not end with a semi-colon, a RETURN/LINEFEED pair will be added to the line.

The PRINT statement has a way of moving the cursor around on the line or the screen.  It does this with the TAB function.  The TAB function can only be used in a PRINT statement.  It can have the following formats:

tab(exp)

This format causes the cursor to be advanced to the exp+1 position on the print line.

tab(exp1,exp2)

This format causes either a CRT control function or a cursor positioning command to be executed.  What determines this is the value of exp1.  If it is equal to -1, then exp2 is a CRT control code such as clear screen.

If exp1 is positive, it represents the terminal row the cursor should be placed on and exp2 represents the column of that row.

This format of the TAB function is ignored for file output operations.

Examples:

   print tab(-1,0);  ! clear the screen
   print tab(12,40); ! set cursor to row 12, col 24

Numbers can be formatted using a formatting template (called a mask).  The formatting mask is composed of special formatting characters and other text that is used to determine the contents of the final output string.  A group of one or more consecutive formatting characters is called a field.  The fields relate to the expressions to be formatted on a one for one basis, left to right.  The first field goes with the first expression, etc.

Formatting is done with the USING operator which has two formats.  The first format is:
     exp USING strexp

Where exp is the typically a numeric expression to be formatted and strexp is the formatting mask.  The second place where USING can show up is in the PRINT statement.  This format is:
     print using strexp,explst

Where strexp is the formatting mask and explst are the one or more expressions to format and output.  Note that you may have a file channel specification (#exp) before the USING clause to cause output to a file channel.  Examples:

   out'str=amount using "$###,###.##"
   print using "###.## #ZZZZ", percentage, cases

As shown in the PRINT USING example, multiple expressions can be formatted using a single output mask.  If we had supplied more expressions to be formatted than there were edit fields, d/BASIC would begin reusing them from the beginning of the formatting mask.  If we had supplied less expressions, output would stop with the last field for which we had supplied a number.

USING has the lowest operator evaluation precedence.

When an expression is formatted with the USING operator, it replaces its edit field in the formatting mask, even if it doesn't completely fill it.

The following list details the special formatting characters available in USING formatting masks:

\

Marks the start and end of a string field.  The number of characters between and including the "\" characters determine the size of the edit field.  Any characters appearing within the "\" characters will be ignored.  You can use that space for comments.  Example:

print using "\name----\  \group--\","Emmet","DAR"
Outputs: "Emmet     DAR      "

!

Specifies a single character string field.  Example:

print using "Sex: !", "M"
Outputs: "Sex: M"

#

Specifies a numeric field.  The expression will be formatted in the space determined by the number of consectutive # characters.  If the parts of the number are too small, they will be rounded to fit.  If the number is larger than the edit field it will output a % character before the field to signify overflow.  Examples:

print using "###",123      ! outputs "123"
print using "###",-5.34    ! outputs " -5"
print using "###",3        ! outputs "  3"
print using "###",6789     ! outputs "%6789"

.

Only in effect if within a numeric edit field (combined with the # character).  It specifies the placement of the decimal point in a numeric field.  It is usually followed by # characters, one for each decimal output position.  Trailing zeros, as necessary, will be output and the number will be rounded accordingly.  Examples:

print using "###.##",10     ! outputs " 10.00"
print using "###.##",2.456  ! outputs "  2.46"
print using "###.##",-200.1 ! outputs "%-200.1"
print using "###.##",.93    ! outputs "  0.93"

$$

This character causes a floating dollar sign to be output.  The $ character will appear to the immediate left of the first digit in the field. "$$" takes up two positions in the output mask.  One of them is a digit position, the other is the $ character itself.  Examples:

print using "$$#####.##", 12345.67 ! outputs " $12345.67"
print using "$$#####.##", 400      ! outputs "   $400.00"
print using "$$#####.##", 157.8    ! outputs "   $157.80"

,

Use of the comma character causes commas to be inserted every three character positions to the left of the decimal point.  Examples:

print using "###,###.##", 12345.6 ! outputs " 12,345.60"
print using "###,###.##", 100     ! outputs "    100.00"

**

These two characters result in leading blanks being replaced with asterisks. This is the typical method by which check amounts are written to prevent modification.  The two characters occupy two digit positions in the field. Examples:

print using "**$###.##", 12345.67 ! outputs "$12345.67"
print using "**$###.##", 400      ! outputs "**$400.00"
print using "**$###.##", 1.8      ! outputs "****$1.80"

Z

This character causes leading spaces to be replaced by zeroes.  The format of the field is a single # character followed by Z characters to define the rest of the field.  Examples:

print using "#ZZZ", 10  ! outputs "0010"
print using "#ZZZ", 2   ! outputs "0002"

-

When placed after a numeric field causes the sign of the number to be output in this position.  If the number is negative, a - character will be output following the number.  Otherwise a blank will be stored in that position. Examples:

print using "$$###.##-",-123.45  ! outputs " $123.45-"
print using "$$###.##-", 10.5    ! outputs "  $10.50 "

^^^^

Specifies that scientific notation is to be used.  The "^^^^" characters take up the position of the "Esnn" part of the output (s is the exponent sign, nn is the exponent).  The significant digits are left justified. The decimal point may appear anywhere.  Examples:

print using ".####^^^^",10     ! outputs ".1000E+02"
print using ".####^^^^",123.45 ! outputs ".1235E+03"
print using ".####^^^^",.007   ! outputs ".7000E-02"
print using "#.###^^^^",10     ! outputs "1.000E+01"
print using "#.###^^^^",123.45 ! outputs "1.235E+02"
print using ".####^^^^",.007   ! outputs "7.000E-03"

Any other characters that appear in a formatting mask have no special meaning and will be directly output.  Example:

   print using "###%",100  ! outputs "100%"
   print using "###%",98.3 ! outputs " 99%"

Note that the output of numbers is governed by the European number format flag in the system.  If set, the meaning of commas and periods in numbers is reversed.


PUT
The PUT Statement

     Syntax:  put byte/word/long #exp1,exp2
Description:  Used to write raw data to disk files
    Example:  put byte #1,13

The PUT statement is used to write the raw data bytes, words, or long words to the file open on channel exp1.  The data to be written is the binary representation of exp2.  No editing of the data will be performed with the exception of type conversion if exp2 is not the same type and size as specified in the word after PUT.  Example:

  map1 char,b,1

        open #1,"TEST.BYT",output
        do i+=1 until i>1000
              print #1, rnd(0)*256
        enddo


READ
The READ Statement

     Syntax:  read {#exp,} varlist
Description:  Used to read data items or records from a file
    Example:  read #1, buffer

The READ statement is used to perform two functions in d/BASIC.  The first is to read items from the DATA pool. The syntax of this type of READ statement is:

   read varlist

Where varlist is one or more variables to be loaded with information from the DATA pool.

The second function that READ performs is to read records from random access data files.  The syntax of this READ statement is:

   read #exp,varlist

Where exp is the file channel number which is associated with an open  random access file.  varlist is a list of one or more variables that the data will be read into.  Each variable in varlist must be the same size as the size of the record being read.  The record number of the variable to be read must have been already set before the READ statement is executed. The variable that defines the record number is specified in the OPEN statement.


RESTORE
The RESTORE Statement

     Syntax:  restore
Description:  Used to reset the internal DATA pool pointer
    Example:  restore

The RESTORE statement will reset the internal DATA pool pointer to the first item in the pool.  The DATA pool is created using the DATA directive.


WRITE
The WRITE Statement

     Syntax:  write #exp,varlist
Description:  Used to write records to a random access file
    Example:  write #1, buffer

The WRITE statement is used to write logical records from memory to the random access data file open on channel exp.  varlist is a list of one or more variables from which the data will be written.  Each variable in varlist must be the same size as the size of the record being written. The record number of the variable to be written must have been already set before the WRITE statement is executed.  The variable that defines the record number is specified in the OPEN statement.


EOF
The EOF() Function

Syntax: eof(exp)

EOF returns the end of file status of the file open on channel exp.  EOF will return zero if the end of the file has not yet been reached by a read file statement.  Otherwise it will return one.

Channel number zero is treated as the user terminal by EOF.  If exp resolves to zero, then EOF will return zero if there are any input characters in the user's terminal input buffer.  Otherwise EOF will return one.  This feature is handy when you want to determine if the operator has typed anything.  Examples:

   if eof(14)=1 goto end'of'file
   if eof(0)=0 goto waiting'input


RENAME
The RENAME Statement

     Syntax:  rename strexp1 to strexp2{,var}
Description:  Used to rename files
    Example:  rename "ARTRX.TMP" to "ARTRX.DAT", result

This statement renames the file defined by the string expression strexp1 to the new name defined by the string expression strexp2.  If a file named strexp2 already exists, an error will result.  You will have to delete or rename the existing file.

strexp1 can be a full file specification.  strexp2 is a file name - extension specification only.  Both have a default extension of ".DAT".

Errors will be handled in one of two ways based on whether or not var is defined.  If defined, it will receive the negative error number resulting from the operation, otherwise the normal d/BASIC error handling will be invoked.  If the operation is successful and var is defined, it will be set equal to 1.

   rename "abc.tmp" to "abc.dat",result
   if result <> 1 goto rename'error


DFREE
The DFREE Function

Syntax: dfree(strexp)

This function returns the largest unallocated contigous block of disk space on the disk device specified by strexp.  Example:

   dfree("DSK1:")   ! may return 1298


ALLOCATE
The ALLOCATE Statement

     Syntax:  allocate strexp,exp
Description:  Used to create a random access disk file
    Example:  allocate "test",100

The ALLOCATE statement is used to create a random access file whose name is defined by the string expression strexp.  (The default extension is .DAT). The size of the file will be exp blocks.  Note that there must be enough unallocated contigous disk space to satisfy the request. Otherwise you will be given a %Device full error.


Error Handling Functions

DIAGNOSTIC
ERF
ERR
ERRMSG
LOG.ERRORS
ON ERROR


diagnostic
The DIAGNOSTIC Statement

     Syntax:  diagnostic exp
Description:  Used to output a value to the status display
    Example:  diagnostic &h0FF

This statement causes the value of the expression exp (MODULO 256) to be output to any hardware status display that exists on your system.  This statement is typically used in the debugging of hardware or just because it's neat to make seven segment displays bow to your every whim and jaded desire.


Erf()
The ERF Function

Syntax: erf(exp)

The ERF function is used to return the actual operating system error code when a file error occurs on file channel number exp.  Your operating system documentation will describe what these values are and what they mean. Examples of ERF usage:

   erf(file'no)    ! channel file'no
   erf(10)         ! channel #10


Err()
The ERR Function

Syntax: err(exp)

ERR is used to provide information to you when a d/BASIC error has occurred.  exp determines the type of information to return to you as follows:

exp = 0

Causes ERR to return the d/BASIC error code.

exp = 1

Causes ERR to return the last line number encountered (if any) before the error occurred.

exp = 2

Causes ERR to return the last file channel number used (if any).

exp = 3

Causes ERR to return the value of the JOBERR field on AMOS/x systems and zero on d/OS systems.

exp = 4

Causes ERR to return the success code resulting from the last EVAL() or SEVAL$() function call.  If non-zero, the processing of the function terminated with an error.  The value with be 255 if an expression syntax error occurred during the processing of the user expression.  Otherwise the value will be the d/BASIC run time error that occurred.

exp = 5

Causes ERR to return the program address of the last error that occurred.  Use of the COMPIL "/L" switch will result in a listing of the program with the address of each statement.

ERR usually can only be effectively used if d/BASIC run time errors are being trapped by you using the ON ERROR statement.  Examples:

   print "Error #";err(0)
   err(1)      ! returns the line #
   if err(4)<>0 print errmsg$(err(4))


Errmsg$()
The ERRMSG Function

Syntax: errmsg$(exp)

ERRMSG$ returns the text string error message that corresponds to the d/BASIC error code represented by exp.  See Appendix B for the d/BASIC error messages and their numbers.  Examples:

   errmsg$(1)    ! returns "Operator interrupt"
   errmsg$(3)    ! returns "Out of memory"


Log.errors
The LOG.ERRORS Statement

     Syntax:  log.errors
Description:  Specifies that d/BASIC errors are to be logged to disk
    Example:  log.errors

This statement is used to cause d/BASIC to log all program errors to the file DBASIC.LOG located in the OPR: account.  The information that will be logged in the file describes the error condition.  The DBASIC.LOG file is a binary data file.

The contents of the file are converted into human readable format by the BASLOG program.  This program produces a file named DBASIC.LST.

Each logged error entry has the format:

 --------------------------------------------------------------------------
 Error: 12 - XCALL routine not found; Occured on 16-Jun-89 at 01:33:14
 MAL/DSOFT using job TIM running T12 in account DSK0:[60,4]
 Last line #: 0; Last file channel #: 0; Program location: 34
 File name: DSK0:ABC.SBR[7,6]

After it has produced the readable error log file BASLOG will prompt as to whether or not it should erase the DBASIC.LOG binary file.  The only affirmative response is a  character.  The file should be periodically purged to maintain performance since all new error entries must go at the end of the file.


Screen Interface Functions

Mask IO
ACCEPT.FIELD
DISPLAY.FIELD
LOAD.MASK
MOVE.FIELD
NUMFIELDS
PUT.MASK

Screen IO
BAR.INPUT
DRAW.FORM
DRAWBOX
DUAL.PRINT
ENDFORM
FORM.DEFINE
FORM.ORIGIN
FORM.PRINT
FORM.PUT
INPUT.FIELD
NEW.FORM
PAGE.SIZE
PICK.LIST
PRINT
STATUS.LINE
WIPEBOX


ACCEPT.FIELD
The ACCEPT.FIELD Statement

     Syntax:  accept.field #exp of strexp/fieldname into var{,result}
Description:  Used to accept input into an input field
    Example:  accept.field #4 of "CUSTOMER'MASTER" into PHONENUMBER

The ACCEPT.FIELD statement is used to accept input into a field according to the parameters specified in the input field specification #exp of strexp/fieldname.

The syntax #exp of strexp1 is used to refer to field number exp of the mask named strexp (previously loaded using the LOAD.MASK statement and created using the DPAINT program).  The syntax fieldname is used to reference a field defined using an INPUT.FIELD directive.

var is the variable that will receive the data input into the field.  It must be a string or unformatted type variable.  If result is defined, it will receive the exit code value of the control code used by the operator to exit the field.  ^C will not be trapped if result is not specified.  If a time out value is specified and the field times out, the exit code 255 will be returned.  Example:

   accept.field SSNUMBER into SS'NO,EXITCODE
   if EXITCODE=3 goto CC'EXIT
   if EXITCODE=30 goto GET'FIRST'FIELD

The ACCEPT.FIELD statement allows use of the d/SOFT special key translation tables if a SET FUNKEY statement has been executed and the special key table (extension=".FNK") is loaded into memory.  The values for the special keys that can be used to exit an ACCEPT.FIELD statement are:

   Key        Returned Value
   F1-F16     128-143 (unshifted function keys)
   sF1-sF16   144-159 (shifted function keys)
   Next page  160
   Prev page  161
   Execute    171
   Print      172
   Help       173

Note that the special keys allowed to exit the field must be defined in the EXIT USING parameter of the field's definition.  Unlisted special keys are used to edit the input text and are not returned.


DISPLAY.FIELD
The DISPLAY.FIELD Statement

     Syntax:  display.field #exp of strexp1/fieldname from strexp2
Description:  Used to output text formatted according to an input field
    Example:  display.field #4 of "CUSTOMER'MASTER" from "2014235577"

The DISPLAY.FIELD statement is used to output strexp2 according to the parameters specified in the input field specification #exp of strexp1/fieldname.

The syntax #exp of strexp1 is used to refer to field number exp of the mask named strexp1 (previously loaded using the LOAD.MASK statement and created using the DPAINT program).  The syntax fieldname is used to reference a field defined using an INPUT.FIELD directive.  Examples:

   display.field SSNUMBER from SS'NO
   load.mask "SALES" named "SALES'DATA"
   display.field #2 of "SALES'DATA" from "12345"


LOAD.MASK
The LOAD.MASK Statement

     Syntax:  load.mask strexp1 {named} strexp2
Description:  Used to load a mask created by the DPAINT program
    Example:  load.mask "CUSMAS" named "CUSTOMER MASTER"

The LOAD.MASK statement is used to load the mask named strexp1 as created by the DPAINT program from disk into the memory mask area named strexp2.  strexp1 can be a full file specification with a default extension of ".PNT".  Example:

   load.mask "CUSMAS" named "CUSTOMER'MASTER"
   put.mask "CUSTOMER'MASTER"


MOVE.FIELD
The MOVE.FIELD Statement

     Syntax:  move.field #exp1 {of} strexp {to} exp2,exp3
Description:  Used to reposition a d/PAINT created input field
    Example:  move.field #3 of "CUS'MASTER" to 20,2

This statement is used to move the starting location of a d/PAINT input field to a new row and column.  exp1 is the field number of the mask named strexp.  exp2 is the new start row number and exp3 is the new starting column number.


NUMFIELDS
The NUMFIELDS Function

Syntax: numfields(strexp)

NUMFIELDS returns the number of input fields contained in the d/PAINT created mask named strexp already loaded into memory by the LOAD.MASK  statement.  Examples:

   numfields("AR")  ! may return 12   numfields(b$)    ! may return 4


PUT.MASK
The PUT.MASK Statement

     Syntax:  put.mask strexp
Description:  Used to output a mask created by the DPAINT program
    Example:  put.mask "CUSTOMER MASTER"

The PUT.MASK statement is used to output an output mask created by the DPAINT program.  The mask must have been previously loaded using the LOAD.MASK statement.  The name of the mask is specified as strexp.  Example:

   load.mask "CUSMAS" named "CUSTOMER'MASTER"
   put.mask "CUSTOMER'MASTER"


INPUT.FIELD
The INPUT.FIELD Statement

     Syntax:  input.field fieldname
Description:  Used to define an input field
    Example:  input.field ACCOUNT'NUMBER

The INPUT.FIELD directive is used to define an input field for use with the ACCEPT.FIELD or DISPLAY.FIELD statements.  fieldname in the syntax is the name of the field.  It must follow the same rules as program label names.

The INPUT.FIELD directive is a multi-line construct that is terminated by an END FIELD directive.  The lines that appear within the construct define the field parameters.

The following are the parameters that you can specify.  Since INPUT.FIELD is a directive, all numeric parameters that you can specify must be numeric constants as they are evaluated at compile time and not run time.

located at row,col

This parameter defines the row and column start of the first character in the field.  It defaults to row 1, column 1.

data type x{,exceptions}

This parameter defines the type of data the operator may enter into the field as x.  If undefined, it will default to any character.  Otherwise it must be one of the following:

y or n

Only the characters Y or N will be accepted as input.  You may use the DEFAULT TO parameter to define which character to default to.

alphabetic

Only letters of either case will be accepted.

digits

Only the digits 0-9 will be accepted as input.

If you specify a data type, you can also specify the following exceptions which appear after the type specification (separated by commas):

spaces allowed

The SPACE character is allowed.

dash allowed

The - character is allowed as input.

slash allowed

The / character is allowed as input.

period allowed

The . character is allowed as input.

maximum size n

This parameter defines the maximum number of characters that can be entered into the field as n which must be less than 256.

minimum size n

This parameter defines the minimum number of characters that must be input into the field as n which must be less than 256 and cannot be larger than the maximum size defined for the field.

input required

Use of this parameter specifies that the field cannot be exited without entering some data in the field.  The exception is a ^C input.

no command file input

Use of this parameter specifies that input into the field is not to come from any active command file.

destructive CR

Use of this parameter specifies that all characters to the right of the cursor in the field are to be erased when the RETURN key is pressed.

automatic entry

Use of this parameter will cause all the program to automatically exit the field when the last character position has been filled in by the operator.

time out n

This parameter specifies that the data input to the field has to be completed within n seconds.  If the field is not exited within the time out period, d/BASIC will return an exit code of 255 and resume execution of the program at the statement following the ACCEPT.FIELD call which referenced the field with this parameter set.  n may range in value from 1 to 65535 seconds.

left margin n

This parameter specifies the left margin starting column number on all lines after the first one of the field.  For example, assume an 80 column wide terminal and a 15 character input field that starts on row 5 in column 70, and a character has just been entered in column 80 of row 5.  If no left margin parameter is specified, the next character input will be on row 6 in column 1.  If a left margin parameter had been specified, this character will be placed in row 6 and the left margin column value.  If we wanted to line up the two lines of input in our example, we would specify a left margin value of 70.

right margin n

This parameter specifies the ending column number of the field before input continues on the next line as n.  Normally the ending column number is the terminal width.  Using the example presented in the LEFT MARGIN parameter, we might want three lines of input, five characters each.  We could accomplish this using the parameters:

   left margin 70
   right margin 74

edit mask text

This parameter specifies text as an edit mask to be used for the data to be input in the field.  The operator must enter data into the field according to this mask.  There are three special characters that may appear in the mask:

#

This character will match any decimal digit.

@

This character will match any alphabetic character.

?

This character will match any character.

All other characters in the mask must match the entered character.  For example, consider the mask "###-##-####" which would be used for social security numbers.  The operator would have to enter 3 digits followed by a "-", two more digits followed by another "-", and then four more digits.

If there are less characters defined in the edit mask then the input field size, the edit mask will be padded on the right with "?" characters.

exit using list

This parameter specifies list as the one or more characters (usually control codes) that can be used to exit the field.  All fields can be exited using the RETURN key, therefore it need not be specified.  All keyboard characters, letter control codes (^A - ^Z), HOME, and ESCAPE can be specified as exit codes.

The specification of the exit codes is straight forward.  For control codes, preface the letter representing the code by the "^" character as in: ^A or ^B.  Otherwise use the mnemonic for a special key as defined here:

f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, f13, f14, f15
f16, sf1, sf2, sf3, sf4, sf5, sf6, sf7, sf8, sf9, sf10, sf11, sf12
sf13, sf14, sf15, sf16, NEXT PAGE, PREV PAGE, EXECUTE, HELP, PRINT

Multiple codes are separated from each other by a comma as in:

   using ^J,^K,HOME,ESCAPE

Note that the mnemonics HOME, TAB, and ESCAPE are allowed for the control codes ^^, ^[, and ^I.

When the operator enters a valid exit code in the field, the value of that code will be returned.  The value of the letter control codes is the position of the letter in the alphabet (^A is 1, ^B is 2, ^Z is 26).  The value of HOME is 30 and the value of ESCAPE is 27.  The value of the special keys are:

Key            Returned Value
F1-F16         128-143 (unshifted function keys)
sF1-sF16       144-159 (shifted function keys)
Next page      160
Prev page      161
Delete char    162
Delete line    163
Insert char    164
Insert line    165
Clear line     166
Toggle insert  167
Next word      168
Prev word      169
Delete word    170
Execute        171
Print          172
Help           173

Note that the SET FUNKEY statement must be executed before special key recognition is possible and the translation table must have been previously loaded into memory.

start at end

This parameter causes the cursor to be placed after the last character in the field when the field is first entered.

format as how

This parameter specifies how the data in the field is to be formatted for display purposes.  The data is displayed when the field is exited or when you use the DISPLAY.FIELD statement.  how in the parameter may be one of the following:

date

The data will be formatted as a date in the format MM/DD/YY or DD/MM/YY depending on the status of the European date flag.

telephone

The data will be displayed as a telephone number in either the format "(xxx) xxx-zzzz" or "xxx-yyyy" depending on the field length.

one digit

The data will be displayed with a single decimal place.  Leading zeroes will be supplied as necessary.

two digits

The data will be displayed with two decimal places.  Leading zeroes will be specified as necessary.

three digits

The data will be displayed with three decimal places.  Leading zeroes will be specified as necessary.

capitalized

The first letter of each word in the data will be capitialized.

upper case

All data input into the field will converted to upper case.

display as how

This parameter specifies how the data is to be displayed during redisplay or input.  how specifies the display as follows:

asterisks

All character input will be echoed as asterisks.  This is typically used for security oriented fields such as passwords.

no echo

Use of NO ECHO specifies that there will be no echoing of data or display of data in the field at all.  The cursor will remain in the same column during input.

right justified

This specifies that the data contained in the field will be displayed in a right justified manner using the maximum size of the field as the "window" in which to justify the data.

use eol clear

This parameter specifies that d/BASIC should use the terminal's built-in clear to end of line function rather than spaces to from the start of the field.

default to what

This parameter specifies what the field should default to as what should the operator enter no data in the field.  what may be one of the following:

todays date

The field will be set to the system date in the format MMDDYY or DDMMYY depending on the status of the European date format flag.

Y

The field will be set to "Y".  This default is usually used in "Y or N" data type fields.

N

The field will be set to "N".  This default is usually used in "Y or N" data type fields.

INPUT.FIELD examples:

   input.field STRING
      located at 10,35
      maximum size 30
      format as capitialized
      exit using ^J,^K,^E,HELP,PRINT,EXECUTE
    end field

   input.field SSNO
      located at 12,35
      maximum size 11
      edit mask ###-##-####
      exit using ^J,^K,HOME,^E,HELP
   end field


DRAWBOX
The DRAWBOX Statement

     Syntax:  drawbox row-exp,col-exp,length-exp,width-exp
Description:  Draws a box on the terminal screen
    Example:  drawbox 10,15,6,50

This statement draws a box on the terminal using the terminal's graphics characters starting on the row defined by row-exp and in the column starting at col-exp.  It will be length-exp rows in length and width-exp columns in width.  If the terminal does not support graphics characters, they will be simulated.


DRAW.FORM
The DRAW.FORM Statement

     Syntax:  draw.form strexp
Description:  Used to draw form on terminal using graphics characters
    Example:  draw.form "-8"

This statement is used to draw on the terminal's screen using the line drawing graphics set of the terminal.  "strexp" is a string expression consisting of the special graphics drawing characters according to the following table:

Character   Meaning
-       Horizontal line
=       Double horizontal
|       Vertical line
!       Double vertical line
>       Right side junction
<       Left side junction
v       Bottom side junction
^       Top side junction
+       Intersection
/       Upper left corner
\       Upper right corner
`       Lower left corner
'       Lower right corner
#       Solid block
%       Crosshatch block
&       Slant block
d       Draw down
u       Draw up
l       Draw left
r       Draw right
pr,c    Position cursor

Example:  draw.form "/-8d\|5l'-8u|5"

This example draws a rectangular box 10 columns by 7 rows.  Note that any character can repeated as with "-8" which says put eight horizontal lines.

Cursor positioning is either absolute or relative to the last cursor set command.  Use "+" or "-" characters before the row and column specifications to specify offsets.  You can mix both relative and absolute addressing.  For example, you can have a absolute row and a relative column number.


FORM.DEFINE
The FORM.DEFINE Statement

     Syntax:  form.define {exp1,exp2}
Description:  Defines a form
    Example:  form.define 6,32

This statement is used to define the actual form to be processed.  You can also set the form size with exp1 as the number of rows and exp2 as the number of columns.  The only time you would usually override the default form size (as set through the PAGE.SIZE statement) would be if multiple copies of the form were to appear on a single output page.

The FORM.DEFINE statement is a multiple line statement which has the following format:

   form.define rows,columns
      background
   end form

The END FORM statement is necessary or an %Unexpected end of file error message will result.  The background lines are the form to be output with field specifiers where ever variable data is to be output.  Example:

  form.define 6,32

         ^a
         ^b
         ^c
         ^d
   Attn: ^e
  end form

This example defines a form of size lines (or rows) and 32 columns.  There are five fields defined.  They all start in column eight.  There is some background text that will appear on the form as Attn:.  Assuming that the fields had been set up as follows:

  ^a="Paul Fistinyerface"
  ^b="1203 Looney Tune Drive"
  ^c="Ward C"
  ^d="Pleasantville, CA  90046"
  ^e="Paul"

Then the form that would be created would look like this:

          Paul Fistinyerface
          1203 Looney Tune Drive
          Ward C
          Pleasantville, CA  90046
   Attn:  Paul


BAR.INPUT
The BAR.INPUT Statement

     Syntax:  bar.input {into} nvar{,exp}
Description:  Used to present and process a light bar menu
    Example:  bar.input into OPTION'NUMBER, REDRAW

The BAR.INPUT statement is used to present and process a light bar oriented input menu.  On entry, the numeric variable nvar will contain the number of the option on which to place the light bar cursor.  The menu options are numbered in order from left to right on a row and then down to the next row.

On return from the statement, nvar will contain the number of the option selected.  If this value is zero, then the operator pressed ^C or ESCAPE. If special key recognition is enabled (by using the SET FUNKEY statement), then the BAR.INPUT statement returns special key information as part of the selected option number according to the following formula:

   special'key=nvar IDIV 256
   nvar-=special'key*256

In this case, the variable special'key will contain the number of the special key pressed.

For special key translation to work, the ".FNK" file for the terminal must previously be loaded into memory.  These function key files are built using the MAKFNK command.  They are usually loaded during the system initialization file using the SYSTEM command.  The possible special key values are:

Key            Returned Value
F1-F16         128-143 (unshifted function keys)
sF1-sF16       144-159 (shifted function keys)
Next page      160
Prev page      161
Delete char    162
Delete line    163
Insert char    164
Insert line    165
Clear line     166
Toggle insert  167
Next word      168
Prev word      169
Delete word    170
Execute        171
Print          172
Help           173

The optional expression exp is used to control whether or not BAR.INPUT is to draw the menu selections on the terminal before waiting for user input.  If the expression is not defined or evaluates non-zero, the menu will be output.

BAR.INPUT is a block structure statement that requires a corresponding END BAR statement.  The format of the structure is:

   bar.input into var,exp
      parameters
   end bar

The parameters that control the presention and definition of the menu are defined by parameters.  One to a line.  The valid parameters are:

located at x,y

Defines where the first option of the menu is to be located.  Following options are then laid out in a row, column format.  x is the starting row number and y is the starting column number.

double space

Specifies that the option rows are to be double spaced.  Recommended.

width n

Defines the width of the light bar as n characters.  This should be at least the width of the longest option plus 2.

delta n

Defines the width of the columns as n characters.

format x by y

Defines the size of the menu as x rows and y columns.

option text

Defines a menu option text as text.  The text may be enclosed in '"' characters or not.  The word option is optional if you do use the quotation marks.

immediate text

Normally items in the menu are selected by moving the light bar to an option and then pressing RETURN.  The immediate parameter allows you to specify single character entries as an immediate character that can be entered to select an option.  text is the list of characters that define these "hot" keys.

text array var

You may use this clause as another way of specifying the option text strings.  var is a string array which contains the options text that you want displayed on the screen.  Do NOT mix this clause and the "option" clause in the same bar.input statement.  Example:

   map1 OPT'TEXT(10),s,16

   bar.input into OPTION,REDRAW
      text array OPT'TEXT(1)
      located at 7,3
      ...

Note that the size of the array elements must be one character larger than the length of the longest option text.

The following is an example of the use of the BAR.INPUT statement:

   bar.input into option,redraw
      located at 7,3
      double space
      immediate "ABCDEFGHIJKLMN"
      width 12
      delta 15
      format 3 by 5
      option d/BASIC
      "d/VUE"
      "d/ASM"
      "d/MAIL"
      "d/TREE"
      "d/SHELL"
      "d/SPOOL"
      "ANDI"
      "TSASS"
      "MCL"
      option COMMON
      "andi 3.0f"
      "tsass 3.0f"
      "mcl 3.0f"
   end bar

This example contains 14 menu options.


FORM.ORIGIN
The FORM.ORIGIN Statement

     Syntax:  form.origin exp1,exp2
Description:  Changes to origin point of the form
    Example:  form.origin 1,40

This statement is used to change the origin of the form on the output page. Normally the form starts at origin point 1,1 which is the top left of the page.  This statement will change it to row exp1 and column exp2.  The advantage in doing this is in the production of multiple forms per printed page.


FORM.PRINT
The FORM.PRINT Statement

     Syntax:  form.print {#exp}
Description:  Causes the form to be printed
    Example:  form.print #1

This statement is used to output the contents of the current form either to file channel exp or the terminal screen.


FORM.PUT
The FORM.PUT Statement

     Syntax:  form.put exp1,exp2 outspec
Description:  Outputs to a form
    Example:  form.put 10,20 amount using "$##,###.##"

This statement is used to output directly to the form.  It can be used to overwrite background information.  Where the output is to start on the form is defined as row exp1 and column exp2.  outspec is any valid PRINT statement output definition.


NEW.FORM
The NEW.FORM Statement

     Syntax:  new.form
Description:  Initializes form area
    Example:  new.form

This statement is used to initalize a form for output processing.  In effect, what it does is transfer the background of the form as defined in the FORM.DEFINE statement to the output area and clear all other areas to blanks.


PAGE.SIZE
The PAGE.SIZE Statement

     Syntax:  page.size exp1,exp2
Description:  Defines the form page size
    Example:  page.size 66,132

This statement is used to define the page size of the form.  It is typically the size of the physical print medium.  exp1 is the number of rows and exp2 is the number of columns.  Use of this statement will set the size of the form also.


PICK.LIST
The PICK.LIST Statement

     Syntax:  pick.list {into} fltvar
Description:  Prompts user for one of "n" list selection
    Example:  pick.list into ITEM'NUMBER

PICK.LIST is a multi-line statement of the format:

   pick.list {into} fltvar
      parameters
   end picklist

The statement is used to provide a scrolling list of items indexed by a reverse video light bar.  The list is contained in a string array defined in the parameters section of the statement.  The number of the list item selected is returned in the floating point variable fltvar.

The user controls the light bar using the following inputs:

HOME

return to first item of first screen

RETURN

select item highlighted

ESCAPE

exit without selecting item

^C

exit without selecting item

^E

go to to list end

^J

go to next line

^K

go to previous line

^R

go to previous page

^T

go to next page

NEXT PAGE

go to next page

PREV PAGE

go to previous page

character

ASCII character.  PICK.LIST will go to the first item found in the list that starts with this letter.

TAB

go to next instance of an item starting with the same first character as the current item.

fltvar will be set to the following:

    0  user pressed ESCAPE.
 65535  user pressed ^C.
    n  item number when user presses RETURN.

 The item number is the relative position of the item in the list.

The statements that comprise the parameters of the PICK.LIST statement are:

text array strvar()

This parameter defines the start of the string array containing the text of the items to be picked from.  Note that either the last entry of the array must be empty or the variable defined immediately after the array should be zero.

depth exp

This parameter determines the number of items that can appear on the screen at any one time as exp.  It will default to "1" if undefined.

display size exp

This parameter defines the width of the item on the screen as exp.  This may be smaller than the actual size of the item text in the array.  If undefined, it will default to the maximum size of the array elements.

window size exp

This parameter defines the size of the graphics box displayed as exp screen positions in width.  If undefined, it will default to eight larger than the display element size.

title strexp

This parameter defines the optional list title as the string expression strexp.  It will appear inside the graphics box.  Make sure that the box is large enough for the title.

located at exp1,exp2

This parameter defines the start of the upper left hand corner of the pick list graphics box as row exp1 and column exp2.

special key variable fltvar

This parameter defines the name of the floating point variable that will recieve the value of any special key pressed besides PREV PAGE and NEXT PAGE.  You must have previously used a SET FUNKEY  statement for special keys to be recognized.

redraw exp

This parameter specifies whether or not the graphics box and title are to be redrawn when the PICK.LIST statement begins execution.  It will be redrawn if exp evaluates non-zero.

Example:
   map1 FILE'NAMES(20),s,10
   map1 ITEM'NUMBER,f,6
   map1 SPEC'KEY,f,6
        ...
        set funkey
        pick.list into ITEM'NUMBER
           located at 10,20
           text array FILE'NAMES(1)
           title "Select File Name"
           depth 3
           display size 10
           window size 24
           special key variable SPEC'KEY
        end picklist
        if SPEC'KEY goto PROCESS'SPECIAL'KEYS
        if ITEM'NUMBER=0 goto ABORT

This example would generate the following screen:

  Located at 10,20 --> +-------------------------+
                       |   Select File Name      |
                       +-+-----------------------+
                    /  |-| ABC.DQL               |
          Depth 3 -<   | | DEF.DQL               |
                    \  |v| CUSMAS.DQL            |
                       +-+-----------------------+
                        \.......... ............/
                                   V
                             Window size 24

Note that title is boxed by itself.  If no title was defined, then the top two lines shown above would not appear.  Also note that unlike the BAR.INPUT  statement, PICK.LIST allows expressions for all its parameters.


STATUS.LINE
The STATUS.LINE Statement

     Syntax:  status.line exp,strexp
Description:  Outputs text to one of the terminal's status lines
    Example:  status.line 1,"Press RETURN to Select Option"

This statement will cause the string defined by strexp to be output to one of the terminal's three status lines.  Which one is based on the numeric expression exp as follows:

   exp = 1 - Top status line
   exp = 2 - Bottom, unshifted, status line
   exp = 3 - Bottom, shifted, status line

If exp is any value other than 1, 2, or 3, it will default to 1.  Example:

   status.line 3,"Press sF4 for more entries"


WIPEBOX
The WIPEBOX Statement

     Syntax:  wipebox row-exp,col-exp,length-exp,width-exp
Description:  Clears a rectangular area on the terminal screen
    Example:  wipebox 10,15,6,50

This statement clears a rectangular area on the terminal screen using blank characters starting on the row defined by row-exp and in the column starting at col-exp.  It will be length-exp rows in length and width-exp columns in width.  This statement is usually used to clear a box drawn with the DRAWBOX statement.


DUAL.PRINT
The DUAL.PRINT Statement

     Syntax:  dual.print print-list
Description:  Displays text using dual output terminal intensities
    Example:  dual.print "This is _highlit_ and this is not!"

This statement is much like the normal print statement with two differences:

No channel number can be specified.

The output is in dual intensity using the high and low intensity settings of the terminal.  The output starts in low intensity. It is then changed by the appearance of "_" characters in the text.  Each underscore toggles between the two intensities.

The DUAL.PRINT statement supports the full range of USING modifiers and TAB functions that are allowed in the standard PRINT statement.


CRT / TCRT codes
KTCRT CodesCRT / TCRT codes

tab(-1,x) calls
NOTE: Calls marked with an asterisk (*) are either obsolete, or special purpose.Their use is not recommended, as they may change in the future.

  0 - Clear Screen
  1 - Home Cursor
  2 - Cursor return ( col 0 )
  3 - Cursor up
  4 - Cursor down
  5 - Cursor left one column
  6 - Cursor right one column
  7 - Lock Keyboard
  8 - Unlock Keyboard
  9 - Erase to end of line
 10 - Erase to end of screen
 11 - Background disply mode (reduced intensity)
 12 - Foreground display mode (normal intensity)
 13 - Enable protected fields
 14 - Disable protected fields
 15 - Delete Line
 16 - Insert Line
 17 - Delete character
 18 - Insert character
 19 - Read cursor address
 20 - Read character at cursor address
 21 - Start Blinking field
 22 - End Blinking field
 23 - Start line draw mode
 24 - End line draw mode
 25 * Set Horizontal position
 26 * Set Vertical position
 27 - Set Terminal attributes
 28 - Cursor On
 29 - Cursor off
 30 - Start underline
 31 - End Underline
 32 - Start reveres video
 33 - End reverse video
 34 - Start reverse blink
 35 - End reverse blink
 36 - Turn off screen display
 37 - Turn on screen display
 38 - Top Left corner character
 39 - Top right corner character
 40 - Bottom left corner character
 41 - Bottom right corner character
 42 - Top Intersect
 43 - Right Intersect
 44 - Left Intersect
 45 - Bottom Intersect
 46 - Horizontal line
 47 - Vertical line
 48 - Intersection
 49 - Solid block
 50 - Slant block
 51 - Cross-Hatch block
 52 - Double line horizontal
 53 - Double line Vertical
 54 - Send Message to function key line
 55 - Send message to shifted function key line
 56 - Set normal display format
 57 - Set horizontal split (follow with row codes from terminal manual)
 58 * Set vertical Split (39 char columns)
 59 * Set vertical split (40 char columns)
 60 * Set vertical split column to next character
 61 - Activate Split Segment 0
 62 - Activate Split Segment 1
 63 - Send message to host field
 64 - Up arrow character
 65 - Down arrow character
 66 - Raised dot
 67 - End of line marker
 68 - Horizontal tab symbol
 69 - Paragraph
 70 - Dagger
 71 - Section
 72 - Cent sign
 73 - One-Quarter
 74 - One-half
 75 - Degree
 76 - Trademark
 77 - Copyright
 78 - Registered
 79 - Print screen
 80 - Set to wide (132 col) mode
 81 - Set to normal (80 col) mode
 82 - Enter transparent print mode
 83 - Exit transparent print mode
 84 - Begin writing to alternate page
 85 - End writing to alternate page
 86 - Toggle page
 87 - Copy to alternate page
 88 - Insert column
 89 - Delete column
 90 - Block fill with attribute
 91 - Block fill with character
 92 - Draw a box
 93 - Scroll box up one line
 94 - Scroll box down one line
 95 - Select jump scroll
 96 - Select fast smooth scroll
 97 - Select med-fast smooth scroll
 98 - Select med-slow smooth scroll
 99 - Select slow smooth scroll
100 - Start underlined, blinking field
101 - End underlined, blinking field
102 - Start underlined, reverse field
103 - End underlined, reverse field
104 - Start underlined, reverse, blinking field
105 - End underlined, reverse, blinking field
106 - Start underline text without space
107 - End underline text without space
108 - Start reverse text without space
109 - End reverse text without space
110 - Start reverse blinking without space
111 - End reverse blinking without space
112 - Start Underlined blinking text without space
113 - End Underlined blinking text without space
114 - Start Underlined reverse text without space
115 - End Underlined reverse text without space
116 - Start underlined, reverse blinking text without space
117 - End underlined, reverse blinking text without space
118 - Start blink without space
119 - End blink without space
120 - Set cursor to blinking block
121 - Set cursor to steady block
122 - Set cursor to blinking underline
123 - Set cursor to steady underline
124 - Reserved
125 - Reserved
126 - Reserved
127 - Reserved
128 - Select top status line without address
129 - End status line ( all kinds )
130 - Select unshifted status line without address
131 - Select shifted status line without address
132 * Select black text
133 * Select white text
134 * Select Blue text
135 * Select magenta text
136 * Select red text
137 * Select yellow text
138 * Select green text
139 * Select cyan text
140 * Select black reverse text
141 * Select white reverse text
142 * Select Blue reverse text
143 * Select magenta reverse text
144 * Select red reverse text
145 * Select yellow reverse text
146 * Select green reverse text
147 * Select cyan reverse text
148 - Save a rectangular area
150 - Enable full graphics mode
151 - Disable full graphics mode
152 - Draw box with rounded corners
153 - Draw "window" style box
154 - Draw double line box
155 - Enable proportionally spaced text
156 - Disable proportionally spaced text
157 - Select color palette
158 - Enable graphics cursor
159 - Disable graphics cursor
160 - Select graphics cursor style
161 - Inquire graphics cursor position
162 - Define graphics cursor region
163 - Form feed symbol
164 - Line feed symbol
165 - New line symbol
166 - Verical tab symbol
167 - Plus-or-minus symbol
168 - Greater-than-or-equal symbol
169 - Less-than-or-equal symbol
170 - Not-equal symbol
171 - British Pound sign
172 - Pi Character
173-255 - Reserved

Programming color

tab(x,y);
 x = -2  Select foreground color
 x = -3  Select background color

 0  Black       4  Red
 1  White       5  Yellow
 2  Blue        6  Green
 3  magenta     7  Cyan


Miscellaneous Operators

BINARY
DEF
DIM
ENDSTRUCTURE
FLOAT
HOTKEY
MAP
MEM
OPERATOR
PROGRAM
RANDOMIZE
SORT.MEMORY
STRING
STRUCTURE
SYSOPR


BINARY
The BINARY Statement

     Syntax:  binary {n} varname{,varname,...}
Description:  Define binary variables
    Example:  binary recno

This directive is used to define binary variables.  You can define more than one to a line.  The variables may be arrays.  All variables defined are defined as MAP1  variables.  The BINARY directive is equivalent to the following MAP statement:

   map1 varname,b,n

Where n is length of each binary variable defined.  If undefined, it will default to 2.  n cannot be zero, greater than 5, or an expression.  You cannot use DEF text as the size either.

The advantage that the BINARY directive gives you is that you can define more than one to a line and also speed up compilations (less lines to process).  Examples:

   binary i,j
   binary 4 recdno, numrecds


DEF
The DEF Statement

     Syntax:  def name=text
Description:  Used to define named equates for program constants.
    Example:  def DIM=-1,11

The DEF directive is used to equate a name to a string of text.  The string of text will then replace the name whenever it appears as a term in an expression or as the array subscript in a MAP directive.  Examples:

   def BRITE=12
   def company="XYZ Corp"
   print tab(-1,BRITE);company

The result of this would be the PRINT statement being compiled as:

   print tab(-1,12);"XYZ Corp"

Consider another example:

   def imax=10
   def jmax=20
   map1 totals(imax,jmax),f,6

This would result in the "totals" array being mapped as followed:

   map1 totals(10,20),f,6

There are two special forms of the DEF directive:

   DEF name=SWITCHVALUE
   DEF name=SIZEOF variable

In the first format, name is still your name for the definition and SWITCHVALUE is any text defined using the "/V:" switch on the COMPIL command line.  Assume that your program was being compiled with the "/V" switch as follows:

   ) compil abc/v:100

And your program contained the following statements:

   def elements=SWITCHVALUE
   map1 things(elements),f

This would result in things being defined as a 100 element array.  The use of SWITCHVALUE occurs mostly when a program is being conditionally compiled.

The SIZEOF clause is used to equate the definition name name to the size of the variable variable which must be predefined in the program.  Example:

   map1 buffer,x,200
   def BUFSIZ=SIZEOF buffer

   map1 nullrecd,BUFSIZ,s,dupstr$("-",BUFSIZ)

DEF definitions must appear before they are used in an expression.  Any DEF definition of the same name as a variable will be found first, and the variable will be ignored during the compilation.


DIM
The DIM Statement

Array variables can be defined using the DIM statement which has the following syntax:

   dim varname(exp1,exp2,...),varname2(...)

Where varname is a valid d/BASIC variable name and exp1 (etc.) are the one or more expressions that evaluate to the maximum size of the particular dimension.  For example:

   dim x(5,2)      ! floating point array
   dim key(i,j+2)  ! floating point array
   dim names$(32)  ! string array

As with variables defined through use in expressions, whether or not the variable name ends with a $ character determines the type of the variable.

Each expression that defines the size of a dimension may be a standard d/BASIC numeric expression.

Variables created using the DIM statement are allocated space at run time. They may not be re-dimensioned using the same or another DIM statement.


STRUCTURE
The STRUCTURE Statement

     Syntax:  structure name
Description:  Used to define a named variable structure.
    Example:  structure dbms'packet

d/BASIC allows you to specify structures for the definition of variables. The format of the structure definition is:

   structure sname
      level name,type,size
      level name,type,size
   end structure

Where sname is the name of the structure being defined.  level is a MAP  level number (1-16).  name is a user variable name.  type is a variable type code ala MAP.  size is the size of the variable.  Example:

   structure dbms'packet
      1  recdno,b,4
      1  flags(5),b,4
      1  filename,s,30
      1  fields(128)
         2  fieldname,x,6
         2  fieldtype,b,1
         2  fieldsize,b,1
   end structure

In the above example none of the variables shown were defined.  We merely defined a structure of variables.  To actually define the variables in a structure we need to name and use it with the following format:

   structure-definition-name structure-name

Where structure-definition-name is the name of the structure as defined in the STRUCTURE directive (dbms'packet in our example above).  Since multiple copies of the same structure can exist, structure-name must be defined to distingush them.  Examples:

   dbms'packet sales
   dbms'packet cust'master

These examples define two structures of "type" dbms'packet.  They are named sales and cust'master.

The individual fields within the structure are now referred to as structure-name followed by the field name of the element within the structure separated by an underscore character.  Examples:

   print sales_recdno
   if cust'master_flag1(1)=1 goto read'record

As you can see, the two names are separated by the underscore character ("_").  Examining the PRINT statement we can see that the recdno field of the sales copy of the structure dbms'packet is being accessed.


FLOAT
The FLOAT Statement

     Syntax:  float varname{,varname,...}
Description:  Define floating point variables
    Example:  float i,j,x,y,z

This directive is used to define floating point variables.  You can define more than one to a line.  The variables may be arrays.  All variables defined are defined as MAP1 variables.  The FLOAT directive is equivalent to the following MAP statement:

   map1 varname,f,6

The advantage is that you can define more than one to a line and also speed up compilations (less lines to process).


MAP
The MAP Directive

In its most basic sense a MAP directive reserves memory for each variable so defined.  MAP directives are usually located at the beginning of the program.  The only placement requirement is that they must appear before the actual first usage of the variable being mapped.

The syntax of the MAP directive is:

   mapn varname,{type}{,size}{,initial-value}{,@origin}

Where n is the MAP level (more on this later), it may range in value from 1-16.  varname is the name of the variable being defined.  It follows standard d/BASIC rules.

You can define arrays using the MAP directive by following the variable name with the dimension maximum sizes (i.e., (4,2)). The dimension sizes must be constants.  Unlike the DIM statement, expressions are not allowed.  This is because the MAP statement allocates memory space for the variable at compilation time and not at run time.

Mapped variables may be defined with a lower bound for the array limit as in:   map1 years(1978:1989),f

This will create a twelve element array by the name of years.  You would refer to the first array element as:

   years(1978)=120

The last element would be years(1989).  You can mix both types of array elements in the same variable definition as in:

   map1 years(1978:1989,10),f

This creates a twelve by ten element array.

The ZEROBASE directive does not affect these types of bounded array elements.  Nor can the lower bound be 0.

type is the type of variable being defined which may be one of the
following:

B - Binary

Size defaults to 2.  May be 1-4 bytes in size.  Cannot have sub-MAP levels.

F - Floating Point

Size can only be 6.  Cannot have sub-MAP levels.

S - String

Size can be 1-32767.

X - Unformatted

Size can be 1-32767.  If type is undefined, it defaults to unformatted.

size in the MAP directive format is the optional size of the variable.  If type is B or F, it will default to 2 or 6, otherwise it will default to the sum of any following lower MAP levels.

initial-value is any valid expression used to initialize the variable when the program begins execution.  If the variable being defined is an array, it cannot have an initial value defined.

origin is the name of a variable that the currently defined variable will be overlaying in memory.  In effect, both variables will occupy the same physical locations.  This is frequently used when reading different record formats of a disk file into a common memory area.

Note that you must define intervening commas if you wish to define a parameter after one you don't define.  As an example, suppose you want to define an initial value for a variable but not its size, an example correct format would be:

   map1 pi,f,,3.1415

Examples of mapping variables:

map1 loop'index,f
Defines a variable named loop'index as a floating point variable.

map1 names(10),s,28
Defines a string array named names which has 10 elements of 28 characters each.

map1 buffer
Defines an unformatted variable whose size is determined by following MAP2-MAP16 levels.

map1 customer'record,,128,,@master'record
Defines an unformatted variable of 128 characters in size which will be relocated to exist in memory at the same locations as the variable named "master'record".  Note that customer'record can be smaller or larger than master'record.  If larger, there may be problems because of other variables following in memory may be affected.

map1 dashes,s,10,"----------"
Defines a string variable of length 10 which is initialized to - characters.

Unless you define an initial-value parameter, MAP directives do not have an effect on program size.  They will only allocate space in the variable data area.

The mega-power of MAP directives is that they allow you to group different variables types and sizes under a single variable name.  You can then operate on those variables as a single unit.  This is where the MAP level numbers mentioned previously come into play.

A mapped variable of type string or unformatted may have up to 15 levels sub-variables.  A variable is a sub-variable of a variable if its MAP level is higher than the previous level.

There is interesting quirk to mapped variables.  It concerns arrays.  If a variable with sub-variables is an array, the sub-variables either become arrays or gain as additional number of dimensions, the number of dimensions that are defined for the variable.  Example:

   map1 ab(10)
      map2 a,f,6
      map2 b,f,6

This will result in the definition of the array ab(10) which will consist of the pairs a(x) and b(x) as in a(1)-b(1), a(2)-b(2), etc.  Both a and b will be defined as single dimension arrays.  If they were already arrays, they would gain an extra dimension with a maximum element size of 10.


HOTKEY
The HOTKEY Statement

     Syntax:  hotkey #exp, strexp, var
Description:  Used to display hot key information
    Example:  hotkey #1, "DOT COMMANDS", result

The HOTKEY statement is used to display text information stored in a d/SOFT hot key file.  Such a file is built using d/VUE and the HOTCMP command supplied with d/VUE.  Details on creating hot key files is given in the d/VUE documentation.

exp defines the channel number of the channel which is open for HOTKEY access using the "open #exp,strexp,HOTKEY" syntax of the OPEN  statement.  strexp is the HOTKEY topic on which to provide help.  var is the optional result variable.  If specified, it will be set equal to 1 if the HOTKEY topic is in the file, otherwise it will be set equal to 0.  In all cases the terminal will beep if the topic cannot be located.

Examples:

   open #1,"HLP:DBASIC.HOT",hotkey
   hotkey #1,"instr"
   hotkey #1,"functions",result
   if result=1 goto TOPIC'NOT'THERE

d/BASIC uses the file DPSHOT.LIT to display the HOTKEY information.  This file can be stored in system memory to speed display time.


MEM
The MEM Statement

Syntax: mem(exp)

MEM returns information about the current memory usage of d/BASIC while your program is running.  exp specifies what information is to be returned as follows:

exp = 0.  Causes MEM to return the amount of free memory.

exp = 1.  Causes MEM to return the size of the user memory partition.

exp = 2, 3, or 4.  Causes MEM to return 0.

exp = 5.  Causes MEM to return the size of the .RUN file.

exp = 6.  Causes MEM to return the size of the data pool area.

exp = 7.  Causes MEM to return the size of the variable definition table.

exp = 8.  Causes MEM to return the size of the variable storage area.

exp = 9.  Causes MEM to return the size of the open file storage area.

exp = 10.  Causes MEM to return the size of the data heap area.

   print "Memory available:";mem(0)
   print "Partition size:";mem(1)


OPERATOR
The OPERATOR Statement

     Syntax:  operator level exp
Description:  Sets the operator's security level
    Example:  operator level 500

This statement allows you to change the operator's current d/SOFT security level temporarily to the value exp.   You cannot set an operator's level higher than your own.  Whatever value you set the level to will result in the operator's system access privileges being changed to reflect the new level (at least until the end of the program).


PROGRAM
The PROGRAM Statement

     Syntax:  program pgmname, ver{,sysopr,account12,operator}
Description:  Specifies program header information
    Example:  program armenu,1.0(23)

The PROGRAM directive is used to define items in the d/BASIC program header. You can define the version number of the program as ver in the standard version number syntax:

   A.BC(D)-E

Where: A is the major version number, B is the minor version number, C is the release letter, D is the edit level, and E is the patch level.  ver can be the special symbol "$" which will cause a version number to be produced in the form:

   YY.MM(DD)

Where "YYMMDD" is the system date when the program is compiled.

Examples:

   program sysmnu,3.4A(101)-2,sysopr
   program cusmas,10.2(13)
   program my'file,1.0(2),operator

The first example shows the use of the optional sysopr clause.  When used, it specifies that the program can only be run by a system operator.  A system operator is someone whose security level is at least 65250.  The third example shows an example of the operator clause.  Use of this caluse will require that the user be logged into the DSK0:[1,2] account in order to run the program.  The third optional clause is account12 which requires that the operator be in any [1,2] account.


RANDOMIZE
The RANDOMIZE Statement

     Syntax:  randomize
Description:  Used to generate a new random number seed
    Example:  randomize

The RANDOMIZE statement is used to generate a new, unique, seed for the random number generator (RND(x) function).  Normally d/BASIC starts out with the same starting seed for the generator.  This can be useful since you'll get the same run of numbers each time.  This can also be a pain since there are times when you want a different random number sequence.  The RANDOMIZE statement makes the difference.


SORT.MEMORY
The SORT.MEMORY Function

     Syntax:  sort.memory exp {records {of}} var {using} varlist
Description:  Used to sort d/BASIC memory arrays
    Example:  sort.memory NUM'RECS records of CUSTOMERS(1) using ZIP,NAME

The SORT.MEMORY statement is used to sort the array records contained in the variable var.  The number of records to be sorted is defined by the expression exp.  The keys to sort the array is defined by varlist which is a list of variables contained within the MAP structure of var.  Each variable can be further followed by either of the key words DESCENDING or ASCENDING which is used to specify the sort order of that key.  The default is an ascending sort.  Example:

  map1 buffer(100)
     map2 name,s,30
     map2 address,s,30
     map2 city,s,21
     map2 zip,f,6

  sort.memory NUM'REC records of buffer(1) using zip(1) descending,name(1)

This example will sort the data records located in the array buffer.  They will be sorted as name within zip.  The zip field will be sorted in descending order (high to low values).  The name field will be sorted in the normal order (low to high values).

Note that in the example varlist you had to define array element.  This element must be the same as var (in this case - buffer(1)).  Otherwise you will be given an error (#49 - sort key not in record).  Likewise, the keys must be sub-map levels of the array being sorted.

The array record must be less than 65536 bytes in size.


STRING
The STRING Directive

     Syntax:  string {n} varname{,varname,...}
Description:  Define string variables
    Example:  string 32,a$,b$

This directive is used to define string variables.  You can define more than one to a line.  The variables may be arrays.  All variables defined are defined as MAP1 variables.  The STRING directive is equivalent to the following MAP statement:

   map1 varname,s,n

Where n is length of each string variable defined.  If undefined, it will default to the current string size (STRSIZ) value.  n cannot be zero or an expression.  You cannot use DEF text as the size either.

The advantage that the STRING directive gives you is that you can define more than one to a line and also speed up compilations (less lines to process).  Examples:

   string a$,b$
   string 10 last'name, FIRST'NAME


User Defined Functions
External User defined Functions

Bit Manipulation:
  bitlit	  bitval	  setbit
  clrbit	  togbit

Date Manipulation:
  DateValue	  DateString	  dow
  cdow	  formatdate

I/O Functions:
  inkey	  inyn	  usr'msg
  fmtnum	  zs	  Scrheader

Math Functions:
  percent	  lesser	  approx
  average	  greater

String Functions:
  segupr


bitlit

Incl  :  BITS.FNC
Syntax:  x = bitlit( y, z )

Return:  True if bit #z ( 0 - x ) of value y is set to 1.


BitVal

Incl  :  BITS.FNC
Syntax:  x = bitval( y )

Return:  Value of bit position y  ( 0 - ? )


SetBit

Incl  :  BITS.FNC
Syntax:  x = setbit( x, y )

Return:  Value x with bit y ( 0 - ? ) turned on.


ClrBit

Incl  :  BITS.FNC
Syntax:  x = clrbit( x, y )

Return:  Value x with bit y ( 0 - ? ) turned off.


TogBit

Incl  :  BITS.FNC
Syntax:  x = togbit( x, y )

Return:  Value x with bit y ( 0 - ? ) flipped.


DateValue

Incl  :  DATES.FNC
Syntax:  x = DateValue( $ )

Return:  Numeric value of date $.

$ format must be MMDDYY{YY}  ( century optional )
Value contains century manipulation, but will handle older serial values.


DateString

Incl  :  DATES.FNC
Syntax:  $ = DateString( Date, x )

Return:  Date as String.

Date contains century manipulation, but will handle older serial values.
x specifies year format.  May be one of the following pre-defined constants:
   century - full century/year
  standard - display 2 digit year only


formatdate

Incl  :  DATES.FNC
Syntax:  $ = formatdate( Date, style, flags )

Return:  Date as String.

formatdate contains century manipulation, but will handle older serial values.

style can be one of the following defines:

mdy   - uses mm/dd/yy format
mtdy  - uses month text dd/yy format
mtdy2 - uses month text dd, yy format

flags can be any combination of the following defines:

century  - display century and year
standard - display year only
dayinit  - day text initial only
day3char - day text as 3 characters only
daystr   - full day of week text
fullmonth - full month text (default is 3 char )


dow

Incl  :  DATES.FNC
Syntax:  x = dow( Date )

Return:  numeric day of week for date.

Date contains century manipulation, but will handle older serial values.
return value is 1 - 7


cdow

Incl  :  DATES.FNC
Syntax:  $ = cdow( Date, ln )

Return:  day of week for date as string.

Date contains century manipulation, but will handle older serial values.
ln specifies length of return string.
  ie  2 yields Mo Tu  etc..
      0 returns full text


inkey

Incl  :  INPUT.FNC
Syntax:  x = inkey()

Return:  Value of key pressed.

Inkey() will pause for user keypress if the keyboard buffer is empty, otherwise it will return the next character in the buffer.

The value will be set to uppercase if the character is an alpha character.


inyn

Incl  :  INPUT.FNC
Syntax:  $ = inyn( p$ )

Return:  Y or N dependant upon user keypress.

Inyn() will print the string p$ on line 24, and pause for user input. The function will only terminate with a valid Y/N value.  When valid keypress is encountered, the 24th line will be cleared prior to returning.


usrmsg

Incl  :  MSG.FNC
Syntax:  x = usr'msg( p$ )

Return:  Value of key pressed.

Usr'msg() is a generic send the user a message function that will print the string p$ on line 24, ring the bell to get his attention, and pause for input.  The text "- Press any key will be concatenated onto the string sent to the function.
The 24th line will be cleared prior to returning.


percent

Incl  :  MATH.FNC
Syntax:  x = percent( a, b )

Return:  Percentile Value a of b.

percent() uses the formula
      / a \
 1/  | --- |  * 100
      \ b /


lesser

Incl  :  MATH.FNC
Syntax:  x = lesser( a, b )

Return:  The lesser value a or b.


approx

Incl  :  MATH.FNC
Syntax:  x = approx( a, b, c )

Return:  true if a and b within c of each other.


fmtnum

Incl  :  FORMAT.FNC
Syntax:  $ = fmtnum( num, len, dec, fl )

Return:  num formatted various ways.

parameters:
  num - value to translate
  len - maximum string size for value
  dec - number of decimal places to set
  fl  - Flags for use of dollar sign / zero suppress etc )

The constant definitions nozero, dollarsign and commas can be used or combined as the flag values to tell the function how to format.
  nozero - will return blank string for 0 values (default print 0)
  dollarsign - will attach floating dollar sign.  (default no $)
  commas - will format the string with comma seperators (default no comma)

negative values will be contained inside parantheses.

sample:
  d$ = fmtnum( x, 12, 2, nozero + dollarsign + commas )
     for x = 123456
     returns $1,234.56

Strings that are greater in length than the specified maximum will be returned as * characters.


zs

Incl  :  FORMAT.FNC
Syntax:  p$ = zs( a, x$, u$ )

Return:  string rep of x or blank.

zs() is a zero supression function.  Any value(s) that result in 0 will be returned as a blank string.  All values will be set into output mask x$ using format mask u$.
for example:
  p$ = zs( .date, "##/##/##", "#ZZZZZ")
  p$ = zs( percent(x,y), "###%", "###")


segupr

Incl  :  STRING.FNC
Syntax:  p$ = segupr( a$, s, e)

Return:  string a$ with segment [s,e] flipped upper.

example:
  NmStr = segupr(NmStr, 1, instr(1, NmStr, ":"))

If either numeric parameter results in 0, the string is unchanged.


greater

Incl  :  MATH.FNC
Syntax:  x = greater( a, b )

Return:  The greater value a or b.


average

Incl  :  MATH.FNC
Syntax:  x = average( a, b )

Return:  The average value of a for b.


Scrheader

Incl  :  HEADER.FNC
Syntax:  x = Scrheader( Title, Xtra)

Return:  nothing of value.

Will produce a standard screen header using Title as the second line contents, and Xtra as text on lower right ( to a max of 12 characters).

format:
 date           company           time
            centered title
 user           program           Xtra