Assembler Programming Guide

This chapter has general information about writing programs in assembly language using the rxas assembler programs. It discusses the assembler file format, linkage conventions, and other useful programming information, including the \crexx{} level B feature which allows including assembly language statements in Rexx programs.

The options on the `rxas` command

The assembler is started by invoking the rxas executable and takes options, which are specified before the name of the source file.

\small \immediate\write18{rxas -h > rxasoutput.txt} \VerbatimInput{rxasoutput.txt} \large

option -a: shows some details of the host architecture
option -d: debug/verbose mode produces more informative messages and a trace file
option -l: enables switching the location in the file system where the command is processed
option -n: switches off the optimizer
option -o: this specifies the name of the resulting .rxbin file. The default is the name of the input file.

The format of an assembler source file

The format of the source lines follows the general layout of assembly source, without fixed offsets. As most .rxas files will be generated by the rxc compiler from Rexx source, let’s have a quick look at what it looks like.

```rexx options levelb import rxfnsb

say “hello, rxas!” say “Today is” date()

The generated assembler source follows:

```rxas <!--hello.rxas-->
main() .locals=8
  say "hello, rxas!"
  load r1,5
  call r7,date(),r1
  sconcat r7,"Today is",r7
  say r7
  ret

date() .expose=rxfnsb.date

We can see that the first component of the lines are the procedure names or the instruction mnemonics ; this program has no labels. After the instructions, their parameters are placed.

Labels

It is recommended that a label starts in the first column of the line.¹ The label needs to be ended by a colon (‘:’). Its purpose is to be a symbolic location to branch into when decisions are taken.

Procedure names

Procedure names are identifiers for routines in the program. Procedure main() carries a special role, as that is the one the VM runtime gives control to when a program is started.

Register names

Linkage conventions

Optimizing actions of the `rxas` assembler

rxas is an optimizing assembler² which can rearrange instructions or eliminate them entirely.

Embedded Rexx Assembler

The assembler command enables the inclusion of arbitrary assembler instructions within a Rexx program. The compiler validates the instruction mnemonic and arguments, ensuring that variables are converted into the appropriate register number.

This example uses the linkarg assembler instruction with two variables and an integer constant.

assembler linkarg e,i,5

it will not hurt, however, if it does not start in column one. It must be the first word of the line, though. ↩
optimization is default but can be switched off, for example when debugging. ↩