| Index | Manual | Download | Source | Macros | Embedded word Case ins.
Sitemap | Links | Forum | Tests | Projects

# Macrolibraries
All macrolibraries
OS API libraries
Calling convention
File functions

This is an overview of libraries which can be included to source files of programs written in EuroAssembler.

Names of all macroinstructions from all macrolibraries are listed in alphabetical order on the main EuroAssembler index page.

> Although macrolibraries in this directory maclib are licensed for public domain, it's not recommendable to add your own macros, structures, constants to those files, because your update would have been lost whenever a new version of EuroAssembler overwrites them.
> Create a new macrolibrary with unoccupied name instead.

Includable libraries shipped with EuroAssembler
Realm | OS | Width | Contents | Maclib file
--- | --- | --- | --- | ---
PROGRAM | any | any | ANSI escape sequences | ansi.htm
EUROASM | any | 16 | BIOS API interface | biosapi.htm
PROGRAM | any | 16 | BIOS structures + symbols. | bioss.htm
EUROASM | any | any | Extensions of CPU machine instructions | cpuext.htm
EUROASM | any | 16 | Extensions of CPU machine instructions | cpuext16.htm
EUROASM | any | 32 | Extensions of CPU machine instructions | cpuext32.htm
EUROASM | any | 64 | Extensions of CPU machine instructions | cpuext64.htm
EUROASM | any | any | Nontinteractive debugging | debug.htm
EUROASM | Dos | 16 | DOS API interface | dosapi.htm
PROGRAM | Dos | 16 | DOS structures and symbols. | doss.htm
EUROASM | Win | 64 | FastCall Windows 64-bit calling-convention macros. | fastcall.htm
EUROASM | Lin | 64 | Linux 64-bit SYSCALL ABI interface. | linabi.htm
EUROASM | Lin | 32 | Linux 32-bit INT 0x80 API interface. | linapi.htm
PROGRAM | Lin | 32 | Wrappers of 32-bit Linux file functions. | linf32.htm
PROGRAM | Lin | 64 | Wrappers of 64-bit Linux file functions. | linf64.htm
PROGRAM | Lin | 32,64 | Struc+symbols for base functions in Linux. | lins.htm
PROGRAM | Lin | 32,64 | Struc+symbols for file access in LinAPI. | linsfile.htm
EUROASM | any | 32 | Memory management macros. | memory32.htm
EUROASM | any | 64 | Memory management macros. | memory64.htm
EUROASM | any | 16 | Data sorting. | sort16.htm
EUROASM | any | 32 | Data sorting. | sort32.htm
EUROASM | any | 64 | Data sorting. | sort64.htm
EUROASM | any | 16 | Boolean flag manipulation. | status16.htm
EUROASM | any | 32 | Boolean flag manipulation. | status32.htm
EUROASM | any | 16 | StdCall 16-bit calling-convention macros. | stdcal16.htm
EUROASM | any | 32 | StdCall 32-bit calling-convention macros. | stdcal32.htm
EUROASM | any | 64 | StdCall 64-bit calling-convention macros. | stdcal64.htm
EUROASM | any | 16 | Operations with zero-terminated strings. | string16.htm
EUROASM | any | 32 | Operations with zero-terminated strings. | string32.htm
EUROASM | any | 64 | Operations with zero-terminated strings. | string64.htm
EUROASM | any | 64 | System V 64-bit calling-convention macros. | sysvcall.htm
PROGRAM | any | 32,64 | Struc+symbols for time functions in Linux and Windows. | time.htm
EUROASM | Win | 64 | Macros for core 64-bit MS Windows functions. | winabi.htm
EUROASM | Win | any | List of MS Windows API functions with ANSI+WIDE variants. | winansi.htm
EUROASM | Win | 32 | Macros for core 32-bit MS Windows functions. | winapi.htm
PROGRAM | Win | 32 | Wrappers of 32-bit MS Windows file functions. | winf32.htm
PROGRAM | Win | 64 | Wrappers of 64-bit MS Windows file functions. | winf64.htm
PROGRAM | Win | 32,64 | Struc+symbols for base functions in WinAPI. | wins.htm
PROGRAM | Win | 32,64 | Struc+symbols for console subsystem in WinAPI. | winscon.htm
PROGRAM | Win | 32,64 | Struc+symbols for common dialogs in WinAPI. | winsdlg.htm
PROGRAM | Win | 32,64 | Struc+symbols for file access in WinAPI. | winsfile.htm
PROGRAM | Win | 32,64 | Struc+symbols for graphic subsystem in WinAPI. | winsgui.htm
PROGRAM | Win | 32,64 | Struc+symbols for networking in WinAPI. | winsnet.htm
PROGRAM | Win | 32,64 | Struc+symbols for printing in WinAPI. | winsprn.htm
PROGRAM | Win | 32,64 | Struc+symbols for registry access in WinAPI. | winsreg.htm
PROGRAM | Win | 32,64 | Struc+symbols for security management in WinAPI. | winssec.htm

The Realm category specifies visibility of included library members in the source.

Realm EUROASM libraries contain only macros and preprocessing %variables, i.e. redefinable resources which are not constrained by PROGRAM..ENDPROGRAM. Their scope begins at the moment of library inclusion, and it ends at the end of source file.
Macrolibraries from this realm may be included inside the PROGRAM block, or only once at the beginning of source file.

> If an EUROASM macrolibrary depends on %variables and macros defined in other library, it should ensure from misorder and start with `INCLUDE1 OtherLibrary`.

Realm PROGRAM libraries contain definitions of constant symbols and structures, which must be unique in a program.
Libraries from this realm should be included inside the PROGRAM block, otherwise the symbols and structures would not be visible for the assembled program.
Order of their inclusion does not matter.

> Structures and symbols retrieved from [WindowsSDK] were classified by their subsystem or functionality and split to several specialized macrolibraries wins*.htm. This should speed up the assembly time, because ordinary programs usually do not need to include all possible functionalities at once.
> Look for the constant/structure name with the Search applet on top of this page when you are not sure which macrolibrary hosts the symbol.
> Lazy Windows programmer can include all those libraries at once with `INCLUDEHEAD1 wins*.htm` in its header.

## ↑ API libraries

This collection provides macros for interaction with the application programming interface of operating system. It also defines homonymous macros for basic functions of the operating systems: standard console input and output (`StdInput, StdOutput`), retrieving of command-line arguments ( `GetArgCount, GetArg`), retrieving of environment variables ( `GetEnv`), return from the program to OS (`TerminateProgram, TerminateStayResident`).

Programming interface macros represent an elegant way of interaction with operating system using only one single statement. Otherwise we would have to push or load appropriate registers with argument values in the right order, store caller-save registers, manually arrange stack alignment, call the imported function and finally restore the stack.

Overview of macrolibraries for interaction with OS
via Application Programming Interface
OS | Width | Macro | Method | Mode | Macrolibrary file
--- | --- | --- | --- | --- | ---
Bios | 16 | BiosAPI | INT 0x10 | Robust | biosapi.htm
Dos | 16 | DosAPI | INT 0x21 | Robust | dosapi.htm
Lin | 32 | LinAPI | INT 0x80 | Robust | Fast | linapi.htm
Lin | 64 | LinABI | SYSCALL | Robust | Fast | linabi.htm
Win | 32 | WinAPI | StdCall | Robust | Fast | winapi.htm
Win | 64 | WinABI | FastCall | Robust | Fast | winabi.htm

## ↑ Calling convention libraries

This set of libraries is designed to create procedures conform with usual calling conventions (macros `Procedure, EndProcedure`). Such procedures can be invoked as an OS-function callback, or invoked by 3rd-party programs, if the procedure is exported from a shared library.

Macros `Invoke` can be used to exploit procedures and functions from OS or from 3rd-party non-OS libraries. Nevertheless, for interaction with OS it's better to use a specialized API macroinstruction.

Overview of OS-independent
calling convention macrolibraries
OS | Width | Macro | Method | Mode | Macrolibrary file
--- | --- | --- | --- | --- | ---
any | 16 | Invoke | StdCall | Robust | stdcal16.htm
any | 32 | Invoke | StdCall | Robust | stdcal32.htm
any | 64 | Invoke | StdCall | Uses | stdcal64.htm
any | 64 | Invoke | System V | Uses | sysvcall.htm
any | 64 | Invoke | FastCall | Robust | Fast | fastcall.htm

The Mode category specifies expansion mode of the macro. Most macros from EuroAssembler libraries are
Robust which means that they do not clobber any registers except for those which return the result. This is suitable for programming style where important variables are kept in GPR permanently and they survive invocation of OS API or of other library function. Robust mode macros also allow to pass function arguments in arbitrary registers.

Fast mode macros do not bother with saving and restoring caller-save registers. Programmers cannot rely on values in scratch registers to remain unchanged by OS interaction. They also need to pay attention to not overwrite values in registers designed for argument transport.

Some API invokation macros allow to select Fast or Robust expansion mode with keyword operand `Fastmode=`.

64bit libraries employ the macro Uses to explicitly specify the list of registers which the invoked procedure should save and restore. The level of robustness then depends on Uses operands.

Calling convention libraries contain homonymous macroinstructions
(`Procedure, EndProcedure, Invoke, LocalVar, ClearLocalVar, Uses`). Only one such library should be included in a program. Calling convention library can be combined with API library, see the sample projects for examples.

## ↑ File functions

Homonymous macroinstructions whose name begins with File~ were created to unify work with files in EuroAssembler programs, regardless of OS and program width.

Overview of macrolibraries
for file functions
OS | Width | Mode | Macrolibrary file
--- | --- | --- | ---
Lin | 32 | Robust | linf32.htm
Lin | 64 | Robust | linf64.htm
Win | 32 | Robust | winf32.htm
Win | 64 | Robust | winf64.htm

As an example of using those File~ macros see the sample testing programs tlinf32.htm, tlinf64.htm, twinf32.htm, twinf64.htm.

▲Back to the top▲