HP 42s Stack Save

Stack Save allows for easy saving and restoring of stack values from within other programs. Traditionally, one must perform tedious manual saving and restoring from within each program. Stack Save simplifies this process, requiring only a few options to be set, and calls to SAVE and RESTORE to be made at the beginning and end of the program.

Usage

SAVE

When run, SAVE will save a copy of the entire stack, and optionally REGS and LAST X. The following options control the behavior of SAVE, and should be set prior to calling it:

ALPHA Register
A unique name that will be appended to the names of the temporary variables used to store the stack. Limited to 4 characters. Using a longer string will not cause errors, but it will be truncated silently.
Flag 91
When set, SAVE will store a copy of REGS along with the stack. Note that flag 91 must have the same state when calling both SAVE and RESTORE. REGS itself will not be modified by calling SAVE, only copied.
Flag 92
Controls LAST X behavior. When clear, the current X value at the time of calling SAVE will become the new LAST X value upon calling RESTORE. When set, the current LAST X value will be saved and restored as-is.

RESTORE

Based on options set beforehand, RESTORE will restore the state of the stack in a fashion consistent with the behavior of built in-functions.

ALPHA Register
This should contain the same value as it did when calling SAVE to ensure the correct temporary variables are loaded. Calling SAVE will leave ALPHA in the same state it was in before executing. You will not need to set this again unless your program uses the ALPHA register.
Flag 91
Controls whether or not REGS will be restored. This flag should be in the same state that it was in when calling SAVE.
Variable "_A"
This variable indicates the number of arguments that your program "consumes" from the stack. For instance, the operator + would consume 2 arguments, and the function LOG would consume 1 argument. In other words, the number represents how many values should be discarded from the "before" stack when restoring.
Variable "_O"
This variable indicates the number of values that your program returns to the stack, and which should not be overwritten by the restored stack values. The function LOG returns one value, and COMPLEX returns two values when it receives a complex number as input.

The reason global variables are used to control the number of inputs and outputs is that being forced to put these values on the stack before calling RESTORE would limit the number of values your program could output to only two. With global variables, they can be set at any point in the program when enough stack levels are available to do so without losing important values.

Program Listing and Download

Program Listing - A plain text listing of the Stack Save programs. Suitable for entry on a real 42s or a simulator.

Raw program file - A .raw format file suitable for loading into a 42s simulator.

Example

Following is a sample program with annotations demonstrating the usage of SAVE and RESTORE.

01 LBL "TEST"
02 STO "_O"
03 RDown
04 STO "_A"
This section takes the values for _O and _A from the stack to allow experimenting with RESTORE behavior in different scenarios. (Normally you would set these to static values at some point in your program before calling RESTORE.) As an example, enter 2 and 1 on the stack before running TEST to see how the stack is saved and restored for a program with two inputs and one output.
05 1
06 2
07 3
08 4
09 SIZE 26
Set up the test "before" state for testing. Some of these values will be considered inputs used by the program based on the value of _A. Normally your "before" state will be whatever is on the stack when the user executes your program.
10 "TEST"
Set the ALPHA register so that "TEST" is added to the temporary variable names. (X_TEST, Y_TEST, etc.)
11 SF 91
12 CF 92
Enable saving and restoring REGS, and use the value of X (4 in our "before" stack) as the new LAST X.
13 XEQ "SAVE"
Here's where the magic happens - or at least the first part of it. Upon completion, the stack, ALPHA, and REGS will be in the same state as before executing SAVE, and your program can carry on with its business.
14 SIZE 10
15 CLST
16 10
17 20
18 30
19 40
These are some sample operations to change the state of the calculator. Lengthy calculations could take place at this point. Some of these sample values placed on the stack will be considered legitimate output values, and some will be considered intermediate "junk" values to be overwritten with restored stack values depending on what _O is set to when RESTORE is called.
21 XEQ "RESTORE"
The remainder of the magic. Using the values supplied for _A and _O, a number of stack values will be restored to what they were prior to calling SAVE. In this example program, REGS will be restored as well, and the value in X when SAVE was called will become the new LAST X.

To run the test program, enter 2 in the Y register, and 1 in the X register, then XEQ "TEST". The values 3 and 4 will be consumed as parameters and removed from the stack. You should see 40 in the X register as the one output value, and 1 and 2 will be moved down to Z and Y respectively, to fill the gap left by 3 which was consumed from the Y register. The value of T will remain 1, as it does when a built-in function causes the T register to fall down to Z and be copied in the process. Also, REGS will be restored to the 26 element size.

Try entering other combinations of values between 0 and 4 before running TEST to see the results. Insert STOP instructions into the TEST program at any locations where you would like to single-step through the program.