Win32 specifics ..
Api calls
In most other languages, api calls are done using 2 instructions (a CALL to a JMP instruction) because of problems bound to linker use (languages can't know where linkers will store the import table). RosAsm does it in one single instruction (CALL 'mem'). The syntax is, for example:
call 'KERNEL32.VirtualAlloc'
Evocations of apis do not need any previous declarations. When RosAsm finds a call 'SOME.Thing', it creates the wished entry in the Import table; that's all. The DLL name is not optional, unless you already provided it somewhere else. You must usually give, even in simple cases like 'COMCTL.InitCommonControls'. The counterpart of this simplicity is that you have to write the true full names of functions, at least one time in your Sources:
call 'User32.DispatchMessageA' msg ; With the 'A'
and not:
call 'DispatchMessage' msg
... unless call 'User32.DispatchMessageA' is already available somewhere else in your Source File. In such cases, RosAsm does the wanted operation silently.
For calling Functions in other Files than DLLs, this is directly available for *.drv, *.sys, *exe Files. For other exotic Files, you have to provide the extension by yourself:
call 'EXOTIC.fth.Function' msg
The great thing with this is that you will never have to browse on the Net to find some missing '.Lib' or '.Inc' (MASM users know what I mean, right? ;)
If you do not know what DLL a Function is from, just Right-Click on the Function name. RosAsm will open a Dialog with the full call. An internal List contains almost all of Api Function calls. If not found, take a look in the Win32 Help File and click on the [Quick Info] of the Function.The name of the 'Lib' is also the name of the DLL.
Upper cases for dlls' names are optional, but cases for Functions' names must be the true ones -apis are case sensitive-. This is one reason why apis need a specific calling writing convention.
RosAsm now tests api calls with 5 possible error messages: Bad DLL / Bad Function / Missing 'A/W' / Exceeding A/W / bad api call form. Parameters number is not controlled, but, when you [Run] your application (Run includes a Debugger), run time errors that the debugger fails to point out are usually such errors.
Simplified Api calls
Once you have written one call to some DLL Function, in the complete format, as discribed above, you can omit the DLL Name. That is, you provide the DLL name, at least once, and this is enough to make the Assembler happy, for the other shots:
call 'KERNEL32.VirtualAlloc' ; One complete version...
...
call 'VirtualAlloc' ; Shortened form allowed.
Api call Error pointing
When the Assembler sends one of the Api Function error Messages, at the time of this computing, it is not working directly on a version of the original Source, but on a couple of tables used to encode the .Import Section. So, at the time of this error warning, the Assembler cannot know where the wrong Statement is in the real Source. Hence, it performs a simple search, from the Top of Source, the same way you would do it when using the [Find] Box. This is why, if, for example, a comment says the same thing, before the targeted call, the error Manager will point to the first (and wrong) instance of the searched name, inside the comment. In normal programming circumstances, this should not be a big problem. This mis-behaviour will be fixed later, when we will implement the Search Type in the [Find/Replace] feature.
Entry Point
Entry point must be called 'Main:'. If you do not like it, change the string at 'EntryPointLabel:' and recompile > you got the eg. Change the 'Main:' label in RosAsm's own source too and recompile again > you got the hen (sometimes a rooster). If you plan to modify some other points, try to fully understand why two compile times are needed here. Auto-compiling needs sometimes killing procedures...
The Win main loop for messages holding (what others usually call 'WinProc') must be named 'MainWindowProc' (same upper comment).
Win32 Equates
RosAsm knows more than 53,000 Win32 Equates . You just need to write a leading '&' at evocations (ex: &TRUE). This list covers all usual needs and much more. For non supported symbols, declare them as user Equates.
Win Structures are provided in an external File. To get a Structure, just run the Dialog associated with the [Struct] menu item.
Win32 Structures
When translating sources from MASM to RosAsm, you will notice that many MASM users declare these Structures as Stack Local Data and then initialize the Structures' values at Run time. This is particularly stupid in most cases. Declare your Structures as any common Data sets and initialize everything you can at writing time, instead. This is much easier to write, easier to read and faster to run. The only case in which Structures are welcome on the stack is when the given Structure is filled by Win32 to give us infos.
Another way of pointing to Structures (when some Structure Pointer is returned by Win32) is to replace the Structure Data by a Structure Equates Set. See a good example in ToolBar T.D. demo for TB_NOTIFY / TOOLTIPTEXT structure:
[TOOLTIPTEX:
@hdr: @NMHDR_hwndFrom: D§ 0
@NMHDR_idfrom: D§ 0
@NMHDR_code: D§ 0
@lpszText: D§ 0]
[@szText: B§ 0 #80]
[@hInst: D§ 0
@uFlags: D§ 0]
May be replaced by an EBX based pointers Equates set (the value to be set in EBX, in this case, is given by Win32 in a Message event):
[TOOLTIPTEXT_NMHDR_hwndFrom ebx
TOOLTIPTEXT_NMHDR_idfrom ebx+4
TOOLTIPTEXT_NMHDR_code ebx+8
TOOLTIPTEXT_lpszText ebx+12
TOOLTIPTEXT_szText ebx+16
TOOLTIPTEXT_hInst ebx+96
TOOLTIPTEXT_uFlags ebx+100]
Various forms of each Structure are given to you by the [Struc]. See Structures. There is also a little Dialog [Tool] / [Data to Equates] that may help you in doing these simple translations from your own Data form Structures.
~~~~~~~