Emulator Enhanced Z80 Instructions v6.10

  1. MUL8
  2. MUL16
  3. DIV16
  4. DIV32
  5. IMUL8
  6. IMUL16
  7. IDIV16
  8. IDIV32
  9. SHELL
  10. MOUSE
  11. IPORT
  12. OPORT
  13. RMEM
  14. WMEM
  15. SSPD
  16. GSPD
  17. OPEN
  18. CLOSE
  19. READ
  20. WRITE
  21. SEEK
  22. ERROR
  23. FINDFIRST
  24. FINDNEXT
  25. LOAD
  26. CHDIR
  27. GETDIR
  28. PATHOPEN
  29. CLOSEALL
  • Multiply two 8 bit values
  • Multiply two 16 bit values
  • Divide two 16 bit values
  • Divide two 32 bit values
  • Multiply two 8 bit signed values
  • Multiply two 16 bit signed values
  • Divide two 16 bit signed values
  • Divide two 32 bit signed values
  • PC DOS Shell function
  • PC Mouse functions
  • Input from PC port
  • Output to PC port
  • Read from PC memory address
  • Write to PC memory address
  • Set CPU speed
  • Get Current CPU speed
  • Open PC file
  • Close PC file
  • Read record from PC file
  • Write record to PC file
  • Move PC file pointer
  • Build PC error mesage
  • Find first matching directory entry
  • Find next directory entry
  • Load object file from PC directory
  • Change PC's working directory
  • Get current working directory
  • Open PC file using default paths & hard disk paths
  • Close single file or all files

Return to emulator documentation


MUL8 D, E

Operation:   Emulator Instruction

Format:
                 Opcode     Operands

     DEFB  EDH

     DEFB  20H

Description:

Multiply register D by register E and return result in DE.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: None

Example:

100       LD     D,15H    ; load D with 15h
110       LD     E,40H    ; load E with 40h
120       DEFB   EDH      ; multiply 8 bit unsigned values
130       DEFB   20H

After execution DE will contain 540h


MUL16 HL, DE

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  21H

Description:

Multiply register HL by register DE and return result in HL:DE.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: None

Example:

100       LD     HL,2015H    ; load HL with 2015h
110       LD     DE,0140H    ; load DE with 140h
120       DEFB   EDH         ; multiply 16 bit unsigned values
130       DEFB   21H

After execution HL will contain 28h and DE will contain 1A40h


DIV16 HL, DE

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  22H

Description:

Divide register HL by register DE and return result in HL and remainder in DE.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

P/V Set if divide by zero; reset otherwise
C: Set if divide by zero; reset otherwise

Example:

100       LD     HL,2175H   ; load HL with 2175h
110       LD     DE,40H     ; load DE with 40h
120       DEFB   EDH        ; divide 16 bit unsigned values
130       DEFB   22H

After execution HL will contain 85h and DE will contain 35h


DIV32 HL:DE, IX:IY

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  23H

Description:

Divide registers HL:DE by registers IX:IY and return result in HL:DE and remainder in IX:IY.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

P/V Set if divide by zero; reset otherwise
C: Set if divide by zero; reset otherwise

Example:

100       LD     DE,2175H   ; load HL:DE with 402175h
110       LD     HL,40H
120       LD     IX,4578H   ; load IX:IY with 14578h
130       LD     IY,0001H
120       DEFB   EDH        ; divide 32 bit unsigned values
130       DEFB   23H

After execution HL:DE will contain 32h and IX:IY will contain 9005h


IMUL8 D, E

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  24H

Description:

Perform a signed multiply of register D and register E and return result in DE.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

P/V Set if overflow; reset otherwise
C: Set if overflow; reset otherwise

Example:

100       LD     D,15H   ; load D with 15h
110       LD     E,40H   ; load E with 40h
120       DEFB   EDH     ; multiply 8 bit signed values
130       DEFB   24H

After execution DE will contain 540h


IMUL16 HL, DE

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  25H

Description:

Perform a signed multiply of register HL by register DE and return result in HL:DE.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

P/V Set if overflow; reset otherwise
C: Set if overflow; reset otherwise

Example:

100       LD     HL,2015H   ; load HL with 2015h
110       LD     DE,0140H   ; load DE with 140h
120       DEFB   EDH        ; multiply 16 bit signed values
130       DEFB   25H

After execution HL will contain 28h and DE will contain 1A40h


IDIV16 HL, DE

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  26H

Description:

Perform a signed divide of register HL by register DE and return result in HL and remainder in DE.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

P/V Set if overflow or divide by zero; reset otherwise
C: Set if overflow or divide by zero; reset otherwise

Example:

100       LD     HL,2175H  ; load HL with 2175h
110       LD     DE,40H    ; load DE with 40h
120       DEFB   EDH       ; divide 16 bit signed values
130       DEFB   26H

After execution HL will contain 85h and DE will contain 35h


IDIV32 HL:DE, IX:IY

Operation:   Emulator Instruction

Format:

         Opcode    Operands

   DEFB  EDH

   DEFB  27H

Description:

Divide registers HL:DE by registers IX:IY and return result in HL:DE and remainder in IX:IY.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

P/V Set if overflow or divide by zero; reset otherwise
C: Set if overflow or divide by zero; reset otherwise

Example:

100       LD     DE,2175H   ; load HL:DE with 402175h
110       LD     HL,40H
120       LD     IX,4578H   ; load IX:IY with 14578h
130       LD     IY,0001H
120       DEFB   EDH        ; divide 32 bit signed values
130       DEFB   27H

After execution HL:DE will contain 32h and IX:IY will contain 9005h


SHELL A, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  28H

Description:

Shell to DOS and execute the command pointed to by register HL. If the command is null (only a zero terminator) then this function shells to a DOS prompt. If Z flag is set then the command executed ok and register BC contains return code else register A contains the error number.

If register A is non-zero then a push any key to continue message will be displayed when the command finishes before the TRS-80 screen is re-displayed.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if shell command ok; reset otherwise

Example:

100       LD     HL,CMD   ; load HL with address of command
110       LD     A,01H    ; display push any key to continue message
120       DEFB   EDH      ; execute shell command
130       DEFB   28H
          .
          .
          .
200 CMD   DEFM   ‘DIR’    ; zero terminated command to execute
210       DEFB   00H


MOUSE A, BC, DE, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  29H

Description:

This function allows access to the PC mouse, there are 6 sub-functions.

Function 1: Get X corr, Y corr and buttons

Before:
            B =   1

After:
           HL = mouse cursor X value
           DE = mouse cursor Y value
           A =   button status
                     bit 0 reset if right button pushed
                  
   bit 1 reset if middle button pushed (left & right pushed for 2 button mice)
                     bit 2 reset if left button pushed

Function 2: Set X corr, Y corr and set button status

Before:
            B =   2
            C =   button status
                     bit 0 set or reset right button pushed
                     bit 1 set or reset left button pushed

After:
          flags = Z flag set if successful

Function 3: Get max X corr, Y corr and sensitivity

Before:
            B = 3

After:
           HL = mouse max X corr value
           DE = mouse max Y corr value
           A =   sensitivity (0 to 3); 3 is most sensitive

Function 4: Set max X corr, Y corr and sensitivity

Before:
            B =    4
            HL = mouse max X corr value
            DE = mouse max Y corr value
            A =   sensitivity (0 to 3); 3 is most sensitive
After:
            flags = Z flag set if successful

Function 5: Get mouse type

Before:
            B = 5

After:
           A = mouse type (0=two button, 1=three button)

Function 6: Get X corr, Y corr and buttons

Before:
            B = 6

After:
          HL = mouse cursor X value (0 - 1024)
          DE = mouse cursor Y value (0 -1024)
          C =
   buttons currently pushed
                    bit 4 set if right button pushed
                    bit 5 set if left button pushed
          B =   buttons pushed since last reset using function #2
                   bit 4 set if right button was pushed
                   bit 5 set if left button was pushed


M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: set according to function type

Example:

100       LD     B,01H   ; load B with get X, Y and buttons command
110       DEFB   EDH     ; execute mouse command
120       DEFB   29H
130       .              ; HL contains X cursor value
140       .              ; DE contains Y cursor value
150       .              ; A contains button status


IPORT A, (HL)

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  2AH

Description:

Read the PC port pointed to by register HL into register A.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: none

Example:

100       LD     HL,0201H   ; read PC game port
110       DEFB   EDH
120       DEFB   2AH



OPORT (HL), A

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  2BH

Description:

Write register A to the PC port pointed to by register HL.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: none

Example:

100       LD     A,0FFH     ; load A with FFh
110       LD     HL,0201H   ; write register A to PC game port
120       DEFB   EDH
130       DEFB   2BH


RMEM A, (DE:HL)

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  2CH

Description:

Read the PC memory address pointed to by register DE:HL into register A. Register DE contains the PC segment and HL contains the address within the segment.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: none

Example:

100       LD     DE,0040H   ; set segment to 0040h
110       LD     HL,0000H   ; set address to 0000h
130       DEFB   EDH        ; read address 0040h:0000h into A
130       DEFB   2CH


WMEM (DE:HL), A

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  2DH

Description:

Write register A to the PC memory address pointed to by register DE:HL. Register DE contains the PC segment and HL contains the address within the segment.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: none

Example:

100       LD     A,0FFH     ; load A with FFh
110       LD     DE,0040H   ; set segment to 0040h
120       LD     HL,0000H   ; set address to 0000h
130       DEFB   EDH        ; read address 0040h:0000h into A
140       DEFB   2DH


SSPD A

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  2EH

Description:

Set CPU speed to value defined by register A.

bits 0-1
   00   2/1.77mhz
   01   4mhz
   10   1mhz
   11   8mhz

bit 2   Turbo speed if set

bit 3   Speed port locked if set

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: none

Example:

100       LD A,0CH          ; Set turbo speed & lock port
110       DEFB EDH          ; execute speed set command
120       DEFB 2EH


GSPD A

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  2FH

Description:

Get CPU speed and return value in register A.

bits 0-1
   00   2/1.77mhz
   01   4mhz
   10   1mhz
   11   8mhz

bit 2   Turbo speed if set

bit 3   Speed port locked if set

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected: none

Example:

100       DEFB EDH          ; get current CPU speed
110       DEFB 2FH


OPEN BC, DE, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  30H

Description:

Opens the file specified by the path pointed to by HL. The path must conform to PC standards and be zero terminated. The BC register is used to define the type of file access. If the file is being created the DE register is used to define the access permission.

If the open is successful the Z flag is set and the file’s channel is returned in the DE register else the Z flag is reset, DE is loaded with FFFFh and the A register contains the error number.

File Access:

bits 0-1 of BC:
     00 open file read only
     01 open file write only
     10 open file read/write

bit 6 of BC create file if doesn't exist (create)
bit 7 of BC used only with bit 6 set. If file exists, an error is returned
bit 9 of BC if file exists then file is truncated (truncate)
bit 10 of BC the file pointer will be set to the end of the file prior to each write (append)

File Access Permission:

bit 7 of DE if set, permission to write to file
bit 8 of DE if set, permission to read to file

only has effect when file is being created. To allow read & write access both bits must be set.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file opened ok; reset otherwise

Example:

100       LD     HL,PCFN     ; load HL with address of filespec
110       LD     BC,0241H    ; create or truncate file & open in write only mode
120       LD     DE,0180H    ; create file with read & write permission
130       DEFB   EDH         ; execute open command
140       DEFB   30H
150       JR     NZ,ERROR    ; jump if error
160       LD     (CHAN),DE   ; save channel number of I/O
          .
          .
          .
200 PCFN  DEFM  ‘PCFILE.CMD’ ; zero terminated filespec to open
210       DEFB  00H
220 CHAN  DEFW 0000H         ; saved channel number


CLOSE DE

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  31H

Description:

Closes file on channel specified by the DE register. The Z flag is set if close successful else the Z flag is reset and the A register contains the error number.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file closed ok; reset otherwise

Example:

100       LD     DE,(CHAN)  ; load DE with channel number of file to close
110       DEFB   EDH        ; execute close command
120       DEFB   31H
130       JR     NZ,ERROR   ; jump if error
          .
          .
          .
200 CHAN  DEFW   0000H      ; saved channel number


READ BC, DE, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  32H

Description:

Read the number of bytes defined by register BC into the buffer area pointed to by register HL from the channel defined by register DE. If the Z flag is set then the read was successful, register BC will contain the number of bytes actually read and the buffer will contain the data read. If BC is less than the value before execution of the instruction and there was no error then the end of file was reached. If an read error occurred then the Z flag is reset and BC will contain the number of bytes actually read, & register A will contain the error number.

It is possible to read 0001h to FFFEh bytes in a single read.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file read ok; reset otherwise

Example:

100       LD     HL,(BUFF)   ; load HL with pointer to buffer
110       LD     DE,(CHAN)   ; load DE with channel number of file to read from
120       LD     BC,0100H    ; load BC with bytes to read
130       DEFB   EDH         ; execute read command
140       DEFB   32H
150       JR     NZ,ERROR    ; jump if error
160       LD     A,B         ; check if all bytes read
170       CP     01H
180       JR     NZ,EOF      ; jump if not
190       LD     A,C
200       CP     00H
210       JR     NZ,EOF      ; jump if not
          .
          .
          .
300 BUFF  DEFS   0100H       ; define a 256 byte buffer
310 CHAN  DEFW   0000H       ; saved channel number


WRITE BC, DE, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  33H

Description:

Write the number of bytes defined by register BC from the buffer area pointed to by register HL to the channel defined by register DE. If the Z flag is set then the write was successful, register BC will contain the number of bytes actually read and the buffer will be unchanged. If an read error occurred then the Z flag is reset and BC will contain the number of bytes actually written & register A will contain the error number.

It is possible to write 0001h to FFFEh bytes in a single write. If register BC contains 0000h then the file will be truncated at the current file pointer location.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file write ok; reset otherwise

Example:

100       LD     HL,(BUFF) ; load HL with pointer to buffer
110       LD     DE,(CHAN) ; load DE with channel number of file to write to
120       LD     BC,0100H  ; load BC with bytes to write
130       DEFB   EDH       ; execute write command
140       DEFB   33H
150       JR     NZ,ERROR  ; jump if error
          .
          .
          .
300 BUFF  DEFS   0100H    ; define a 256 byte buffer
310 CHAN  DEFW   0000H    ; saved channel number


SEEK C, DE, HL

Operation:   Emulator Instruction (DOS Int 21h Function 42h)

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  34H -or- 3DH

Description:

Set the file position to the 32 bit signed integer value pointed to by register HL using the method defined in register C. If successful the Z flag is set and the 32 bit signed integer value pointed to by HL is updated with the new file position. If an error occurs then the Z flag is reset and register A contains the error number.

Using method 1 or 2 it is possible to position beyond the start of the file without an error, an error will occur upon a subsequent read or write to the file.

Method code:

C = 0 absolute byte offset from beginning of file (always positive double integer)
C = 1 byte offset from current location (positive or negative double integer)
C = 2 byte offset from end of file (positive or negative double integer)

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file seek ok; reset otherwise

Example:

100        LD     HL,0100H    ; save new file position (00000100h)
110        LD     (BUFF),HL
120        LD     HL,0000H
130        LD     (BUFF+2),HL
140        LD     HL,(BUFF)   ; load HL with pointer to buffer (at least 4 bytes)
150        LD     DE,(CHAN)   ; load DE with channel number of file to write to
160        LD     C,00H       ; load BC with method code (absolute)
170        DEFB   EDH         ; execute seek command
180        DEFB   34H
190        JR     NZ,ERROR    ; jump if error
           .
           .
           .
300 BUFF   DEFS   0100H       ; define a 256 byte buffer
310 CHAN   DEFW   0000H       ; saved channel number


ERROR A, BC, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  35H

Description:

Builds error message in buffer pointed to by register HL for the error number in register A. If the length of the buffer is not able to hold the entire message the message is truncated to fit and register A contains range error, else register A is set to zero.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: always set

Example:

100        LD     DE,(CHAN)  ; load DE with channel number of file to close
110        DEFB   EDH        ; execute close command
120        DEFB   31H
130        JR     NZ,ERROR   ; jump if error, error number is in register A
           .
           .
           .
200 ERROR  LD     HL,ERRMSG  ; load HL with pointer to message buffer
210        DEFB   EDH        ; execute error message command
220        DEFB   35H        ; upon return the error message is in buffer, zero terminated
           .
           .
           .
300 ERRMSG DEFS   0100H      ; define a 256 byte buffer
310 CHAN   DEFW   0000H      ; saved channel number


FINDFIRST BC, DE, HL

Operation:   Emulator Instruction (DOS Int 21h Function 4Eh)

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  36H

Description:

Given a file specification in the form of an ASCIIZ string, searches the default or specified directory on the default or specified disk drive for the first matching file. If a match is found the buffer pointed to by register HL will be loaded with the file data found and the Z flag is set, else the Z flag is reset and register A contains the error number.

Wildcard characters ? and * are allowed in the filename. Files found are based on the attributes set in the DE register.

WARNING: Buffer must be at least 43 bytes long.

File Attributes:

bit 0 of DE read-only
bit 1 of DE hidden
bit 2 of DE system
bit 3 of DE volume labels (if set only volume labels are returned)
bit 4 of DE subdirectory; entry excluded from normal searches
bit 5 of DE archive

Buffer Structure:

bytes 0-20   reserved for DOS on subsequent calls
byte   21      attribute of matching file
bytes 22-23 file time
bytes 24-25 file date
bytes 26-29 file size (32 bit integer)
bytes 30-42 filename & extension in form of ASCIIZ string

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file match found; reset otherwise

Example:

100       LD     HL,BUFF   ; load HL with address of filespec
110       LD     BC,43     ; buffer must be 43 bytes long
120       LD     DE,01H    ; find all normal and read only files
130       DEFB   EDH       ; execute findfirst command
140       DEFB   36H
150       JR     NZ,ERROR  ; jump if no matching files
          .                ; buffer filled with directory entry, filename starts at byte 30
          .
          .
200 BUFF  DEFM   ‘*.*’     ; zero terminated filespec to search for
210       DEFB   00H
220       DEFS   39        ; buffer must be 43 bytes long


FINDNEXT BC, HL

Operation:   Emulator Instruction (DOS Int 21h Function 4Fh)

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  37H

Description:

Assuming a successful previous FINDFIRST function the FINDNEXT function finds the next file in the default or specified directory on the default or specified disk drive that matches the original file specification. If a match is found the buffer pointed to by register HL will be loaded with the file data found and the Z flag is set, else the Z flag is reset and register A contains the error number.

WARNING: Buffer must be at least 43 bytes long.

Buffer Structure:

bytes 0-20 reserved for DOS on subsequent calls
byte 21 attribute of matching file
bytes 22-23 file time
bytes 24-25 file date
bytes 26-29 file size (32 bit integer)
bytes 30-42 filename & extension in form of ASCIIZ string

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file match found; reset otherwise

Example:

100       LD     HL,BUFF  ; load HL with address of filespec
110       LD     BC,43    ; buffer must be 43 bytes long
120       LD     DE,01H   ; find all normal and read only files
130       DEFB   EDH      ; execute findnext command
140       DEFB   37H
150       JR NZ,ERROR     ; jump if no more matching files
          .               ; buffer filled with directory entry,
          .               ; filename starts at byte 30
          .
200 BUFF  DEFS   43       ; buffer must be 43 bytes long


LOAD BC, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  39H

Description:

Open and load the object file specified by the path pointed to by HL. The path must conform to PC standards and be zero terminated.

If the load is successful the Z flag is set and if the object file contained an execution address then the C flag is also set and register BC contains the execution address. If the file was not found or was not a valid object file then the Z flag is reset and the A register contains the error number.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file opened ok; reset otherwise

Example:

100       LD     HL,PCFN      ; load HL with address of filespec
110       DEFB   EDH          ; execute load command
120       DEFB   39H
130       JR     NZ,ERROR     ; jump if error
140       JR     NC,EXIT      ; exit if no exec address found
150       DI                  ; disable interrupts
150       PUSH   BC           ; push exec address on stack
160       RET                 ; execute loaded program
          .
          .
          .
200 PCFN  DEFM   ‘GALAXY.CMD’ ; zero terminated filespec to load
210       DEFB   00H


CHDIR HL

Operation:   Emulator Instruction

Format:

           Opcode    Operands

   DEFB  EDH

   DEFB  3AH

Description:

Changes the current drive and directory to the path pointed to by the register HL. If the command is successful the Z flag is set else the Z flag is reset and the A register contains the error number.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file chdir ok; reset otherwise

Example:

100       LD     HL,BUFF    ; load HL with address of path
110       DEFB   EDH        ; execute chdir command
120       DEFB   3AH
130       JR     NZ,ERROR   ; jump if error
          .
          .
          .
200 BUFF  DEFM   ‘C:\TRS80’ ; zero terminated path to change to
210       DEFB   00H


GETDIR BC, HL

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  3BH

Description:

Gets the current working directory and drive. The path and drive are stored in the buffer pointed to by the register HL. If the command is successful the Z flag is set else the Z flag is reset and the A register contains the error number. If the full path is longer than the buffer an error will occur.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file getdir ok; reset otherwise

Example:

100       LD     HL,BUFF  ; load HL with address of path
110       LD     BC,128   ; save length of buffer
120       DEFB   EDH      ; execute getdir command
130       DEFB   3BH
140       JR     NZ,ERROR ; jump if error
          .               ; upon return the path is in buffer,
          .               ; zero terminated
          .
200 BUFF  DEFS 128        ; create a buffer long enough to hold path


PATHOPEN BC, DE, HL

Operation:   Emulator Instruction

Format:

           Opcode    Operands

   DEFB  EDH

   DEFB  3EH

Description:

Opens the file specified by the path pointed to by HL. The path must conform to PC standards and be zero terminated. The BC register is used to define the type of file access. If the file is being created the DE register is used to define the access permission.

If the open is successful the Z flag is set and the file’s channel is returned in the DE register else the Z flag is reset, DE is loaded with FFFFh and the A register contains the error number.

Unlike the OPEN command this command is used in writing floppy & hard disk drivers for TRS-80 DOS's.

If no path is given the current floppy path will be used (set in the floppy selection screen). If no extension is given the extension .DSK will be used.

If 'HARDX-YY' (where X= '1', '3' or '4' and YY= a value of 0-7) is given as the filename then one of the 8 hard disk filenames (16 in the Model 3/4 emulator) defined in the configuration screen will be opened.

File Access:

bits 0-1 of BC:
     00 open file read only
     01 open file write only
     10 open file read/write

bit 6 of BC create file if doesn't exist (create)
bit 7 of BC used only with bit 6 set. If file exists, an error is returned
bit 9 of BC if file exists then file is truncated (truncate)
bit 10 of BC the file pointer will be set to the end of the file prior to each write (append)

File Access Permission:

bit 7 of DE if set, permission to write to file
bit 8 of DE if set, permission to read to file

NOTE: Only has effect when file is being created. To allow read & write access both bits must be set.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file opened ok; reset otherwise

Example:

100       LD     HL,HARD    ; load HL with address of filespec
110       LD     BC,0002H   ; open in read/write mode
120       DEFB   EDH        ; execute open command
130       DEFB   3EH
140       JR     NZ,ERROR   ; jump if error
150       LD     (CHAN),DE  ; save channel number of I/O
          .
          .
          .
200 HARD  DEFM   ‘HARD4-0’  ; open defined Model 4 mode hard drive #0
210       DEFB   00H
220 CHAN  DEFW   0000H      ; saved channel number

If in the configuration screen the Model 4 drive #0 is defined as:

C:\TRS-80\LDOS0.HDV

Then, if the file exists, it will be opened for read/write I/O and the channel number returned in DE.

 


CLOSEALL DE

Operation:   Emulator Instruction

Format:

          Opcode    Operands

   DEFB  EDH

   DEFB  3FH

Description:

Closes file on channel specified by the DE register or closes all open files if DE=FFFFh. The Z flag is set if close successful else the Z flag is reset and the A register contains the error number.

If DE=FFFFh then no error is reported even if no files are closed.

M CYCLES: 4      T STATES: 4       4 MHZ E.T.: 1.00

Condition Bits Affected:

Z: Set if file closed ok; reset otherwise

Example:

100       LD     DE,FFFFH  ; load DE FFFFh to close all files
110       DEFB   EDH       ; execute close command
120       DEFB   3FH
130       JR     NZ,ERROR  ; jump if error
          .
          .
          .