Difference between revisions of "83Plus:BCALLs:4027"
(Explained how to call this from a shell) |
|||
| (3 intermediate revisions by 3 users not shown) | |||
| Line 6: | Line 6: | ||
== Synopsis == | == Synopsis == | ||
'''Official Name:''' JForceCmdNoChar | '''Official Name:''' JForceCmdNoChar | ||
| + | |||
'''BCALL Address:''' 4027 | '''BCALL Address:''' 4027 | ||
| − | + | Exits the current application and returns to the homescreen. | |
| − | + | ||
| − | Exits | + | |
=== Inputs === | === Inputs === | ||
| Line 17: | Line 16: | ||
* None | * None | ||
=== Destroys === | === Destroys === | ||
| − | * All (but it doesn't matter | + | * All (but it doesn't matter) |
== Comments == | == Comments == | ||
| − | This is the | + | 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 [[83Plus:RAM:858F|cxPPutAway]] routine, followed by the current [[83Plus:RAM:8591|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 [[83Plus:BCALLs:4C36|ReloadAppEntryVecs]] | ||
| + | B_JUMP [[83Plus:BCALLs:403C|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 == | == Example == | ||
| − | + | BJUMP JForceCmdNoChar | |
| − | BJUMP JForceCmdNoChar | + | |
| − | + | ||
Latest revision as of 10:04, 4 February 2013
Contents
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
