KEYWORDS

PSIONICS FILE - KEYWORDS
========================
More information about OPL keywords
Last modified 1998-11-09
===================================

This document consists of two parts. The first is a complete list of keywords,
and the second is a set of notes on various keywords, listing information not
given in the standard manual.

In general, a "standard" keyword is one found on both the 3t and the 3a, while
an "extra" keyword is only on the 3a.


List of keywords
================

There are two kinds of keywords: commands and functions. Within the OPL
translator, each keyword has from 1 to 6 bytes of associated data; this may
differ between the 3t and the 3a.

The tag "changed" after the associated data means that it differs between the
3t and the 3a; the 3a data is shown, and the 3t data is obtainable from it:
  commands:  subtract 3 from the first byte
  functions: change the last byte to 00
In addition, the second byte of the data for all functions (not just the
changed ones) is only present in the 3a (in both the native and compatibility
modes), not the 3t. Apart from this, the compatibility mode on the 3a uses the
same data as the 3t.


ABS             Fn  80 02 21
ACOS            Fn  81 02 21
ADDR            Fn  00 00 51
ADJUSTALLOC     Fn  4D 00 03 00        extra
ALERT           Fn  38 00 3D 33 33
ALLOC           Fn  4B 00 41           extra
APP             Cmd F3
APPEND          Cmd 03 9D
APPENDSPRITE    Cmd 7E 7F 07           extra
ASC             Fn  01 00 31
ASIN            Fn  82 02 21
AT              Cmd 04 1E
ATAN            Fn  83 02 21
BACK            Cmd 05 9F
BEEP            Cmd 06 20
BREAK           Cmd 07 3F
BUSY            Cmd 69 70              changed
CACHE           Cmd 77 FF 0E           extra
CACHEHDR        Cmd 79 7F 15           extra
CACHEREC        Cmd 7A 7F 16           extra
CACHETIDY       Cmd 78 7F 13           extra
CALL            Fn  02 00 0E 00 00 00
CHANGESPRITE    Cmd 80 7F 09           extra
CHR$            Fn  C0 03 01
CLOSE           Cmd 08 A1
CLOSESPRITE     Cmd 82 7F 0B           extra
CLS             Cmd 09 22
CMD$            Fn  D6 03 01
COMPRESS        Cmd 0A A3
CONTINUE        Cmd 0B 3F
COPY            Cmd 0C A4
COS             Fn  84 02 21
COUNT           Fn  03 00 00
CREATE          Cmd 0D A5
CREATESPRITE    Fn  3B 00 00           extra
CURSOR          Cmd 0E 26
DATETOSECS      Fn  45 01 06 00 00 00
DATIM$          Fn  C1 03 00
DAY             Fn  04 00 00
DAYNAME$        Fn  C2 03 01
DAYS            Fn  40 01 03 00
DBUTTONS        Cmd 64 6D              changed
DCHOICE         Cmd 5D 6D              changed
DDATE           Cmd 60 6D              changed
DEDIT           Cmd 61 6D              changed
DEFAULTWIN      Cmd 7C 7F 01           extra
DEG             Fn  85 02 21
DELETE          Cmd 0F A7
DFILE           Cmd 63 6D              changed
DFLOAT          Cmd 65 6D              changed
DIALOG          Fn  37 00 00
DIAMINIT        Cmd 70 7F 02           extra
DIAMPOS         Cmd 71 7F 03           extra
DINIT           Cmd 5B 6C              changed
DIR$            Fn  C3 03 31
DLONG           Cmd 5E 6D              changed
DO              Cmd 00 00
DOW             Fn  05 00 03 00
DPOSITION       Cmd 66 6D              changed
DRAWSPRITE      Cmd 7F 7F 08           extra
DTEXT           Cmd 5C 6D              changed
DTIME           Cmd 5F 6D              changed
DXINPUT         Cmd 62 6D              changed
EDIT            Cmd 2F C2
ELSE            Cmd FB
ELSEIF          Cmd FC
ENDA            Cmd EE
ENDIF           Cmd FA
ENDP            Cmd F7
ENDV            Cmd F4
ENDWH           Cmd FD
ENTERSEND       Fn  49 00 0D A0 AA     extra
ENTERSEND0      Fn  4A 00 0D A0 AA     extra
EOF             Fn  06 00 00
ERASE           Cmd 10 A8
ERR             Fn  07 00 00
ERR$            Fn  C4 03 01
ESCAPE          Cmd 11 29
EVAL            Fn  99 02 31
EXIST           Fn  08 00 31
EXP             Fn  86 02 21
EXT             Cmd F1
FIND            Fn  09 00 31
FINDFIELD       Fn  54 00 34 00 00     extra
FINDLIB         Fn  3E 00 62 03        extra
FIRST           Cmd 12 AA
FIX$            Fn  C5 03 23 00
FLT             Fn  87 02 11
FONT            Cmd 72 7F 04           extra
FREEALLOC       Cmd 74 7F 0C           extra
GAT             Cmd 40 52
GBORDER         Cmd 54 74
GBOX            Cmd 45 5B
GBUTTON         Cmd 56 7F 0F           extra
GCLOCK          Cmd 55 75
GCLOSE          Cmd 34 C6
GCLS            Cmd 3F 51
GCOPY           Cmd 49 E1
GCREATE         Fn  26 00 05 00 50     changed
GCREATEBIT      Fn  27 00 02 00
GDRAWOBJECT     Cmd 58 7F 11           extra
GEN$            Fn  C6 03 22 00
GET             Fn  0A 00 00
GET$            Fn  C7 03 00
GETCMD$         Fn  D5 03 00
GETEVENT        Cmd 4E 64
GETLIBH         Fn  3F 00 01           extra
GFILL           Cmd 47 5F
GFONT           Cmd 38 CA
GGMODE          Cmd 3A 4C
GGREY           Cmd 7B 7F 00           extra
GHEIGHT         Fn  2F 00 00
GIDENTITY       Fn  2B 00 00
GINFO           Cmd 3E 50
GINVERT         Cmd 52 72
GIPRINT         Cmd 6F 7C              changed
GLINEBY         Cmd 44 5A
GLINETO         Cmd 4C 65
GLOADBIT        Fn  28 00 3B 00
GLOADFONT       Fn  29 00 31
GLOBAL          Cmd F8
GMOVE           Cmd 41 53
GORDER          Cmd 3D 4F
GORIGINX        Fn  30 00 00
GORIGINY        Fn  31 00 00
GOTO            Cmd 13 3F
GPATT           Cmd 48 E0
GPEEKLINE       Cmd 4D 66
GPOLY           Cmd 46 5E
GPRINT          Cmd 42 54
GPRINTB         Cmd 43 59
GPRINTCLIP      Fn  33 00 32 00
GRANK           Fn  2A 00 00
GSAVEBIT        Cmd 33 C5
GSCROLL         Cmd 4A 62
GSETWIN         Cmd 36 48
GSTYLE          Cmd 3C 4E
GTMODE          Cmd 3B 4D
GTWIDTH         Fn  32 00 31
GUNLOADFONT     Cmd 39 CB
GUPDATE         Cmd 4B 63
GUSE            Cmd 35 C7
GVISIBLE        Cmd 37 49
GWIDTH          Fn  2E 00 00
GX              Fn  2C 00 00
GXBORDER        Cmd 57 7F 10           extra
GXPRINT         Cmd 53 73
GY              Fn  2D 00 00
HEX$            Fn  C8 03 11
HOUR            Fn  12 00 00
IABS            Fn  41 01 11
ICON            Cmd F0
IF              Cmd 02 00
INPUT           Cmd 14 94
INT             Fn  42 01 21
INTF            Fn  88 02 21
IOA             Fn  0B 00 05 60 AA
IOC             Fn  4F 00 0D A0 AA     extra
IOCANCEL        Fn  52 00 01           extra
IOCLOSE         Fn  10 00 01
IOOPEN          Fn  0D 00 63 05
IOREAD          Fn  0F 00 03 04
IOSEEK          Fn  21 00 03 70
IOSIGNAL        Cmd 32 37
IOW             Fn  0C 00 04 A0 0A
IOWAIT          Fn  11 00 00
IOWAITSTAT      Cmd 50 68
IOWRITE         Fn  0E 00 03 04
IOYIELD         Cmd 51 69
KEY             Fn  13 00 00
KEY$            Fn  C9 03 00
KEYA            Fn  23 00 62 06
KEYC            Fn  24 00 61
KMOD            Fn  22 00 00
LAST            Cmd 15 AC
LCLOSE          Cmd 16 AD
LEFT$           Fn  CA 03 32 00
LEN             Fn  14 00 31
LENALLOC        Fn  4E 00 01           extra
LINKLIB         Cmd 75 7F 0D           extra
LN              Fn  89 02 21
LOADLIB         Fn  3C 00 63 03        extra
LOADM           Cmd 17 AE
LOC             Fn  15 00 32 03
LOCAL           Cmd F9
LOCK            Cmd 6A 71              changed
LOG             Fn  8A 02 21
LOPEN           Cmd 18 AF
LOWER$          Fn  CB 03 31
LPRINT          Cmd 19 0C
MAX             Fn  93 02 08
MCARD           Cmd 5A 6B              changed
MEAN            Fn  94 02 08
MENU            Fn  36 00 59           changed
MID$            Fn  CC 03 33 00
MIN             Fn  95 02 08
MINIT           Cmd 59 6A              changed
MINUTE          Fn  16 00 00
MKDIR           Cmd 6B F8              changed
MONTH           Fn  17 00 00
MONTH$          Fn  CD 03 01
NEWOBJ          Fn  46 00 02 00        extra
NEWOBJH         Fn  47 00 02 00        extra
NEXT            Cmd 1A B0
NUM$            Fn  CE 03 22 00
ODBINFO         Cmd 76 7F 12           extra
OFF             Cmd 1B 32
ON              Cmd F5
ONERR           Cmd 1C 31
OPEN            Cmd 1D B4
OPENR           Cmd 31 C4
OS              Fn  35 00 0B 00
PARSE$          Fn  D7 03 33 63
PATH            Cmd F2
PAUSE           Cmd 1E 35
PEEK$           Fn  CF 03 41
PEEKB           Fn  18 00 41
PEEKF           Fn  8B 02 41
PEEKL           Fn  43 01 41
PEEKW           Fn  19 00 41
PI              Fn  8C 02 00
POKE$           Cmd 23 1B
POKEB           Cmd 1F 1C
POKEF           Cmd 22 1A
POKEL           Cmd 21 19
POKEW           Cmd 20 18
POS             Fn  1A 00 00
POSITION        Cmd 24 B6
POSSPRITE       Cmd 81 7F 0A           extra
PRINT           Cmd 25 08
PROC            Cmd F6
RAD             Fn  8D 02 21
RAISE           Cmd 26 38
RANDOMIZE       Cmd 27 39
REALLOC         Fn  4C 00 02 04        extra
RECSIZE         Fn  1B 00 00
REM             Cmd FF
RENAME          Cmd 28 BA
REPT$           Fn  D0 03 32 00
RETURN          Cmd 29 40
RIGHT$          Fn  D1 03 32 00
RMDIR           Cmd 6C F9              changed
RND             Fn  8E 02 00
SCI$            Fn  D2 03 23 00
SCREEN          Cmd 30 43
SCREENINFO      Cmd 83 7F 14           extra
SECOND          Fn  1C 00 00
SECSTODATE      Cmd 6E 7B              changed
SEND            Fn  48 00 0D A0 AA     extra
SETNAME         Cmd 67 6E              changed
SETPATH         Cmd 6D 7A              changed
SIN             Fn  8F 02 21
SPACE           Fn  44 01 00
SQR             Fn  90 02 21
STATUSWIN       Cmd 68 6F              changed
STATWININFO     Fn  53 00 02 06        extra
STD             Fn  96 02 08
STOP            Cmd 2A 3B
STYLE           Cmd 73 7F 05           extra
SUM             Fn  97 02 08
TAN             Fn  91 02 21
TESTEVENT       Fn  34 00 00
TRAP            Cmd 2B 3C
TYPE            Cmd EF
UADD            Fn  50 00 42 00        extra
UNLOADLIB       Fn  3D 00 01           extra
UNLOADM         Cmd 2E C1
UNTIL           Cmd FE
UPDATE          Cmd 2C BD
UPPER$          Fn  D3 03 31
USE             Cmd 2D BE
USESPRITE       Cmd 7D 7F 06           extra
USR             Fn  1D 00 45 44 44
USR$            Fn  D4 03 45 44 44
USUB            Fn  51 00 42 00        extra
VAL             Fn  92 02 31
VAR             Fn  98 02 08
VECTOR          Cmd 4F 2B
WEEK            Fn  20 00 03 00
WHILE           Cmd 01 00
YEAR            Fn  1E 00 00


Commands
--------
All extra commands have 3 bytes of data, while all standard commands have 1
or 2 bytes.

The first byte of data is unique to each command. Commands with 2 or 3 bytes
have values from $00 to $83 inclusive, while those with 1 byte have values
from $EE to $FF inclusive; in neither case is there a gap. The extra commands
fall into two blocks: three are inserted in the middle of the sequence (and
so all commands with higher first bytes are different between the 3t and 3a),
while the remainder occur after the last standard command.

The commands with only 1 byte are:
    APP             ENDV            ON
    ELSE            ENDWH           PATH
    ELSEIF          EXT             PROC
    ENDA            GLOBAL          REM
    ENDIF           ICON            TYPE
    ENDP            LOCAL           UNTIL
none of which directly correspond to Q-code.

With a few exceptions, the second byte of the data is the Q-code opcode of
that keyword, except that the top bit of the opcode is always set while
that of the data byte may be either clear or set (there is no obvious
meaning to the bit); thus opcode $AB might be represented as $2B or $AB.
If there is a third byte, this is the second byte of the opcode. If the
keyword maps to more than one opcode, the opcode represented is the lowest.

The exceptions are the following:
  $00   DO            IF            WHILE
  $3F   BREAK         CONTINUE      GOTO     ($BF is the opcode for GOTO)

All dialog commands other than DINIT share the second byte $6D; the second
byte of the opcode is not represented here.


Functions
---------
The associated data varies from 3 to 6 bytes (2 to 5 bytes on the 3t).

The first data byte is the second byte of the Q-code opcode. Integral valued
functions have values from $00 to $54, real valued functions from $80 to $99,
and string valued functions values from $C0 to $D7. There are 4 codes that
do not appear ($1F, $25, $39, $3A); these correspond to alternate versions
of the keyword.

The second byte (3a only) gives the type of the function:
  0 = word
  1 = long
  2 = real
  3 = string

The remaining bytes describe the arguments to the function. Each byte is
divided into two nibbles, with the least significant being processed first.
The first nibble (N) indicates the number of arguments:
   0 to  7: exactly N arguments, described by the next N nibbles
   8:       either a list or reals, or a real array followed by an integer
   9:       1 optional argument, described by the next nibble
  10 to 15: between 1 and N-8 arguments, described by the next N-8 nibbles

The remaining nibbles each describe one argument, in order:
   0 = word value (signed)
   1 = long value
   2 = real value
   3 = string value
   4 = word value (unsigned)
   5 = special case (meaning varies)
   6 = word variable
   7 = long variable
  10 = any variable


Notes on keywords
=================

FINDFIELD
---------
The manual description of flags% is wrong; it should be:
    0 = backwards starting at current record
    1 = forwards  starting at current record
    2 = backwards starting at end of file
    3 = forwards  starting at record 0
plus:
    0 = case independent
   16 = case dependent
(in other words, the bold text should be attached to the first bullet item,
not the second).

In all releases up to 3.22F, the keyword will actually do a FIND unless a
certain byte in memory is zero. To ensure this, each use of FINDFIELD should
be immediately preceeded by:
    POKEB PEEKW(28)+7,0

It is reported that the start% and no% parameters only count string fields
in the records; that is, if a record contains other types of field, these
are ignored when doing the searching. This is consistent with the underlying
system call.

If a backwards search fails to find a record, the keyword returns 1 rather
than 0 as it should. The pointer is left at record 1 but the field variables
are all zero or empty strings. If this happens, the instructions:
    CALL($03D8,PEEKW(ODB%))
    BACK
must be done before record 1 can be accessed, where ODB% is the appropriate
element of an array initialized with ODBINFO.

GBORDER
-------
It is reported that the $400 flag of GXBORDER also works with this call.

GFILL
-----
It is reported that this can't cope with negative parameters.

GPATT
-----
It is reported that this can't cope with negative parameters.

LOADM
-----
It is reported that the 3c behaves differently from the 3a when dealing
with calls from one module to another. One specific case mentioned is
that such calls lose track of which data file is current, so that USE must
be used to reselect the correct file.

ON
--
This keyword is not documented. @I don't know what it does.

USE
---
See LOADM.