Hello !
Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
en:multiasm:papc:chapter_6_13 [2026/02/20 10:15] – [Macro functions] ktokarzen:multiasm:papc:chapter_6_13 [2026/06/22 17:10] (current) – pczekalski
Line 1: Line 1:
 ====== Macros ====== ====== Macros ======
-Macros are elements of language that enable the replacement of one, usually shorter text, with another. In different assemblers (NASM, FASM), macros can be implemented differently.  The syntax can differ, but the idea remains the same. In this chapter, we'll present the MASM implementation. There are a few types of macros in MASM:+Macros are elements of language that enable the replacement of one, usually shorter text, with another. In different assemblers (e.g., NASM and FASM), macros can be implemented differently.  The syntax can differ, but the idea remains the same. In this chapter, we'll present the MASM implementation. There are a few types of macros in MASM:
   * Text macros,   * Text macros,
   * Macro procedures,   * Macro procedures,
Line 10: Line 10:
  
 ===== Text macros ===== ===== Text macros =====
-Text macros are a simple replacement of one text with another. They are defined with the directive **TEXTEQU**, which creates a new symbolic name and assigns the text to it. The text assigned should be closed in angle brackets, can be a previously defined macro, or can be a text representation of an expression. In the last case, the percent operator calculates the result of an expression and converts it into a text representation. This process is named expansion, and the percent operator is the expansion operator.+Text macros are a simple way to replace one text with another. They are defined with the directive **TEXTEQU**, which creates a new symbolic name and assigns the text to it. The text assigned should be closed in angle brackets, can be a previously defined macro, or can be a text representation of an expression. In the last case, the per cent operator evaluates an expression and converts the result to a text representation. This process is named expansion, and the per cent operator is the expansion operator.
  
 <code asm> <code asm>
Line 38: Line 38:
 </code> </code>
 ===== Macro procedures ===== ===== Macro procedures =====
-Macro procedure is a definition of a fragment of code that can be used later in the resulting program. In some assemblers, they are named multi-line macros. The use of the name of a macro procedure later in the source program causes the so-called expansion of the macro. It is worth noting that for every usage of the macro, the assembler will place in the resulting program all elements specified in the statements inside the macro. These include:+Macro procedure is a definition of a fragment of code that can be used later in the resulting program. In some assemblers, they are named multi-line macros. The use of the name of a macro procedure later in the source program causes the so-called expansion of the macro. It is worth noting that for each invocation of the macro, the assembler will place in the resulting program all elements specified in the statements within the macro. These include:
   * instructions,    * instructions, 
   * directives,   * directives,
Line 61: Line 61:
 </code> </code>
  
-An example of a simple macro which makes a copy of data from the source to the destination can be seen in the following code.+An example of a simple macro that copies data from the source to the destination is shown in the following code.
 <code asm> <code asm>
 copy MACRO arg1, arg2 copy MACRO arg1, arg2
Line 68: Line 68:
      ENDM      ENDM
 </code> </code>
-Note that the arguments of the macro must fit the instructions used inside it. They can be previously defined variables, the first argument can be a constant, or you can even pass the names of other registers.+Note that the macro's arguments must match the instructions used inside it. They can be previously defined variables, the first argument can be a constant, or you can even pass the names of other registers.
  
 <code asm> <code asm>
Line 97: Line 97:
 </code> </code>
  
-The solution to avoid such a situation is to assign the default parameter value or mark the parameter as required. In the first case, the default value will be assigned to the missing parameter. +The solution to avoid such a situation is to assign a default value to the parameter or mark it as required. In the first case, the default value will be assigned to the missing parameter. 
 <code asm> <code asm>
 ; The "copy" macro with default values of parameters ; The "copy" macro with default values of parameters
Line 113: Line 113:
 </code> </code>
  
-In the second case, the error will be signalled, but at the line with a macro use, not inside the macro, which makes it easier to localise the error.+In the second case, the error will be signalled at the line where a macro is used, not inside the macro, which makes it easier to localise the error.
 <code asm> <code asm>
 ; The "copy" macro with required parameters ; The "copy" macro with required parameters
Line 125: Line 125:
 </code> </code>
  
-If a label needs to be defined inside the macro, it must be declared as local to avoid ambiguity. In general, any symbol can be declared as local. In such a case, it will only be visible inside the macro. The **LOCAL** directive can be used for this purpose. It must appear in the line next to the **MACRO** statement.+If a label needs to be defined inside the macro, it must be declared as local to avoid ambiguity. In general, any symbol can be declared as local. In that case, it will only be visible within the macro. The **LOCAL** directive can be used for this purpose. It must appear in the line next to the **MACRO** statement.
  
 <code asm> <code asm>
Line 176: Line 176:
 </code> </code>
  
-Now, let's examine four repeat blocks that result in the same data definitions. All of them define five bytes with initialising values from 1 to 5.+Now, let's examine four repeated blocks that yield the same data definitions. All of them define five bytes with initialising values from 1 to 5.
 <code asm> <code asm>
  i = 1  i = 1
Line 201: Line 201:
 ===== Macro functions ===== ===== Macro functions =====
  
-A macro function is a macro which returns a value. As all macros are texts, macro functions always return text. Returning the value is possible with the use of the **EXITM** directive. Argument of the **EXITM** must be text or the result of another macro function. Numeric values must be converted to text form with the expansion operator %.+A macro function is a macro which returns a value. As all macros are texts, macro functions always return text. Returning a value is possible using the **EXITM** directive. Argument of the **EXITM** must be text or the result of another macro function. Numeric values must be converted to text form with the expansion operator %.
  
 ===== Predefined macro functions ===== ===== Predefined macro functions =====
-Masm offers a set of predefined macro functions, usually used to process texts. There are two versions of them. First is the macro function, which returns the resulting text. Second is the directive, which returns the same text and additionally creates a new symbol. The macro function **@SubStr** returns part of a source string. The **SUBSTR** directive assigns part of a source string to a new symbol. The macro function **@InStr** searches for one string within another and returns its position. The **INSTR** creates a new symbol containing the position of one string in another. The macro function **@SizeStr** determines the string size. The **SIZESTR** creates a new item and assigns to it the size of a string. The macro function **@CatStr** concatenates one or more strings to a single string and returns a concatenated string. The **CATSTR** directive concatenates one or more strings to a newly defined string. The following code demonstrates the equivalent use of both versions.+Masm offers a set of predefined macro functions, usually used to process texts. There are two versions of them. First is the macro function, which returns the resulting text. Second is the directive, which returns the same text and additionally creates a new symbol. The macro function **@SubStr** returns part of a source string. The **SUBSTR** directive assigns part of a source string to a new symbol. The macro function **@InStr** searches for one string within another and returns its position. The **INSTR** creates a new symbol containing the position of one string in another. The macro function **@SizeStr** determines the size of the string. The **SIZESTR** creates a new item and assigns to it the size of a string. The macro function **@CatStr** concatenates one or more strings to a single string and returns a concatenated string. The **CATSTR** directive concatenates one or more strings to a newly defined string. The following code demonstrates the equivalent use of both versions.
 <code asm> <code asm>
 name SUBSTR string, start [, length ] name SUBSTR string, start [, length ]
en/multiasm/papc/chapter_6_13.txt · Last modified: by pczekalski
CC Attribution-Share Alike 4.0 International
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0