



B-Terp
The Brief Macro Interpreter
for Codewright


Copyright (c) 1993, Starbase Corporation.  All rights reserved.

Publication History
December, 1992  First Release
March, 1993     Minor changes


Trademarks
Starbase(r) is a registered trademark of Starbase Corporation.
Codewright(tm) is a trademark of Starbase Corporation.
Brief(r) is a registered trademark of Borland International.
Windows(tm) is a trademark of Microsoft Corporation.
Other product names are the trademarks of their respective holders.

Starbase Corporation
9615 SW Allen Blvd.
Beaverton, Oregon  97005
Phone:  (503) 641-6000
Fax:  (503) 641-6001
www.premia.com



Table of Contents

1.  Introduction    
    What is B-Terp? 
2.  B-Terp Installation 
    Requirements    
    Installing the Files    
    Using the INSTALL Program   
    Manual Installation 
    Changing Codewright's Configuration 
    Using Brief's Keymap    
    Using Codewright's Brief Emulation  
    Allowing Keymaps to Overlay 
    Completed Installation  
3.  Using B-Terp    
    BFLAGS Environment Variable 
    Calling Codewright Functions from Brief Macros  
    An Example  
4.  Errors  




1.  Introduction

Welcome to B-Terp for Codewright.  The B-Terp release consists of 
this manual and an installation disk.  Please ensure that you have 
received both in good condition.


What is B-Terp?

B-Terp reads compiled Brief macros, .CM files, much as Brief itself 
does.  Instead of executing the macros in Brief, however, B-Terp 
executes equivalent operations in Codewright.  B-Terp is not a stand-
alone executable.  It is a Dynamic Link Library, which must be loaded 
by Codewright in order to be useful.

If you are willing to modify your Brief macros in ways that render 
them less that 100% Brief compatible, you may modify your macros to 
call functions in Codewright.


2.  B-Terp Installation

There are three steps to installing B-Terp.  This chapter of the
B-Terp  manual describes these steps.  They are as follows:

*   Ensuring that your Codewright installation meets the 
requirements for running B-Terp,

*   Copying the files on the distribution disk to their intended 
locations,

*   Modifying Codewright's configuration, so that it will make 
use of the files installed.


Requirements

B-Terp works with versions of Brief macros, 3.1 and prior.  You must 
have macros that have been compiled with the Brief Macro Compiler 
that you want to run from within Codewright, in order to be able to 
make use of B-Terp.  You need not have the source code for these 
macros.  The macros may have been written in either of Brief's macro 
languages, CBrief or the original Lisp-like language.

B-Terp requires that Codewright V2.0gh or later be installed on your 
machine.  Earlier versions of Codewright do not contain special 
functions added to Codewright to support B-Terp.

If you are using a version of Codewright prior to V2.0, you will have 
to purchase an upgrade before you will be able use B-Terp.  To 
obtain an upgrade, contact Starbase's sales department at 1-800-547-
9902.


Installing the Files

There are only three files and a readme file, BTERP.TXT, that you 
need to install.  The files are not compressed.  
   
Simply copy the distribution files to the appropriate destinations as 
described in the table below:

File         Destination               Description
----------------------------------------------------------------
BTERP.DLL    Directory containing      The DLL that interprets 
             Codewright EXE's.         your compiled Brief macros.

CWSTART.CB   One of the directories    B-Terp's equivalent of 
             listed by the BPATH       STARTUP.CB.  You can customize 
             environment variable.     this macro file for use with 
                                       Codewright without affecting 
                                       the operation of Brief. It also
                                       contains key bindings which in 
                                       Brief are made internally.

CWSTART.CM   One of the directories    This is the compiled form of 
             listed by the BPATH       CWSTART.CB.
             environment variable.


Changing Codewright's Configuration

After installing the distribution files are into their appropriate 
directories, you are ready to modify Codewright's configuration file.
Typically, this file is named CWRIGHT.INI and is found in 
Codewright's home directory.  When you load this file into Codewright
for editing, you should see the following lines at or near the
beginning  of the file:

[DefaultKeymap]
DefaultKeymap=brief

This section of the configuration file defines which emulation or 
keymap is initially in effect.  This example assumes that you are
using  the Brief emulation.  You need not be using the Brief emulation
to be  able to use B-Terp, however.

Your next step in configuring Codewright to use B-Terp depends on 
which of three configurations you wish to use.  They are as follows:

1.  Use only the Brief key bindings defined in Brief Macros

2.  Use Codewright's Brief emulation in conjunction with other 
Brief Macros

3.  Use a Codewright emulation and the Brief key bindings, 
allowing either one to be overlaid by the other.


Using Brief's Keymap

If you select configuration 1, where you use only Brief key bindings 
defined in macros, modify your configuration file to look as follows:

[DefaultKeymap]
libpreload=bterp.dll  

In this configuration, the "DefaultKeymap" command has been 
replaced with a "LibPreload" command.  Note that if you select this 
configuration, you will have no keystroke commands defined for 
Selective Display mode, Hex mode, or several other features of 
Codewright not offered by Brief.

On the plus side, this arrangement means that commands executed 
through [F10] automatically will be run through B-Terp.


Using Codewright's Brief Emulation

If you select the second configuration option, in which you use 
Codewright's Brief emulation, modify your configuration file to appear 
as follows:

[DefaultKeymap]
DefaultKeymap=brief
libpreload=bterp.dll

B-Terp will detect that the Brief emulation has already been
installed and will not install Brief's default keymap.  This is
special treatment  for the Brief emulation.  Other emulations will be
overlaid by the  keystrokes in the Brief macros.

In this configuration, the [F10] key accesses the Codewright API,
rather  than providing direct access to B-Terp.


Allowing Keymaps to Overlay

The third configuration option allows either Codewright's emulation to 
overlay the Brief macro assignments or visa versa.  This most 
commonly takes a form such as shown in the example below:

[DefaultKeymap]
libpreload=bterp.dll
DefaultKeymap=brief

This example allows Codewright's Brief emulation to overlay the key 
assignments in the Brief macros.  This has the effect of supplementing 
Codewright's Brief emulation with any keystrokes not included in that 
emulation.  Another example follows:

[DefaultKeymap]
DefaultKeymap=cua
libpreload=bterp.dll

This example supplements the assignments in the Brief macros with 
CUA keystrokes.  This will have the benefit of adding keystrokes for 
Selective Display and Hex modes.

You may find other similar combinations useful.


Completed Installation

Brief relies on a semicolon separated list of directories, described
by  the environment variable BPATH, to find its macros.  B-Terp relies
on  this same environment variable to find its startup macro, 
CWSTART.CM.  When B-Terp has been properly installed and  configured,
this search will be successful, and B-Terp will be ready for  use.


3.  Using B-Terp

With B-Terp installed, you are executing Brief macros every time you 
press a key to which a Brief macro is assigned.  You will also want to 
execute Brief macros that have not been assigned to a key, and also 
execute Codewright API functions interactively.  How you do these 
things will depend largely on what configuration you have selected.
If B-Terp has a hold of your [F10] key, you can execute Brief macros
by pressing [F10] and responding as follows: 

Command: keys 

This example would execute Brief's keys() function. If a Codewright
keymap has control of [F10], you would instead press  the API Command
key and respond as follows: 

Command: bterp keys 

This example also executes Brief's keys() function, but the command
must be prefixed with the function name "bterp". The table below
indicates what to push and when, depending on when  the BTERP.DLL was
loaded, relative to any Codewright keymap:

Configuration        B-Terp access          API Access
---------------------------------------------------------------------
BTERP Alone          press [F10]            through Utility menu

After Brief keymap   press [F10],           Press [F10]
                     use "bterp" prefix.    

After other keymap   press [F10]            through Utility menu

Before any keymap    press API command key, Press API command key
                     use "bterp" prefix.


BFLAGS Environment Variable

Brief relies on the environment variable BFLAGS to store many of its 
command line options that do not normally change.  B-Terp supports a 
subset of these options.  The options supported are as follows:

-m<macro name>
Execute the macro named by <macro name> as part of startup.

-i<idle time>
Set the idle time interval, primarily used by auto-save.

-t 
Convert tabs to spaces.

-b 
Turn backup file creation on or off.

For a further description of these flags consult your Brief manual.
Calling Codewright Functions from Brief Macros

B-Terp adds a couple of functions to those available in the Brief
macro  language to enable you to call functions in a DLL from within
Brief  macros.  Here are those functions:

cwLibExport( string )
cwLibFunctionExec( string )
cwKmapAssignRange( int, int, string )

The functions above are direct calls to the Codewright functions 
LibExport, LibFunctionExec and KmapAssignRange functions, 
respectively.  The LibExport function describes a function to 
Codewright, so that it may allow it to be called interactively.  
LibFunctionExec executes a function call contained within a string.  
KmapAssignRange conveniently assigns a single function to a range 
of keys.

See the Codewright Programmer's Reference Manual for further 
details of these functions.


An Example

For the purpose of this example, let us imagine that you want to call
the function myDLLFunc from within a Brief macro.  This function is 
in a DLL and takes two parameters: an integer and a string pointer.
It  has a void return value.

The code depicted below is as it would be in a Brief .CB file.  It
would  need to be compiled with the Brief Macro Compiler before it
could be  used by B-Terp.


extern cwLibExport( string );
extern cwLibFunctionExec( string );


void myfunc( )
{
    // export the function for Codewright describing
    // its parameter types
    cwLibExport( "void myDLLFunc int LPSTR" );   

    // call the dll function with two parameters:
    // 1 and "any-string"
    cwLibFunctionExec( "myDLLFunc 1 'any-string'" );
}



4.  Errors

ERROR: unimplemented id type 0xXX

If you encounter this error, please record the id type value (i.e.
0xXX)  and the function/macro package which you were executing.  Then,
call  Starbase Technical Support to report the problem.  This will help
us to  add support for functions that are not yet supported.

B-Terp: Unknown file format: <filename>

The format of the .CM file that B-Terp is trying to interpret is not 
recognized by B-Terp. Try recompiling the macro without the -d 
compiler option.
