A guide to the RichMasm editor

[jj2007]

When you install MasmBasic (a library that allows to use Basic syntax in assembler), the first thing you'll see after clicking OK is the file MbGuide.rtf in MasmBasic's editor called "RichMasm", a special editor for working with assembler source code.

To see your first "Hello World" program running, simply hit F6.

RichMasm has been designed for long sources, and concentrates on effective navigation rather than on beauty and/or abundance of features. The package includes a number of easy-to-use "skeletons", including dll and library examples.

On a green background, some simple instructions to build your first Hello World are shown.

In the right half of the screen, you can click into a listbox with "found matches", in this case: all ca. 500 occurrences of the Find string _Mb (an internal code to identify help topics). For example, if you change the string to _Mb*file and hit Enter, the find box will contain all 19 help entries dealing with files. The wildcard * means "find a line that contains both strings"; the string push eax*****pop would mean "find a line that contains push eax and has a pop on the same line or within the next 4 lines".

To the right, there are also a few bookmarks; you can click into them to jump e.g. to the "StringToArray" section. Bookmarks are defined by selecting a (meaningful) text, e.g. start: or Parser proc, and hitting Ctrl D. In contrast to so-called "bookmarks" in other editors, RichMasm bookmarks will be saved with the text, so that you can work with them next time you open the document. Press Alt K to toggle between keys and bookmarks view.

Another way to navigate in the text are the left and right arrows in the upper right corner: The document's history is stored with the source, and by clicking on the left arrow, you can go to sections that you edited earlier. Hitting the Alt Left or Alt Right keys will do the same.

To explore the menus, please go to the top of MbGuide.rtf and left-click on try 90+ snippets as shown below:


A new document opens, MbSnippets.asc.
- Hover over the File menu, it will open without clicking:



As usual, Open, Save, Save as are on top; what you will most frequently need is New Masm source, the F6 and F7 keys, the Guide to MasmBasic, and the recent files list. Hopefully, you will never need the Last good version entry 8)

Some notes:

- New Masm source opens the file Template.asc; click on any link to "create a new project" (hint: "MessageBox" in the upper left corner opens a simple Hello World with really boring grey on black colours). Just edit according to your needs. When you try to save your work, you will be prompted to choose a new name, i.e. you are not allowed to overwrite the template.

- The yellow area "to build any"... on top is an optional extra window that serves to keep a portion of the document visible independently of the current edit position. Imagine you have a structure defined somewhere near the top, and you'd like to see the definition while working with it near the end of the document; just select the lines you want to see and press Ctrl F12 (if nothing is selected, the window disappears).

- The word Init is selected. If you hit F6 (=build & run), RichMasm will search backwards to "include..." and forward to either end start or EndOfCode, and if they are present, it will conclude that user wants to build only the section that contains Init. The whole document has 94 such "snippets", you can build and run them all either by selecting Init by hand, or by clicking into the "94 matches" listbox and hitting F6.

- In the upper right corner under "Find:", the text L1200... indicates Line1200, Column 3, +4 characters selected, 73d is the decimal Ascii code of the selected "I", while 49 6E 69 74h is the hexadecimal representation of Init.

- Now hover over the Edit & Format menu:
There are a number of formatting options, like colours, tabs and fonts, plus functions for exporting selected text. You will need the F4 (comment) key fairly often; when selecting several lines of text, the whole block gets commented out. Pressing F4 again turns comments into code, and in addition colours MasmBasic commands in blue, while push/pop pairs are formatted in red, for obvious reasons.

Hint for those who are scared of coloured code: Press Ctrl A (select all), then twice Ctrl E. The whole text will be black.



- Finally, the menus System & Plugins, Help and AutoCode can be defined in \Masm32\MasmBasic\Res\menus.ini:
 


Note that the help files, where technically possible, receive the currently selected text for jumping to their dedicated help page.

Here is an example of the output window, which can be toggled pressing the F7 key:



The code contains an error, so when hitting F6, RichMasm highlights the error message in the output window and jumps to the error line in the main edit window.

[satpro]

GREAT post jj.  Keep 'em coming.

[jj2007]

Thanks, satpro ;)

One element of the RichMasm philosophy is that a "project" doesn't need to be distributed over a dozen tiny little files. If possible, why not use one single file? Why, for example, should we use a separate resource file, if it can be integrated into the main source? Attached a simple example - a single *.asc file. Open it in RichMasm, edit a resource string (e.g. change "Welcome" to "Good night") and hit F6.



As you can see in the screenshot, the AutoCode menu has an entry "Resource section". Just put the cursor behind GuiEnd (or end start/EndOfCode, wherever your source ends), click this entry and voilà, you have now an editable resource section. Every little change that you make can immediately be tested, you don't even have to save first (but do save it when you feel the code is OK 8)).

[jj2007]

As of version 19 May 2016, RichMasm can assign keystrokes to menu functions:

- hover over a menu title, e.g. System & Plugins
- move down until the desired function is highlighted, e.g. "Find on disk" (a plugin)
- hold Shift and right-click into the highlighted menu item
- the menu closes, and you see "Press a key" in the status bar in the upper right corner
- press a key, e.g. f

Afterwards, the key sequence F12, f will do exactly what the menu would do. Hitting F12 twice will toggle between the list of shortcut keys and your bookmarks (try also pressing Alt K repeatedly).

Note this is saved immediately, and your shortcuts will not be overwritten by a re-installation of MasmBasic.

[jj2007]

RichMasm beta: extract to \Masm32\MasmBasic\RichMasm.exe (you might rename the old one before).
Attachment removed, the beta has been promoted and is now included in the normal release :icon_cool:

Main feature is a much speedier (20*) load of files in the megabyte range. The culprit was the EM_LINEINDEX message. You may test the difference with the F9 key, which displays a file info message:

File info (when opened):
17.06.2016, 03:14:35, 1720890 bytes in 29146 lines

Loading MasmBasic.asc took 0.70 seconds

Other changes:
- in case of assembly errors, the jump to the offending line is now more precise for large files
- searching has become much faster; for example, finding 3483 times eax in the 18,000 lines of the RichMasm source takes now about 50ms on the i5, counted from hitting Return to seeing the listbox; in short: it's immediate

[jj2007]

With RichMasm, you don't normally need any options - most of the \Masm32\examples sources, for example, build just fine by hitting F6. The editor detects fairly accurately if your source is a GUI application (/subsystem:Windows) or a console program. And yet, you can set quite a number of options. They consist of an uppercase OPT_SomeKeyword and are embedded in the source. Thus, they are available also when you copy the file to another computer, or you post it in the forum.

Here is a loose collection. In practice, OPT_Arg1, OPT_Wait and OPT_Icon are the most frequently needed options.

OPT_Assembler   ml                      ; mlv9, Jwasm, asmc, ... whatever is in \masm32\bin\
OPT_Linker      link                    ; polink, ...
OPT_Olly        1                       ; 0...9: use \masm32\OllyDbg\OLLYDB1.EXE (default is OllyDbg.exe)
OPT_DebugA      /Fl /Sn                 ; add items to the assembler commandline
OPT_DebugL      /verbose xfile.obj      ; add items to the linker commandline
OPT_Debug       1                       ; enable the heap debugger (useful if you suspect heap corruption; console only)
OPT_Susy        WINDOWS                 ; force subsystem: windows or console (but autodetect rarely fails)
OPT_Out         somepath.exe            ; force a different output file
OPT_Run         dosomething.exe with args
OPT_Res         someresourcefile        ; default are rsrc and ThisFile; no .rc extension please
OPT_Icon        smiley                  ; see \Masm32\MasmBasic\icons
OPT_Arg1        pass some arguments to the exe
OPT_Arg2        pass even more arguments
OPT_DelDef      0                       ; do not delete def files
OPT_DelExp      0
OPT_DelLib      1
OPT_DelPdb      1
OPT_DelLst      1
OPT_DelObj      1
OPT_DelTmp      0                       ; do not delete Tmp_File.asm
OPT_DelRes      1
OPT_DelBatch    1
OPT_Verbose     1                       ; show related files after building
OPT_BatA   SayHello                      ; run any bat or exe, e.g. SayHello.bat after assembling
OPT_BatL   congrats                      ; run any bat or exe, e.g. congrats.exe after linking
OPT_Wait        0                       ; do not wait for a keypress (useful e.g. for Windows apps with subsystem console)
OPT_Tmp2Asm     0                       ; create MyFile.asm
OPT_Tgt         dll                     ; default is exe, otherwise dll or rml aka RichMasm Lib

When they appear inside the code, use ; OPT_something, or

Code Select Expand

if 0
  OPT_Wait 0
  OPT_Susy Console
endif

Note that when building a project with RichMasm, all options become temporary environment variables. You can use them in your code with Masm's built-in @Environ macro, for example:

Code Select Expand

; OPT_Arg1 These are 'some arguments'
tmp$ CATSTR <Print "Arg1=[>, @Environ(oArg1), <]">
tmp$

[jj2007]

Step-by-step instructions to build 64-bit assembly programs:
1. install the latest MasmBasic version from here
2. after clicking Accept & Install, you'll see the MasmBasic help file (light green background)
3. select Init below the -- same as 64-bit code: -- line
4. hit F6 to see your first 64-bit program build and run

More examples are in menu File/New Masm source. Note that the deb macro has some limitations, as compared against its big 32-bit brother. Inter alia, it works only in console applications:

Code Select Expand

deb 1, "Testing the debug macro:", rax, rcx, rsi, xmm0, xmm1, ST(0), ST(1), ST(2), ST(3)

Let me know if you run into any trouble (AntiVirus, ...) 8)

[jj2007]

With MasmBasic version 26 Nov 2016, RichMasm has a new feature, inspired by Hutch:

Code Select Expand

Imagine some boring
text that you would
like to turn into a
Masm-readable bunch
of db declarations.

- select the text
- hit Alt R (replace)
- in the edit control in the upper right corner, enter db "]#[", 0
- hit Enter to confirm
- click Yes in the MsgBox and see this:

Code Select Expand

db "Imagine some boring", 0
db "text that you would", 0
db "like to turn into a", 0
db "Masm-readable bunch", 0
db "of db declarations.", 0

The ]#[ marker is a placeholder for the line content. For adding text only to the left, use e.g. $Data]#[ (i.e. no text on the right).

You may use this for a new variant of the Data macro with a leading $ sign, meaning "no quotes needed to recognise this as a string":

include \masm32\MasmBasic\MasmBasic.inc
$Data Imagine some boring
$Data text that you would
$Data like to turn into an
$Data easy-to-use array of
$Data strings for display.

  Init
  Read my$()
  For_ ecx=0 To eax-1
      PrintLine my$(ecx)
  Next
  Inkey "... simple, right?"
EndOfCode

Output:

Code Select Expand

Imagine some boring
text that you would
like to turn into an
easy-to-use array of
strings for display.
... simple, right?

[jj2007]

Wouldn't it be nice if you could hit F6 to build your project, and see immediately the debugger?

Code Select Expand

include \masm32\include\masm32rt.inc ; plain Masm32 for the fans of pure assembler

.code ; make sure Olly sits in \Masm32\OllyDbg\ollydbg.exe
start:
  mov eax, chr$("Welcome to OllyDbg") ; you will see this text in Olly
  mov eax, chr$("Hit F9 to advance to the breakpoint")
  xor ebx, ebx ; argument counter
  .While 1
mov esi, cmd$(ebx)
int 3 ; set a breakpoint for Olly
.Break .if ecx!=1 ; read the Masm32 help on cmd$() to understand why
print "arg #"
print str$(ebx), ":", 9
print esi, 13, 10
inc ebx
  .Endw
  inkey
  exit

end start

OPT_Symbols 1 ; create symbols for OllyDbg
OPT_Arg1 "Hello Masm32 Forum"
OPT_Arg2 what's going on today?

When opened in RichMasm, the snippet (attached) builds as console application when hitting F6, but instead of running the exe directly, OllyDbg will be launched. Hit F9 and see what happens at the breakpoint.

If you comment out the breakpoint: ; int 3, RichMasm understands that you don't want to debug, and launches the executable normally.

Note also that for console applications, RichMasm takes care to activate OllyDbg instead of the console output window - a minor feature maybe, but if you have to activate the debugger a hundred times because the console is always in front, you may start to appreciate RichMasm's little service ;-)

[jj2007]

RichMasm has a comfortable plug-in interface, giving access to e.g. the selected text, the handle to the RichEdit control, etc.

Attached are two examples:
- FindOnDisk allows to quickly search files for two search patterns
- CompileBasic is for compiling sources written in various BASIC dialects, plus some C/C++ variants.

Both need to be extracted to \Masm32\MasmBasic\Plugins
After a restart of RichMasm, they appear in System & Plugins menu.

[jj2007]

Most people never need filenames in exotic languages, but sometimes it might be necessary.
Attached is an example of a source with an Arabic name and an Arabic MsgBox.
Open it in RichMasm (version 11 February 2017 or later) and hit F6 to build the demo.

[mabdelouahab]

Hi jj

you need \masm32\bin\HJWasm32.exe ...

Why?
I have Windows 8.1 X64 Arabic, And I use HJWasm64.exe To create 32/64 application

[jj2007]

Hi mabdelouahab,

Probably, RichMasm saw a very old ML.exe in your \bin and suggested to download & install HJWasm32.exe. You can indeed use any MASM-compatible assembler except the old one (6.14) that comes with the Masm32 package.

In the example I posted above, there are OPT_* lines. Change them according to your needs, for example:

Code Select Expand

OPT_Assembler mlv615
OPT_Linker linkv614

Assuming, of course, there are \Masm32\bin\mlv615.exe and \Masm32\bin\linkv614.exe on your disk. If there are no OPT_* lines, or they are disabled with e.g. OxPT..., RichMasm uses HJWasm32 and polink.

I attach a 64-bit example, with OPT_Linker linkv10 (version 6.14 and polink won't work with an Arabic filename and 64-bit code)

[jj2007]

Update 14 Feb 2017: RichMasm works now also with Unicode file names and 64-bit code, see attachment. The restrictions regarding assemblers and linkers are no longer valid, i.e. it works fine with ML, HJWasm32, AsmC and various linkers including polink.

include \Masm32\MasmBasic\Res\JBasic.inc      ; ## console demo, builds in 32- or 64-bit mode with ML, AsmC, JWasm, HJWasm ##
  Init            ; OPT_64 1      ; put 0 for 32 bit, 1 for 64 bit assembly
  PrintLine Chr$("This code was assembled with ", @AsmUsed$(1), " in ", jbit$, "-bit format")
  wMsgBox 0, 'This is a "text" for a Unicode MessageBox', "Title:", MB_OK
  wMsgBox 0, "Это окно с сообщением", "Это название:", MB_OK
  wMsgBox 0, "هذا هو مربع الرسالة.", "أهلا بك", MB_OK
  wMsgBox 0, '这是一个消息框。', "这是一个标题:", MB_OK
EndOfCode

[mabdelouahab]

hi JJ, I've downloaded Update .
How do I deal with this?

Code Select Expand


** Start C:\Masm32\MasmBasic\Res\bldallRM.bat **
*** user-defined OPT_xx variables: ***
Page de codes activeÿ: 65001
**** 64-bit assembly ****

OPT_Arg1:
OPT_Arg2:
OPT_Out:  Tmp_File.exe
OPT_Res:  Tmp_file


*** Assemble, link and run صندوÙ, رساÙ,,Ø© ***

*** Assemble using \masm32\bin\HJWasm32 /c /Zp8 -win64 tmp_file.asm ***
HJWasm v2.17, Dec  5 2016, Masm-compatible assembler.
Portions Copyright (c) 1992-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.

Error A2106: Cannot open file: "tmp_file.asm" [ENOENT]
*** Assembly Error ***