Feedback Search Top Backward Forward

Customizing the Enhanced Editor

Written by Jörg Schwieder



If you talk with OS/2 developers, you will soon get the impression that most of them are desperately looking for a good programming editor even though OS/2 includes EPM, a very capable and flexible editor. One of the reasons for the bad reputation EPM seems to have may be its standard configuration which makes it resemble the system editor, OS/2's version of the Windows Notepad. Another reason may be that - though it is very flexible - it shares the problem of a lot of software that was 'born to use': that is it was written to be used not to be sold or that evolved from a line of more simple product improved over the time. Its user-interface clearly shows some of the author's preferences and remainders from former stages of development. For example, this means that EPM is almost completely incapable of using 'hard' tabs (which doesn't matter if you don't like them but if you're used to using such features it is quite a drawback).

So if you want to use EPM you may need to customize it. To do this you need the complete EPM toolkit available on various ftp sites such as It includes an updated (and reconfigured) version of EPM along with a better documentation and a compiler for the E macro language (ETPM). This article will cover custom configuration of your editor using this toolkit and - through examples - provide you with some nice additional features such as file autoloading and positioning and keyboard undo.

The EPM Programming Model

Programming EPM

There are two ways of programming EPM: using REXX and using the E macro language. Using REXX you may write EPM macros that don't need to be compiled and you don't have to learn the E macro language. This is quite powerful and lets you use most of EPM's features including custem menus, etc. and so it may be great for user macros but you cannot change the default configuration using REXX and since its interpreted and not compiled its quite slow so we will use the macro language here.

What is EPM?

EPM is not a "program" as such. The key element of the editor is the Enhanced Multi-Line Edit control (E-MLE) that is defined if the E-Toolkit (ETK) DLL's. It may also be used in custom programs (see the ETK documentation). Most of the basic functionality as well as macro language and REXX support are provided by the control. It can be used to edit multiple files in a "ring" which may be as large as system memory permits. EPM itself is just a small program that manages E-MLEs and the user interface (e.g. dialogs).

The Macro Language

Most of the features that make EPM were added using the E macro language and therefore may be rewritten or changed as well as used within other programs. For example, it would be possible to write applications using E-MLEs for their own editing purpose but incorporating the user's individual EPM setup. Given its capability to use the REXX language this makes for a great shot in the way of finding an individual standard user interface (a paradox within conventional application design).

Okay, let's get back to EPM. Macros that were written using the macro language (*.E) are compiled with the macro compiler ETPM and become ETPM modules (*.EX). An E-MLE has one main module (EPM.EX for EPM) which is executed upon creation and which contains startup and close-down code as well as basic functions and commands, menus, key-definitions etc. There may be additional modules that define external commands, they can be executed at runtime or linked into a running system meaning they're loaded permanently.

The macro language itself closely resembles REXX with some compiler specific differences especially regarding variable handling. See the EPM Technical Reference included in the complete EPM distribution.

Changing Your Configuration

The EPM main module is called EPM.E. (Well, in fact EPM.E currently does nothing else than including E.E which is the real main module but in the documentation the main module is said to be EPM.E so we call it that.) It includes the other EPM modules and is compiled to EPM.EX. Changes to the default configuration have to be recognized by EPM.E; usually this is done by changing a set of files that are included in EPM.E: MYCNF.E, MYKEYS.E, MYSTUFF.E, MYMAIN.E, MYSELECT.E and MYKEYSET.E.

MYCNF.E is a configuration file you should use to set configuration switches whereas the other ones are thought to include code. You may recompile your standard configuration by just recompiling EPM.E.

  • Changing the default configuration via MYCNF.E
  • Adding your own key definitions via MYKEYS.E
  • Your own commands and procedures via MYSTUFF.E
  • Editor startup code via MYMAIN.E
  • File initializations and focus changes via MYSELECT.E
You should use MYKEYSET.E to define a whole new keyset. This would be a little too much for this article so we won't cover it here.

Changing The Default Configuration via MYCNF.E

EPM's standard configuration is stored in a file calles STDCNF.E. Every definition primitive is given a default value here. You should not change this file since it may be changed with the next release of EPM and you had to rewrite all your changes. Instead you should write a file called MYCNF.E which is included before STDCNF.E andso settings you specify here override settings in STDCNF.E.

Configuration Constants

Configuration constants are constants so you can set them using the const statement:

        FOO = 'VALUE'
There are, well, quite a lot of configuration constants within EPM so we will cover only a subset which I think are the more important ones. See the EPM User's Manual for the complete set of constants. Along with the constants the default values are given:
Defines if support for alternate keysets is included. The default is to include it. Support for alternate keysets allows you to define user keysets and switch between them. It is needed for C, E, Pascal, or REXX syntax assist. If it is set to 0 these are not included. Also MYKEYSET.E would not be included.

Specifies the path where "autosave" files will be placed. The default value means that they're placed in the current directory. There is also an AUTOSAVE PATH setting in EPM's settings notebook. The path specified there overrides the setting in MYCNF.E

Specifies the path setting for backup files. Same as for AUTOSAVE_PATH but there is no setting in the notebook for this one and it has another option: '=' will place the backup file in the same directory as the saved one (and give it the extension '.BAK'). The backup directory must end with a backslash.

When used within the Workframe/2, EPM displays compiler errors. This constant is used to set the color used for the errors. Default is red on white. See Configuring Colors

Set this to 1 to include syntax assist for the C language. Syntax assist automatically expands specific keywords into the corresponding language constructions.

Specifies the default tab size for C files.

Use this setting to define the default behaviour of the paste key (Shift+Insert). '' always pastes as new lines, 'B' pastes as a block and 'C' pastes as a stream of characters.

In advanced marking mode on dragging the mouse a new block is only marked if there is no one currently marked. This can be helpful, e.g. if you want to set the cursor using the mouse and don't want the current mark to be deselected. It can be quite annoying if you're not used to it so you can set this switch to 1 to turn it off. DRAG_ALWAYS_MARKS has no effect in CUA-marking mode.

Set this one to 1 to be able to set the action performed by the Enter keys with EPMs settings notebook. Using the default value only lets you use configuration constants (ENTER_ACTION and C_ENTER_ACTION, see EPM Users Guide).

Set this to 1 to tell EPM to bring up the "Print" dialog when you specify the print command from the menu instead of just printing the file.

Specifies the environment variable used to store EPM's search path.

This must be set to 1. Code size for .EX-files is limited to 64K, which is too small for the standard configuration. If EXTRA_EX is set to one it is split into two files, EPM.EX and EXTRA.EX both of which are loaded on startup.

Enables syntax assist for the E language. See C_SYNTAX_ASSIST.

Sets the default tab setting for .E files. See C_TABS.

Sets the filename for the "Quick Help" file.

Sets the color that is used to draw these fancy circles around found search strings. There is no default so you have to specify it. See Configuring Colors

Specifies if support for IBM WorkFrame/2 is included in the configuration.

Sets the color used to mark marked marks in your file. See Configuring Colors

You can edit several files in one EPM window using the file ring. Usually these files can be accessed with the Ring menu command which brings up a dialog box containing the files that are currently being edited. Specifying any number greater than 0 (n) for this constant tells EPM to add n files to the Ring menu and bring up the dialog box only if there are more than n files in the ring. There is no limit for n but 120 makes no sense.

Sets the color used to display the message line or error messages. See Configuring Colors

Set default options for the edit command. These default options will be overridden by options specified on each specific edit command.

Same as MY_DEFAULT_EDIT_OPTIONS for the save command.

Another one, this time for search commands!

Set this to 1 to tell EPM to automatically compresses spaces to tabs when saving. This is the same as specifying '/t' for MY_DEFAULT_SAVE_OPTIONS.

Sets the language for National Language Support.

Includes Pascal syntax assist. See C_SYNTAX_ASSIST.

Sets the tab size for Pascal files. See C_TABS.

Includes REXX syntax assist. See C_SYNTAX_ASSIST.

Sets the tab size for REXX files. See C_TABS.

This option controls where the cursor is located after a change command. 0 means it is located on the last changed string, 1 means it stays where it was before the command and '?' defines a STAY command to change this behavior.

STATUS_TEMPLATE='Line %l of %s Column %c %i %m %f'
This is the status string used to configure the status line. The template can be up to 128 characters long and may contain characters and status tags. A status tag make EPM display certain status information. The following tags are defined:

    %A   Number of changes made since last autosave.
    %C   Current column number
    %F   Number of files in ring
    %I   Insert or replace state
    %L   Current line number
    %M   Modified status
    %S   Total number of lines in current file
    %X   Hexadecimal value of current character
    %Z   ASCII value of current character

Set this to 1 to add a 'View Technical Reference' command to the help menu.

Set this to 1 to add a 'View Users Guide' command to the help menu.

User Exits are procedures that are called by certain command, e.g. load and save. Setting SUPPORT_USER_EXITS to 1 enables this feature. See Your own commands and procedures via MYSTUFF.E

Specifies the number of spaces used for syntax indent when syntax assist is used.

Specifies the color used to display normal unmarked text in the edit window. See Configuring Colors

Set this to 1 to define the ESCAPEKEY command.

Set this to 1 to define the TABKEY command.

If set to 1 temporary files (which begin with a '.') will be quit without warning even if not saved. This may be useful (e.g. if you use the ALL command and don't want to be asked if you wanted to save the '.ALL' file upon exit).

Specifies the style of the cursor used in the editor. Default is a vertical bar in front of the actual character. Set to 1 changes it to a horizontal bar below the actual character.

Use this switch if you want marked text to be unmarked after a move operation. Default is that it is not.

Set this to 1 to make EPM search for files along DPATH if they can't be found in the current directory.

Set this to 1 to include the ALL command.

Specifies whether or not bookmark support is included. The default is that bookmark support is linked at runtime (or included in EXTRA.EX if this is used).

Set this to 0 to disable character marking mode support.

Set this to 1 to use the CUA marking style instead of the EPM block marking. A value of SWITCH adds a switch for this to the Preferences menu.

Includes the DRAW command. Default is to include it and define the 'F6' key for it. Other options are 1 and 0.

Includes dynamic prompt support. If it is included (default) there is a Prompting option in the Frame Controls menu. Prompting shows a description of the currently selected menu item in the message line.

Includes the ET command to issue ETPM from EPM.

If keyboard help is activated the CTRL-H key is redefined to issue a keyword help procedure that looks through the files specified in the HELPNDX environment variable for the keyword under the cursor. If it is found help for this keyword is given as specified in the .NDX-file, usually by invoking VIEW.EXE.

Includes support for long names. A value of SWITCH defines a Longnames command.

Includes support for a REXX profile. If profile support is included EPM looks for a file called PROFILE.ERX upon startup and executes it if found. A value of SWITCH defines the Profile command.

Includes a set of stack commands. The commands are PushPos, PopPos, SwapPos, PushMark, PopMark, SwapMark and can be used to create a stack to store cursor positions and marks. A value of SWITCH defines an entry in the Preferencs menu.

Set this to 1 to make EPM use a stream mode approach to file editing that is the edited file is seen as a continuing stream of characters. In the default mode a file is interpreted as a set of lines. A value of SWITCH enables you to switch between these modes at runtime using the Preferences menu.
See Example MYCNF.E

Configuring Colors

EPM includes the file COLORS.E which defines a set of color values to be used within EPM macros. The available constants are:

Foreground ColorsBackground Colors

These constants may be used to set the display color variables. Note that these constants may only be used if COLORS.E was included. This may not be the case for external commands that include MYCNF.E. Use the COMPILE IF statement to include them if the color constants are defined. Also note that the color variables are not constants and therefore should be define'd.

compile if defined(BLACK)
      MARKCOLOR       = BLUE + GREYB
compile endif

Example MYCNF.E

Here's an example MYCNF.E file.

    C_TABS = '4'
    E_TABS = '4'
    REXX_TABS = '4'
    P_TABS = '4'
    USE_APPEND = 1
    SETSTAY = '?'
    WANT_ALL = 1
    EXTRA_EX = 1
    TOGGLE_TAB = 1
    MENU_LIMIT = 25

compile if defined(BLACK)
compile endif

Adding your own key definitions via MYKEYS.E

The file MYKEYS.E should be used for your own key definitions and redefinitions. It is included into E.E after most of the definition stuff and directly before MYSTUFF.E. Currently it does not matter which of those you use to store your key DEFs but that may change.

Key definitions start with a DEF statement and give the key name with an additional S_ for Shift+key, A_ for Alt+key or C_ for Ctrl+key in front of it. Alphanumeric keys are addressed by their alphanumeric value while special keys are listed below:

F1-F12The function keys
DELThe delete key
INSThe insert key
UP, DOWN, LEFT, RIGHTThe cursor keys
PGUP, PGDNThe paging keys
HOME, ENDHome and End :)
ENTER, ESC, TABThe respective keys.
PADENTERThe pad-enter key on AT or MFII keyboards.
PAD5(S_ only) The pad-number 5 on AT or MFII keyboards
EQUAL(A_ only) =
MINUS(A_ and C_ only) -
BACKSLASH(C_ only) \
PRTSC(C_ only) Print Screen

Following the DEF statement you simply start writing your key function.

def a_s=
This makes ALT+S execute the SAVEALL command.

You may, of course, also include other key definition files in MYKEYS.E, e.g. REVERSE.E and GLOBFIND.E from the EPM distribution demos:

include 'reverse.e'
include 'globfind.e'

Example MYKEYS.E

The following example MYKEYS.E defines an undo key for ALT+U. It uses EPM's undoaction command to take back changes one by one. So you don't have to use the UNDO-dialog if you just want to take back a few changes. The one thing making this a little bit complicated is the fact that the undo itself is regarded as a change and therefore is stored by undoaction. So if you did undo twice you would restore the state before the undo. However the intention of the undo key is to be able to take back more than one step. The solution is to store information about which steps in the undo-chain are UNDOs itself and to skip them.

/* This is an example MYKEYS.E file defining an undo key
   <C> 1993 Joerg Schwieder, Berlin, Germany               */
-- define ALT-U
def a_u=
-- define an universal variable to store UNDOs taken
    universal undostates
-- get the first and the last actions stored in the UNDO-tree
    undoaction 6, states
-- parse the 2 values into sfirst and slast
    parse value states with sfirst slast
-- copy our undo-states
    undoakt = undostates
-- save the actual state to our new UNDO-state list
    newstate = slast
-- last entry we could UNDO to
    slast = slast - 1
-- loop through the UNDO-tree
    while slast >= sfirst do
-- look at our last undo
        parse value undoakt with thisone undoakt

        if (thisone < slast) or
           (not thisone) or
           (thisone < sfirst) then

            -- if its older than the last tree entry or if
            -- we never undid - leave, it's OK!


-- add our last UNDO to our new list
        if thisone then newstate = newstate' 'thisone; endif
-- if the actual tree entry is an old UNDO
        if thisone = slast then slast = slast - 1; endif
-- look at the one before
-- if a possible tree-entry was found,
    if slast >= sfirst then
-- add it to the start of the new UNDO-list
        newstate = newstate' 'slast

-- add the remaining old UNDO list to the new one
    while undoakt and (thisone >= sfirst) do
-- but strip entries no longer in the UNDO tree
        newstate = newstate' 'thisone

        parse value undoakt with thisone undoakt

-- set undostates to the new list
    undostates = newstate
-- if an entry was fond
    if slast >= sfirst then
        undoaction 7, slast

-- else remove the actual entry from the list
        parse value undostates with . undostates


/* This is the sample ALT-S definition for SAVEALL */

def a_s=

/* Include REVERSE and GLOBFIND keys from the
EPM distribution demos if present. */

tryinclude 'reverse.e'
tryinclude 'globfind.e'
Select this to go to the next section

Your own commands and procedures via MYSTUFF.E

This is the place to put your own commands and procedures. Usually you won't put them into the file directly but include other files. Don't be concerned if these files contain key definitions as well. EPM includes MYSTUFF.E directly after MYKEYS.E. The distinction is for organizational purposes. You might want to put everything in MYSTUFF.E, especially if you write large extensions part of which are key definitions and if you don't want to split them up into several files.

include 'saveall.e'
This would put the SAVEALL command into the default configuration.

Commands are defined using the DEFC statement followed by the command's name, arguments are passed through arg(1) which returns a parameter string:

defc gocol
    .col = arg(1)
This defines a GOCOL command that moves the cursor to the column passed as parameter.


The following sample MYSTUFF.E file uses another EPM feature - user exits. Several hooks are spread in the editor code which give user procedures notice of certain events, e.g. a file is being saved. User exits are procedures that are called by EPM if they are defined. We will use them to write an autostart feature that "reminds" of its closedown state. If EPM is closed with open files, these filenames are stored in EPM.INI; should EPM be started later without parameters, it will reload these files. Additionally the cursor position in each open file is stored in extended attributes upon shutdown; reloading this file later repositions the cursor right where it was.

This feature is quite useful when you are editing several large files. If you want to leave EPM but continue the next day just close down EPM and if you restart it the next day without parameters; you are right back where you were without having to load all your files and having to find your way through your code back to where you left.

There is just one drawback: Since defmain_exit has to be called from MAIN.E it has to be included before it and therefore has to be included into MYCNF.E. We include this section as a file called MAINEXIT.E into MYCNF.E.


include 'saveall.e'

defc gocol
    .col = arg(1)

/* For the autoload feature we maintain a list of
the currently open files in a profile entry named
STARTUP_FILES. The first one is the file actually
edited to make shure it comes up on restart */

/* This one makes shure that the file that was on
top on shutdown will reappear there on startup.
Defselects are called whenever a file is selected */


   /* The application name and INI-handle
   are stored in these global variables */

   universal appname, app_hini

   -- Save cursor position

   -- get actual filelist
   filelist = queryprofile( $HINI_PARM appname,

   -- find actual file
   if wordpos(.filename, filelist) then

      -- and remove it
      filelist = delword(filelist,


   if (not wordpos(.filename, filelist)) and
      (substr(.filename, lastpos('\', .filename)
      + 1, 1) <> '.') then

       -- add the actual filename at the beginning
       filelist = .filename' 'filelist


   -- write the new list to the INI-file
   setprofile( $HINI_PARM appname, 'STARTUP_FILES',
               filelist )

   -- Restore cursor position

-- called just after file was saved
defproc postsave_exit (fname)

   /* oldfile is the old filename
   if file was renamed */

   universal appname, app_hini, oldfile

   -- Save cursor position

   -- get the old file list
   filelist = queryprofile( $HINI_PARM appname,

   -- if old filename is in the list
   if wordpos(oldfile, filelist) then

       -- delete it
       filelist = delword(filelist,


   if (not wordpos(fname, filelist)) and
      (substr(fname, lastpos('\', fname)
      + 1,1) <> '.') then

       -- Add actual filename if its not
       -- a tempfile ('.---')
       filelist = fname' 'filelist

       -- remove the 'and (substr...' section if
       -- you want to restart temp files


   -- store the new list
   setprofile( $HINI_PARM appname,
               'STARTUP_FILES', filelist )

   -- Restore cursor position

-- called if file was renamed
defproc rename_exit (oldfile, fname)

   universal appname, app_hini

   -- Save cursor position

   -- same as for postsave_exit
   filelist = queryprofile( $HINI_PARM appname,

   if wordpos(oldfile, filelist) then
      filelist = delword(filelist,


   if (not wordpos(fname, filelist)) and
      (substr(fname, lastpos('\', fname)
      + 1, 1) <> '.') then

       filelist = fname' 'filelist


   setprofile( $HINI_PARM appname,
               'STARTUP_FILES', filelist )

   -- Restore cursor position

-- called if file is closed
defproc quit_exit (fname)

   universal appname, app_hini

   -- just delete entry
   filelist = queryprofile( $HINI_PARM appname,

   if wordpos(fname, filelist) then
      filelist = delword(filelist,


   setprofile( $HINI_PARM appname,
               'STARTUP_FILES', filelist )

-- Defload functions are called whenever a file was loaded

defload        /* same as for namefile and savefile,
               just that there are no old names to
               delete */

   universal appname, app_hini
   filelist = queryprofile( $HINI_PARM appname,

   if (not wordpos(.filename, filelist)) and
      (substr(.filename, lastpos('\', .filename)
      + 1, 1) <> '.') then

       filelist = .filename' 'filelist


   setprofile( $HINI_PARM appname,
               'STARTUP_FILES', filelist )

/* Here comes the Cursor position feature */

-- issued just before a file is saved
defproc presave_exit

   -- used to store the filename for postsave_exit
   universal oldfile

   -- delete old 'EPM.POS' entry in the EAs

   -- get cursor and screen position,...

   -- and store it in the EA
   'addea EPM.POS' screenpos

   -- this one's needed for the restart feature
   oldfile = .filename

-- This one's for setting the Cursor and window
--position for the loaded file

    if find_ea('EPM.POS', ea_seg, ea_ofs, ea_ptr1,
       ea_ptr2, ea_len, ea_entrylen, ea_valuelen) then

        -- if there's an EPM.POS EA...

        -- that's the actual file
        getfileid myid

        'postme restore_ORG_pos
        'myid get_EAT_ASCII_value('EPM.POS')

         /* restore postions. have to post it 'cause
         the screen may not yet be painted. Also I
         had to make this the last of my defloads to
         make it work correctly */


-- This sets the cursor and screen-positions.
-- It does the same as
defc restore_ORG_pos

        -- prestore_pos except for being passed
        -- the fileid as first parameter

        parse value arg(1) with myid fline fcol cx cy
        myid.cursorx = cx
        myid.cursory = cy
        myid.line = fline
        myid.col = fcol


-- 5.20 adds a HINI to the *Profile calls.
compile if EVERSION >= '5.20'
   HINI_PARM = 'app_hini,'
compile else
   HINI_PARM = ' '
compile endif

-- called just before files are loaded upon startup
defproc defmain_exit (var cmdline)

   universal appname, app_hini

   -- this is the command line + 'e '.
   -- If no parameters are specified ...
   if cmdline = 'e ' then

       -- ...add the ones from 'STARTUP_FILES'
       cmdline ='e 'queryprofile( $HINI_PARM appname,
                                  'STARTUP_FILES' )

Editor startup code via MYMAIN.E

MYMAIN.E is included and executed directly after the editors own startup code so you can put code here that has to be executed once after the editor was initialized e.g. recognizing messages for other applications (sorry, could not think of anything else). With the exception of the different include position handling of MYMAIN.E is the same as for MYSTUFF.E

File initializations and focus changes via MYSELECT.E

MYSELECT.E is another file that does not differ much from MYSTUFF.E. It is included after MYMAIN.E but before MYSTUFF.E. Theoretically, it should contain DEFSELECTs, code that is executed whenever a file is selected, but this does not necessarily have to be the case so we put this code into MYSTUFF.E also. See the MYSTUFF.E example.

Typical tasks for DEFSELECTs are cursor positioning, file-type specific changes to the keyset or the messageline or adding of file-type specific menus etc. Using DEFSELECTs you can change the behavior of the editor depending on the file-type.


We have seen how the EPM toolkit can be used to change your EPM configuration and how commands that you write can be integrated into the system. A little thought can yield a good editor for your uses at a great price. Also, support for EPM-related topics can already be found in comp.os.os2.programmer.misc and is provided by Larry "Mr. Macro" Margolis, who wrote most of the standard macros provided by EPM and is currently a member of the EPM development group within IBM.