2-266 The OPL keywords - (to find a keyword, precede it by a dot)"266 Scanning the keyboard directly+267 I/O calls: read cursor, set alarm, dial 268 Recording and playing sounds
269 Foreground and background&270 Serial/parallel ports and printing
271 OPAs and the System screen!272 Calling procedures by strings
273 Data files!274 The text and graphics windows
275 Error messages#276 File extensions and directories
277 Hexadecimals
278 Operators and expressions
279 Character set and key codes
v0.92 8/8/941Comments, bugs etc to nhealey@cix.compulink.co.uk@
a=ABS(x)dReturns the absolute value of a floating-point number - that is, without any +/- sign - for example:
ABS(-10.099) is 10.099
If x is an integer, you won't get an error, but the result will be converted to floating-point - for example ABS(-6) is 6.0. Use IABS to return the absolute value as a long integer.
.ACOS a=ACOS(x)-Returns the arc cosine (inverse cosine) of x.
x must be in the range -1 to +1. The number returned will be an angle in radians. To convert the angle to degrees, use the DEG function.
.ADDR
a%=ADDR(variable):Returns the address at which variable is stored in memory.pThe values of different types of variables are stored in bytes starting at ADDR(variable). See PEEK for details.
See also UADD, USUB.
.ADJUSTALLOC$pcelln%=ADJUSTALLOC(pcell%,off%,am%)
Opens or closes a gap at off% within the allocated cell pcell%, returning the new cell address or zero if out of memory. off% is 0 for the first byte in the cell. Opens a gap if the amount am% is positive, and closes it if negative.
.ALERTmr%=ALERT(m1$,m2$,b1$,b2$,b3$)
r%=ALERT(m1$,m2$,b1$,b2$)
r%=ALERT(m1$,m2$,b1$)
r%=ALERT(m1$,m2$)
r%=ALERT(m1$)
Presents an alert - a simple dialog - with the messages and keys specified, and waits for a response. m1$ is the message to be displayed on the first line, and m2$ on the second line.XIf m2$ is not supplied or if it is a null string, the second message line is left blank.
Up to three keys may be used. b1$, b2$ and b3$ are the strings (usually words) to use over the keys. b1$ appears over an Esc key, b2$ over Enter, and b3$ over Space. This means you can have Esc, or Esc and Enter, or Esc, Enter and Space keys.MIf no key strings are supplied, the word "Continue" is used above an Esc key.EThe key number - 1 for Esc, 2 for Enter or 3 for Space - is returned.
.ALLOC
pcell%=ALLOC(size%)
Allocates a cell on the heap of the specified size, returning the pointer to the cell or zero if there is not enough memory. The new cell is uninitialised - you cannot assume that it is zeroed.
APP name
ENDAfBegins definition of an OPA. name gives the name of the OPA. (Note that it does not have quote marks.)TThe APP line may be followed by any or all of the keywords PATH, EXT, ICON and TYPE.
.APPEND
APPEND
Adds a new record to the end of the current data file. The record which was current is unaffected. The new record, the last in the file, becomes the current record.{The record added takes the current values of the field variables A.field1$, A.field2$, and so on, of the current data file.
If a field has not been assigned a value, zero will be assigned to it if it is a numeric field, or a null string if it is a string field.BTo overwrite the current record with new field values, use UPDATE.p
.APPENDSPRITE>APPENDSPRITE time%,bit$(),dx%,dy%
APPENDSPRITE time%,bit$()
Appends a single bitmap-set to the current sprite. It can be called up to 13 times for each sprite, before the sprite is drawn.
time% gives the duration in tenths of seconds for the bitmap-set to be displayed before going on to the next bitmap-set in the sequence.zbit$() contains the names of bitmap files in the set, or "" to specify no bitmap. The array must have at least 6 elements: bit$(1) for setting black pixels!bit$(2) for clearing black pixels"bit$(3) for inverting black pixels
bit$(4) for setting grey pixels bit$(5) for clearing grey pixels!bit$(6) for inverting grey pixels
Use "" to specify no bitmap. If "" is used for all the bitmaps in the set, the sprite is left blank for the specified duration.
All the bitmaps in a single bitmap-set must be the same size or `Argument' error (-2) is raised on attempting to draw the sprite. Bitmaps in different bitmap-sets may differ in size.
dx% and dy%, if supplied, are the (x,y) offsets from the sprite position to the top-left of this bitmap-set, with positive for right and down. The default value of each is zero.
Sprites may use a lot of memory. A sprite should generally be created, initialised and closed in the same procedure to prevent memory fragmentation. Care should also be taken in error handling to close a sprite that is no longer in use.8
a%=ASC(a$)8Returns the character code of the first character of a$.:See also the entry entitled "Character set and key codes".FAlternatively, use A%=%char to find the code for char - eg %X for `X'.4If a$ is a null string ("") ASC returns the value 0.
Example:.A%=ASC("hello") returns 104, the code for `h'.
.ASIN a=ASIN(x))Returns the arc sine (inverse sine) of x.
x must be in the range -1 to +1. The number returned will be an angle in radians. To convert the angle to degrees, use the DEG function.v
AT x%,y%
Positions the cursor at x% chars across the text window and y% rows down. AT 1,1 moves to the top left corner of the window. Initially, the window is the full size of the screen, but you can change its size and position with the SCREEN command.aA common use of AT is to display strings at particular positions in the text window. For example:
AT 5,2 :PRINT "message".
PRINT statements without AT display on the left of the window on the line below the last PRINT statement (unless you use `,' or `;'). Strings displayed at the top of the window scroll off as more strings are shown at the bottom of the window.
Displayed strings always overwrite anything that is on the screen - they do not cause things below them on the screen to scroll down.sAn example in the entry entitled "I/O calls: read cursor, set alarm, dial" shows a way to read the cursor position.
.ATAN a=ATAN(x).Returns the arc tangent (inverse tanget) of x.gThe number returned will be an angle in radians. To convert the angle to degrees, use the DEG function.
.BACK
BACKFMakes the previous record in the current data file the current record._If the current record is the first record in the file, then the current record does not change.\
.BEEP
BEEP time%,pitch%
Sounds the buzzer. The beep lasts for time%/32 seconds - so for a beep a second long make time%=32, etc. The maximum is 3840 (2 minutes).9The pitch (frequency) of the beep is 512/(pitch%+1) KHz.,BEEP 5,300 gives a comfortably pitched beep.
If you make time% negative, BEEP first checks whether the sound system is in use (perhaps by another OPL program), and returns if it is. Otherwise, BEEP waits until the sound system is free. Example - a scale from middle C:
PROC scale:
LOCAL freq,n%
REM n% relative to middle A
n%=3 REM start at middle C
WHILE n%<16
freq=440*2**(n%/12.0)
REM middle A = freq 440Hz
BEEP 8,512000/freq-1.0
n%=n%+1* IF n%=4 OR n%=6 OR n%=9 OR n%=11 OR n%=13 n%=n%+1
ENDIF
ENDWH
ENDP{Alternatively, sound the buzzer with this statement: PRINT CHR$(7). This beeps at a fixed pitch for a fixed length of time.
.BREAK
BREAK
Makes a program performing a DO...UNTIL or WHILE...ENDWH loop exit the loop and immediately execute the line following the UNTIL or ENDWH statement.
.BUSY3BUSY str$,c%,delay%
BUSY str$,c%
BUSY str$
BUSY OFF
BUSY str$ displays str$ in the bottom left of the screen, until BUSY OFF is called. Use this to indicate `Busy' messages, usually when an OPL program is going to be unresponsive to keypresses for a while.DIf c% is given, it controls the corner in which the message appears: c% corner
0 top left
1 bottom left (default)
2 top right
3 bottom right
delay% specifies a delay time (in half seconds) before the message should be shown. Use this to prevent `busy' messages from continually appearing very briefly on the screen._Only one message can be shown at a time. The string to display can be up to 19 characters long.
.CACHE#CACHE init%,max%
CACHE ON
CACHE OFF
CACHE creates a procedure cache of a specified initial number of bytes init% which may grow up to the maximum size max%. You should usually TRAP this.
The minimum cache size is 2000 bytes, which is used if any lower value is specified. If the maximum size specified is less than the initial size, the maximum is set to the initial size. The maximum cache size cannot be changed once the cache has>been created and an error is returned if you attempt to do so.
Once a cache has been created, CACHE OFF prevents further cacheing, although the cache is still searched when calling subsequent procedures. CACHE ON may then be used to re-enable cacheing.wYou can specify init% and max% up to 32,767 bytes. If you use hex, you can even exceed this figure, if you need to - eg
CACHE $9000,$9000WHowever, you cannot exceed the 64k total memory limit which each Series 3a process has.
.CACHEHDR
CACHEHDR addr(hdr%())
The cache index begins with a header, then has one index record for each procedure cached. CAHCEHDR reads the header into array hdr%(), which must have at least 11 integer elements.+hdr%(1) current address of the cache itself-hdr%(2) number of procedures currently cached*hdr%(3) maximum size of the cache in bytes*hdr%(4) current size of the cache in bytes)hdr%(5) number of free bytes in the cacheWhdr%(6) total number of bytes in cached procedures which are freeable (ie. not running)Ohdr%(7) offset from the start of the cache index to the first free index record_hdr%(8) offset from start of cache index to most recently used procedure's record; zero if none`hdr%(9) offset from start of cache index to least recently used procedure's record; zero if noneDhdr%(10) address of the cache index, or zero if no cache created yet:hdr%(11) non-zero if cacheing is on, and zero if it is offmAll offsets mentioned give the number of bytes from the start of the index to the procedure record specified.TIf no cache has yet been created, hdr%(10)=0 and the other data read is meaningless.
Note that any information returned is liable to change whenever a procedure is called, so you cannot save these values over a procedure call.
.CACHEREC
CACHEREC addr(rec%()),off%kRead the cache index record at offset off% into array rec%(), which must have at least 18 integer elements.
Alternatively off%=0 specifies the most recently used (MRU) procedure's record, if any, and off%<0 the least recently used procedure (LRU) procedure's record, if any.Irec%(1) offset to less recently used procedure's record or zero if on LRUIrec%(2) offset to more recently used procedure's record or zero if on MRU)rec%(3) usage count - zero if not runningMrec%(4) offset in cache itself to descriptor for building the procedure frameCrec%(5) offset in cache itself to translated code for the procedureRrec%(6) offset in cache itself to the end of the translated code for the procedureArec%(7) number of bytes used by the procedure in the cache itselfMrec%(8-15) leading byte counted procedure name, followed by some private dataDrec%(16) address of the procedure's leading byte counted module nameDrec%(17) address of the cache index, or zero if no cache created yet:rec%(18) non-zero if cacheing is on, and zero if it is offeFor a free index record only rec%(1) is significant, giving the offset of the next free index record.
The data returned by CACHEREC is meaningless if no cache exists (in which case rec%(17)=0) or if there are no procedures cached yet (when hdr%(8)=0 as returned by CACHEHDR).
Note that any information returned is liable to change whenever a procedure is called, so you cannot save these values over a procedure call.
The index records for cached procedures form a doubly linked list, starting from first the most recently used procedure (MRU), then from the least recently used procedure (LRU). A further singly linked list gives the offsets to free index records.NThis is an advanced command, intended for use during program development only.G
.CACHETIDY CACHETIDY
Remove from the cache any procedures that have returned to their callers. This might be called after performing a large, self-contained action in the program which required many procedures.sNote that a procedure which has returned is automatically removed from the cache if you unload the module it is in.
.CALL
e%=CALL(s%,bx%,cx%,dx%,si%,di%)
This function enables you to make operating system calls. To use it requires extensive knowledge of the Operating System and related programming techniques.
The INT number is the least significant byte of s%. The AH value (the subfunction number) is the most significant byte of s%. The values of the other arguments are passed to the corresponding 8086 registers. The value of the AX register is returned.>
Changes the bitmap-set specified by ix% (1 for the first bitmap-set) in the current sprite, using the supplied bitmap files, offsets and duration in the same way as for APPENDSPRITE.1CHANGESPRITE can be called only after DRAWSPRITE.
.CHR$
a$=CHR$(x%)-Returns the character with character code x%.
You can use it to display characters not easily available from the keyboard - for example, the instruction PRINT CHR$(174) displays
.:See also the entry entitled "Character set and key codes".
.CLOSE
CLOSEXCloses the current file (that is, the one which has been OPENed and most recently USEd).
If you've used ERASE to remove some records, CLOSE recovers the memory used by the deleted records, provided it is held either in the internal memory or on a Ram SSD.<
.CLOSESPRITE
CLOSESPRITE id%
Closes the sprite with ID id%.
CLS'Clears the contents of the text window.
The cursor then goes to the beginning of the top line. If you have used CURSOR OFF the cursor is still positioned there, but is not displayed.T
.CMD$
c$=CMD$(x%)
Returns the command-line arguments passed when starting a program. Null strings may be returned. x% should be from 1 to 5. cmd$(2) to cmd$(5) are only for OPAs (OPL applications).Ecmd$(1) returns the full path name used to start the running program.Pcmd$(2) returns the full path name of the file to be used by an OPA application.
cmd$(3) returns "C" for "Create file" or "O" for "Open file". If the OPA is being run with a new filename, this will return "C". This happens the very first time the OPA is used, and whenever a new filename is used to run it. Otherwise, the OPA isIbeing run with the name of an existing file, and cmd$(3) will return "O".Zcmd$(4) returns the alias information, if any. In practice this has no relevance for OPAs.Gcmd$(5) returns the application name, as declared with the APP keyword.
See also GETCMD$.
.COMPRESS
COMPRESS src$,dest$
Copies data file src$ to another data file dest$. If dest$ already exists, the records in src$ are appended to the end of dest$.
Deleted records are not copied. This makes COMPRESS particularly useful when copying from a Flash SSD. (The space used by deleted records on a Ram SSD or in internal memory is automatically freed when you close the file.)>If you want src$ to overwrite instead of append to dest$, use:
TRAP DELETE dest$
before the COMPRESS statement.
You can use wildcards to copy more than one file at a time. But if the first name contains any wildcards, the second name must not include a filename, just the device and directory to which the files are to be copied under their original names.VExample: to copy all the data files on A: (in \OPD, the default directory) to B:\BCK\:
COMPRESS "A:*.ODB","B:\BCK\"5(Remember the final backslash on the directory name.)&See COPY for copying any type of file.
.CONTINUE
CONTINUE
Makes a program immediately go to the UNTIL... line of a DO...UNTIL loop or the WHILE... line of a WHILE...ENDWH loop - ie to the test condition.
See also BREAK.X
.COPY
COPY src$,dest$
Copies the file src$, which may be of any type, to the file dest$. Any existing file with the name dest$ is deleted. You can copy across devices.
Use the appropriate file extensions to indicate the type of file, and wildcards if you wish to copy more than one file at a time:
If src$ contains wildcards, dest$ must not specify a filename, just the device and directory to which the files are to be copied under their original names.G
You must specify either an extension or .* on the first filename.LExample: To copy all the OPL files from internal memory (in \OPL) to B:\ME\:
COPY "M:\OPL\*.OPL","B:\ME\"5(Remember the final backslash on the directory name.)
See COMPRESS for more control over copying data files. If you use COPY to copy a data file, deleted records are copied and you cannot append to another data file.
c=COS(x)8Returns the cosine of x, where x is an angle in radians.9To convert from degrees to radians, use the RAD function.t
.COUNT
c%=COUNT7Returns the number of records in the current data file.+This number will be 0 if the file is empty.
.CREATE
CREATE file$,log,f1,f2,...!Creates a data file called file$.x
The filename may be a full file specification of up to 128 characters. Field names may be up to 8 letters/numbers.
The file may have up to 32 fields, as specified by f1, f2... (if viewed in the Database application, field f1 starts on the top line of the window, f2 is below it, etc.)
log specifies the logical file name - A, B, C or D. This is used as an abbreviation for the file name when you use other data file commands such as USE.MImmediately after the CREATE statement, the file is open and can be accessed.
Example:
CREATE "CLIENTS",B,NM$,PHON$]would create a data file in the internal memory with the name CLIENTS and the logical name B.J
.CREATESPRITE
id%=CREATESPRITE*Creates a sprite, returning the sprite ID.z
.CURSORQCURSOR ON
CURSOR OFF
CURSOR id%,asc%,w%,h%
CURSOR id%,asc%,w%,h%,type%
CURSOR id%hCURSOR ON switches the text cursor on at the current cursor position. Initially, no cursor is displayed.
You can switch on a graphics cursor in a window by following CURSOR with the ID of the window. This replaces any text cursor. At the same time, you can also specify the cursor's shape, and its position relative to the baseline of text.
asc% is the ascent - the number of pixels (-128 to 127) by which the top of the cursor should be above the baseline of the current font. h% and w% (both from 0 to 255) are the cursor's height and width.BIf you do not specify them, the following default values are used:
asc% =font ascent
h% =font height
w% =2-If type% is given, it can have these effects:
1 obloid
2 not flashing
4 greylYou can add these values together to combine effects - eg if type% is 6 a grey non-flashing cursor is drawn.BAn error is raised if id% specifies a bitmap rather than a window.#CURSOR OFF switches off any cursor.sAn example in the entry entitled "I/O calls: read cursor, set alarm, dial" shows a way to read the cursor position.
.DATETOSECS&s&=DATETOSECS(yr%,mo%,dy%,hr%,mn%,sc%)WReturns the number of seconds since 00:00 on 1 January 1970 at the date/time specified.0Raises an error for dates before 1 January 1970./The value returned is an unsigned long integer.
(Values up to +2,147,483,647, which is 03:14:07 on 19/1/2038, are returned as expected. Those from +2,147,483,648 upwards are returned as negative numbers, starting from -2,147,483,648 and increasing towards zero.)*See also SECSTODATE, HOUR, MINUTE, SECOND.
.DATIM$ d$=DATIM$RReturns the current date and time from the system clock as a string - for example:
"Fri 16 Oct 1992 16:25:30"5The string returned always has the format shown here.R
d%=DAYEReturns the current day of the month (1 to 31) from the system clock.
.DAYNAME$
d$=DAYNAME$(x%)]Converts x%,a number from 1 to 7, to the day of the week, expressed as a three letter string.
Eg d$=DAYNAME$(1) returns MON.
Example:
PROC Birthday:
LOCAL d&,m&,y&,dWk%
dINIT
dTEXT "","Date of birth",2
dTEXT "","eg 23 12 1963",$202
dLONG d&,"Day",1,31
dLONG m&,"Month",1,12
dLONG y&,"Year",1900,2155
IF DIALOG=0 :BREAK :ENDIF
dWk%=DOW(d&,m&,y&)
CLS :PRINT DAYNAME$(dWk%),
PRINT d&,m&,y&
dINIT
dTEXT "","Again?",$202
dBUTTONS "No",%N,"Yes",%Y
UNTIL DIALOG<>%y
See also DOW.
.DAYS
d&=DAYS(day%,month%,year%),Returns the number of days since 01/01/1900.:Use this to find out the number of days between two dates.
Example:
PROC deadline:
LOCAL a%,b%,c%,deadlin&
LOCAL today&,togo%
PRINT "What day? (1-31)" INPUT a%
PRINT "What month? (1-12)" INPUT b%
PRINT "What year? (19??)" INPUT c%
deadlin&=DAYS(a%,b%,1900+c%)
today&=DAYS(DAY,MONTH,YEAR)
togo%=deadlin&-today&
PRINT togo%,"days to go"
See also dDATE, SECSTODATE.t
.dBUTTONSJdBUTTONS p1$,k1%,p2$,k2%,p3$,k3%
dBUTTONS p1$,k1%,p2$,k2%
dBUTTONS p1$,k1%2Defines exit keys to go at the bottom of a dialog.
From one to three exit keys may be defined. Each pair of p$ and k% specifies an exit key; p$ is the text to be displayed above it, while k% is the keycode of the key. DIALOG returns the keycode of the key pressed (in lower case for letters).
For alphabetic keys, use the % sign - %A means `the code of A', and so on. See the entry entitled "Character set and key codes" for the codes of keys (such as Tab) which are not part of the character set. If you use the code for one of these keys,9its name (eg `Tab', or `Enter') will be shown in the key.
If you use a negative value for a k% argument, that key is a `Cancel' key. The corresponding positive value is used for the key to display and the value for DIALOG to return, but if you do press this key to exit, the var variables used in the0commands like dEDIT, dTIME etc. will not be set.
The Esc key will always cancel a dialog box, with DIALOG returning 0. If you want to show the Esc key as one of the exit keys, use -27 as the k% argument (its keycode is 27) so that the var variables will not be set if Esc is pressed.
There can be only one dBUTTONS item per dialog, and it takes up three lines on the screen. dBUTTONS must be the last dialog command you use before DIALOG itself.JSome keypresses, such as those using the Control key, cannot be specified.RThis example presents a simple query, returning `True' for Yes, or `False' for No.
PROC query:
dINIT
dTEXT "","FORGET CHANGES",2
dTEXT "","Sure?",$202
dBUTTONS "No",%N,"Yes",%Y
RETURN DIALOG=%y
ENDP\
.dCHOICE
dCHOICE var choice%,p$,list$(Defines a choice list to go in a dialog.
p$ will be displayed on the left side of the line. list$ should contain the possible choices, separated by commas - for example, "Yes,No". One of these will be displayed on the right side of the line; LEFT/RIGHT move between the choices.
choice% must be a LOCAL or a GLOBAL variable. It specifies which choice should initially be shown - 1 for the first choice, 2 for the second, and so on. When you finish the dialog, choice% is given a value indicating which choice was selected -)again, 1 for the first choice, and so on.
.dDATE
dDATE var lg&,p$,min&,max&2Defines an edit box for a date, to go in a dialog.2p$ will be displayed on the left side of the line.
lg&, which must be a LOCAL or a GLOBAL variable, specifies the date to be shown initially. Although it will appear on the screen like a normal date, for example 15/03/92, lg& must be specified as "days since 1/1/1900".
min& and max& give the minimum and maximum values which are to be allowed. Again, these are in days since 1/1/1900. An error is raised if min& is higher than max&.bWhen you finish using the dialog, the date you entered is returned in lg&, in days since 1/1/1900.PThe system setting determines whether years, months or days are displayed first.
See also DAYS, SECSTODATE.U
.dEDIT+dEDIT var str$,p$,len%
dEDIT var str$,p$-Defines a string edit box, to go in a dialog.2p$ will be displayed on the left side of the line.
str$ is the string variable to edit. Its initial contents will appear in the dialog. The length used when str$ was defined is the maximum length you can type in.
len%, if supplied, gives the width of the edit box (allowing for the widest possible character in the font). The string will scroll inside the edit box, if necessary.gIf len% is not supplied, the edit box is made wide enough for the maximum width str$ could possibly be.
See also dTEXT.<
.DEFAULTWIN
DEFAULTWIN mode%tChange the default window (ID=1) to enable or disable the use of grey. Initially grey cannot be used in that window. mode%=1 enables the use of grey.!mode%=0 disables the use of grey.;A side-effect of DEFAULTWIN is to clear the default window.6Using grey does use more memory than using black only.
You are advised to call DEFAULTWIN once and for all near the start of your program if you need to use grey. If it fails with `Out of memory' error, the program can then exit cleanly without losing vital information.
See also gGREY and gCREATE.
d=DEG(x)!Converts from radians to degrees.UReturns x, an angle in radians, as a number of degrees. The formula used is: 180*x/PI
All the trigonometric functions (SIN,COS etc.) work in radians, not degrees. You can use DEG to convert an angle returned by a trigonometric function back to degrees - for example:
PROC xarctan:
LOCAL arg,angle
PRINT "Enter argument:";
INPUT arg
PRINT "ARCTAN of",arg,"is"
angle=ATAN(arg)
PRINT angle,"radians"
PRINT DEG(angle),"degrees"
ENDP,To convert from degrees to radians, use RAD.
.DELETE
DELETE filename$
Deletes any type of file.KYou can use wildcards - for example, to delete all the OPL files in B:\OPL:
DELETE "B:\OPL\*.OPL"=See also the entry entitled "File extensions and directories"
See also RMDIR.M
.dFILE
dFILE var str$,p$,f%kDefines a filename edit box, to go in a dialog. A `Disk' selector is automatically added on the line below.2p$ will be displayed on the left side of the line.uf% controls the type of file editor, and the kind of input allowed. You can add together any of the following values:
value meaning
1 use an edit box
2 allow directory names
4 directory names only
8 disallow existing files
16 query existing files
32 allow null string input
64 don't display extension
128 obey/allow wildcards
The first of the list is the most crucial. If you add 1 into f%, you will see an file edit box, as when creating a new file. If you do not add 1, you will see the `matching file' selector, used when choosing an existing file.
If performing a `copy to' operation, you might use 1+2+16, to specify a file edit box, in which you can type the name of a directory to copy to, and which will produce a query if you type the name of an existing file.kIf asking for the name of a directory to remove, you might use 4, to allow an existing directory name only.
`Query existing' is ignored if `disallow existing' is set. These two, as well as `allow null string input', only work with file edit boxes, not `matching file' selectors.
str$ is the string variable to edit. Its initial contents always control the initial drive and directory used. For a file edit box, any filename part of str$ is shown.
For a `matching file' selector, you can use wildcards in the filename part (such as *.tmp) to control which filenames are matched. To do this, you must add 128 to f%.w128 also allows wildcard specifications to be entered (returned in str$), for both `matching' and `new file' selectors.
If str$ does not contain any drive or directory information, the path as set by SETPATH is used. If SETPATH has not been used, the \OPD directory on the default drive (usually M:, `Internal') is used.
With a matching file selector (as opposed to an edit box) the value 8 restricts the selection to files which match the filename/extension in str$.
Matching file selectors can also use 64, in which case files with the same extension as that in str$ are shown without this extension. (Many Series 3a file selectors are like this.)MYou can always press Tab to produce the full file selector with a dFILE item.Pstr$ must be declared to be at least 128 bytes long, or an error will be raised.
.dFLOAT
dFLOAT var fp,p$,min,maxCDefines an edit box for a floating-point number, to go in a dialog.2p$ will be displayed on the left side of the line.vmin and max give the minimum and maximum values which are to be allowed. An error is raised if min is higher than max.
fp must be a LOCAL or a GLOBAL variable. It specifies the value to be shown initially. When you finish using the dialog, the value you entered is returned in fp.Y
.DIALOG n%=DIALOG
Presents the dialog prepared by dINIT and commands such as dTEXT and dCHOICE. If you complete the dialog by pressing Enter, your settings are stored in the variables specified in dTEXT, dCHOICE etc., although you can prevent this with dBUTTONS.
If you used dBUTTONS when preparing the dialog, the keycode which ended the dialog is returned. Otherwise, DIALOG returns the line no. of the item which was current when Enter was pressed. The top item (or the title line, if present), is line 1.[If you cancel the dialog by pressing Esc, the variables are not changed, and 0 is returned.}
.DIAMINIT
DIAMINIT pos%,str1$,str2$...
Initialises the Diamond list (discarding any existing list). str1$, str2$ etc. contain the text to be displayed in the status window for each item in the list.
pos% is the initial item on to which the Diamond indicator should be positioned, with pos%=1 specifying the first item. (Any value greater than the number of strings specifies the final item.) If pos%>=1 you must supply at least this many strings.mIf pos% is not supplied or if pos%=0, or if DIAMINIT is used on its own with no arguments, no bar is defined.OIf pos%=-1 the list is replaced by the icon instead in the large status window.
.DIAMPOS
DIAMPOS pos%4Positions the Diamond indicator on the Diamond list.~Positioning outside the range of the items wraps around in the appropriate way. pos%=0 causes the Diamond symbol to disappear.6
.dINIT
dINIT title$
dINIT
Prepares for definition of a dialog, cancelling any existing one. Use dTEXT, dCHOICE etc. to define each item in the dialog, then DIALOG to display the dialog.xIf title$ is supplied it will be displayed at the top of the dialog, centred and with a line across the dialog below it.
.DIR$#d$=DIR$(filespec$) then
d$=DIR$("")
Lists filenames, including subdirectory names, matching a file specification. You can include wildcards in the file specification. If filespec$ is just a directory name, include the final backslash on the end - for example, "M:\TEMP\".
Use the function like this:Y
DIR$(filespec$) returns the name of the first file matching the file specification.I
DIR$("") then returns the name of the second file in the directory.2
DIR$("") again returns the third, and so on.]
When there are no more matching files in the directory, DIR$("") returns a null string..Example, listing all the .DBF files in M:\DAT: PROC dir:
LOCAL d$(128)
d$=DIR$("M:\DAT\*.DBF")
WHILE d$<>""
PRINT d$
d$=DIR$("")
ENDWH
.dLONG
dLONG var lg&,p$,min&,max&:Defines an edit box for a long integer, to go in a dialog.2p$ will be displayed on the left side of the line.zmin& and max& give the minimum and maximum values which are to be allowed. An error is raised if min& is higher than max&.
lg& must be a LOCAL or a GLOBAL variable. It specifies the value to be shown initially. When you finish using the dialog, the value you entered is returned in lg&.s
.DO...UNTIL!DO
...statements
UNTIL conditiontDO forces the set of statements which follow it to execute repeatedly until the condition specified by UNTIL is met.IThis is the easiest way to repeat an operation a certain number of times.<
Every DO must have its matching UNTIL to end the loop.
If you set a condition which is never met, the program will go round and round, locked in the loop forever. You can escape by pressing Psion-Esc, provided you haven't set ESCAPE OFF.
If you have set ESCAPE OFF, you will have to return to the System screen, move to the program name under the RunOpl icon, and press Delete.
d%=DOW(day%,month%,year%)MReturns the day of the week - from 1 (Monday) to 7 (Sunday) - given the date.Oday% must be between 1 and 31, month% from 1 to 12 and year% from 1900 to 2155.:For example, D%=DOW(4,7,1992) returns 6, meaning Saturday.
.dPOSITION
dPOSITION x%,y%GPositions a dialog. Use dPOSITION at any time between dINIT and DIALOG.
dPOSITION uses two integer values. The first is the horizontal position, and the second, the vertical. dPOSITION -1,-1 positions to the top left; dPOSITION 1,1 to the bottom right; dPOSITION 0,0 to the centre, the usual position for dialogs.zdPOSITION 1,0, for example, positions to the right-hand edge of the screen, and centres the dialog half way up the screen.@
.DRAWSPRITE
DRAWSPRITE x%,y%UDraws the current sprite in the current window with top-left at pixel position x%,y%.mIf any bitmap-set contains bitmaps with different sizes, DRAWSPRITE raises an `Invalid arguments' error (-2).^Once the sprite has been drawn, no further file access is performed, even when it is animated.
.dTEXT#dTEXT p$,body$,t%
dTEXT p$,body$3Defines a line of text to be displayed in a dialog.
p$ will be displayed on the left side of the line, and body$ on the right side. If you only want to display a single string, use a null string ("") for p$, and pass the desired string in body$. It will then have the width of the dialog to itself.-An error is raised if body$ is a null string.xbody$ is normally displayed left aligned (although usually in the right column). You can override this by specifying t%: t% effect
0 left align body$
1 right align body$
2 centre body$[In addition, you can add any or all of the following three values to t%, for these effects: t% effect
$100 use bold text for body$ $200 draw a line below this item%$400 (allow this item to be selected)
Only one line can be drawn across a dialog. It will be below the last item which asks for it, whether the title from dINIT or a dTEXT item.
See also dEDIT.'
.dTIME
dTIME var lg&,p$,t%,min&,max&2Defines an edit box for a time, to go in a dialog.2p$ will be displayed on the left side of the line.
lg&, which must be a LOCAL or a GLOBAL variable, specifies the time to be shown initially. Although it will appear on the screen like a normal time, for example 18:27, lg& must be specified as seconds after 00:00. PA value of 60 means one minute past midnight; 3600 means one o'clock, and so on.
min& and max& give the minimum and maximum values which are to be allowed. Again, these are in seconds after 00:00. An error is raised if min& is higher than max&.bWhen you finish using the dialog, the time you entered is returned in lg&, in seconds after 00:00.6t% specifies the type of display required, as follows:
t% time display
0 absolute time no seconds
1 absolute time with seconds
2 duration no seconds
3 duration with seconds^For example, 03:45 represents an absolute time while 3 hours 45 minutes represents a duration.`Absolute times are displayed in 24-hour or am/pm format according to the current system setting.
.dXINPUT
dXINPUT var str$,p$LDefines a secret string edit box, such as for a password, to go in a dialog.2p$ will be displayed on the left side of the line.pstr$ is the string variable to take the string you type. Important: str$ must be at least eight characters long.
Initially the dialog does not show any characters for the string; the initial contents of str$ are ignored. A special symbol will be displayed for each character you type, to preserve the secrecy of the string.~
.EDIT
EDIT a$
Displays a string variable which you can edit directly on the screen. All the usual editing keys are available - the arrow keys move along the line, Esc clears the line, and so on.
When you have finished editing, press Enter to confirm the changes. If you press Enter before you have made any changes, then the string will be unaltered.
If you use EDIT in conjunction with a PRINT statement, use a comma at the end of the PRINT statement, so that the string to be edited appears on the same line as the displayed string - eg:
PRINT "Edit address:",
EDIT A.address$
UPDATE
TRAP EDIT
If the Esc key is pressed while no text is on the input line, the `Escape key pressed' error (number -114) will be returned by ERR - provided that the EDIT has been trapped.bYou can use this feature to enable someone to press the Esc key to escape from inputting a string.
See also INPUT, dEDIT.@
'.ELSE/.ELSEIF/.ENDIF/.ENDA/.ENDV/.ENDWH
See IF/APP/VECTOR/WHILE
.ENTERSEND#ret%=ENTERSEND(pobj%,m%,var p1,...)
This is the same as SEND except that, if the method leaves, the error code is returned to the caller. Otherwise the value returned is as returned by the method.
.ENTERSEND0$ret%=ENTERSEND0(pobj%,m%,var p1,...)ZThis is the same as ENTERSEND except that, if the method does not leave, zero is returned.
e%=EOF2Finds out whether you're at the end of a file yet.UReturns -1 (true) if the end of the file has been reached, or 0 (false) if it hasn't.
When reading records from a file, you should test whether there are still records left to read, otherwise you may get an error.
Example:
PROC eoftest:
OPEN "myfile",A,a$,b%
PRINT A.a$
PRINT A.b%
NEXT
PAUSE -40
UNTIL EOF
PRINT "The last record"
RETURN
.ERASE
ERASE.Erases the current record in the current file.
The next record is then current. If the erased record was the last record in a file, then following this command the current record will be null and EOF will return true.
e%=ERRUReturns the number of the last error which occurred, or 0 if there has been no error.
Example:
PRINT "Enter age in years"
age::
TRAP INPUT age% IF ERR=-1
PRINT "Number please:" GOTO age
ENDIF
See also ERR$.
.ERR$
e$=ERR$(x%):Returns the error message for the specified error code x%.GERR$(ERR) gives the message for the last error which occurred. Example:
TRAP OPEN "B:\FILE",A,field1$
IF ERR
PRINT ERR$(ERR)
RETURN
ENDIF
See also ERR.
.ESCAPE OFF
ESCAPE OFF...ESCAPE ON{ESCAPE OFF stops Psion-Esc being used to break out of the program when it is running. ESCAPE ON enables this feature again.
ESCAPE OFF takes effect only in the procedure in which it occurs, and in any sub-procedures that are called. Psion-Esc is always enabled when a program begins running.
If your program enters a loop which has no logical exit, and ESCAPE OFF has been used, you will have to return to the System screen, move to the program name under the RunOpl icon, and press the Delete key.
.EVAL
d=EVAL(s$)
Evaluates the mathematical string expression s$ and returns the floating-point result. s$ may include any mathematical function or operator (eg. sin(x)/(2**3)). Note that floating-point arithmetic is always performed.
For example:
AT 10,5 :PRINT "Calc:",
TRAP INPUT n$
IF n$="" :CONTINUE :ENDIF
IF ERR=-114 :BREAK :ENDIF
CLS :AT 10,4
PRINT n$;"=";EVAL(n$)
UNTIL 0pYou cannot use variables in the expression you pass to EVAL. A workaround is to use Calculator memories instead.
See also VAL.
.EXIST
e%=EXIST(filename$)!Checks to see that a file exists.EReturns -1 (`True') if the file exists and 0 (`False') if it doesn't.
Use this function when creating a file to check that a file of the same name does not already exist, or when opening a file to check that it has already been created:
IF NOT EXIST("CLIENTS")
CREATE "CLIENTS",A,names$
OPEN "CLIENTS",A,names$
ENDIFd
e=EXP(x)UReturns the value of the arithmetic constant e (2.71828...) raised to the power of x.8
.EXT EXT name$ZGives the file extension for the System screen to use when listing files used by this OPA.+This can only be used between APP and ENDA.
If you do not specify this, .ODB is used. Note that the files used by an OPA do not have to be data files, as the I/O commands give access to files of all kinds.
.FIND
f%=FIND(a$)
Searches the current data file for fields matching a$. The search starts from the current record, so use NEXT to progress to subsequent records. FIND makes the next record containing a$ the current record and returns the number of the record found. &Capitals and lower-case letters match.
You can use wildcards:
? matches any single character#* matches any group of characters.LTo find a record with a field containing Dr and either BROWN or BRAUN, use:
F%=FIND("*DR*BR??N*")^FIND("BROWN") will find only those records with a field consisting solely of the string BROWN."You can only search string fields.
See also FINDFIELD.
.FINDFIELD"f%=FINDFIELD(a$,start%,no%,flags%)
FINDFIELD, like FIND, finds a string, makes the record with this string the current record, and returns the number of this record.
a$ is the string to look for, as for FIND. start% is the number of the field to start looking in (1 for the first field), and no% is the number of fields to search in (starting from the field specified by the start%).{If you want to search in all fields, use start%=1 and for no% use the number of fields you used in the OPEN/CREATE command. flags% adds together two values:
0 for a case independent match, where capitals and lower-case letters match, or 1 for a case dependent match. This value should be multiplied by 16.
0 to search backwards from the current record, 1 to search forwards from the current record, 2 to search backwards from the end of the file, or 3 to search forwards from the start of the file.
Important: use
POKEB(PEEKW($1c)+7),0Ibefore using FINDFIELD. This is a bugfix to make FINDFIELD work reliably.Y
.FINDLIB
ret%=FINDLIB(var cat%, name$)~Find DYL category name$ (including .DYL extension) in the ROM. On success returns zero and writes the category handle to cat%.
To get the handle of a RAM-based DYL, use LOADLIB which guarantees that the DYL remains loaded in RAM. FINDLIB will get the handle of a RAM-based DYL but does not keep it in RAM.E
.FIRST
FIRST7Positions to the first record in the current data file.^
.FIX$
f$=FIX$(x,y%,z%)sReturns a string representation of the number x, to y% decimal places. The string will be up to z% characters long.,Example: FIX$(123.456,2,7) returns "123.46".
If z% is negative then the string is right-justified - for example FIX$(1,2,-6) returns " 1.00" where there are two spaces to the left of the 1.Z
If z% is positive then no spaces are added - for example FIX$(1,2,6) returns "1.00".
If the number x will not fit in the width specified by z%, then the string will just be asterisks - for example FIX$(256.99,2,4) returns "****".
See also GEN$, NUM$, SCI$.
.FLT f=FLT(x&)fConverts an integer expression (either integer or long integer) into a floating-point number. Example:
PROC gamma:(v)
LOCAL c
c=3E8
RETURN 1/SQR(1-(v*v)/(c*c))
You could call this procedure like this: gamma:(FLT(a%)) if you wanted to pass it the value of an integer variable without having first to assign the integer value to a floating-point variable.
See also INT and INTF.
.FONT
FONT id%,style%7Sets the text window font and style (as used by PRINT).MYou can use any of the fonts described under gFONT; initially font 4 is used.<See also the entry entitled "The text and graphics windows".i
.FREEALLOC
FREEALLOC pcell%LFrees a previously allocated cell at pcell%. Does nothing if pcell% is zero.
.gAT gAT x%,y%mSets the current position using absolute co-ordinates. gAT 0,0 moves to the top left of the current drawable.
See also gMOVE.^
.gBORDER/gBORDER flags%,width%,height%
gBORDER flags%
Draws a one-pixel wide border around the edge of the current drawable. If width% and height% are supplied, a border shape of this size is drawn with the top left corner at the current position.WIf they are not supplied, the border is drawn around the whole of the current drawable.
flags% controls three attributes of the border - a shadow to the right and beneath, a one-pixel gap all around, and the type of corners used:
flags% effect
1 single pixel shadow
2 gap for single pixel shadow
3 double pixel shadow
4 gap for double pixel shadow
$100 one-pixel gap all round
$200 more rounded corners
You can combine the values to control the three different effects. (1, 2, 3 and 4 are mutually exclusive; you cannot use more than one of them.) For example, for rounded corners and a gap for a double pixel shadow, use flags%=$204.8Set flags%=0 for no shadow, no gap, and sharper corners.dFor example, to de-emphasise a previously emphasised border, use gBORDER with the shadow turned off:
gBORDER 3 REM show border
gBORDER 4 REM border off
See also gXBORDER.
.gBOX
gBOX width%,height%pDraws a box from the current position, width% to the right and height% down. The current position is unaffected.'
.gBUTTON
gBUTTON text$,type%,w%,h%,st%
Draws a 3-D black and grey button (a key, not an application button) at the current position in a rectangle of the supplied width w% and height h%, which fully encloses the button in all its states.
text$ specifies up to 64 characters to be drawn in the button in the current font and style. You must ensure that the text will fit in the button.Ktype%=0 it draws a Series 3 style button; type%=1 draws a Series 3a button.0The meaning of state% varies according to type%:[
For type%=0, state%=0 for a raised button and state%=1 for a depressed (flat) button.
For type%=1, state%=0 for a raised button, state%=1 for a semi-depressed (flat) button and state%=2 for a fully-depressed (sunken) button. An error is raised if the current window has no grey plane.
.gCLOCK
gCLOCK ON/OFF
gCLOCK ON,mode%
gCLOCK ON,mode%,offset%
gCLOCK ON,mode%,offset%,format$
gCLOCK ON,mode%,offset%,format$,font%
gCLOCK ON,mode%,offset%,format$,font%,style%
Displays or removes a clock showing the system time. The current position in the current window is used. Only one clock may be displayed in each window.
mode% controls the type of clock. Modes 1 to 5 are for Series 3 compatibility, and produce Series 3 clocks: small (digital), medium (system setting), medium (analog), medium (digital), and large (analog) respectively. Other values are:(6 black and grey medium, system setting 7 black and grey medium, analog
8 second type medium, digital
9 black and grey extra large&10 formatted digital (described below)'You can OR the value with any of these:B $10 shows the date (except for extra large and formatted clocks)g $20 shows seconds in small digital, large analog, black and grey medium analog and extra large clocks@ $40 shows am/pm in small digital and black medium clocks only.
$80 specifies that a clock is to be drawn in the grey plane (only for clocks that do not contain both black and grey: ie. all except the black and grey, medium, analog clock and the extra large clock).Xformat$, font% and style% are used only for formatted digital clocks as described below.oNote: Do not use gSCROLL on a region containing a clock. The whole window may, however, be moved using gSETWIN.QNote: clocks that include grey are drawn even in windows that have no grey plane.
Digital clocks display in 24-hour or 12-hour mode according to the system-wide setting in Time. The `am/pm' flag ($40) can be used with digital clocks in 12-hour mode, and with medium analog clocks.
offset% specifies an offset in minutes from the system time to the time displayed. This allows you to display a clock showing a time other than the system time.)By default, mode% is 1, and offset% is 0.
For the formatted digital clock (mode%=10), you can specify font% and style%, as for gFONT and gSTYLE. The defaults are the system font (value $9a) and normal style (0).
For the formatted digital clock, a format string (up to 255 chars long) specifies how the clock is to be displayed. The format string contains a number of format specifiers in the form of a % followed by a letter. (Upper or lower case may be used.)
To make each item as abbreviated as possible, you can use a * after the %. For example, "%*T" at 11:05 pm abbreviates `05' to `5'.8Other abbreviations are marked, appropriately, by "Abb":
%% =a % characterA %:, %/ =time and date separators, as set in the Time application( %A =`am' or `pm' text (Abb: 1st letter)F %D,%W,%M =day/week/month number as two digits, 01-31, 01-53 and 01-12J %E,%N =day/month name (Abb: shorter form, eg 1st 3 characters in English): %H,%I =hour in 24-hour or 12-hour format, 00-23 and 01-12
%S,%T =seconds/minutes, 00-59> %X =suffix string for day number, eg st in `1st', nd in `2nd'< %Y =year as a four digit number (Abb: discards the century)
%1,%2,%3 =day,month,year as ordered in the Time application. Eg Europe is Day/month/year, so %1=%D, %2=%M, %3=%Y. So to display a date in correct format use "%1/%2/%3". (Abb: see %G/%P/%U.)5 %4,%5 =day,month as ordered in the Time application.
%F,%O =toggles days/months (displayed by %1, %2 and %3) between numeric and name formats. On 9th March 1993, with European date type, "%1%F%1%F%1" gives "09Tuesday09"
%G,%P, %U =toggles %1, %2 and %3 between long form and abbreviation. On 9th March 1993, with European date type, "%F%1%G%1%G%1" gives "TuesdayTueTuesday"
%L =toggles the suffix on the day number for %1/%2/%3 (in numeric form only). On 9th March 1993, with European date type, "%G%1%L%1%L%1" gives "99th9"
%6,%7 =hour and am/pm text according to the format selected in the Time application. With am-pm format, %6=%I and %7=%A. With 24-hour format, %6=%H and %7 gives no `am/pm' characters.ISo e.g. "%4%/%5" gives a clock with just day and month in selected order.jFor specifiers that toggle, note that the toggle state is restored to the default setting for a new clock.
.gCLOSE
gCLOSE id%\Closes the specified drawable that was previously opened by gCREATE, gCREATEBIT or gLOADBIT.[If the drawable closed was the current drawable, the default window (ID=1) becomes current.:An error is raised if you try to close the default window.o
.gCLS
gCLScClears the whole of the current drawable and sets the current position to 0,0, its top left corner./
.gCOPY
gCOPY id%,x%,y%,w%,h%,mode%
Copies a rectangle of the specified size (width w%, height h%) from the point x%,y% in drawable id%, to the current position in the current drawable.
As this command can copy both set and clear pixels, the same modes are available as when displaying text. Set mode% = 0 for set, 1 for clear, 2 for invert or 3 for replace.k0, 1 and 2 act only on set pixels in the pattern; 3 copies the entire rectangle, with set and clear pixels.6The current position is not affected in either window.MgCOPY is affected by the setting of gGREY (in the current window) as follows:&with gGREY 0 it copies black to black;Nwith gGREY 1 it copies grey to grey, or black to grey if source is black only;awith gGREY 2 it copies grey to grey and black to black, or black to both if source is black only.
.gCREATE@id%=gCREATE(x%,y%,w%,h%,v%)
id%=gCREATE(x%,y%,w%,h%,v%,grey%)
Creates a window with specified position and size (width w%, height h%), and makes it both current and foreground. Sets the current position to 0,0, its top left corner. If v% is 1, the window will immediately be visible; if 0, it will be invisible.fIf grey% is not given or is 0, the window will not have a grey plane. If grey% is 1, it will have one.EReturns id% (2 to 8) which identifies this window for other keywords.#See also gCLOSE, gGREY, DEFAULTWIN.
.gCREATEBIT
id%=gCREATEBIT(w%,h%)
Creates a bitmap with the specified width and height, and makes it the current drawable. Sets the current position to 0,0, its top left corner.EReturns id% (2 to 8) which identifies this bitmap for other keywords.
See also gCLOSE.
.gDRAWOBJECT
gDRAWOBJECT type%,flags%,w%,h%
Draws the scaleable graphics object specified by type%, scaled to fit in the rectangle with top left at the current graphics cursor position and with the specified width w% and height h%.
The Series 3a has only one object type (set type%=0) - a `lozenge'. This is a 3-D rounded box lit from the top left, with a shadow at bottom right and a grey body. (For an example, see the text 'City' in the top left of the World application.)3For type%=0, flags% specifies the corner roundness:
0 for normal roundness
1 for more rounded.2 for a single pixel removed from each corner.;An error is raised if the current window has no grey plane.U
.GEN$
g$=gen$(x,y%)]Returns a string representation of the number x. The string will be up to y% characters long.GExample GEN$(123.456,7) returns "123.456" and GEN$(243,5) returns "243"
If y% is negative then the string is right-justified. For example GEN$(1,-6) returns " 1" where there are five spaces to the left of the 1.U
If y% is positive then no spaces are added - for example GEN$(1,6) returns "1".
If the number x will not fit in the width specified by y%, then the string will just be asterisks. For example GEN$(256.99,4) returns "****".
See also FIX$, NUM$, SCI$.
g%=GETJWaits for a key to be pressed and returns the character code for that key.
For example, if the `A' key is pressed with Caps Lock off, the integer returned is 97 (a), or 65 (A) if `A' was pressed with the Shift key down.`You can use KMOD to check whether modifier keys (Shift, Control, Psion and Caps Lock) were used.:See also the entry entitled "Character set and key codes".
See also KEY.+
.GET$
g$=GET$QWaits until a key is pressed and then returns which key was pressed, as a string.VFor example, if the `A' key is pressed in lower case mode, the string returned is "a".dYou can use KMOD to check whether any modifier keys (Shift, Control, Psion and Caps Lock) were used.
See also KEY$.3
.GETCMD$
w$=GETCMD$
Returns new command-line arguments to an OPA, after a "change files" or "quit" event has occurred. The first character of the returned string is "C", "O" or "X". If it is "C" or "O", the rest of the string is a filename..The first character has the following meaning:E"C" - close down the current file, and create the specified new file.H"O" - close down the current file, and open the specified existing file.<"X" - close down the current file (if any) and quit the OPA.7You can only call GETCMD$ once for each system message.
See also CMD$.
.GETEVENT
GETEVENT var a%()
Waits for an event to occur. Returns with a%() specifying the event. The data returned in a%() depends on the type of event that occurred.
If the event is a key-press, (a%(1) AND $400) is guaranteed to be zero. For other events (a%(1) AND $400) is guaranteed to be non-zero.
If a key has been pressed:
a%(1)= keycode (as for GET)) a%(2) AND $00ff= modifier (as for KMOD)/ a%(2)/256= auto-repeat count (ignored by GET)%If a program has moved to foreground:
a%(1)= $401%If a program has moved to background:
a%(1)= $402
If the machine has switched on:
a%(1)= $4036If the Series 3a wants an OPA to change files or exit:
a%(1)= $404
If the date changes:
a%(1)= $405
Note: events are ignored while you are using keywords which wait for keypresses - GET, GET$, EDIT, INPUT, MENU and DIALOG. If you need to use these keywords in OPAs, use LOCK ON / LOCK OFF around them.WIf you do use GETEVENT you should allow for other events to be specified in the future.UFor a key-press event, the modifier is returned in a%(2) and is not returned by KMOD.
Note: If a non-key event such as `foreground' occurs while a keyboard keyword such as GET, INPUT, MENU or DIALOG is being used, the event is discarded. So GETEVENT must be used if non-key events are to be monitored.Y(OPAs can still handle the $404 event correctly - see the LOCK command for more details.)CThe array (or string of integers) must be at least 6 integers long.
See also TESTEVENT, GETCMD$.v
.GETLIBH
cat%=GETLIBH(num%)YConvert a category number num% to a handle. If num% is zero, gets the handle for OPL.DYL.
.gFILL
gFILL width%,height%,gMode%lFills a rectangle of the specified size from the current position, according to the graphics mode specified.#The current position is unaffected.3
.gFONT gFONT Id%ySets the font for current drawable to Id%. The font may be one of the predefined fonts in the ROM or a user-defined font.
Id% Description Pixel size
1 Series 3 normal 8
2 Series 3 bold 8
3 Series 3 digits 6x6
4 Mono 8x8
5 Roman 8
6 Roman 11
7 Roman 13
8 Roman 16
9 Swiss 8
10 Swiss 11
11 Swiss 13
12 Swiss 16
13 Mono 6x6
The special font number $9a is set aside to give a machine's default graphics font; this is the font used initially for graphics text.
The actual font may vary from machine to machine - eg it is font 1 on the Series 3 and font 11 on the Series 3a. So gFONT 11 or gFONT $9a both set the Series 3a standard font, which gPRINT normally uses.aUser-defined fonts must first be loaded by gLOADFONT, which returns the fontId% needed for gFONT.
See also gLOADFONT, FONT.
.gGMODE
gGMODE mode%bSets the effect of all subsequent drawing commands - gLINEBY, gBOX etc. - on the current drawable.
mode% Pixels will be:
0 set 1 cleared
2 invertednWhen you first use drawing commands on a drawable, they set pixels in the drawable. Use gGMODE to change this.
For example, if you have drawn a black background, you can draw a white box outline inside it with either gGMODE 1 or gGMODE 2, followed by gBOX.
.gGREY
gGREY mode%
Controls whether all subsequent graphics drawing and graphics text in the current window draw to the grey plane, the black plane or to both. (Ordinary text as printed by PRINT is not affected by grey.)&mode%=0 for black plane only (default)
mode%=1 for grey plane only
mode%=2 for both planes|It is helpful to think of the black plane being in front of the grey plane, so a pixel set in both planes will appear black.
To enable the use of grey in the default window (ID=1) use DEFAULTWIN 1 at the start of your program. If grey is required in other windows you must create the windows with a grey plane using gCREATE.<gGREY cannot be used with bitmaps which have only one plane. See also DEFAULTWIN and gCREATE.G
.gHEIGHT
height% = gHEIGHT+Returns the height of the current drawable.^
.gIDENTITY
id%=gIDENTITY'Returns the ID of the current drawable.
The default window has ID=1.
.gINFO
gINFO var i%()
Gets general information about the current drawable and about the graphics cursor (whichever window it is in). The information is returned in the array i%() which must be at least 32 integers long.
The information is about the drawable in its current state, so eg the font information is for the current font in the current style.&The following information is returned:
i%(1) lowest character code
i%(2) highest character code
i%(3) height of font
i%(4) descent of font
i%(5) ascent of font
i%(6) width of '0' character
i%(7) maximum character width!i%(8) flags for font (see below)
i%(9-17) name of font%i%(18) current graphics mode (gGMODE)!i%(19) current text mode (gTMODE)
i%(20) current style (gSTYLE) i%(21) cursor state (ON=1,OFF=0):i%(22) ID of window containing cursor (-1 for text cursor)
i%(23) cursor width
i%(24) cursor height
i%(25) cursor ascent"i%(26) cursor x position in window"i%(27) cursor y position in window i%(28) 1 if drawable is a bitmap
i%(29) cursor effects
i%(30) gGREY setting.i%(31) reserved (Window Server ID of drawable)
i%(32) reservedDi%(8) specifies a combination of the following font characteristics:
Value: Meaning:/1 font uses standard ASCII characters (32-126)/2 font uses Code Page 850 characters (128-255)
4 font is bold
8 font is italic
16 font is serifed
32 font is monospaced/$8000 font is stored expanded for quick drawing@Use PEEK$(ADDR(i%(9))) to read the name of the font as a string.QIf the cursor is on (i%(21)=1), it is visible in the window identified by i%(22).
i%(29) has bit 0 set (i%(29) AND 1) if the cursor is obloid, bit 1 set (i%(29) AND 2) if not flashing, and bit 2 set (i%(29) AND 4) if grey.pIf the cursor is off (i%(21)=0), or is a text cursor (i%(22)=-1), i%(23) to i%(27) and i%(29) should be ignored.
.gINVERT
gINVERT width%,height%wInverts the rectangle width% to the right and height% down from the cursor position, except for the four corner pixels.I
.GIPRINT
GIPRINT str$,c%
GIPRINT str$hGIPRINT displays an information message for about two seconds, in the bottom right corner of the screen.
For example, GIPRINT "Not Found" displays Not Found. The string you specify can be up to 64 characters. If a string is too long for the screen, it will be clipped.DIf c% is given, it controls the corner in which the message appears: c% corner
0 top left
1 bottom left
2 top right
3 bottom right (default)
Only one message can be shown at a time. You can make the message go away - for example, if a key has been pressed - with GIPRINT "".$
.gLINEBY
gLINEBY dx%,dy%
Draws a line from the current position to a point dx% to the right and dy% down. Negative dx% and dy% mean left and up respectively. The current position moves to the end of the line drawn.3gLINEBY 0,0 sets the pixel at the current position.
See also gLINETO, gPOLY.
.gLINETO
gLINETO x%,y%_Draws a line from the current position to the point x%,y%. The current position moves to x%,y%.MTo plot a single point, use gLINETO to the current position (or gLINEBY 0,0).
See also gLINEBY, gPOLY.x
.gLOADBITLid%=gLOADBIT(name$,write%,i%)
id%=gLOADBIT(name$,write%)
id%=gLOADBIT(name$)
Loads a bitmap from the named bitmap file and makes it the current drawable. Sets the current position to 0,0, its top left corner. If name$ has no file extension .PIC is used. The bitmap is kept as a local copy in memory.EReturns id% (2 to 8) which identifies this bitmap for other keywords.
write%=0 sets read-only access. Attempts to write to the bitmap in memory will be ignored, but the bitmap can be used by other programs without using more memory. write%=1 allows you to write to and re-save the bitmap. This is the default case.
For bitmap files which contain more than one bitmap, i% specifies which one to load. For the first bitmap, use i%=0. This is also the default value. Bitmap files saved with gSAVEBIT have only one bitmap, and this argument is not needed for them.
See also gCLOSE.
.gLOADFONT
fontId%=gLOADFONT(name$)
Loads the user-defined font name$. It returns a font ID; use this with gFONT to make the current drawable use this font. If name$ does not contain a file extension, .FON is used.igFONT itself is very efficient, so you should normally load all required fonts at the start of a program.eNote that the built-in Series 3/Series 3a fonts are automatically available, and do not need loading.
See also gUNLOADFONT.
.GLOBAL
GLOBAL variables
Declares variables to be used in the current procedure (as does the LOCAL command) and (unlike LOCAL) in any procedures called by the current procedure, or procedures called by them.GThe variables may be of 4 types, depending on the symbol they end with:c
Variable names not ending with $ % & or () are floating-point variables, for example price, xK
Those ending with a % are integer variables, for example x%, sales92%S
Those ending with an & are long integer variables, for example x&, sales92&.
Those ending with a $ are string variables. String variable names must be followed by the maximum length of the string in brackets - for example names$(12), a$(3)
Array variables have a number immediately following them in brackets which specifies the number of elements in the array. Array variables may be of any type, for example: x(6),y%(5),f$(5,12),z&(3)
When declaring string arrays, you must give two numbers in the brackets. The first declares the number of elements, the second declares their maximum length. For example surname$(5,8) declares five elements, each up to 8 characters long.
Variable names may be any combination of up to 8 numbers and alphabetic letters. They must start with a letter. The length includes the % & or $ sign, but not the () in string and array variables.~More than one GLOBAL or LOCAL statement may be used, but they must be on separate lines, immediately after the procedure name.
See also LOCAL.
.gMOVE
gMOVE dx%,dy%WMoves the current position dx% to the right and dy% downwards, in the current drawable.RA negative dx% causes movement to the left; a negative dy% causes upward movement.
See also gAT.
.gORDER
gORDER id%,position%hSets the window specified by id% to the selected foreground/background position, and redraws the screen.
Position 1 is the foreground window, position 2 is next, and so on. Any position greater than the number of windows is interpreted as the end of the list.3On creation, a window is at position 1 in the list.#Raises an error if id% is a bitmap.
See also gRANK.
.gORIGINX
x%=gORIGINX\Returns the gap between the left side of the screen and the left side of the current window.4Raises an error if the current drawable is a bitmap.
.gORIGINY
y%=gORIGINYPReturns the gap between the top of the screen and the top of the current window.4Raises an error if the current drawable is a bitmap.d
.GOTO1GOTO label or GOTO label::
...statements
label::LGoes to the line following the label:: and continues from there. The label -&
Must be in the current procedure|
Must start with a letter and end with a double colon, although the double colon is not necessary in the GOTO statement:
May be up to 8 characters long excluding the colons.D
.gPATT
gPATT id%,width%,height%,mode%gFills a rectangle of the specified size from the current position with repetitions of the drawable id%.
As with gCOPY, this command can copy both set and clear pixels, so the same modes are available as when displaying text. Set mode% = 0 for set, 1 for clear, 2 for invert or 3 for replace.k0, 1 and 2 act only on set pixels in the pattern; 3 copies the entire rectangle, with set and clear pixels.5If you set id%=-1 a pre-defined grey pattern is used.#The current position is unaffected.[gPATT is affected by the setting of gGREY (in the current window) in the same way as gCOPY:&with gGREY 0 it copies black to black;Nwith gGREY 1 it copies grey to grey, or black to grey if source is black only;awith gGREY 2 it copies grey to grey and black to black, or black to both if source is black only.1
.gPEEKLINE
gPEEKLINE id%,x%,y%,d%(),ln%
Reads a horizontal line from the black plane of the drawable id%, length ln%, starting at x%,y%. The leftmost 16 pixels are read into d%(1), with the first pixel read into the least significant bit.
The array d%() must be long enough to hold the data. You can work out the number of integers required with ((ln%+15)/16) (using whole-number division).[If you set id% to 0, this just reads from the whole screen, not from any particular window.MIf you add $8000 to id%, the grey plane (not the black plane) will be peeked.
.gPOLY
gPOLY a%()?Draws a sequence of lines, as if by gLINEBY and gMOVE commands.
The array is set up as follows:
a%(1) starting x position
a%(2) starting y position a%(3) number of pairs of offsets
a%(4) dx1%
a%(5) dy1%
a%(6) dx2%
a%(7) dy2% etc.
Each pair of numbers - dx1%,dy1%, for example - specifies a line or a movement. To draw a line, dy% is the amount to move down, while dx% is the amount to move to the right multiplied by two.hTo specify a movement (ie without drawing a line) work out the dx%,dy% as for a line, then add 1 to dx%.8(For drawing/movement up or left, use negative numbers.)=gPOLY is quicker than combinations of gAT, gLINEBY and gMOVE.[Example, to draw three horizontal lines 50 pixels long at positions 20,10, 20,30 and 20,50:
a%(1)=20 :a%(2)=10 REM 20,10
a%(3)=5 REM 5 operations
REM draw right 50
a%(4)=50*2 :a%(5)=0
REM move down 20
a%(6)=0*2+1 :a%(7)=20
REM draw left 50
a%(8)=-50*2 :a%(9)=0
REM move down 20
a%(10)=0*2+1 :a%(11)=20
REM draw right 50
a%(12)=50*2 :a%(13)=0
gPOLY a%()
.gPRINT
gPRINT list of expressions~Displays a list of expressions at the current position in the current drawable. All variable types are formatted as for PRINT.
Unlike PRINT, gPRINT does not end by moving to a new line. A comma between expressions is still displayed as a space, but a semi-colon has no effect. gPRINT without a list of expressions does nothing.7See also gPRINTB, gPRINTCLIP, gTWIDTH, gXPRINT, gTMODE.H
.gPRINTBlgPRINTB t$,w%,al%,tp%,bt%,m%
gPRINTB t$,w%,al%,tp%,bt%
gPRINTB t$,w%,al%,tp%
gPRINTB t$,w%,al%
gPRINTB t$,w%
Displays text t$ in a cleared box of width w% pixels. The current position is used for the left side of the box and for the baseline of the text.nal% controls the alignment of the text in the box - 1 for right aligned, 2 for left aligned, or 3 for centred.
tp% and bt% are the clearances between the text and the top/bottom of the box. Together with the current font size, they control the height of the box. An error is raised if tp% plus the font ascent is greater than 255.
m% controls the margins.VFor left alignment, m% is an offset from the left of the box to the start of the text.VFor right alignment, m% is an offset from the right of the box to the end of the text.
For centering, m% is an offset from the left or right of the box to the region in which to centre, with positive m% meaning left and negative meaning right.GIf values are not supplied for some arguments, these defaults are used:
al% left
tp% 0
bt% 0
m% 0.See also gPRINT, gPRINTCLIP, gTWIDTH, gXPRINT.
.gPRINTCLIP
w%=gPRINTCLIP(text$,width%)
Displays text$ at the current position, displaying only as many characters as will fit inside width% pixels. Returns the number of characters displayed.3See also gPRINT, gPRINTB, gTWIDTH, gXPRINT, gTMODE.
.gRANK
rank%=gRANKOReturns the foreground/background position, from 1 to 8, of the current window.4Raises an error if the current drawable is a bitmap.
See also gORDER.~
.gSAVEBIT/gSAVEBIT name$,width%,height%
gSAVEBIT name$
Saves the current drawable as the named bitmap file. If width% and height% are given, then only the rectangle of that size from the current position is copied. If name$ has no file extension .PIC is used.vSaving a window to file when it includes grey will save both planes to the file - black bitmap first followed by grey.
.gSCROLL0gSCROLL dx%,dy%,x%,y%,wd%,ht%
gSCROLL dx%,dy%
Scrolls pixels in the current drawable by offset dx%,dy%. Positive dx% means to the right, and positive dy% means down. The drawable itself does not change its position.rIf you specify a rectangle in the current drawable, at x%,y% and of size wd%,ht%, only this rectangle is scrolled.RThe areas dx% wide and dy% deep which are "left behind" by the scroll are cleared.%The current position is not affected.
.gSETWIN-gSETWIN x%,y%,width%,height%
gSETWIN x%,y%AChanges position and, optionally, the size of the current window.7An error is raised if the current drawable is a bitmap.#The current position is unaffected.
If you use this command on the default window, you must also use the SCREEN command to ensure that the area for PRINT commands to use is wholly contained within the default window.
.gSTYLE
gSTYLE style%oSets the style of text displayed in subsequent gPRINT, gPRINTB and gPRINTCLIP commands on the current drawable.
style% Text style:
0 normal
1 bold
2 underlined 4 inverse
8 double height
16 mono 32 italic
You can combine these styles by adding their values - for example, to set bold, underlined and double height, use gSTYLE 11, as 11=1+2+8.?This command does not affect non-graphics commands, like PRINT.p
.gTMODE
gTMODE mode%kSets the way characters are displayed by subsequent gPRINT and gPRINTCLIP commands on the current drawable.
mode% Pixels will be:
0 set 1 cleared
2 inverted
3 replaced
When you first use "graphics text" commands on a drawable, each dot in a letter causes a pixel to be set in the drawable. This is mode%=0.
When mode% is 1 or 2, graphics text commands work in a similar way, but the pixels are cleared or inverted. When mode% is 3, entire character boxes are drawn on the screen - pixels are set in the letter and cleared in the background box.9This command does not affect other text display commands.
.gTWIDTH
width%=gTWIDTH(text$)9Returns the width of text$ in the current font and style..See also gPRINT, gPRINTB, gPRINTCLIP, gXPRINT.
.gUNLOADFONT
gUNLOADFONT fontId%xUnloads a user-defined font that was previously loaded using gLOADFONT. Raises an error if the font has not been loaded.TThe built-in Series 3/Series 3a fonts are not held in memory and cannot be unloaded.
See also gLOADFONT.-
.gUPDATE
gUPDATE ON
gUPDATE OFF
gUPDATE
The Series 3a screen is usually updated whenever you display anything on it. gUPDATE OFF switches off this feature. The screen will then be updated as few times as possible (though note that some keywords will always cause an update.)FYou can still force an update by using the gUPDATE command on its own.
This can result in a considerable speed improvement in some cases. You might, for example, use gUPDATE OFF, then a sequence of graphics commands, followed by gUPDATE.VYou should certainly use gUPDATE OFF if you are about to write exclusively to bitmaps.-gUPDATE ON returns to normal screen updating.
gUPDATE affects anything that displays on the screen. If you are using a lot of PRINT commands, gUPDATE OFF may make a noticeable difference in speed.zNote that with gUPDATE OFF, the location of errors which occur while the procedure is running may be incorrectly reported.
For this reason, gUPDATE OFF is best used in the final stages of program development, and even then you may have to remove it to locate some errors.
.gUSE
gUSE id%
Makes the drawable id% current. Graphics drawing commands will now go to this drawable. gUSE does not bring a drawable to the foreground (see gORDER).~
.gVISIBLE
gVISIBLE ON/OFF.Makes the current window visible or invisible.4Raises an error if the current drawable is a bitmap.A
.gWIDTH
width%=gWIDTH*Returns the width of the current drawable.U
x%=gXJReturns the x current position (in from the left) in the current drawable.
.gXBORDER4gXBORDER type%,flags%,w%,h%
gXBORDER type%,flags%
Draws a border in the current drawable of a specified type, fitting inside a rectangle of the specified size or with the size of the current drawable if no size is specified.Mtype%=0 for drawing the Series 3 type border; flags% are then as for gBORDER.
type%=1 for drawing the Series 3a 3-D grey and black border. A shadow or a gap for a shadow is always assumed. flags%=1,2,3,4 are as for gBORDER.
When the shadow is enabled (1 or 3) only the grey and black parts of the border are drawn; you should pre-clear the background for the white parts.
When the shadow is disabled (2 or 4) the outer and inner border lines are drawn, but the areas covered by grey/black when the shadow is enabled are now cleared. (This allows a shadow to be turned off simply by calling gXBORDER again.)9The following values of flags% apply to all border types:
0 for normal corners2OR with $100 leaves 1 pixel gap around the border.%OR with $200 for more rounded corners'OR with $400 for losing a single pixel.AIf both $400 and $200 are mistakenly supplied, $200 has priority.;An error is raised if the current window has no grey plane.
See also gBORDER.
.gXPRINT
gXPRINT string$,flags%
Displays string$ at the current position, with precise highlighting or underlining. The current font and style are still used, even if the style itself is inverse or underlined.RText mode 3 (replace) is used - both set and cleared pixels in the text are drawn. flags% has the following effect:
6 thin underlinedlWhere lines of text are separated by a single pixel, the thin options maintain the separation between lines.OgXPRINT does not support the display of a list of expressions of various types.V
y%=gYKReturns the y current position (down from the top) in the current drawable.
.HEX$
h$=HEX$(x&)cReturns a string containing the hexadecimal (base 16) representation of integer or long integer x&..For example HEX$(255) returns the string "FF".k
.HOUR
h%=HOUR\Returns the number of the current hour from the system clock as an integer between 0 and 23.
.IABS
i&=IABS(x&)^Returns the absolute value, ie without any sign, of the integer or long integer expression x&.
For example IABS(-10) is 10.ISee also ABS, which returns the absolute value as a floating-point value.
.ICON
ICON name$hGives the name of the bitmap file to incorporate into the OPA, for use as the icon in the System screen.
If no file extension is given, .PIC is used. If you do not use ICON, the OPA is shown on the System screen with a standard OPA icon.+This can only be used between APP and ENDA.nYou should add $1000 to the argument to TYPE if the bitmap file has a Series 3a's 48x48 pixel black/grey icon.
Any initial 24x24 icon in the file (for use on a Series 3) will then be ignored when the OPA is installed on a Series 3a, with two 48x48 icon patterns (black and grey respectively) being read from the OPA file instead.GIf you want to design your own icon using an OPL program, see gSAVEBIT.
.IF...ENDIFWIF condition1
...statements
ELSEIF condition2
...statements
...statements
ENDIF
Does either/
the statements following the IF condition
the statements following one of the ELSEIF conditions (there may be as many ELSEIF statements as you like - none at all if you want)
or~
the statements following ELSE (or, if there is no ELSE, nothing at all). There may be either one ELSE statement or none.HAfter the ENDIF statement, the lines following ENDIF carry on as normal.1IF, ELSEIF, ELSE and ENDIF must be in that order..Every IF must be matched with a closing ENDIF.FYou can also have an IF...ENDIF structure within another, for example:
IF condition1
IF condition2
ENDIF
ENDIF
"condition" is an expression returning a logical value, for example a<b. If the expression returns logical true (non-zero) then the statements following are executed. If the expression returns logical false (zero) then those statements are ignored.]
.INPUT!INPUT variable
INPUT log.fielduWaits for a value to be entered at the keyboard, and then assigns the value entered to a variable or data file field.
You can edit the value as you type it in. All the usual editing keys are available - the arrow keys move along the line, Esc clears the line and so on.
If inappropriate input is entered, for example a string when the input was to be assigned to an integer variable, a ? is displayed and you can try again.
However, if you used TRAP INPUT, control passes on to the next line of the procedure, with the appropriate error condition being set and the value of the variable remaining unchanged.<INPUT is usually used in conjunction with a PRINT statement:
PROC exch:
LOCAL pds,rate
PRINT "Pounds Sterling?",
INPUT pds
PRINT "Rate (DM)?",
INPUT rate
PRINT "=",pds*rate,"DM"
UNTIL 0
Note the commas at the end of the PRINT statements, used so that the cursor waiting for input appears on the same line as the messages.
TRAP INPUT
If a bad value is entered (for example "abc" for a%) in response to a TRAP INPUT, the ? is not displayed, but the ERR function can be called to return the value of the error which has occurred.
If the Esc key is pressed while no text is on the input line, the `Escape key pressed' error (number -114) will be returned by ERR (provided that the INPUT has been trapped).aYou can use this feature to enable someone to press the Esc key to escape from inputting a value.
See also EDIT. This works like INPUT, except that it displays a string to be edited and then assigned to a variable or field. It can only be used with strings.e
.INT i&=INT(x)
Returns the integer (in other words the whole number) part of the floating-point expression x. The number is returned as a long integer.
Positive numbers are rounded down, and negative numbers are rounded up - for example INT(-5.9) returns -5 and INT(2.9) returns 2.{If you want to round a number to the nearest integer, add 0.5 to it (or subtract 0.5 if it is negative) before you use INT.
In the Calculator, you need to use INT to pass a number to a procedure which requires a long integer parameter. This is because the Calculator passes all numbers as floating-point by default.
See also INTF.
.INTF i=INTF(x)
Used in the same way as the INT function, but the value returned is a floating-point number. For example, INTF(1234567890123.4) returns 1234567890123.0LYou may also need this when an integer calculation may exceed integer range.
See also INT.%
.IOA'r%=IOA(h%,f%,var status%,var a1,var a2)xThe device driver opened with handle h% performs the asynchronous I/O function f% with two further arguments, a1 and a2.
status% will usually be set to -46, which means that the function is still pending. When, at some later time, the function completes, status% is automatically changed.
(For this reason, status% should usually be global - if the program is still running, status% must be available when the request completes, or the program will probably crash.)
If status%>=0, the function completed without error. If <0, the function completed with error. The error number is specific to the device driver.>At the same time, a signal is sent to the running OPL program.
In most cases, you cannot perform another I/O read/write function to this device until you first read the signal of this function's completion.
If this is the only I/O device with a function pending, wait for the signal with IOWAITSTAT status%. (If you have other functions pending on other devices, you must use IOWAIT and IOSIGNAL.)
Alternatively, you can cancel the pending function with IOW(handle%,4). The program will still receive a signal, which should be read with IOWAITSTAT or IOWAIT.dIf an OPL program is ready to exit, it does not have to wait for any signals from pending IOA calls.^
.IOC'r%=IOC(h%,f%,var status%,var a1,var a2)
Make an I/O request with guaranteed completion. This has the same form as IOA etc but it returns zero always (ie the return value can be ignored).tIOC allows you to assume that the request started successfully - any error is always given in the status word stat%.
If there was an error, stat% contains the error code and the next IOWAIT will return immediately as if the error occurred after completion.
There is seldom a requirement to know whether an error occurred on starting a function, and IOC should therefore be used in preference to IOA nearly always.
.IOCANCEL
r%=IOCANCEL(h%)
Cancels any outstanding asynchronous I/O request (IOC or IOA) on the specified channel, causing them to complete with the completion status word containingJ-48 ("I/O cancelled"). The return value is always zero and may be ignored.
Device drivers that support truly asynchronous services provide a cancel service. The detailed effect of the cancel depends on the device driver. However, the following general principles apply:eThe cancel precipitates the completion of the request (it does not stop the request from completing).oThe cancel may or may not be effective (ie. the request may complete naturally before the cancel is processed).
After a cancel, you must still process the completion of the asynchronous request (typically by immediately calling IOWAITSTAT to "use up" the signal).
The IOCANCEL function is harmless if no request is outstanding (eg if the function completed just before cancellation requested).:
.IOCLOSE
r%=IOCLOSE(h%)!Closes a file with the handle h%.<
.IOOPEN
r%=IOOPEN(var h%,name$,mode%)WCreates or opens a file called name$. Defines handle h% for use by other I/O functions.
For unique file creation, use
IOOPEN(var h%,addr%,mode%)
mode% specifies how the file is to be opened. It is formed by ORing together values which fall into the three following categories:4"Open mode" - choose one and only one of the values;6"File format" - choose one and only one of the values;6"Access flags" - any combination af values is allowed.
OPEN MODE:h$0000 - Open an existing file (or device). The initial current position is set to the start of the file.5$0001 - Create a file (which must not already exist).V$0002 - Replace a file (truncate it to zero length) or create it if it does not exist.
$0003 - Open an existing file for appending. The initial current position is set to the end of the file. For text format files (see $0020 below) this is the only way to position to end of file.
$0004 - Creates a file with a unique name. For this case, you must use addr%, the address of a string at least 130 characters long, instead of name$.
This string specifies the path of the file to be created (any file name in the string is ignored). IOOPEN then set the string to the unique file name generated (including the full path).
FILE FORMAT:X$0000 - Binary. Up to 16K can be read from or written to the file in a single operation.
$0020 - Text. Lines are terminated by any combination of the CR and LF ($0D, $0A) characters. The maximum record length is 256 bytes and Ctrl-Z ($1A) marks the end of the file.
ACCESS FLAGS:
$0100 - Update flag - Allows the file to be written to as well as read. If not set, the file is opened for reading only. You must use this flag when creating or replacing a file.u$0200 - Random access flag - the file is opened for random access (not sequential access), using the IOSEEK function.
$0400 - Share flag - the file can still be opened by other processes. If not specified, the file is locked and may only be used by this program.jIf the file is opened for writing ($0100 above), this flag is ignored, since sharing is then not feasible.*
.IOREAD
r%=IOREAD(h%,addr%,maxLen%)
Reads from the file with the handle h%. address% is the address of a buffer large enough to hold a maximum of maxLen% bytes. The value returned to r% is the actual number of bytes read or, if negative, is an error value.pThe buffer could be an array or even a single integer as required. No more than 16K bytes can be read at a time.
FOR TEXT FILES:
If maxLen% exceeds the current record length, data only up to the end of the record is read into the buffer; no error is returned and the file position is set to the next record.
If a record is longer than maxLen%, the error value `Record too large' (-43) is returned. In this case the data read is valid but is truncated to length maxLen%, and the file position is set to the next record.
A string can be used for the buffer. Pass the address UADD(ADDR(str$),1) to IOREAD. You can then POKEB the first byte of the string with the length (returned to ret%) so that the string conforms to normal OPL string format.
FOR BINARY FILES:
If you request more bytes than are left in the file, the number of bytes actually read (even zero) will be less than the number requested. So if ret%<maxLen%, end of file has been reached.rNo error is returned by IOREAD in this case, but the next IOREAD would return the error value `End of file' (-36).
.IOSEEK
r%=IOSEEK(h%,mode%,var off&)ESeeks to a position in a file that has been opened for random access.joff& may be positive to move forwards or negative to move backwards. The values you can use for mode% are:o1 Set position in a binary file to the absolute value specified in off&, with 0 for the first byte in the file.G2 Set position in a binary file to off& bytes from the end of the file.O3 Set position in a binary file to off& bytes relative to the current position.
6 Rewind a text file to the first record. off& is ignored, but you must still pass it as a argument, for compatibility with the other cases.;IOSEEK sets the variable off& to the absolute position set.Q
.IOSIGNAL
IOSIGNAL=Replace a signal of an I/O function's completion. See IOWAIT.
r%=IOW(h%,func%,var a1,var a2)sThe device driver opened with handle h% performs the synchronous I/O function func% with the two further arguments.z
.IOWAIT
IOWAITbWaits for an asynchronous I/O function (such as one requested by IOC or IOA) to signal completion.
IOWAIT returns when any asynchronous I/O function completes. Check status% to see whether it was the function which you called with IOA/IOC. You must keep a count of the number of times IOWAIT returns due to other functions completing.
When status% finally shows that IOWAIT has returned because of this function completing, you must then call IOSIGNAL once for each other function which completed, to replace these other signals.XIf you have no other functions pending on different I/O handles, use IOWAITSTAT instead.m
.IOWAITSTAT
IOWAITSTAT var stat%KWaits for a particular asynchronous function, called with IOA, to complete.P
.IOWRITE
r%=IOWRITE(h%,addr%,length%)LWrites length% bytes in a buffer at address% to the file with the handle h%.lWhen a file is opened as a binary file, the data written by IOWRITE overwrites data at the current position.oWhen a file is opened as a text file, IOWRITE writes a single record; the closing CR/LF is automatically added.
.IOYIELD
IOYIELDOEnsures that any asynchronous handler set up with IOA is given a chance to run.
Some devices are unable to perform an asynchronous request if an OPL program becomes computationally intensive, using no I/O (screen, keyboard etc) at all. In such cases, the OPL program should use IOYIELD before checking its status% variable.
IOYIELD is the equivalent of IOSIGNAL followed by IOWAIT - the IOWAIT returns immediately with the signal from IOSIGNAL, but the IOWAIT causes any asynchronous handlers to run.
k%=KEY
Returns the character code of the last key pressed, if there has been one since the last call to the keyboard. These functions count as calling to the keyboard: INPUT, EDIT, GET, GET$, KEY and KEY$.-If no key has been pressed, zero is returned.
See the entry entitled "Character set and key codes" for a list of special key codes. You can use KMOD to check whether modifier keys (Shift, Control, Psion and Caps Lock) were used.?This command does not wait for a key to be pressed, unlike GET.
.KEY$
k$=KEY$
Returns the last key pressed as a string, if there has been a keypress since the last use of the keyboard by INPUT, EDIT, GET, GET$, KEY or KEY$.;If no key has been pressed, a null string ("") is returned.
See the entry entitled "Character set and key codes" for a list of special key codes. You can use KMOD to check whether modifier keys (Shift, Control, Psion and Caps Lock) were used.@This command does not wait for a key to be pressed, unlike GET$.
.KEYA err%=KEYA(var stat%,var key%(1))
This is an asynchronous keyboard read function. You must declare an integer array with two elements - here, key%(1) and key%(2) - to receive the keypress information.
If a key is pressed, key%(1) is assigned the character code of the key. The least significant byte of key%(2) takes the key modifier, in the same way as KMOD - 2 for Shift down, 4 for Control down and so on. (KMOD cannot be used with KEYA.)NThe most significant byte of key%(2) takes the count of keys pressed (0 or 1).,KEYA needs an IOWAIT in the same way as IOA.
KEYA has been included in OPL because the handle of the keyboard driver is unknown to the programmer. Otherwise it is equivalent to IOA(keyhand%,1,status%,key%()).Z
.KEYC
err%=KEYC(var stat%)>Cancels the previously called KEYA function with status stat%.i
.KMOD
k%=KMOD
Returns a code representing the state of the modifier keys (whether they were pressed or not) at the time of the last keyboard access, such as a KEY function. The modifiers have these codes: binary
2 Shift down 10
4 Control down 100
8 Psion down 1000
16 Caps Lock on 10000
If there was no modifier, the function returns 0. If a combination of modifiers was pressed, the sum of their codes is returned - for example 20 is returned if Control (4) was held down and Caps Lock (16) was on.;Always use immediately after a KEY/KEY$/GET/GET$ statement.
The value returned by KMOD has one binary bit set for each modifier, as shown above. By using the logical operator AND on the value returned by KMOD you can check which of the bits are set, in order to see which modifier keys were held down.
Example:
PROC modifier:
LOCAL k%,mod%
PRINT "Press a key" :k%=GET
CLS :mod%=KMOD
PRINT "Key code",k%,"with" IF mod%=0
PRINT "no modifier"
ENDIF
IF mod% AND 2
PRINT "Shift down"
ENDIF
IF mod% AND 4
PRINT "Control down"
ENDIF
IF mod% AND 8
PRINT "Psion down"
ENDIF
IF mod% AND 16
PRINT "Caps Lock on"
ENDIF
ENDP8
.LAST
LAST,Positions to the last record in a data file.s
.LCLOSE
LCLOSEcCloses the device opened with LOPEN. (The device is also closed automatically when a program ends.)
.LEFT$
b$=LEFT$(a$,x%)6Returns the leftmost x% characters from the string a$.OFor example if n$ has the value Charles, then b$=LEFT$(n$,3) assigns Cha to b$.
a%=LEN(a$)'Returns the number of characters in a$.DEg if a$ has the value "34 Kopechnie Drive" then LEN(a$) returns 18.bYou might use this function to check that a data file string field is not empty before displaying:
IF LEN(A.client$)
PRINT A.client$
ENDIF_
.LENALLOC
len%=LENALLOC(pcell%)>Returns the length of the previously allocated cell at pcell%.N
.LINKLIB
LINKLIB cat%7Link any libraries that have been loaded using LOADLIB.h
a=LN(x),Returns the natural (base e) logarithm of x..Use LOG to return the base 10 log of a number.
.LOADLIB"ret%=LOADLIB(var cat%,name$,link%)
Load and optionally link a DYL that is not in the ROM. If successful, this writes the category handle to cat% and returns zero. The DYL is shared in memory if already loaded by another process.
.LOADM
LOADM module$
Loads a translated OPL module so that procedures in that module can be called. Until a module is loaded with LOADM, calls to procedures in that module will give an error.gmodule$ is a string containing the name of the module. Specify the full file name only where necessary.
Example: LOADM "MODUL2"
Up to 4 modules can be in memory at any one time; if you try to LOADM a fifth module, you get an error. Use UNLOADM to remove a module from memory so that you can load a different one.
By default, LOADM always uses the directory of the initial running program, or the one specified by a OPA application. It is not affected by the SETPATH command.&
a%=LOC(a$,b$)
Returns an integer showing the position in a$ where b$ occurs, or zero if b$ doesn't occur in a$. The search matches upper and lower case.
Example: LOC("STANDING","AND") would return the value 3 because the substring AND starts at the third character of the string STANDING.
.LOCAL
LOCAL variables
Used to declare variables which can be referenced only in the current procedure. Other procedures may use the same variable names to create new variables. Use GLOBAL to declare variables common to all called procedures.GThe variables may be of 4 types, depending on the symbol they end with:e
Variable names not ending with $ % & or () are floating-point variables - for example: price, xK
Those ending with a % are integer variables, for example x%, sales92%S
Those ending with an & are long integer variables, for example x&, sales92&.
Those ending with a $ are string variables. String variable names must be followed by the maximum length of the string in brackets - for example names$(12), a$(3)
Array variables have a number immediately following them in brackets which specifies the number of elements in the array. Array variables may be of any type, for example: x(6),y%(5),f$(5,12),z&(3)
When declaring string arrays, you must give two numbers in the brackets. The first declares the number of elements, the second declares their maximum length. For example surname$(5,8) declares five elements, each up to 8 characters long.
Variable names may be any combination of up to 8 numbers and alphabetic letters. They must start with a letter. The length includes the % & or $ sign, but not the () in string and array variables.~More than one GLOBAL or LOCAL statement may be used, but they must be on separate lines, immediately after the procedure name.
See also GLOBAL.F
.LOCK
LOCK ON
LOCK OFF
Mark an OPA (OPL application) as locked or unlocked. When an OPA is locked with LOCK ON, the System screen will not send it events to change files or quit.
If, for example, you move onto the file list in the System screen and press Delete to try to stop that running OPA, a message will appear, indicating that the OPA cannot close down at that moment.
You should use LOCK ON if your OPA uses a command, such as EDIT or DIALOG, which accesses the keyboard. You might also use it when the OPA is about to go busy for a considerable length of time, or wherever a clean exit is not possible.=Do not forget to use LOCK OFF as soon as possible afterwards.
`Foreground', `background' and `Machine on' events may still occur while the OPA is accessing the keyboard, and will be discarded.
An OPA is initially unlocked.[
a=LOG(x)#Returns the base 10 logarithm of x.(Use LN to find the base e (natural) log.
.LOPEN
LOPEN device$1Opens the device to which LPRINTs are to be sent.ANo LPRINTs can be sent until a device has been opened with LOPEN."You can open any of these devices:+
The parallel port, with LOPEN "PAR:A")
The serial port, with LOPEN "TTY:A"W
A file on the Series 3a or an attached computer. LOPEN the file name, eg on a PC:
LOPEN "REM::C:\BAK\MEMO.TXT"
or on an Apple Macintosh:
LOPEN "REM::HD40:ME:MEMO5"MAny existing file of the name given will be overwritten when you print to it.
Only one device may be open at any one time. Use LCLOSE to close the device. (It also closes automatically when a program finishes running.)<See the entry entitled "Serial/parallel ports and printing".
.LOWER$
b$=LOWER$(a$)oConverts any upper case characters in the string a$ to lower case and returns the completely lower case string.9Eg if a$="CLARKE", LOWER$(a$) returns the string "clarke"-Use UPPER$ to convert a string to upper case.l
.LPRINT
LPRINT list of expressions}Prints a list of items, in the same way as PRINT, except that the data is sent to the device most recently opened with LOPEN.
The expressions may be quoted strings, variables, or the evaluated results of expressions. The punctuation of the LPRINT statement (commas, semi-colons and new lines) determines the layout of the printed text, in the same way as PRINT statements.>If no device has been opened with LOPEN you will get an error.ASee also the entry entitled "Serial/parallel ports and printing".*See LOPEN for opening a device for LPRINT.'See PRINT for displaying to the screen.
.MAX%m=MAX(list)
m=MAX(array(),element)0Returns the greatest of a list of numeric items.
The list can be either:F
A list of variables, values and expressions, separated by commas
or-
The elements of a floating-point array.UWhen operating on an array, the first argument must be the array name followed by ().
The second argument, separated from the first by a comma, is the number of array elements you wish to operate on - for example m=MAX(arr(),3) would return the value of the largest of elements arr(1), arr(2) and arr(3).y
.mCARD9mCARD title$,n1$,k1%
mCARD title$,n1$,k1%,n2$,k2%
etc.QDefines a menu. When you have defined all of the menus, use MENU to display them.ttitle$ is the name of the menu. From one to eight items on the menu may be defined, each specified by two arguments.
The first is the item name, and the second the keycode for a hot-key. This specifies a key which, when pressed together with the Psion key, will select the option.\If the keycode is for an upper case key, the hot-key will use both the Shift and Psion keys.oYou can display a grey line under an option by passing the negative value corresponding to the hot-key keycode.k
.MEAN'm=MEAN(list)
m=MEAN(array(),element)AReturns the arithmetic mean (average) of a list of numeric items.
The list can be either:F
A list of variables, values and expressions, separated by commas
or-
The elements of a floating-point array.UWhen operating on an array, the first argument must be the array name followed by ().
The second argument, separated from the first by a comma, is the number of array elements you wish to operate on - for example m=MEAN(arr(),3) would return the average of elements arr(1), arr(2) and arr(3).
This example displays 15.0:
a(1)=10
a(2)=15
a(3)=20
PRINT MEAN(a(),3)
.MENU!val%=MENU
val%=MENU(var init%)
Displays the menus defined by mINIT and mCARD, and waits for you to select an item. Returns the hot-key keycode of the item selected, as defined in mCARD, in lower case.7If you cancel the menu by pressing Esc, MENU returns 0.
If the name of a variable is passed is sets the initial menu and item to be highlighted. init% should be 256*(menu%)+item%; for both menu% and item%, 0 specifies the first, 1 the second and so on.WIf init% is 517 (=256*2+5), for example, this specifies the 6th item on the third menu.
If init% was passed, MENU writes back to init% the value for the item which was last highlighted on the menu. You can then use this value when calling the menu again. You only need do this if you have more than one menu in your program.
.MID$
m$=MID$(a$,x%,y%)ZReturns a string comprising y% characters of a$, starting at the character at position x%.IEg if name$="McConnell" then MID$(name$,3,3) would return the string Con.
.MIN%m=MIN(list)
m=MIN(array(),element)0Returns the smallest of a list of numeric items.
The list can be either:F
A list of variables, values and expressions, separated by commas
or-
The elements of a floating-point array.UWhen operating on an array, the first argument must be the array name followed by ().
The second argument, separated from the first by a comma, is the number of array elements you wish to operate on - for example m=MIN(arr(),3) would return the minimum of elements arr(1), arr(2) and arr(3).
.mINIT
mINITzPrepares for definition of menus, cancelling any existing menus. Use mCARD to define each menu, then MENU to display them.u
.MINUTE m%=MINUTEBReturns the current minute number from the system clock (0 to 59).
Eg at 8.54am MINUTE returns 54.
.MKDIR
MKDIR name$
Creates a new directory. For example, MKDIR "M:\MINE\TEMP" creates a M:\MINE\TEMP directory, also creating M:\MINE if it is not already there.
.MONTH
m%=MONTHOReturns the current month from the system clock as an integer between 1 and 12./Eg on 12th March 1992 m%=MONTH returns 3 to m%.
.MONTH$
m$=MONTH$(x%)eConverts x%, a number from 1 to 12, to the month name, expressed as a three-letter mixed case string.$Eg MONTH$(1) returns the string Jan.
.NEWOBJ
pobj%=NEWOBJ(num%,clnum%)
Create a new object by category number num% belonging to the class clnum%, returning the object handle on success or zero if out of memory.
.NEWOBJH
pobj%=NEWOBJH(cat%,clnum%)
Create a new object by category handle cat% belonging to the class clnum%, returning the object handle on success or zero if out of memory.
.NEXT
NEXT6Positions to the next record in the current data file.
If NEXT is used after the end of a file has been reached, no error is reported but the current record is a null and the EOF function returns true.G
.NUM$
n$=NUM$(x,y%)
Returns a string representation of the integer part of the floating-point number x, rounded to the nearest whole number. The string will be up to y% characters wide.
If y% is negative then the string is right-justified, for example NUM$(1.9,-3) returns " 2" where there are two spaces to the left of the 2.0
If y% is positive no spaces are added, eg:
NUM$(-3.7,3) returns "-4".
If the string returned to n$ will not fit in the width y%, then the string will just be asterisks; for example NUM$(256.99,2) returns "**".
See also FIX$, GEN$, SCI$.
.ODBINFO
ODBINFO var info%()
Provided for advanced use only, this keyword allows you to use OS and CALL to access data file interrupt functions not accessible with OPL keywords.
ODBINFO returns info%() (which must have four elements) containing pointers to four blocks of data; the first corresponds to the file with logical name A, the second to B and so on.
Take extreme care not to corrupt these blocks of memory, as they are the actual data structures used by the OPL runtime interpreter.MA data block which has no open file using it has zero in the first two bytes.
Otherwise, the block of data for each file has the following structure, giving the offset to each component from the start of the block and with offset 0 for the 1st byte of the block:
Offset Bytes DescriptionE0 2 DBF system's file control block (handle) or zero if file not open52 2 offset in the record buffer to the current record$4 2 pointer to the field name buffer
6 2 number of fields%8 2 pointer to start of record buffer
10 2 length of a NULL record$12 1 non-zero if all fields are text 13 1 non-zero for read-only file,14 1 non-zero if record has been copied down
15 1 number of text fields
16 2 pointer to device name
OFF x%
Switches the Series 3a off.ZWhen you switch back on, the statement following the OFF command is executed, for example:
OFF :PRINT "Hello again"
If you specify an integer, x%, between 8 and 16383, the machine switches off for that number of seconds and then automatically turns back on and continues with the next line of the program (16383 is about 4 1/2 hours).sHowever, during this time the machine may be switched on by an alarm, and of course you can turn it on with ON/Esc.
Warning: be careful how you use this command. If, due to a programming mistake, a program uses OFF in a loop, you may find it impossible to switch the Series 3a back on, and may have to reset the computer.}
.ONERR,ONERR label or
ONERR label::
ONERR OFF
ONERR label:: establishes an error handler in a procedure. When an error is raised, the program jumps to the label:: instead of the program stopping and an error message being displayed.
The label may be up to 8 characters long starting with a letter. It ends with a double colon (::), although you don't need to use this in the ONERR statement.}ONERR OFF disables the ONERR command, so that any errors occurring after the ONERR OFF statement no longer jump to the label.pIt is advisable to use the command ONERR OFF immediately after the label:: which starts the error handling code.
.OPEN
OPEN file$,log,f1,f2...pOpens an existing data file file$, giving it the logical file name log, and giving the fields the names f1, f2..lYou need only specify those fields which you intend to update or append, though you cannot miss out a field.ZThe opened file is then referred to within the program by its logical name (A, B, C or D)."Up to 4 files can be open at once.
Example:
OPEN "clients",A,name$,addr$
See also CREATE, USE and OPENR.
.OPENR
This command works exactly like OPEN except that the opened file is read-only - in other words, you cannot APPEND or UPDATE the records it contains._This means that you can run two separate programs at the same time, both sharing the same file.
.OS.a%=OS(i%, addr1%)
a%=OS(i%, addr1%, addr2%)eCalls the Operating System interrupt i%, reading the values of all returned 8086 registers and flags.
The CALL function, although simpler to use, does not allow the AL register to be passed and no flags are returned, making it suitable only for certain interrupts.
The input registers are passed at the address addr1%. The output registers are returned at the address addr2% if supplied, otherwise they are returned at addr1%. Both addresses can be of an array, or of six consecutive integers.
Register values are stored sequentially as 6 integers and represent the register values in this order: AX, BX, CX, DX, SI and DI. The interrupt's function number, if required, is passed in AH.
The output array must be large enough to store the 6 integers returned in all cases, irrespective of the interrupt being called.
The value returned by OS is the flags register. The Carry flag, which is relevant in most cases, is in bit 0 of the returned value, so (a% and 1) will be `True' if Carry is set.]Similarly, the Zero flag is in bit 6, the Sign flag in bit 7 and the Overflow flag in bit 10.
For example, to find cos(pi/4): PROC add:
local ax%,bx%,cx%,dx%,si%,di%
local result,cosArg,flags%
cosArg=pi/4
si%=addr(cosArg)
di%=addr(result)
ax%=$0100 REM AH=1 for cosine
flags%=os(140,addr(ax%))hThe OS function requires extensive knowledge of the Operating System and related programming techniques.
See also CALL.v
.PARSE$
p$=PARSE$(f$,rel$,var off%())eReturns a full file specification from the filename f$, filling in any missing information from rel$.
The offsets to the filename components in the returned string is returned in off%() which must be declared with at least 6 integers:'off%(1) filing system offset (1 always)
off%(2) device offset
off%(3) path offset
off%(4) filename offset
off%(5) file extension offset.off%(6) flags for wildcards in returned string"The flag values in offset%(6) are:
0 : no wildcards
1 : wildcard in filename
2 : wildcard in file extension
3 : wildcard in both
If rel$ is not itself a complete file specification, the current filing system, device and/or path are used as necessary to fill in the missing parts.'f$ and rel$ should be separate strings.
Example:(p$=PARSE("NEW","LOC::M:\ODB\*.ODB",x%());sets p$ to LOC::M:\ODB\NEW.ODB and x%() to (1,6,8,13,16,0).9
.PATH
PATH name$UGives the directory for the System screen to use when listing files used by this OPA.
If you do not use this, the normal \OPD directory will be used. The maximum length, including a final \, is 19 characters. Don't include any drive name in this path.+This can only be used between APP and ENDA.
.PAUSE
PAUSE x%DPauses the program for a certain time, depending on the value of x%: x% result 0 waits for a key to be pressed.*+ve pauses for x% twentieths of a second.C-ve pauses for x% twentieths of a second or until a key is pressed.
So PAUSE 100 would make the program pause for 100/20 = 5 seconds, and PAUSE -100 would make the program pause for 5 seconds or until a key is pressed.
If x% is 0, a GET, GET$, KEY or KEY$ will return the key press which terminated the pause. If you are not interested in this keypress, but in the one which follows it, clear the buffer after the PAUSE with a single KEY function:
PAUSE 0 :KEY
You should be especially careful about this if x% is negative, since then you cannot tell whether the pause was terminated by a keypress or by the time running out.a
".PEEKB/.PEEKW/.PEEKL/.PEEKF/.PEEK$
@p%=PEEKB(x%) returns the integer value of the byte at address x%.p%=PEEKW(x%) returns the integer at address x%9p&=PEEKL(x%) returns the long integer value at address x%:p=PEEKF(x%) returns the floating-point value at address x%-p$=PEEK$(x%) returns the string at address x%
Usually you would find out the byte address with the ADDR function. For example, if var% has the value 7, PEEKW(ADDR(var%)) returns 7.>The different types are stored in different ways across bytes:b
Integers are stored in two bytes. The first byte is the least significant byte, for example:
1 0 =1
0 1 =256?ADDR returns the address of the first (least significant) byte.u
Long integers are stored in four bytes, the least significant first and the most significant last, for example:
0 0 1 0 =65536?ADDR returns the address of the first (least significant) byte.k
Strings are stored with one character per byte, with a leading byte containing the string length, eg:
3 65 66 67 ="ABC"CEach letter is stored as its character code - for example, A as 65.vFor example, if var$="ABC", PEEK$(ADDR(var$)) will return the string ABC. ADDR returns the address of the length byte.
Floating-point numbers are stored under IEEE format, across eight bytes. PEEKF automatically reads all eight bytes and returns the number as a floating-point. For example if var=1.3 then PEEKF(ADDR(var)) returns 1.3.
You can use ADDR to find the address of the first element in an array, for example ADDR(x%()). You can also specify individual elements of the array, for example ADDR(x%(2)).$See also the POKE commands and ADDR.-
p=PI#Returns the value of Pi (3.14... ).
".POKEB/.POKEW/.POKEL/.POKEF/.POKE$
XPOKEB x%,y% stores the integer value y% (less than 256) in the single byte at address x%
POKEW x%,y% stores the integer y% across two consecutive bytes, with the least significant byte in the lower address, that is x%FPOKEL x%,y& stores the long-integer y& in bytes starting at address x%LPOKEF x%,y stores the floating-point value y in bytes starting at address x%@POKE$ x%,y$ stores the string y$ in bytes starting at address x%<Use ADDR to find out the address of your declared variables.VWarning: Casual use of these commands can result in the loss of data in the Series 3a.MSee PEEK for more details of how the different types are stored across bytes.
p%=POSeReturns the number of the current record in the current data file, from 1 (the first record) upwards.
A file can have up to 65534 records. However integers can only be in the range -32768 to +32767. Record numbers above 32767 are therefore returned like this:
record value returned by POS
32767 32767
32768 -32768
32769 -32767
32770 -32766
65534 -22To display record numbers, you can use this check:
IF POS<0
PRINT 65536+POS
ELSE PRINT POS
ENDIF
.POSITION
POSITION x%CMakes record number x% the current record in the current data file._If x% is greater than the number of records in the file then the EOF function will return true.R
.POSSPRITE
POSSPRITE x%,y%6Set the position of the current sprite to pixel x%,y%.
.PRINT
PRINT list of expressions^Displays a list of expressions on the screen. The list can be punctuated in one of these ways:e
If items to be displayed are separated by commas, there is a space between them when displayed.@
If they are separated by semi-colons, there are no spaces.j
Each PRINT statement starts a new line, unless the preceding PRINT ended with a semi-colon or comma.q
There can be as many items as you like in this list. A single PRINT on its own just moves to the next line.
Example:
On 1st January 1993,
PRINT "TODAY is",
PRINT DAY;".";"MONTH;".";YEAR
would display TODAY is 1.1.1993?See also LPRINT, gUPDATE, gPRINT, gPRINTB, gPRINTCLIP, gXPRINT.
r=RAD(x)#Converts x from degrees to radians.
All the trigonometric functions assume angles are specified in radians, but it may be easier for you to enter angles in degrees and then convert with RAD.
Example:
PROC xcosine:
LOCAL angle
PRINT "Angle (degrees)?:";
INPUT angle
PRINT "COS of",angle,"is",
angle=RAD(angle)
PRINT COS(angle)
ENDP+To convert from radians to degrees use DEG.\
.RAISE
RAISE x%
Raises an error.|The error raised is error number x%. This should usually be one of the errors listed in the entry entitled "Error messages".
The error is handled by the error processing mechanism currently in use - either OPL's own, which stops the program and displays an error message, or the ONERR handler if you have ONERR on.
.RANDOMIZE
RANDOMIZE x&%Gives a `seed' (start-value) for RND.
Successive calls of the RND function produce a sequence of random numbers. If you use RANDOMIZE to set the seed back to what it was at the beginning of the sequence, the same sequence will be repeated.
For example, you might want to use the same `random' values to test new versions of a procedure. To do this, precede the RND statement with the statement RANDOMIZE value. Then to repeat the sequence, use RANDOMIZE value again.
.REALLOC
pcelln%=REALLOC(pcell%,size%)
Change the size of a previously allocated cell at pcell% to size%, returning the new cell address or zero if there is not enough memory. If out of memory, the old cell at pcell% is left as it was.
If successful, pcelln% will not be the same as pcell% if the size increases and there was no free cell following the cell being grown which was large enough to accomodate the extra amount.
.RECSIZE
r%=RECSIZE;Returns the number of bytes occupied by the current record.qUse this function to check that a record may have data added to it without overstepping the 1022 character limit.
REM textzPrecedes a remark you include to explain how a program works. All text after the REM up to the end of the line is ignored.eWhen you use REM at the end of a line you need only precede it with a space, not a space and a colon.
.RENAME
RENAME file1$,file2$:Renames file1$ as file2$. You can rename any type of file.
You cannot use wildcards.'You can rename across directories - eg:
RENAME "\dat\x.dbf","\x.dbf"MIf you do this, you can choose whether or not to change the name of the file.
.REPT$
r$=REPT$(a$,x%)1Returns a string comprising x% repetitions of a$.;For example, if a$="ex", r$=REPT$(a$,5) returns exexexexex.
.RETURN
RETURN or RETURN variable
Terminates the execution of a procedure and returns control to the point where that procedure was called (ENDP does this automatically).
RETURN variable does this as well, but also passes the value of one variable back to the calling procedure. The variable may be of any type. You can return the value of any single array element - for example RETURN x%(3).tRETURN on its own, and the default return through ENDP, causes the procedure to return the value 0 or a null string.D
.RIGHT$
r$=RIGHT$(a$,x%)*Returns the rightmost x% characters of a$.^
.RMDIR
RMDIR str$KRemoves the directory given by str$. You can only remove empty directories.
r=RNDSReturns a random floating-point number in the range 0 (inclusive) to 1 (exclusive).xTo produce random numbers between 1 and n - eg between 1 and 6 for a dice - use the following statement: f%=1+INT(RND*n)
RND produces a different number every time it is called within a program. A fixed sequence can be generated by using RANDOMIZE.
You might begin by using RANDOMIZE with an argument generated from MINUTE and SECOND (or similar), to seed the sequence differently each time.
.SCI$
s$=SCI$(x,y%,z%)wReturns a string representation of x in scientific format, to y% decimal places and up to z% characters wide. Examples:
SCI$(123456,2,8)="1.23E+05"
SCI$(1,2,8)="1.00E+00"
SCI$(1234567,1,-8)=" 1.2E+06"^If the number does not fit in the width specified then the returned string contains asterisks.5If z% is negative then the string is right-justified.
See also FIX$, GEN$, NUM$.5
.SCREEN4SCREEN width%,height%
SCREEN width%,height%,x%,y%
Changes the size of the window in which text is displayed. x%,y% specify the character position of the top left corner; if they are not given, the text window is centred in the screen.>An OPL program can initially display text to the whole screen.n
.SCREENINFO
SCREENINFO var info%();Gets information on the text screen (as used by PRINT etc.)
This keyword allows you to mix text and graphics. It is required because while the default window is the same size as the physical screen, the text screen is slightly smaller and is centred in the default window.oThe few pixels gaps around the text screen, referred to as the left and top margins, depend on the font in use.^On return, the array info%(), which must have at least 10 elements, contains this information:
info%(1) left margin in pixels
info%(2) top margin in pixels-info%(3) text screen width in character units.info%(4) text screen height in character units7info%(5) reserved (window server id for default window)!info%(6) font id (FONT and gFONT)2info%(7) pixel width of text window character cell)info%(8) pixel height of text window line
info%(9), info%(10) reserved
Initially SCREENINFO returns the values for the initial text screen. Subsequently any keyword which changes the size of the text screen font, such as FONT, will change some of these values and SCREENINFO should therefore be called again.
See also FONT.x
.SECOND s%=SECONDDReturns the current time in seconds from the system clock (0 to 59). Eg at 6:00:33 SECOND returns 33.
Sets the variables passed by reference to the date corresponding to s&, the number of seconds since 00:00 on 1 January 1970. yrday% is set to the day in the year (1-366).qs& is an unsigned long integer. To use values greater than +2,147,483,647, subtract 4,294,967,296 from the value.7See also DATETOSECS, HOUR, MINUTE, SECOND, dDATE, DAYS.
.SEND
ret%=SEND(pobj%,m%,var p1,...)
Send a message to the object pobj% to call the method number m%, passing between zero and three arguments (p1...) depending on the requirements of the method, and returning the value returned by the selected method.
.SETNAME
SETNAME name$hSets the name of the running OPA to name$ and redraws any status window, using that name below the icon.
.SETPATH
SETPATH name$
Sets the current directory for file access - for example, SETPATH "a:\docs". LOADM continues to use the directory of the initial program, or the one specified by a OPA application, but all other file access will be to the new directory.
s=SIN(angle)9Returns the sine of angle, an angle expressed in radians.9To convert from degrees to radians, use the RAD function.n
.SPACE
s&=SPACE]Returns the number of free bytes on the device on which the current (open) data file is held.,
s=SQR(x)
Returns the square root of x.F
.STATUSWIN-STATUSWIN ON,type%
STATUSWIN ON
STATUSWIN OFF0Displays or removes a `permanent' status window.
If type%=1 the small status window is shown. If type%=2 the large status window is shown. STATUSWIN ON on its own displays an appropriate status window; on the Series 3a this will always be the large status window.
The permanent status window is behind all other OPL windows. In order to see it, you must use FONT (or both SCREEN and gSETWIN) to reduce the size of the text and graphics windows.OYou should ensure that your program does not create windows over the top of it.
.STATWININFO
t%=STATWININFO(type%,var xy%())
Sets xy%(1),xy%(2), xy%(3) and xy%(4) to the top left x, top left y, width and height respectively of the specified type of status window.
type%=1 is the small status window; type%=2 is the large status window; type%=3 is the Series 3 compatibility mode status window; type%=-1 is whichever status window is current.
STATWININFO returns t%, the type of the current status window (with values as for type%, or zero if there is no current status window).v
.STD%s=STD(list)
s=STD(array(),element):Returns the standard deviation of a list of numeric items.
The list can be either:F
A list of variables, values and expressions, separated by commas
or-
The elements of a floating-point array.
When operating on an array, the first argument must be the array name followed by (). The second argument, separated from the first by a comma, is the number of array elements you wish to operate on.eFor example m=STD(arr(),3) would return the standard deviation of elements arr(1), arr(2) and arr(3).QTo convert to population standard deviation, multiply the result by SQR((n-1)/n).%
.STOP
Ends the running program.
.STYLE
STYLE style%
Sets the text window character style for all characters subsequently written to the text window. style% can be 2 for underlined, or 4 for inverse. Any other styles are ignored as they would change the size of the characters.
.SUM%s=SUM(list)
s=SUM(array(),element)+Returns the sum of a list of numeric items.
The list can be either:F
A list of variables, values and expressions, separated by commas
or-
The elements of a floating-point array.
When operating on an array, the first argument must be the array name followed by (). The second argument, separated from the first by a comma, is the number of array elements you wish to operate on.VFor example m=SUM(arr(),3) would return the sum of elements arr(1), arr(2) and arr(3).
t=TAN(angle)<Returns the tangent of angle, an angle expressed in radians.9To convert from radians to degrees, use the DEG function.
.TESTEVENT
t%=TESTEVENT
Returns `True' if an event has occurred, otherwise returns `False'. The event is not read by TESTEVENT - it may be read with GETEVENT.
.TRAP
TRAP commandHTRAP is an error handling command. It may precede any of these commands:
Data file commandsZAPPEND, UPDATE, BACK, NEXT, LAST, FIRST, POSITION, USE, CREATE, OPEN, OPENR, CLOSE, DELETE
Any error resulting from the execution of the command will be trapped. Program execution will continue at the statement after the TRAP statement, but ERR will be set to the error code.
TRAP overrides any ONERR.y
.TYPE TYPE num%\Sets the type of an OPA, from 0 to 4, with num%. This can only be used between APP and ENDA.
A Series 3a OPA should also add $1000 to the type if it has its own 48x48 pixel, black/grey icon (see the explanation of ICON for details).0
TYPE 0 (like Calc): The OPA uses no files.
TYPE 1: Only one file is used. A type 1 OPA will look the same as a type 0. The only difference is that the type 1 is using a file, of the same name as the OPA.j
TYPE 2 (like World): You can have more than one file, but only one can be in use (bold) at any time.
When you pick a new file to use, its name becomes bold, and the one that was previously bold reverts to normal. What has actually happened is that the running OPA has switched files - it has not closed down, and no new copy of the OPA is run.
TYPE 3 (like Data, Word, Agenda and Sheet): You can have more than one file, and any number may be open (bold) at a given time.
When you select a new file, one of the running OPAs normally switches to this file, as with type 2 OPAs. You can, however, with Shift-Enter, start a new OPA running just for this file, without a different file exiting.
TYPE 4 (like RunOpl): Many files can be used, and any number may be in use at a given time. When you select a new file, a new version of the OPA is always run, to use the new file.
Types 3 and 4 allow more than one file to be in use (ie have their names in bold). When this happens a separate version of the OPA runs for each bold file. With types 0, 1 and 2, only one version of the OPA can be running at any time.
Initially, the OPA's name appears beneath the icon. If you move onto this and press Enter, file-based OPAs (types 1 to 4) will use a file of this name. Types 2, 3 and 4 allow you to create lists of files below the icon (with the `New file' option).EYou can also add any of these numbers to the value you use with TYPE:
$8000 (-32768) stops the System screen's `New file' option from working, as for the RunOpl icon (translated OPL modules).
$4000 (16384) stops the System screen from closing the OPA, as for the Time icon. You should not use this without a very good reason.
$100 (8192) causes the System screen to terminate the OPA (when Delete is pressed) without sending a "quit" message, as for the RunOpl icon again. This should be used only for OPAs which have no data that could be lost by sudden termination.?
.UADD
i%=UADD(val1%, val2%)
Add val1% and val2%, as if both were unsigned integers with values from 0 to 65535. Prevents integer overflow for pointer arithmetic - eg UADD(ADDR(text$),1) should be used instead of ADDR(text$)+1.LOne argument would normally be a pointer and the other an offset expression.
See also USUB.[
.UNLOADLIB
ret%=UNLOADLIB(var cat%)6Unload a DYL from memory. If successful, returns zero.{
.UNLOADM
UNLOADM module$9Removes from memory the module module$ loaded with LOADM.Amodule$ is a string containing the name of the translated module.PThe procedures in an unloaded module cannot then be called by another procedure.
Note that it considered bad practice to unload a module containing procedures that are still running - eg. for a procedure to unload its own module.
.UNTIL
See DO.
.UPDATE
UPDATE~Deletes the current record in the current data file and saves the current field values as a new record at the end of the file.BThis record, now the last in the file, remains the current record.<Use APPEND to save the current field values as a new record.
.UPPER$
u$=UPPER$(a$)eConverts any lower case characters in a$ to upper case, and returns the completely upper case string.$Use LOWER$ to convert to lower case.
USE logical name
Selects the data file with the logical name A, B, C or D. The file must previously have been opened with OPEN, OPENR or CREATE and not yet be closed.XAll the record handling commands (such as POSITION or UPDATE) then operate on this file.
u%=USR(pc%,ax%,bx%,cx%,dx%)
Executes your machine code, returning an integer. The USR code (ie the assembler code you have written) must return with a far RET, otherwise the program will crash.
The values of of ax%,bx%... are passed to the AX, BX... 8086 registers. The microprocessor then executes the machine code starting at pc%. At the end of the routine, the value in the AX register is passed back to u%.UWARNING: Casual use of this function can result in the loss of data in the Series 3a.=This example shows a simple operation, ending with a far RET:
PROC trivial:
LOCAL t%(2),u%,ax%
t%(1)=$c032 REM xor al,al
t%(2)=$cb REM retf ax%=$1ab
u%=usr(addr(t%(1)),ax%,0,0,0)
REM returns (ax% AND $FF00)
PRINT u% REM 256 ($100)
ENDP See also USR$, ADDR, PEEK, POKE.K
.USR$
u$=USR$(pc%,ax%,bx%,cx%,dx%)
Executes your machine code, returning a string. The USR$ code you have written must return with a far RET, otherwise the program will crash.
The values of of ax%,bx%... are passed to the ax, bx... 8086 registers. The microprocessor then executes the machine code starting at pc%.
At the end of the routine, the value in the ax register must point to a length-byte preceded string. This string is then copied to u$.UWARNING: Casual use of this function can result in the loss of data in the Series 3a.2See USR for an example. See also ADDR, PEEK, POKE.
.USUB
i%=USUB(val1%, val2%)
Subtract val2% from val1%, as if both were unsigned integers with values from 0 to 65535. Prevents integer overflow for pointer arithmetic.
See also UADD.)
v=VAL(numeric string)DReturns the floating-point number corresponding to a numeric string.
The string must be a valid number - eg not "5.6.7" or "196f". Expressions, such as "45.6*3.1", are not allowed. Scientific notation such as "1.3E10", is OK.
Eg VAL("470.0") returns 470.
See also EVAL.R
.VAR%v=VAR(list)
v=VAR(array(),element)0Returns the variance of a list of numeric items.
The list can be either:F
A list of variables, values and expressions, separated by commas
or-
The elements of a floating-point array.
When operating on an array, the first argument must be the array name followed by (). The second argument, separated from the first by a comma, is the number of array elements you wish to operate on.[For example m=VAR(arr(),3) would return the variance of elements arr(1), arr(2) and arr(3).ATo convert to population variance, multiply the result by (n-1)/n
.VECTOR'VECTOR I%
label1,label2,...
labelN
VECTOR I% jumps to label number i% in the list - if i% is 1 this will be the first label, and so on. The list is terminated by the ENDV statement.|The list may spread over several lines, with a comma separating labels in any one line but no comma at the end of each line.
If i% is not in the range 1 to N, where N is the number of labels, the program continues with the statement after the ENDV statement.
See also GOTO.
.WEEK
w%=WEEK(day%,month%,year%)YReturns the week number in which the specified day falls, as an integer between 1 and 53.Tday% must be between 1 and 31, month% between 1 and 12, year% between 1900 and 2155.
Each week is taken to begin on the `Start of week' day, as specified in the Time application. When a year begins on a different day, it counts as week 1 if there are four or more days before the next week starts.]
.WHILE...ENDWH%WHILE expression
...statements
ENDWH
Repeatedly performs the set of instructions between the WHILE and the ENDWH statement, so long as expression returns logical true - non-zero.SIf expression is not true, the program jumps to the line after the ENDWH statement.1Every WHILE must be closed with a matching ENDWH.
See also DO...UNTILb
.YEAR
y%=YEARSReturns the current year as an integer between 1900 and 2155 from the system clock.
Scanning the keyboard directly
CALL($288e,ADDR(scan%())) returns with the array scan%(), which must have at least 10 elements, containing a bit set for keys currently being pressed.
The following table lists each key (according to the text printed on the physical key itself), the scan%() array element for that key and the hexadecimal bit mask to be ANDed with that array element to check whether the key is being pressed.
KEY: scan% mask
System 5 $200
Data 4 $200
Word 6 $200
Agenda 2 $200
Time 1 $200
World 3 $200
Calc 2 $100
Sheet 1 $100
Esc 8 $100
1 8 $02
2 8 $04
3 6 $40
4 5 $04
5 5 $08
6 8 $08
7 4 $40
8 3 $08
9 3 $10
0 2 $10
+ 2 $08
Delete 3 $01
Tab 1 $04
Q 7 $02
W 7 $20
E 6 $20
R 5 $02
T 5 $10
Y 1 $08
U 4 $20
I 3 $04
O 3 $20
P 2 $20
- 2 $04
Enter 1 $01
Control 3 $80
A 7 $04
S 7 $10
D 6 $10
F 6 $02
G 5 $20
H 8 $40
J 4 $10
K 3 $02
L 3 $40
* 2 $40
/ 2 $02
Left shift 2 $80
Z 7 $08
X 7 $40
C 6 $08
V 6 $04
B 5 $40
N 1 $40
M 4 $08
, 4 $02
. 8 $10
Up 8 $20
Right shift 4 $80
Psion 1 $80
Menu 6 $80
Diamond 5 $80
Space 5 $01
Help 4 $04
Left 1 $10
Down 1 $20
Right 1 $02
For example, pressing Tab sets bit 2 of scan%(1), pressing Control sets bit 7 of scan%(3) and pressing both together sets both these bits.
'I/O calls: read cursor, set alarm, dial
LOCAL a%(6)
a%(1)=x1% :a%(2)=y1%
a%(3)=x2% :a%(4)=y2%)IOW(-2,8,a%(),a%()) REM 2nd a% is ignored
READS THE CURSOR POSITION in the rectangle x1%,y1% (top left), x2%,y2% (bottom right), writing the x and y positions to a%(5) and a%(6) respectively.
This returns 0,0, not 1,1, as the top left. Set x1%,y1%,x2%,y2% to the screen top left and bottom right (as set by SCREEN), to read the cursor position in the current screen.
r%=IOOPEN(h%,"ALM:",0)
IF r%<0 :RAISE r% :ENDIF
...#IOC(h%,2,s%,a&(),#UADD(ADDR(b$),1))
IOCLOSE(h%)
SETS AN ALARM. a&() is an array of 2 long integers - the first is the time for the alarm to go off, and the second is the time for which the event is due. (Both are given in seconds since midnight on 1/1/1970.)Nb$ is the alarm message (up to 64 characters), which has been zero-terminated.
The parameter 2 means that the day and time are shown when the alarm rings. If you use 1 instead, only the date (and no time) is shown.GIf you press the Time button, such alarms are shown as `RunOpl' alarms.
At the moment the alarm rings, either s% must still be available to take the status word set by this ALM: function, or the program must have exited. (Otherwise the status word will be written to a random area of memory.)
r%=IOOPEN(h%,"SND:",0)
IF r%<0 :RAISE r% :ENDIF$r%=IOW(h%,10,#UADD(ADDR(b$),1),a%())
IF r%<0 :RAISE r% :ENDIF
r%=IOCLOSE(h%)
IF r%<0 :RAISE r% :ENDIFiDIALS A NUMBER WITH DTMF. b$ is the number to dial (up to 24 characters), which has been zero-terminated.
a%() is an array of 2 integers. The first is the tone length (*256) plus the delay length, and the second is the pause length. All of these are specified in 1/32s of a second.
Recording and playing sounds
Sound files have a .WVE extension. They contain a 32-byte header and a byte stream of digital sound at 8000 bytes per second (12-bit sound is converted to 8-bit using A-Law encoding).)The file header has the following format:
Offset Bytes Contents(0 16 0-terminated text "ALawSoundFile**"
16 2 version of this format
18 4 number of 8-bit samples
22 2 trailing silence in ticks
24 2 repeats(26 6 spare bytes reserved for future useBThe number of samples is the number of bytes following the header.
The silence in system ticks is appended to each repeat on playback (in practice, you get at least 2 ticks between repeats). A system tick is 1/32s or 250 samples.fThe repeats are the number of times to repeat the sound on playback (0 and 1 are treated as the same).
You can truncate the sound file, change the repeats and the trailing silence by changing the file length and header using IOOPEN, IOW, IOSEEK, IOWRITE etc. For example, you can truncate the file to length newLen& using:
ret%=IOW(handle%,11,newLen&,#0)UThe following set of procedures perform asynchronous recording and playing of sounds:
...RECORDS ASYNCHRONOUSLY TO FILE f$. Any existing file is replaced. You can only record to RAM-based disks. (You can playback from a Flash SSD, however.)
size% specifies the maximum number of bytes to be recorded in units of 2048 bytes. For one second size%=4. This figure excludes the 32-byte header.uBefore recording, a file of length 32+size%*2048 bytes is created and there must actually be room on the disk for it.`pstat% is the address of the status word to take the completion code for asynchronous recording.
PROC recordw%:(f$,size%)
LOCAL name$(128),p%,ret%, p%=PEEKW($1c)+6 REM address of saved flags
name$=f$+chr$(0)+ ret%=CALL($2286,UADD(ADDR(name$),1),size%), IF PEEKW(p%) AND 1 REM carry set for error' RETURN ret% OR $FF00 REM return error
ENDIF
ENDP6...RECORDS SYNCHRONOUSLY TO FILE f$, in a similar way.
PROC recordc:
CALL($2386)
ENDPTCANCELS RECORDING and truncates the file to the length recorded before cancellation.
ENDPk...PLAYS f$ ASYNCHRONOUSLY. (f$ can be a `*' followed by just the name of the sound file. .WVE is assumed.)
The file is searched for (in order) in the ROM, then in the \WVE directories of M: (Internal disk), A: and B:. (The ROM:: .WVE files have names SYS$AL01 and SYS$AL02.)
t% is the duration to play back, in system ticks. If shorter than the sound, playback is truncated to that time. If t% is negative, in addition to truncating longer files, it pads out as necessary to that duration with silence.
If duration is zero, it plays the file without truncation or padding. (Alarms use the value -480 to truncate or pad out to 15 seconds.)
vol% is between 0 and 5 inclusive, with 0 being the loudest. On the Series 3a there are only 4 levels: 0/1, 2, 3, and 4/5. pstat% is the address of the status word to take the completion code for asynchronous playback.
PROC playw%:(f$,ticks%,vol%)
LOCAL n$(128),p%,ret%0 p%=PEEKW($1c)+6 REM address of flags after CALL
n$=f$+chr$(0). ret%=CALL($1F86,UADD(ADDR(n$),1),ticks%,vol%)/ IF PEEKW(p%) AND 1 REM carry set for error' RETURN ret% OR $FF00 REM return error
ENDIF
...PLAYS f$ SYNCHRONOUSLY.
PROC playc:
CALL($2086)
ENDP ...CANCELS PLAYING BACK A SOUND.Y
Foreground and background
CALL ($6c8d) tells the Series 3a to send a "machine switch on" event to the current program, whenever the Series 3a switches on, even if this program is in the background. If required, use it just once at the start of your program.C
CALL($198d,0,0) brings the current program to the foreground.9
CALL($198d,100,0) sends it to the background again.SEach of these should be followed by gUPDATE to ensure they take effect immediately.
Note: when a program runs in the background it can stop the "automatic turn off" feature from working. However, as soon as the program waits for a keypress or an event, with GET/GET$ or GETEVENT, auto-turn off can occur.
Auto-turn off can also occur if the program does a PAUSE (of 2 or more 20ths of a second), but only if the program has used CALL($138b) ("unmark as active")
"Serial/parallel ports and printing
LOPEN opens a serial port, parallel port or file, and LPRINT then sends text to it. (You can't access the advanced page formatting and font features from OPL.)
LOPEN "TTY:A" opens the serial port with these default characteristics: 9600 baud, no parity, 8 data bits, 1 stop bit, RTS handshaking. (Note: printers often use DSR (DSR/DTR) handshaking.)+Set up the serial port with this procedure:2PROC rsset:(baud%,parity%,data%,stop%,hand%,term&)#LOCAL frame%,srchar%(6),dummy%,err%
frame%=data%-5&IF stop%=2 :frame%=frame% OR 16 :ENDIF&IF parity% :frame%=frame% OR 32 :ENDIF
srchar%(1)=baud% OR (baud%*256)"srchar%(2)=frame% OR (parity%*256)#srchar%(3)=(hand% AND 255) OR $1100
!To READ from the serial port use:MIOW(-1,1,buffer,maxlen). (The -1 tells I/O keywords to use the LOPEN handle.)
The read terminates only after reading exactly maxlen bytes, UNLESS you specifying a terminating mask (term&) when setting up the port with rsset:.
The 32 bits of term& each represent an ASCII character from 1 to 31 which should terminate the read, after it is read into the buffer. For example, to terminate on Control-Z or [CR], set bits 26 and 13 - &04002000 in hex - as in:
rsset:(11,0,8,1,0,&04002000)'You can then read up to 255 bytes with: len%=255( ret%=IOW(-1,1,#UADD(ADDR(buf$),1),len%)Elen% is then the length actually read, including any terminator char.
OPAs and the System screen
To make an OPA, your OPL file should begin with the APP/ENDA construction. Between APP and ENDA you may use any or all of the OPA keywords PATH, EXT, ICON and TYPE.ZA translated OPA is saved in a \APP directory, and the "Install" menu option will list it.
(If you previously translated the module without the APP...ENDA at the start, the old translated version will still be listed under the RunOpl icon, and should be deleted.)
Once installed, file-based OPAs are shown with the list of available files, if any are found. Otherwise, the name given with the APP keyword appears below the icon.
When a file-based OPA starts running it should first call CMD$(2), for the full name of the file to use, then CMD$(3), which returns "C" for "Create" or "O" for "Open".
All file-based OPAs (types 1 to 4) should create or open the file as specified; if a "Create" fails because the file exists already, or an "Open" fails because it does not, OPL raises the error, and the OPA should take suitable action.
When the System screen wants an OPA to exit or to switch files (eg when you press Delete to stop a running OPA, or select a new file for a type 2 or 3 OPA), it tells the OPA via an event.
If TESTEVENT returns non-zero, an event has occurred, and can be read with GETEVENT. All types of OPA MUST use these keywords to check both for keypresses and for events.
If the event is a System message to change files or quit, a%(1)=$404. Use GETCMD$ as soon as possible. It returns a string, whose first character is "C", "O" or "X". (If it is "C" or "O", the rest of the string is a filename.)
You should close the current file (if any) and then either create the new file ("C"), open it ("O"), or exit. You can only call GETCMD$ once for each event.
If an OPA lets you change files with its own `Open file' option, it should always use SETNAME to inform the System screen of the new filename.
Whenever creating a file, an OPA should first use PARSE$ to find the disk and directory requested. It should then use TRAP MKDIR to ensure that the directory exists.
Note: events are ignored while you are using keywords which pause the execution of the program - GET, GET$, EDIT, INPUT, PAUSE, MENU and DIALOG. Use LOCK ON / LOCK OFF around these keywords to prevent the System screen from sending messages.5
Calling procedures by strings
Procedures can be called using a string expression for the procedure name. Use an @, optionally followed by a character to show what type of value is returned - for example, % for an integer. Follow this with the string expression in brackets.+You can use upper or lower case characters.HHere are examples showing the four types of value which can be returned:'i% = @%(name$):(parameters) for integer,l& = @&(name$):(parameters) for long integer&s$ = @$(name$):(parameters) for string,f = @(name$):(parameters) for floating-point
Data files
When you change or delete records in a data file on `Internal' or on a RAM SSD, the space used by the old information is recovered when you close the file.+To prevent this data file compression, use:
p%=PEEKW($1c)+$1e
POKEW p%,PEEKW(p%) or 1
You could then use the COMPRESS keyword to compress the file later. (To compress a data file on Flash, you have to use COMPRESS.
To re-enable the compression:
p%=PEEKW($1c)+$1e
POKEW p%,PEEKW(p%) and $fffe
?You can open a data file made by the Database application - eg:& OPEN "\dat\data.dbf",A,a$,b$,c$,d$...
You can use up to 32 field variables, all strings. Any further fields in a record are inaccessible, and cannot be changed by OPL.Z
If a record is longer than 255 characters it appears as more than one record to OPL.Y
If a record is longer than 1022 characters a `Record too large' error (-43) occurs.8The Database application can open an OPL data file - eg:
\opd\example.odb%as long as it only has string fields.
The text and graphics windows
?The text window is in fact part of the default graphics window.
The FONT keyword first sets the default graphics window as large as possible (excluding any status window), then resizes the text window to be as many whole character widths/heights as possible inside it.
You shouldn't normally mix text and graphics windows. If you need to - for example to use keywords like EDIT in a graphical program - use one of these methods:K
Use SCREEN to put the text window out of the way of graphics windows.
Use gSETWIN and gORDER 1 to set the default graphics window at a suitable size and position, then SCREEN to place the text window inside it.<
Error messages
^These are the numbers of the errors which OPL can raise, and the message associated with them:
-1 General failure
-2 Invalid arguments
-3 O/S error
-4 Service not supported
-5 Underflow (number too small)
-6 Overflow (number too large)
-7 Out of range
-8 Divide by zero8-9 In use (eg serial port being used by another program)
-10 No system memory)-13 Process table full/Too many processes
-14 Resource already open
-15 Resource not open
-16 Invalid image/device file
-17 No receiver
-18 Device table full8-19 File system not found (eg if you unplug cable to PC)
-20 Failed to start
-21 Font not loaded
-22 Too wide (dialogs)
-23 Too many items (dialogs)'-24 Batteries too low for digital audio'-25 Batteries too low to write to Flash
File and device errors
-32 File already exists
-33 File does not exist
-34 Write failed
-35 Read failed7-36 End of file (when you try to read past end of file)
-37 Disk full
-38 Invalid name0-39 Access denied (eg to a protected file on PC)
-55 Incorrect parity8-56 Serial frame (usually because Baud setting is wrong)9-57 Serial overrun (usually because Handshaking is wrong)"-58 Cannot connect to remote modem
-59 Remote modem busy
-60 No answer from remote modeml-61 Number is black listed (you may try a number only a certain number of times; wait a while and try again)
-62 Not ready
-63 Unknown media (corrupt SSD)j-64 Root directory full (on any device, the root directory has a maximum amount of memory allocated to it)
-65 Write protected
-66 Media is corrupt
-67 User abandoned
-68 Erase pack failure
-69 Wrong file type
Translator errors
-70 Missing "
-71 String too long
-72 Unexpected name
-73 Name too long
-74 Logical device must be A-D
-75 Bad field name
-76 Bad number
-77 Syntax error
-78 Illegal character
-79 Function argument error
-80 Type mismatch
-81 Missing label
-82 Duplicate name
-83 Declaration error
-84 Bad array size
-85 Structure fault
-86 Missing endp
-87 Syntax Error
-88 Mismatched ( or )
-89 Bad field list
-90 Too complex
-91 Missing ,
-92 Variables too large
-93 Bad assignment
-94 Bad array index$-95 Inconsistent procedure arguments
OPL specific errors5-96 Illegal Opcode (corrupt module - translate again)J-97 Wrong number of arguments (to a function or parameters to a procedure)T-98 Undefined externals (a variable has been encountered which hasn't been declared)
-99 Procedure not found
-100 Field not found
-101 File already open
-102 File not open?-103 Record too big (data file contains record too big for OPL)1-104 Module already loaded (when trying to LOADM)2-105 Maximum modules loaded (when trying to LOADM)1-106 Module does not exist (when trying to LOADM)C-107 Incompatible translator version (OPL file needs retranslation)/-108 Module not loaded (when trying to UNLOADM)6-109 Bad file type (data file header wrong or corrupt)5-110 Type violation (passing wrong type to parameter)9-111 Subscript or dimension error (out of range in array)
-112 String too long/-113 Device already open (when trying to LOPEN)
-114 Escape key pressed!-115 Incompatible runtime version
-116 ODB file(s) not closedF-117 Maximum drawables open (maximum 8 windows and/or bitmaps allowed)
-118 Drawable not open<-119 Invalid Window (window operation attempted on a bitmap)4-120 Screen access denied (when run from Calculator)
File extensions and directories
EFiles are saved in these directories, and with these file extensions:
File type Dir. Ext.
Database \DAT .DBF
Agenda \AGN .AGN
World \WLD .WLD
Spreadsheet \SPR .SPR
Word \WRD .WRD
Printer drivers \WDR .WDR
Word templates \WDR .WRT
Sound files \WVE .WVE
OPL modules \OPL .OPL
Translated modules \OPO .OPO
Other OPL files \OPD .ODB&Programs/OPAs \APP,\IMG .APP,.IMG,.OPA
Groups/lists \APP .ALS,.GRP
Hexadecimals
To enter integer hexadecimal constants (16 bit) put a $ in front of them. For example $FF is 255 in decimal. (Don't confuse this use of $ with string variable names.)xTo enter long integer hexadecimal constants (32 bit) put a & in front of them. For example &FFFFF is 1048575 in decimal.
All hexadecimal constants are integers ($) or long integers (&). So arithmetic operations involving hexadecimal numbers behave in the usual way. For example, &3/&2 returns 1, &3/2.0 returns 1.5, 3/$2 returns 1.
Operators and expressions
ARITHMETIC OPERATORS:
+ add
- subtract
* multiply / divide
** raise to a power$- unary minus (in negative numbers) % percent
COMPARISON OPERATORS:
> greater than
>= greater than or equal to
< less than
<= less than or equal to
= equal to
<> not equal to
LOGICAL AND BITWISE OPERATORS:
NOTuWhen used with floating-point numbers they are logical operators; when used with integers they are bitwise operators.dA quick way of calculating NOT for integers is to add 1 to the original number and reverse its sign.
THE % OPERATOR:"60+5% 60 plus 5% of 60. Result: 63#60-5% 60 minus 5% of 60. Result: 57
60*5% 5% of 60. Result: 3,60/5% what number is 60 5% of. Result: 1200.B105>5% what number, when increased by 5%, becomes 105. Result: 1003105<5% how much of 105 was a 5% increase. Result: 5
PRECEDENCE OF OPERATORS:
Highest: **
- (unary minus) NOT
* /
+ -
= > < <> >= <=
Lowest: AND OR
In an expression where all operators have equal precedence, they are evaluated from left to right (with the exception of powers). You can always change precedence with brackets.
If you mix floating-point and integer values in expressions, OPL uses the simplest arithmetic possible for each part of the calculation, then finally converts the evaluted result to the same type as the variable to which it is assigned.
If you assign a floating-point value to an integer variable, the value is converted to an integer, always rounded towards zero.8
Character set and key codes
[dec] [hex] [char]
32 20 33 21 ! 34 22 " 35 23 #
36 24 $ 37 25 % 38 26 & 39 27 '
40 28 ( 41 29 ) 42 2A * 43 2B +
44 2C , 45 2D - 46 2E . 47 2F /
48 30 0 49 31 1 50 32 2 51 33 3
52 34 4 53 35 5 54 36 6 55 37 7
56 38 8 57 39 9 58 3A : 59 3B ;
60 3C < 61 3D = 62 3E > 63 3F ?
64 40 @ 65 41 A 66 42 B 67 43 C
68 44 D 69 45 E 70 46 F 71 47 G
72 48 H 73 49 I 74 4A J 75 4B K
76 4C L 77 4D M 78 4E N 79 4F O
80 50 P 81 51 Q 82 52 R 83 53 S
84 54 T 85 55 U 86 56 V 87 57 W
88 58 X 89 59 Y 90 5A Z 91 5B [
92 5C \ 93 5D ] 94 5E ^ 95 5F _
96 60 ` 97 61 a 98 62 b 99 63 c#100 64 d 101 65 e 102 66 f 103 67 g#104 68 h 105 69 i 106 6A j 107 6B k#108 6C l 109 6D m 110 6E n 111 6F o#112 70 p 113 71 q 114 72 r 115 73 s#116 74 t 117 75 u 118 76 v 119 77 w#120 78 x 121 79 y 122 7A z 123 7B {#124 7C | 125 7D } 126 7E ~ 127 7F
#128 80
129 81
130 82
131 83
#132 84
133 85
134 86
135 87
#136 88
137 89
138 8A
139 8B
#140 8C
141 8D
142 8E
143 8F
#144 90
145 91
146 92
147 93
#148 94
149 95
150 96
151 97
#152 98
153 99
154 9A
155 9B
#156 9C
157 9D
158 9E
159 9F
#160 A0
161 A1
162 A2
163 A3
#164 A4
165 A5
166 A6
167 A7
#168 A8
169 A9
170 AA
171 AB
#172 AC
173 AD
174 AE
175 AF
#176 B0
177 B1
178 B2
179 B3
#180 B4
181 B5
182 B6
183 B7
#184 B8
185 B9
186 BA
187 BB
#188 BC
189 BD
190 BE
191 BF
#192 C0
193 C1
194 C2
195 C3
#196 C4
197 C5
198 C6
199 C7
#200 C8
201 C9
202 CA
203 CB
#204 CC
205 CD
206 CE
207 CF
#208 D0
209 D1
210 D2
211 D3
#212 D4
213 D5
214 D6
215 D7
#216 D8
217 D9
218 DA
219 DB
#220 DC
221 DD
222 DE
223 DF
#224 E0
225 E1
226 E2
227 E3
#228 E4
229 E5
230 E6
231 E7
#232 E8
233 E9
234 EA
235 EB
#236 EC
237 ED
238 EE
239 EF
#240 F0
241 F1
242 F2
243 F3
#244 F4
245 F5
246 F6
247 F7
#248 F8
249 F9
250 FA
251 FB
!252 FC
253 FD
254 FE
255 FF
Other characters:
0 - Carriage Return symbol
1 - three dots (ellipsis)
2 - Psion symbol
5 - phone
6 - padlock
14 - broken dash, 16/17/24/25 - fat left/right/up/down arrows? 18-23 - pairs of left/right rounded ends, in hollow/grey/black
26/27 - thin left/right arrows
28 - right-pointing triangle
29 - bell
30 - stubby up arrow
Any of the characters in the character set can be entered directly from the keyboard - hold down the Control key and type the 3-digit code, then release the Control key. (Add preceding zeros if necessary to make a code three digits long.)
The GET and KEY functions return the character code of the key that was pressed. Some of the keys are not in the character set. They return these numbers:
Esc 27 Tab 9
Delete 8 Enter 13
Up 256 Down 257
Right 258 Left 259
Pg Up 260 Pg Dn 261
Home 262 End 263
Menu 290 Help 291
Diamond 292]The Psion key adds 512 to the value of the key pressed. For example, Psion-a is 609 (512+97).
/These values can be used with PRINT and CHR$():
7 beep
8 backspace
9 tab
10 line feed
12 form feed (clear screen)-13 carriage return (cursor to left of window)
(.txt)