Black Box 4/BlackBox.cdr/bbs_opus/oac121.arj/OACOMP.DOC

Text File | 1990-12-26 | 11KB | 218 lines

                      Documentation for Opus/Avatar COMPiler

The Opus/Avatar COMPiler is an OECC clone, with some new features, primarily
the ones regarding the new codes in OPUS 1.1x (see the OACOMP.KWD for a
complete description of all the internally supported keywords). There are,
however, some minor differences existing between Opus/Avatar COMPiler and the
Opus Embedded Command Compiler (OECC):

  Opus/Avatar COMPiler does not support tokens split between two or more
lines. OECC does. One exception is the [COMMENT] token, which MAY be split
over several lines, but Opus/Avatar COMPiler may treat them differently than
OECC does.

  Opus/Avatar COMPiler supports externally defined tokens (see below). OECC
doesn't.

  Opus/Avatar COMPiler supports wild cards, default file types, date compa-
risons before compilation, sub directories, ARChive attribute and compiling
files after a certain date. OECC doesn't. Generally, you should just enter
your directory with .OEC files and type OACOMP, then the Opus/Avatar COMPiler
will compile all .OEC files that have a newer time stamp than the
corresponding .BBS file, or if the corresponding .BBS file doesn't exist.

Otherwise Opus/Avatar COMPiler should be fully OECC 1.06 compatible, including
LABELs, GOTOs etc. Opus/Avatar COMPiler, however, treats LABELs and GOTOs in
a slightly different manner than OECC. In OECC you would define a GOTO as

                              [GOTO][TARGET]

whereas in Opus/Avatar COMPiler you should use [GOTO TARGET]. This is because
Opus/Avatar COMPiler flags all unknown tokens as errors, and OECC flags them
as labels. Opus/Avatar COMPiler will work both ways, but the recommended form
is [GOTO TARGET]. This also allows you to have labels the same name as tokens.
If Opus/Avatar COMPiler encounters an unknown token, it will write a warning
to the screen and reserve 5 bytes for the offset of a label. In case that it
is NOT a label, these will then be filled out with zeros, just as OECC does
with unknown tokens, but you will then be warned. The recommended method of
obtaining the 4 byte binary offset of a label is with the [ADDR lbl] token,
and the 5 byte decimal offset of a label with the [OFS lbl].


Also, in OECC you would define a label as

                                 [/TARGET]

whereas in Opus/Avatar COMPiler you should use [LABEL TARGET]. Opus/Avatar
COMPiler recognizes both forms, however.

------------------------------------------------------------------------------

                        Various practical information

Labels has a maximum length of 200 characters and is not case-sensitive.
Lines in the .OEC file may be a maximum of 255 characters long. (You can't
  be serious about having lines longer than this?). If you have .OEC files
  with lines longer than that, you can use the /LONG switch.
Externally defined token names has a maximum length of 20 characters.
Opus/Avatar COMPiler requires DOS 3.10 or higher and should be able to run
  on all MS-DOS machines. It uses no IBM specific calls, only DOS.
Opus/Avatar COMPiler supports the CMDLINE environment string as used in 4DOS
  and will thus work with command lines up to 255 characters in length.
  (A hint to users of 4DOS: "SET .BBS=C:\OPUSUTIL\OAVIEW.EXE" will make it
   a lot easier to view files)

------------------------------------------------------------------------------

                        Setting up standard switches

You may set up an environment string OACOMP (or whatever you may rename the
.EXE file to) containing all your standard switches. F.ex. if you never use
multi-line comments, you can

                             SET OACOMP=/C-

to speed up things quite a bit. If you then have a single file with multi-
line comments, all you have to do is specify /C+ on the command tail to turn
on multi-line comment processing for that invokation of Opus/Avatar COMPiler.

The programs OAVIEW and OADECOMP have similar environment strings.

------------------------------------------------------------------------------

                 Privilege codes

If you have problems remembering the OECC tokens used for controlling output
based on privileges, the Opus/Avatar COMPiler is for you. Incorporating many
new ways of defining the same with, you should now be able to get on with the
programming and forget if @BELOW is below-or-equal-see or below-don't-see etc.

Some examples of the privilige control tokens in Opus/Avatar COMPiler.

[Cls]
[EQ Sysop      SEE]Your current privilege level is........... [yellow]SysOp[lightcyan]
[EQ AsstSysop  SEE]Your current privilege level is........... [yellow]Assistant SysOp[lightcyan]
[EQ Clerk      SEE]Your current privilege level is........... [yellow]Clerk[lightcyan]
[EQ Extra      SEE]Your current privilege level is........... [yellow]Extra[lightcyan]
[EQ Favored    SEE]Your current privilege level is........... [yellow]Favored[lightcyan]
[EQ Privileged SEE]Your current privilege level is........... [yellow]Privileged[lightcyan]
[EQ Worthy     SEE]Your current privilege level is........... [yellow]Worthy[lightcyan]
[EQ Normal     SEE]Your current privilege level is........... [yellow]Normal[lightcyan]
[EQ Limited    SEE]Your current privilege level is........... [yellow]Limited[lightcyan]
[EQ Disgrace   SEE]Your current privilege level is........... [yellow]Disgrace[lightcyan]
[EQ Twit       SEE]Your current privilege level is........... [yellow]Twit[lightcyan]
[LT AsstSysop  SEE]This is shown to all below AsstSysop
[GT AsstSysop  SEE]This is shown to all above AsstSysop
[BE AsstSysop  SEE]This is shown to all Below or Equal to AsstSysop
[AE AsstSysop  SEE]This is shown to all Above or Equal to AsstSysop
[EQ AsstSysop  SEE]This is shown to all with AsstSysop privilege
[NE AsstSysop  SEE]This is shown to all Non-AsstSysops
[GT AsstSysop SKIP]This is not shown to any above AsstSysop
[LT AsstSysop SKIP]This is not shown to any below AsstSysop
[EQ AsstSysop SKIP]This is not shown to AsstSysops
[NE AsstSysop SKIP]This is not shown to any Non-AsstSysops
Again [[y,N][Menu]YN
[Choice]Y[Top]

Try to compile this and then view it with the Opus/Avatar VIEW utility. When
the program asks you "Again [y,N]" you can press the ctrl key and the privi-
lege you want to be now, ie. ^A to be AsstSysop. Then answer Yes to the
prompt and see the effect.

------------------------------------------------------------------------------

                            Uppercase support

Opus/Avatar COMPiler has internal support for code pages and should uppercase
all code pages correctly. This means that you must have set your country code
and/or code page correctly to get proper functionality from the Opus/Avatar
COMPiler. Danish and Norwegian users, especially, will have to set the country
code correctly to be able to uppercase the special Danish/Norwegian character
¢ to ¥ (You foreigners may se a cent and Yen character there :-). No matter
what your country code says, it will always uppercase é to É even if DOS
doesn't define this as a standard uppercase method.

If you want to use another upper case table than the default one, you can
create a file UPPER.nnn in a directory pointed to by the environment string
XLATE (or any where in the PATH), where nnn is the code page you are using.
Users of DOS 3.2 or below have code page 865 (if country code is Danish (045)
or Norwegian (047)) or code page 437 if not one of these. The file must be 256
bytes long and must contain a one-to-one character lookup table for
uppercase'ing, ie. if you want ï (character 139) to be uppercased to I
(character 73), you must set the 140th character (file starts with character 0)
in the file to the value 73.

The INSFILTR program used in my FILTER package can be used to set up trans-
late tables.

------------------------------------------------------------------------------

                           User-Defined Tokens

In the Opus/Avatar COMPiler, you can define your own tokens. Just create
a file named OACOMP.TOK in the same directory as the OACOMP.EXE file. The
format of this file is:

                        <Token><WhiteSpace><Value>

where <Token> can be any word up to 20 characters in length, and <Value>
any string up to 200 characters in length. <WhiteSpace> is one or more
TABs or spaces. The <Value> is taken as beginning at the first non-white-
space after the <Token>. This means, that if you want your <Value> to start
with a whitespace, you must use the control character shortcuts, described
below. Starting with version 1.15, this value may now contain tokens (both
internal and external ones) and they will be compiled. Previous versions
only used it as text macros.

                   Setting control characters in <Value>

Opus/Avatar COMPiler recognizes the standard way with a ^ followed by a
letter (as in ^P), and to actually get a ^ in your <Value>, just type it
twice. Also, you may use the Turbo Pascal way of defining character codes
with the #<chr> construct, as in #13 (which is the same as ^M). To actually
get a # character just (you guessed it!) type it twice. The <chr> may be
expressed in hexadecimal notation by prefixing it with a $, as per the Turbo
Pascal standard.

                    Having local tokens for each file

By creating a file with the same name as an .OEC file, but with the extension
of .TOK instead, and placing it in the same directory as the .OEC file (or
in the same directory as the OACOMP.EXE file), you can have local tokens to
each and every .OEC file you have. The format is the same as the OACOMP.TOK
file, and tokens defined in the OACOMP.TOK file will be overridden by the
tokens defined in the *.TOK files. The order of search for the *.TOK file
is first in the directory of the .OEC file and then, if not found there, in
the directory of the OACOMP.EXE file.

                               Examples

SYSOP           Your Sysops
KRH             Keld "HeartWare" Hansen, Sysop 2:234/10
MIWO            Michael Wolthers, Sysop 2:234/10
CHEERS          Cheerio,#13#10  Keld "HeartWare" Hansen, Sysop 2:234/10
USER            #$20 Your name goes here... ##11
TwoTabs         #9^I
ThreeSpaces     #32 #$20
PUSH        [SAVE]
POP        [LOAD]

As you can see, the last two values start with a whitespace, and must thus
define the first character in another way.

.OEC file               .BBS file
[SYSOP]                 'Your Sysops'
[USER]                  '  Your name goes here... #11'
[ThreeSpaces]           '   '
[CHEERS]                'Cheerio,
                           Keld "HeartWare" Hansen, Sysop 2:234/10'

You may use upper and lower case letters in the token names, they're treated
the same by the Opus/Avatar COMPiler, ie. Opus/Avatar COMPiler will uppercase
all tokens before comparison. Read the section regarding uppercase support
for more information.

Hope this helps you get along.

[CHEERS]