Pl GEMDOS.DOC

Languages:

English  • français

                            ---------------------
                              CHAPTER 5:  

                             *** THE GEMDOS ***

                            ---------------------


 
                      *** GEMDOS FUNCTIONS ***
                      -------------------------------

- The GEMDOS functions can be directly called in assembly.
  Just:

   .Pass the parameters needed by the function in the system stack
    (WORDS or L-W).

   .Pass the function code in the system stack. (WORD)

   .Call the GEMDOS with a TRAP #1 


- The same is true for BIOS and XBIOS functions.
  (Only the TRAP number changes: TRAP #13 for BIOS and TRAP #14 for
  XBIOS)

- ATTENTION! The GEMDOS, BIOS and XBIOS functions often return
  information: in certain data registers and some
  address registers.
  Care must be taken to preserve the concerned registers before 
  calling one of these functions so as not to lose their content.
  (e.g. using MOVEM)

- Before using the GEMDOS, BIOS and XBIOS functions, it is necessary
  to reserve a certain amount of memory because when the operating
  system launches your program, we must allocate the quantity of memory
  that the program really needs.
  (To avoid overlapping of data in memory)
  The operating system (the GEM Desktop) will read the BASE PAGE which
  is at the start of your .PRG program (see the INTRODUCTION chapter)
  before executing it.
  This BASE PAGE is of size $100 (256) bytes and contains all
  the information needed by the operating system for the loading
  of the PRG, but it is up to us to indicate the size of memory
  that will need to be reserved.
  After loading the program, SP points to the BASE PAGE, so 
  the various data contained in the
  BASE PAGE can easily be read by incrementing SP for example.

  Organization of the BASE PAGE:
                     ------------
  Byte:$00=Start of the Base Page
  ----- $04=Pointer to the end of free memory
        $08=Pointer to the start of the prg
        $0C=Size of the TEXT area
        $10=Pointer to the DATA area
        $14=Size of the DATA area
        $18=Pointer to the BSS area
        $1C=Size of the BSS area
        $20=Pointer to the DTA buffer
        $24=Pointer to the base page of the calling PRG (parent)
        $80=The command line

  To indicate the size of memory to reserve, there is a GEMDOS function, the parameters to pass are:

  .the number of BYTES to reserve (L-W)
  .A L-W which is the pointer to the end of free memory
  .a WORD equal to 0
  
  The function code is $4A (function 'SETBLOCK')

  To find the number of bytes to reserve (the total size of the PRG)
  thanks to the Base Page, we add:

  .The size of the Base Page ($100 bytes)
  .The space occupied by the instructions (L-W at $C(SP) because SP points to
   the start of the base page)
  .The size of the DATA area (L-W at $14(SP) )
  .The size of the BSS area  (L-W at $1C(SP) )
  
  We put the result in a dn register and place it as a parameter
  (L-W) in the system stack (MOVE.L  dn,-(SP) ) followed by a L-W which is
  the pointer to the end of free memory and a WORD equal to 0: 
  (MOVE  #0,-(SP) ) 
  Then we stack the code of the function SETBLOCK: MOVE  #$4A,-(SP)
  and call the GEMDOS with TRAP #1.

  This initialization must be done at the beginning of any program.
  ----------------------------------------------------------------
  To avoid retyping everything each time, we will create a
  MACRO INSTRUCTION that will do it for us.

  A MACRO is delimited by the directives:
  
  MACRO (After the name of the Macro to mark the beginning of the MACRO)
  -----
  ENDM  (At the end of the MACRO to mark the end of it)
  ----

     Example: A MACRO called ADD which adds the low word
     ---- of registers d0 and d1 will be written:


        TEXT

add      MACRO            ;beginning of the macro
        ADD.W    d0,d1   ;the Macro itself
        ENDM             ;End of the Macro

    ; This MACRO can then be used:

        MOVE     #3,d0
        MOVE     #5,d1
        add              ;call of the MACRO 'add'
        MOVE     d1,res

        BSS

res     DS.W     1       ;We will find the word 5+3=8 in 'res'

        END

  The MACRO can be used as many times as you want, but
  care must be taken not to put Labels in your MACRO because they
  would be rewritten multiple times and this would cause errors...

  The MACRO can then be saved in a file.

  To indicate to the LINKER that you are going to use a MACRO that is in
  an external file, you will have to use the DIRECTIVE:

  INCLUDE   "file.xxx"
  -------
  It must be used before the first MACRO from 'file.xxx' is
  used. 
  The entire file will be ASSEMBLED separately, but only the used MACROs
  will be included.
  

  But let's go back to our GEMDOS 'setblock' function:

  The Listing of the SETBLOCK Macro will be:

          TEXT

SETBLOCK  MACRO               ;beginning macro
          move.l    a7,a5     ;USP in a5
          lea       stack,a7  ;'stack' is the address pointing to an area
                              ;of memory reserved for certain 
                              ;functions. 
                              ;(the name of the label is arbitrary...)
                              ;(Of course, you must reserve this area with
                              ;DS.x space: 200 bytes are generally enough)
          move.l   4(a5),a5   ;free memory ending address in a5
          move.l   $c(a5),d0  ;TEXT area length in d0
          add.l    $14(a5),d0 ;adds the size of the DATA zone 
          add.l    $1C(a5),d0 ;adds the size of the BSS zone
          add.l    #$100,d0   ;adds size of Base P. to d0

          move.l   d0,-(sp)   ;STACKS the space to reserve (1st parameter)
          move.l   a5,-(sp)   ;STACKS a5                  (2nd parameter)
          move     #0,-(sp)   ;STACKS word=0              (3rd parameter)
          move     #$4a,-(sp) ;STACKS the CODE of SETBLOCK
          trap     #1         ;GEMDOS call ->execution of the function.
          add.l    #12,sp     ;When returning, SP is incremented to
                              ;regain its initial value.

          ENDM                ;end of the MACRO

          END                 ;end of assembly


 We will save this macro in the file 'INIT_TOS.L'.


 All the programs we write will therefore have to look like this:
 ---------------------------------------------------------------------
 
     TEXT

     INCLUDE   "INIT_TOS.L"   ;Linkage of the file


     SETBLOCK                 ;call of the MACRO SETBLOCK

     .                        ;the instructions 
     .                        ;that form the prg
     .

     DATA                     ;the data zone

     .                        ;with the initialized data
     .
     .

     BSS                      ;the bss zone

     .                        ;with the reservations
     .
     .

     DS.B      200            ;and space reserved for the needs 
stack DS.B      1             ;of the GEMDOS, BIOS, XBIOS functions we
                              ;will use. (Upstream of the
                              ;'stack' label). USP points on 'stack' and 
                              ;will be decremented when passing the 
                              ;parameters to the functions 
                              ;(MOVE.x source, -(SP) )
                              ;:Let's not forget that only the memory that
                              ;the program really needs is 
                              ;reserved after SETBLOCK.
     END


  The listing of the SETBLOCK macro instruction is found in the file
  INIT_TOS.L on this disk and is fully available to you.


 NB:You will therefore always have to make sure to reserve memory in the
 -- BSS zone upstream from the address pointed to by the label we
    named 'STACK'.
    There is no need to economize on space by reserving little memory,
    the size of the BSS segment does not affect the
    size of the PRG...
    

- I will now enumerate the various functions of the GEMDOS.

  Only the commonly used functions will be studied, for the
  others, you will have to refer to THE ST BIBLE, but I doubt you
  will need to use them in the near future...

  For each function, I will give you:

  .The CODE and the NAME of the function
      ----       ---
  .The PARAMETERS to pass
       ----------
  .The PURPOSE of the function
      ---

  .A MACRO INSTRUCTION that uses the studied function if it 
   can be frequently useful to us...

       All these macro instructions that we will create from the 
   GEMDOS, BIOS and XBIOS functions will be collected in the file
   MACROS.L and of course, you can use them whenever
   you desire.



                      *** THE GEMDOS FUNCTIONS ***
                      -------------------------------

$00 (TERM), no parameter
---
TERM allows to end the program and return to the calling program
(or parent program).
That is to say that if we use the TERM function of gemdos, the prg stops and
returns to the GEM DESKTOP (if the program has only been loaded from
the DESKTOP) or to the instruction following the calling instruction, of
the FATHER program. In this latter case, the PRG using the term function is
named SON program and has been loaded by the so called 'FATHER' program.

TERM      MACRO               ;TERM macro named 'TERM'
          CLR.W     -(SP)     ;TERM code
          TRAP      #1        ;GEMDOS call
          ENDM                ;MACRO end


$01 (CCONIN), no parameter
---
CCONIN waits for a character on the keyboard and displays it at the current
cursor position.
The function returns, the ASCII code of the pressed key in the low
byte of the low word of d0 and the SCANCODE of the
key in the low byte of the high word of d0.
The SCANCODE allows to identify keys that do not have an ASCII code
(such as function keys) and it also allows to distinguish between
keys that have the same ASCII code (such as numbers on the numeric
keypad and those on the main block)

The ASCII code and SCANCODE can be reached in this way for
example:

     MOVE      #$01,-(SP)     ;CCONIN CODE
     TRAP      #1             ;-->gemdos
     ADDQ.L    #2,SP          ;we reinitialize SP
     CMPI.B    #'A',d0        ;compare the low byte of the low word of
                              ;d0 with the ASCII code of
                              ;'A' that is $41
     BEQ       yes
     SWAP.W    d0             ;SWAP the 2 words of d0
     CMPI.B    #0,d0          ;is the SCANCODE nill ???
     BNE       no
     etc...
  
NB:You have noticed that I wrote:CMPI  #'A',d0.
-- Writing 'A' or the ASCII code of A that is $41 is identical.
   You can therefore for example replace MOVE  #$42,d0 with MOVE  #'B',d0
   ,this makes the listing more readable if you use instructions
   that must move data representing ASCII codes...
   The assembler will make the correction. (just as MOVE source,an is
   accepted and replaced by MOVEA source,an)
 
CCONIN    MACRO                    ;The equivalent macro
          MOVE      #$1,-(SP)
          TRAP      #1
          ADDQ.L    #2,SP
          ENDM

          
$02  (CCONOUT), WORD=ascii code
---
CCONOUT displays the character represented by the ASCII code that is passed
as a parameter on the stack at the current cursor position.

CCONOUT   MACRO     $\1         ;here, $\1 tells the assembler that we 
                                ;will pass a parameter to the macro.
          move      \1,-(SP)    ;we stack the parameter \1
          move      #2,-(SP)    ;then the code of CCONOUT   
          trap      #1          ;gemdos
          addq.l    #4,SP       ;correction of the stack   
          ENDM                  ;end of the MACRO

As you can see, we have just created a MACRO instruction
that accepts a PARAMETER.
It is indicated to the assembler by the directive: MACRO   $\1
   
The parameter can be for example:#'A' or d0 or #$48 etc...

Examples of using the macro CCONOUT (with a parameter):

     CCONOUT   #'a'

will display an 'a' on the screen

     MOVE      #'a',d0
     CCONOUT   d0

idem

     CCONOUT   #53

will display the character with ASCII code 53.



$03 (CAUXIN), no parameter
---
CAUXIN allows the reception of a character via the RS232 interface.
If there has been no error, the ASCII code of the character returns in
the low byte of d0.

     MOVE      #$3,-(SP)
     TRAP      #1
     ADDQ.L    #2,SP

$04 (CAUXOUT), WORD=ascii code
---
CAUXOUT causes the emission of the character whose ASCII code has been passed
as a parameter in the stack to the RS232 interface.

     MOVE      #'A',-(SP)     ;sends an 'A'
     MOVE      #$4,-(SP)
     TRAP      #1
     ADDQ.L    #4,SP


$05 (CPRNOUT),WORD=ascii code
---
CPRNOUT emits the character whose ASCII code has been stacked to 
the printer.
If the character was well sent, we obtain the word -1 in d0.
If the printer is unable to receive the character, we obtain a
word equal to 0 in d0.

     MOVE      #'A',-(SP)     ;we print an 'A'
     MOVE      #$5,-(SP)      ;CPRNOUT code
     TRAP      #1
     ADDQ.L    #4,SP

$06 (CRAWIO),WORD=$FF or ascii code
---
CRAWIO admits two types of parameters.
If the parameter is a WORD equal to $FF, CRAWIO tests if a key of
the keyboard IS pressed.(like INKEY in BASIC)
If a key was pressed, its ASCII code and its scan code enter
in d0, otherwise d0 remains unchanged.
If the parameter is different from $FF, this value is interpreted as
the ASCII code of a character to send to the screen.

INKEY     MACRO                   ;CRAWIO with $FF as parameter
          MOVE      #$FF,-(SP)
          MOVE      #$6,-(SP)
          TRAP      #1
          ENDM

  Example of using the INKEY macro:
  -------
test       INKEY               ;macro call  INKEY
          CMPI.B    #'A',d0   ;compare the ASCII code of d0 with 'A'
          BEQ       yes       ;key 'A' pressed? If yes, goes to 'yes'
          JMP       test      ;otherwise return to 'test'     
yes       NOP  

As long as the 'A' key is not pressed, we jump to 'test'.


$07 (CRAWCIN), no parameter
---
CRAWCIN waits for a key to be pressed.
The recognized character is not displayed, but the ASCII code and scan code
of the pressed key is transmitted to d0 in return.

WAIT      MACRO               ;waiting macro for a key
          MOVE      #$7,-(SP) ;CRAWCIN code
          TRAP      #1
          ADDQ.L    #2,SP     ;keys codes in d0.
          ENDM
              
$08 (CNECIN), no parameter
---
Identical function to CRAWCIN, except that here, pressing CONTROL-C ends the
PRG (like with PTERM), CONTROL-S stops the display, CONTROL-Q resumes
the display interrupted by control-s.

$09 (PRINT LINE), L-W= address of a string of characters terminated by a 
---                zero byte.

This function allows to display a string of characters on the screen.
The string of characters to be displayed must be located in the  DATA area
and must be terminated by a NULL byte.

PRINTLINE      MACRO     $\1       ;MACRO with \1 parameter: The address of
                                   ;the string of characters to be displayed.
               PEA       \1        ;STACK the address \1.
               MOVE      #$9,-(SP) ;PRINTLINE code
               TRAP      #1
               ADDQ.L    #6,SP
               ENDM
 
Example of using the macro PRINTLINE:

          PRINTLINE      laurent
          PRINTLINE      exp2
          PRINTLINE      exp3

          DATA

laurent   DC.B           'laurent PIECHOCKI 8,impasse Bellevue 57980',0
exp2      DC.B           53,54,56,80,45,25,0
exp3      DC.B           27,'E',7,'LAURENT',25,0


 NB:  To obtain effects such as screen erasing, line jumps... there are special codes that must be transmitted to
 ---  functions such as PRINTLINE,CCONOUT... 

      The codes preceded by the ASCII value 27 (ESC).
      -----------------------------------------------
      27,'E'  :erase the screen
      27,'B'  :positions the cursor one line lower
      27,'A'  :positions the cursor one line higher
      27,'C'  :positions the cursor one line further to the right
      27,'D'  :positions the cursor one line further to the left
      27,'J'  : clear the screen from the current cursor position
      27,'L'  : insert a line
      27,'M'  : delete the line where the cursor is
      27,'I'  : scroll the cursor and text upwards
      27,'H'  : position the cursor at line 1, column 1
      27,'K'  : delete a line from the cursor to the end of the line

      27,'Y',x,y : position the cursor at line x-32 and at column
                  y-32                             
                  ----
                  ----
      27,'b',x   : Change the text color to color number x
      27,'c',x   : Change the background color to color number x
      27,'f'     : Makes the cursor disappear
      27,'e'     : Makes the cursor reappear
      27,'j'     : Memorize the cursor position
      27,'k'     : Position the cursor at the memorized position
      27,'p'     : VIDEO-INVERSE mode of writing
      27,'q'     : Return to normal VIDEO


      Thus, if I write:  
      ------------------
        PRINTLINE  clear
   
        DATA

clear  DC.B       27,'E','laurent',0

      or
      --
        CCONOUT    #27
        CCONOUT    #'E'
        PRINTLINE  laurent

        DATA

laurent DC.B       'laurent',0


Clear the screen (ESC,'E') and display the string:'laurent'


$0A (READLINE), L-M pointing to a buffer
---
READLINE allows the entry of a certain quantity of characters on the screen.
(similar to INPUT in BASIC).
The string can be modified during editing with 
[Backspace] and [Delete] and will be validated by [Return] or [Enter].
(CONTROL-C ends the program)

You must provide the address of a buffer organized as follows:

In BSS area: DS.B   maximum number of characters to enter+2

You must have placed at the beginning of this buffer a BYTE representing the maximum
number of characters to enter (MOVE.B x,buffer) before using the
READLINE function.

After returning from the function:
In 'buffer'+1 is the number of entered characters
In 'buffer'+2 is the start of the entered character string.

READLINE       MACRO          $\1       ;parameter=buffer address
               PEA            \1
               MOVE           #$0A,-(SP)
               TRAP           #1
               ADDQ.L         #6,SP
               ENDM

   Example of using the READLINE macro:
   ---------------------
     MOVE.B    #5,resu   ;5 characters to enter
     LEA       resu,a5   ;address of 'resu' in a5
     READLINE  resu      ;readline
     addq.l    #2,a5     ;a5 points to the entered character string
     MOVE.B    #0,zero   ;places a NULL BYTE at the end of the string for
     PRINTLINE a5        ;display the string with PRINTLINE
     TOUCH                ;waiting for a key press
     DESKTOP              ;then exit the program     

     BSS

resu DS.B      7         ;reservation for READLINE
zero DS.B      1         ;reservation for the NULL byte that will end the 
                         ;string for PRINTLINE




$0B (CONIN STAT),no parameter
---
Calling this function returns a WORD in d0 equal to -1 if the keystroke buffer contains characters.
d0=0 if there are no characters available in this buffer.

     MOVE      #$B,-(SP)
     TRAP      #1
     ADDQ.L    #2,SP
     TST.W     D0
     BNE       nothing

$0E (SETDRIVE),WORD=drive number to activate.
---
SETDRIVE activates the drive whose number is passed as a parameter in
the system stack.
0=Drive A
1=Drive B etc...

In return, the function gives d0 which is organized in such a way that the
only active bit of d0 represents the last activated drive.
(active bit number=drive number)


DRIVE     MACRO     $\1            ;param. \1=drive number
          MOVE      \1,-(SP)      
          MOVE      #$E,-(SP)
          TRAP      #1
          ADDQ.L    #4,SP
          ENDM

     Example of use:
     ------------------
     DRIVE     #2

Drive C is activated.
If the last active Drive was drive B, we would have:

d0=%0000000000000010
                  |
                 \|/

           bit number1=drive B


$19 (CURRENT DISK),no parameter
---
This function allows you to know which DRIVE is ACTIVE.
The number of the active drive is returned in d0 in the previous format.

WATHDRIVE      MACRO                    ;Which is the active drive?
               MOVE      #$19,-(SP)
               TRAP      #1
               ADDQ.L    #2,SP     
               ENDM

$1A (SETDTA), L-M=address of the DTA buffer
---
SETDTA installs the DTA buffer used by some GEMDOS functions that operate on files.
This buffer must be 44 bytes in size, its address must be 
stacked in the system stack and must be EVEN.

To obtain an even address, you can reset the PC with the
BSS directive or use appropriate directives (but specific to
the assembler used): ALIGN.W for PROFIMAT
                        :CNOP 0,2 for METACOMCO

You can also simply make a correction by adding 1 BYTE
to a lower address (DS.B 1), this has the effect of increasing the value
of the DTA address: odd address+1=even address.

 
          PEA       buffer
          MOVE      #$1A,-(SP)
          TRAP      #1
          ADDQ.L    #6,SP

          BSS

buffer    DS.B      44


$20 (SUPER),L-M=0 or L-M=new SP value
---
Here is the function that allows you to switch to SUPERVISOR MODE.

If the parameter you provide is a L-M=0, SUPER will activate SUPERVISOR MODE and return the SP value in d0.
You must save this address because it will be essential to
return to USER MODE (To exit the program for example)

If you stack another L-M than 0, it will be interpreted as the new 
SP value and d0 will contain the old SP value.

SUPER     MACRO                    ;switching to SUPERVISOR MODE
          CLR.L     -(SP)
          MOVE.W    #$20,-(SP)
          TRAP      #1
          ADDQ.L    #6,SP
          MOVE.L    d0,sauv_sp     ;save SP in 'sauv_sp'
          ENDM

Of course, a L-M must be reserved in 'sauv_sp'!

To return to USER MODE (essential to exit the program
for example...):
Use the same function, but pass it the old
SP value that was saved in sauv_sp.

USER      MACRO                    ;returning to USER MODE
          MOVE.L    sauv_sp,-(SP)  ;restore SP
          MOVE.W    #$20,-(SP)
          TRAP      #1
          ADDQ.L    #6,SP
          ENDM



$2A  (GET DATE),no parameter
---
Allows you to obtain the DATE of the GEM desktop clock in d0 as follows:

Bits 0 to  4=day
Bits 5 to  8=month
Bits 9 to 15=(year-1980)

     MOVE      #$2A,-(SP)
     TRAP      #1
     ADDQ.L    #2,SP

Example: if d0=%0001000000100001

The date is:

DAY:bits 0 to 4 :%00001=the 1st
MONTH:bits 5 to 8 :%00001=January
YEAR :bits 9 to 15:%0001000=8+1980=1988

$2B (SET DATE),WORD=date 
---
SET DATE allows setting the GEM clock to the date you provide as a parameter.

The date (WORD) is in the format previously described.

bits 0 to 4: day
bits 5 to 8: month
bits 9 to 15: (year-1980)

If the date is incorrect (45/20/1745...), d0 returns with the value -1,
otherwise, it returns with the value 0.

     MOVE      #%00010000000100001,-(SP)     ;January 1st, 1988
     MOVE      #$2A,-(SP)
     TRAP      #1
     ADDQ.L    #4,SP


$2C (GET TIME),no parameter
---
GET TIME returns the time from the GEM clock in d0 in the form:

bits 0 to 4  :(seconds/2)
bits 5 to 10 :minutes 
bits 11 to 15:hour 

     Example:

test MOVE      #$2C,-(SP)     ;GET TIME
     TRAP      #1
     ADDQ.L    #2,SP
                              ;d0 contains the time
     AND.W     #%11111,d0     ;we MASK bits 0 to 4 of d0:
                              ;bits 5 to 15 of d0 are therefore cleared.
                              ;it leaves the seconds.

     MULS      #2,d0          ;x2 because seconds=(seconds/2) in d0
     CMPI      #30,d0         ;do we have seconds=30?
     BEQ       yes            ;if yes: go to 'yes'
     JMP       test           ;otherwise, return and request the time again. 

$2D (SET TIME),WORD=time
---
SET TIME sets the time of the GEM clock with the parameter provided.

The time must be coded in the form:

bits 0 to 4  :(seconds/2)
bits 5 to 10 :minutes 
bits 11 to 15:hours 

     Example:

     MOVE      #%0001000000100001,-(SP)
     MOVE      #$2D,-(SP)
     TRAP      #1
     ADDQ.L    #4,SP

We set the clock to 2h, 1 min, 2 sec


$31 (KEEP PROCESS),WORD=0,L-M=number of bytes to protect.
---
KEEP PROCESS, like PTERM, ends the program and returns to the 'parent' program.

With PTERM, the exited program is permanently erased from memory,
while with KEEP PROCESS, a certain amount of BYTES in memory (parameter 2) is reserved and the program to exit is placed there.

This is important for interrupt-driven programs, for example, 
we will talk about this again... 

KEEP      MACRO     $\1            ;parameter=number of bytes to reserve
          CLR.W     -(SP)
          MOVE.L    #\1,-(SP)     
          MOVE      #$31,-(SP)
          TRAP      #1
          ADDQ.L    #8,SP
          ENDM

Example of use:

          KEEP   1024

We place the PRG in the reserved KO and exit...

NB: Be careful that you reserve enough memory...
--

$3C (CREATE),WORD=file attribute,L-M=address of the file name
---

CREATE allows creating a file in which you can place data.

The first parameter is the file attribute:

0=file accessible in Read and Write
1=file accessible in Read only
2=invisible file
4=system file (invisible to desktop)
8=volume label file (invisible to desktop)

The second parameter is the address pointing to the file name:

Organized like this:      'A:\file\name.ext',0

If the name of the program to create is 'name.ext' and if it is in the
'file' (unnecessary if it is not in a file...).
'A:' indicates that it is on the floppy disk unit A.
The character string must end with a NULL byte.

In return, CREATE returns in d0 the FILE HANDLE number of the file.
This number is used to distinguish the different external programs loaded.


CREATE     MACRO     $\1,$\2,$\3         ;CREATE with 3 parameters
          MOVE      #\1,-(SP)           ;\1=file attribute
          PEA       \2                  ;\2=address of the name 
          MOVE      #$3C,-(SP)
          TRAP      #1
          ADDA.L    #8,SP
          MOVE      d0,\3               ;\3=address to save d0.
          ENDM

Example of use:

          CREATE     0,prg,handle        ;file in Read/Write mode

          DATA

prg       DC.B      'A:\laurent.gag',0  ;name of the file to create

          BSS

handle    DS.W      1                   ;1 Word for the handle