Difference between revisions of "83Plus:BCALLs:4027"

From WikiTI
Jump to: navigation, search
(more info)
(Explained how to call this from a shell)
 
Line 19: Line 19:
  
 
== Comments ==
 
== Comments ==
This routine is the standard way of exiting a Flash Application.  (Although there are other ways, in practice this is the only one you'll ever need.  Note that simply returning with the 'ret' statement does not work.)  In contrast, normal RAM assembly programs should '''never''' use this routine.  (In the middle somewhere are scripts and hooks; don't use this routine in a hook or script unless you really know what you're doing.)
+
This routine is the standard way of exiting a Flash Application.  (Although there are other ways, in practice this is the only one you'll ever need.  Note that simply returning with the 'ret' statement does not work.)  In contrast, normal RAM assembly programs should never use this routine, unless you know what you're doing.  (In the middle somewhere are scripts and hooks; don't use this routine in a hook or script unless you really know what you're doing.)
  
 
TI suggests that this routine be called using B_JUMP rather than B_CALL.  In fact it doesn't matter; either way this routine never returns (and of course, using B_CALL saves you two bytes.)  This routine will reset the hardware stack, FPS, and OPS to their default states, so you can call it at any point in the middle of your app.
 
TI suggests that this routine be called using B_JUMP rather than B_CALL.  In fact it doesn't matter; either way this routine never returns (and of course, using B_CALL saves you two bytes.)  This routine will reset the hardware stack, FPS, and OPS to their default states, so you can call it at any point in the middle of your app.
Line 31: Line 31:
  
 
(Note that PutAway, unlike JForceCmdNoChar, does need to be jumped to -- a B_CALL would not work in this case.)
 
(Note that PutAway, unlike JForceCmdNoChar, does need to be jumped to -- a B_CALL would not work in this case.)
 +
 +
=== Doing it from a RAM Program ===
 +
The only reason it isn't safe to do JForceCmdNoChar from a RAM program is that your memory will not be freed when you exit. Therefore, you can safely do so from a nostub RAM program---that has not been launched from a shell---if you copy into scrap RAM and run a stub that frees your memory and then runs JForceCmdNoChar; stack level is not important. However, you might cause a crash if you try this from within a shell. (For example, Doors CS, which doesn't respect programs that don't want to be run from a shell. Although, on all OS versions I know of, page 7 will be in the 4000h range when running from the OS, so you might be able to tell by reading from port 6.)
 +
; It might be wise to IM 1 \ EI here.
 +
ld hl, stub
 +
ld de, 8000h ; or any scrap RAM
 +
ld bc, 12
 +
ldir
 +
jp 8000h
 +
stub:
 +
ld hl, 9D95h
 +
ld de, (asm_prgm_size) ; 89ECh
 +
b_call(_DelMem)
 +
b_call(_JForceCmdNoChar)
  
 
== Example ==
 
== Example ==
 
  BJUMP JForceCmdNoChar
 
  BJUMP JForceCmdNoChar

Latest revision as of 11:04, 4 February 2013


Synopsis

Official Name: JForceCmdNoChar

BCALL Address: 4027

Exits the current application and returns to the homescreen.

Inputs

  • None

Outputs

  • None

Destroys

  • All (but it doesn't matter)

Comments

This routine is the standard way of exiting a Flash Application. (Although there are other ways, in practice this is the only one you'll ever need. Note that simply returning with the 'ret' statement does not work.) In contrast, normal RAM assembly programs should never use this routine, unless you know what you're doing. (In the middle somewhere are scripts and hooks; don't use this routine in a hook or script unless you really know what you're doing.)

TI suggests that this routine be called using B_JUMP rather than B_CALL. In fact it doesn't matter; either way this routine never returns (and of course, using B_CALL saves you two bytes.) This routine will reset the hardware stack, FPS, and OPS to their default states, so you can call it at any point in the middle of your app.

Note that this routine (like most OS routines that switch from one app to another) will call the current cxPPutAway routine, followed by the current cxPutAway routine. If you install your own PutAway routine, it should do something like the following in order to call the standard cleanup code:

AppPutAway:
    ; clean up temporary memory allocations, flags, etc.
    B_CALL ReloadAppEntryVecs
    B_JUMP PutAway

(Note that PutAway, unlike JForceCmdNoChar, does need to be jumped to -- a B_CALL would not work in this case.)

Doing it from a RAM Program

The only reason it isn't safe to do JForceCmdNoChar from a RAM program is that your memory will not be freed when you exit. Therefore, you can safely do so from a nostub RAM program---that has not been launched from a shell---if you copy into scrap RAM and run a stub that frees your memory and then runs JForceCmdNoChar; stack level is not important. However, you might cause a crash if you try this from within a shell. (For example, Doors CS, which doesn't respect programs that don't want to be run from a shell. Although, on all OS versions I know of, page 7 will be in the 4000h range when running from the OS, so you might be able to tell by reading from port 6.)

	; It might be wise to IM 1 \ EI here.
	ld	hl, stub
	ld	de, 8000h ; or any scrap RAM
	ld	bc, 12
	ldir
	jp	8000h
stub:
	ld	hl, 9D95h
	ld	de, (asm_prgm_size) ; 89ECh
	b_call(_DelMem)
	b_call(_JForceCmdNoChar)

Example

BJUMP JForceCmdNoChar