STATUP [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== STATUP=====

^Published By^Date^Version^Knowledge Level^Keywords^
|Revelation Technologies|14 NOV 1989|2.X|EXPERT|STATUP|

The subroutine STATUP allows you to write information to the 
Advanced Revelation status line.

<code>
STATUP( operation, location, data )
</code>

==== Using STATUP ====

The Advanced Revelation status line consists of 10 cells (3 
on top, 7 on the bottom), each of which has a fixed length.  
By convention, certain cells tend to be used for specific 
functions (although you may use any but cell 10):

^Cell^Length^Used For^
|Top|
|1|6 char|name of current process (e.g. Paint)|
|2|6 char|current function (e.g. Enter, Roam)|
|3|64 char|dynamic information (program-specific)|
|Bottom|
|4|6 char|editor status|
|5|6 char|(varies)|
|6|11 char|(varies; Row indicator)|
|7|8 char|(varies)|
|8|15 char|User name|
|9|18 char|"Updating Indexes" indicator|
|10|8 char|Level indicator|

This describes the status line for Help level 0 (advanced).  

Help levels 1 and 2 reserve the bottom portion of the status 
line for their own use.

When certain programs run, it appears as if cell 3 comprises 
more than 1 cell; this is an illusion generated by embedding 
vertical lines (CHAR(179)) into the string placed into cell 
3.

Most Advanced Revelation programs "write" to the status 
line in order to indicate their current status.  This status 
line updating can take 3 forms:

  * Display a pre-defined template
  * Update one or more cells directly
  * Display a template and update all or a portion of cell 3


Dynamically-updated information is usually placed into cell 
3 (and the system provides a mechanism to do this), but 
other cells can be used for this purpose if desired.

=== operation ===

Use operation to specify the type of update operation to 
perform.

The following are the definitions for the STATUP operators 
(these are also defined in the STATUS.CONSTANTS record of 
the INCLUDE file):

<code>
EQU MULTI.MODAL$  TO 1
EQU SINGLE$       TO 2
EQU MULTI$        TO 3
EQU PUSH$         TO 4
EQU POP$          TO 5
EQU SINGLE.MODAL$ TO 6
</code>

The operations performed are described below:

^Operator^Operation^
|PUSH$|Stores the current status line (those cells containing data) in data.|
|POP$|Restores and displays the status line in the data variable saved by a preceding PUSH$ operation.  Note that only status line cells containing data at the time of the PUSH$ operation are restored.|
|SINGLE$|Updates a single status line cell.|
|MULTI$|Updates multiple status line cells.|
|SINGLE.MODAL$|Updates a single data column of cell 3 in the status line (does not affect constituent cell 3 data).|
|MULTI.MODAL$|Updates multiple data columns of cell 3 in the status line (does not affect constituent cell 3 data).|

=== location ===

Use location to pass the location of the data to use in the 
update process.  The value is determined by the operation 
specified:

^Operation^Value^
|PUSH$|A template name in the STATUS.LIST record.  If null, the current status line template (in @STATLIST) is used.  Note!  You cannot use the PUSH$ operation and pass a null value if your Help level is 1 or 2 you must pass a template name.|
|POP$|Unused (should be null).|
|SINGLE$|An integer indicating the status line cell to update.|
|MULTI$|A dynamic array of integers delimited by %%|%% or @FM) indicating the status line cells to update.|
|SINGLE.MODAL$|This must be 1 or null, indicating the starting data column in cell 3 to be updated.  The data column (and any formatting) is specified in the STATUS.LIST template|
|MULTI.MODAL$|A dynamic array of integers (delimited by %%|%% or @FM) indicating the starting data columns in cell 3 to be updated.  The numbers correspond to the fields in data.  The data columns (and any formatting) are specified in the STATUS.LIST template.|

=== data ===

The status line display data.  The value is determined by 
the operation specified:

^Operation^Value^
|PUSH$|A variable in which to save the current status line.|
|POP$|The variable used by a preceding PUSH$ operation to store the status line.|
|SINGLE$|The data to display at the specified location.  Data exceeding the cell length is truncated.|
|MULTI$|Dynamic array of data (delimited by %%|%% or @FM) to display at the specified location.  Data exceeding the cell length is truncated.|
|SINGLE.MODAL$|The data to display in the column of cell 3 of the status line referenced by location.|
|MULTI.MODAL$|A dynamic array of data (delimited by %%|%% or @FM) to display in the columns of cell 3 of the status line referenced by location.|

==== Values returned ====

None.

==== Correct Use of STATUP ====

<code>
/* program to call STATUP

This program requires a new template in the STATUS.LIST 
record in the SYSTEM file.  See code for details on layout 
of this item. */

$INSERT INCLUDE, STATUS.CONSTANTS
DECLARE SUBROUTINE INPUT.CHAR, MSG

/* Save the current status line into the variable 
STATUP.STATE and display the status line MYPROG from the 
system file record STATUS.LIST. 

The following code is the layout of the template MYPROG in 
STATUS.LIST in SYSTEM).  Once in the SYSTEM file, log off, 
then back on in order to re-initialize the status list.

*/

STATUP(push$, "MYPROG", statup.state)

/* There are 10 positions in the status line the following 
updates each cell individually by using the SINGLE$ function 
*/

MSG("Ready to update one cell at a time","","","")
FOR I = 1 TO 10
    STATUP(single$, I, "TEST":I)
    * used as a pause
    INPUT.CHAR(key)
NEXT I

* pause between printing and clearing
INPUT.CHAR(key)

* clear the status line 1 position at a time
MSG("Ready to clear one cell at a time","","","")
FOR  I = 1 TO 10
    STATUP(single$,I,"")
    INPUT.CHAR(key)
NEXT I

* final pause
INPUT.CHAR(key)

* restore status line
STATUP(pop$, "", statup.state)

/* The following updates more than one cell concurrently 
using the MULTI$ function.  Arguments 2 and 3 are FM-
delimited arrays containing positions and data strings, 
respectively. */

* save old state again
STATUP(push$, "", statup.state)
MSG("Ready to clear all cells","","","")

* clear current status line by blanking all cells
pos = "" ; string = ""
FOR X = 1 TO 10
    pos<<X>>   = X          ;* build array of all positions
    string<<X>> = SPACE(65) ;* build array of blanks
NEXT
STATUP(multi$, pos, string)
INPUT.CHAR(X) ; *  pause

* write real data to several positions concurrently
MSG("Ready to update several cells","","","")
pos = 1 : @FM : 2 : @FM : 3 : @FM : 4 : @FM : 5
string  = "AAAAA" : @FM : "BBBBB" : @FM :  STR("C",65) : @FM 
string := "DDDDD" : @FM : "EEEEE"
STATUP(multi$, pos, string)
INPUT.CHAR(X)

* restore old line again
STATUP(pop$, "", statup.state)

/* The following illustrates the MODAL$ capability.  This 
updates a portion of cell 3 (only), while leaving the rest 
of the cell intact.  It requires a format specification in 
the status line template "record" in the STATUS.LIST record 
in the SYSTEM file. */

* save current state again
STATUP(push$, "MYPROG", statup.state)
MSG("Ready to update one position in cell 3","","","")

* create loop to display loop counter on cell 3
FOR I = 1 TO 10
/* displays value of X at specific location in cell 3 (as 
determined by value 1 in format specs) */
    STATUP(single.modal$, 1, I)
    INPUT.CHAR(X)
NEXT I

* this time, display more than one value in cell 3
MSG("Ready to update two positions in cell 3","","","")
FOR I = 1 TO 10
    disp = I : @FM : (10-I)
    STATUP(multi.modal$, 1:@FM:2, disp)
    INPUT.CHAR(X)
NEXT I
INPUT.CHAR(X)

* restore original line again
STATUP(pop$, "", statup.state)
STOP
</code>