# SCRSTS
> [HTML Version](scrsts_sbr.htm)
**xcall SCRSTS, opcode \{params\}**
The parameter syntax varies with the _opcode_: .
**xcall SCRSTS, SCROP\_INIT, srow, scol, erow, ecol\{, parentid, sflags, title, closecmd, coldef, xt'kbdstr, xt'flags, ctlid\}**
**xcall SCRSTS, SCROP\_ADD, msgfmt, arg1, ... argN**
**xcall SCRSTS, SCROP\_TMADD, msgfmt, arg1, ... argN**
**xcall SCRSTS,SCROP\_SCROLL \{,msg, exitcode\}**
**xcall SCRSTS,SCROP\_CLR**
**xcall SCRSTS,SCROP\_DEL**
SCRSTS.SBX outputs a status message to a window, scrolling previous messages up. Three variations are supported, depending on flags and environment:
· Text mode using INMEMO
· GUI mode using multi-line INFLD control
· GUI mode using XTREE
Some examples using SCRSTS are provided below. Source, additional samples and related functions can be found in [SOSLIB:\[907,20\]](https://bitbucket.org/microsabio/soslib/src/master/907020/).
**Parameters**
_opcode _([Num](num.htm.md)) \[in\]_ _
specifies the operation using one of the options from the following table:
| **Symbol** | **Value** | **Description** |
|------|------|------|
| SCROP\_INIT | 0 | Initialize (create) the control. |
| SCROP\_ADD | 1 | Add a message. |
| SCROP\_CLR | 2 | Clear all the messages. |
| SCROP\_DEL | 3 | Delete the control. |
| SCROP\_SCROLL | 4 | Explicitly scroll the control contents; needed only in text mode. |
| SCROP\_TMADD | 5 | Add a message with an automatic timestamp. |
| **Definition file: **[ashinc:scrsts.def](https://bitbucket.org/microsabio/soslib/src/master/907016/scrsts.def) | |
_srow,scol,erow,ecol_ _ _([Num](num.htm.md)) \[in\]
specify coordinates of the rectangle in normal or milli-units
_sflags_
takes MBF\_xxxxx flags (from ashell.bsi); the only ones of interest so far are MBF\_DIALOG and MBF\_MODELESS, which, together cause the scrolling status control to be placed inside its own modeless dialog window (ignored in text mode). Also, MBF\_LISTBOX causes GUI version to use XTREE instead of INFLD, eliminating the scrolling limit
_title_
title string to display in the dialog; ignored unless _sflags_ contains the MBF\_DIALOG option.
_closecmd_
if MBF\_KBD and MBF\_SYSMENU flags included in _sflags_, then _closecmd_ determines what happens when X clicked (if "", then dialog is closed internally; else string is sent in place of the normal ESC) (Virtual click codes supported)
_coldef_
can be a legal XTREE advanced column definition, if MBF\_LISTBOX (The default is "1~512~ ~S~~") **Warning**: if you define any columns, it is up to you to pass subsequent MSG strings formatted to be compatible with the definition). Also note that if the header fields are all blank, the header row will be removed entirely.
_xt'kbdstr_
if MBF\_KBD and MBF\_LISTBOX defined, clicking on the control will send this string (which applications would typically responsd to by calling SCROP\_SCROLL).
_xt'flags_
optional XTREE flags (if MBF\_LISTBOX)
_xt'ctlno_
B,2 optionally returns XTREE control ID ([XTR.CTLNO](xtr_ctlno.htm.md)) or INFLD AUI ID
When the XTREE option is requested (see Using XTREE with SCRSTS), three additional optional parameters can be passed to the SCROP\_INIT call:
_xt'kbdstr _([String](string.htm.md),10)
sets the XTR.KBDSTR member of the _xtrctl_ structure, so that clicking on the status control sends the specified string. This can be useful if you want to allow the user to manipulate the status window, such as to sort, select, etc. This probably only makes sense in conjunction with a _coldef_ that defines relevant features such as columns, popup menus, etc. The application would normally call the SCROP\_SCROLL opcode to in response to receiving the XT'KBDSTR.
_xt'flags_
may be used to specify additional XTREE flags, such as perhaps XTF\_MSEL, etc.
_ctlid_
will return the XTREE control number ([XTR.CTLNO](xtr_ctlno.htm.md)), or in the case of INFLD, the AUI control id. This would only be of interest in sophisticated situations where you wanted to bypass SCRSTS.SBX and operate on the control directly using XTREE or INFLD.
These parameters apply only to the SCROP\_ADD and SCROP\_TMADD:
_msgfmt_ ([String](string.htm.md)) \[in\]
The message to output. May contain zero or more of the following special field markers, some of which are supplied by the next parameter in sequence (see _arg1,...argN_ and Examples below):
| | | |
|------|------|------|
| %d | decimal value | (from arg1,...argN) |
| %s | string value | (from arg1,...argN) |
| %x | hex value | (from arg1,...argN) |
| %u | user name | |
| %m | machine name | |
| %p | program name | |
| %v | program version | |
_arg1,...argN_ (various types) \[in\]
These arguments are plugged into the %d, %s, and %x field markers from _msgfmt_
These parameters apply only to the SCROP\_ADD and SCROP\_TMADD:
_msg_ ([String](string.htm.md)) \[in\]
A string message to add to the bottom of the list. For text mode, the list is scrolled up one line to first to make room. For GUI mode, the scroll operation is automatic and thus this opcode is typically not used, although when it is used, it has the effect of suspending the application and putting the focus on the list control (allowing the operator to perform any operations supported internally by the control itself). To exit back to the application the user must issue some kind of _exitcode_ (such as ESC); see _exitcode_.
_exitcode_ (Signed [Num](num.htm.md)) \[out\]
When specified in GUI mode, the [standard XTREE exitcode value](exitcode.htm.md) will be returned here, indicating how the user exited from the state of having the focus on the message list.
**Examples**
Display/add a message to the window:
xcall SCRSTS, SCROP\_ADD, msgfmt \{,arg1,...argN\}
Clear the message window:
xcall SCRSTS, SCROP\_CLR
Delete the message window (restore area in text mode)
xcall SCRSTS, SCROP\_DEL
(If message window created inside its own dialog, dialog will be automatically deleted)
Allow user to scroll/activate the window.
xcall SCRSTS, SCROP\_SCROLL \{,msg\{,exitcode\}
**Extended Example**
The following example, from the actual AshLPD utility, illustrates the variation of SCRSTS based on XTREE, and includes the relatively advanced feature of using XTREE foreground row colors to code the various types of messages.
**(./images/ashref_img179.jpg)**
The initialization code for this image is:
\! Columns 1-8 are the hh:mm:ss; 10 is the color code
COLDEF = "0~0~ ~H~RGBfg=200,200,220,D~" \! D = Debug
COLDEF = COLDEF + "RGBfg=250,100,0,E~" \! E = Error (Red Orange)
COLDEF = COLDEF + "RGBfg=255,0,0,F~" \! F = Fatal (Red)
COLDEF = COLDEF + "RGBfg=0,0,204,I~" \! I = Info (Blue)
COLDEF = COLDEF + "RGBfg=100,100,180,L~" \! L = Low level info (gray)
COLDEF = COLDEF + "RGBfg=0,0,0,P~" \! P = Printing msg (black)
COLDEF = COLDEF + "RGBfg=210,0,210,W~~" \! W = Warning (yellow)
COLDEF = COLDEF + "1~8~ ~S~~10~1~ ~Hc~~11~120~ ~S~~" \! column layout of msgs
xcall SCRSTS,SCROP\_INIT,3,5,20,75,0,SFLAGS,"","",COLDEF
Messages are added with calls such as the following one. (Note that the color code letter, "I" in this case, indicating Info (Blue), is just sandwiched at the start of the message (matching the _coldef_ layout set up above).
xcall SCRSTS,SCROP\_TMADD,"IPerforming housekeeping..."
xcall SCRSTS, SCROP\_TMADD, "I Archive for %d day(s), age cutoff = %d seconds", CFG'ARCHIVE, cutoff
**Comments**
The name (SCROLL) is slightly misleading because in GUI mode, you could scroll without this, but it is necessary in text mode, and in XTREE mode it activates the control allowing other features (such as sorting, selecting, etc. to take place). If _exitcode_ is specified, returns _exitcode_, if any.
Stores data between calls using memory module SCRSTS.MEM (meaning that currently there can be only one of them active per A-Shell instance.)
Note that in text mode, if the height is >= 3, we use a border (which occupies 2 of the allowed rows). Otherwise no border. Also, on _opcode_ 0, we save the area, and restore it on _opcode_ 3.
The SCROP\_SCROLL operation now supports the return of an exitcode:
**xcall SCRSTS, SCROP\_SCROLL, msg, exitcode**
Since the SCROP\_SCROLL opcode actually puts the focus on the status control, the _exitcode_ will be that which you would have gotten from XTREE, INFLD, or INMEMO, depending on the environment. This would probably be most useful if you defined a PopupMenu, which returned interesting exitcodes.
The sample program [REGPTR in EXLIB:\[908,29\]](https://bitbucket.org/microsabio/exlib/src/master/908029/regptr.bp) illustrates some of the capabilities of SCRSTS.
**Using XTREE with SCRSTS**
SCRSTS.SBX 1.3(108), A-Shell’s scrolling status window handler, supports an option to use XTREE rather than INFLD to display the scrolling status window. To specify XTREE, you must set the MBF\_LISTBOX bit in the _sflags_ parameter when creating the scrolling status window. An optional new parameter allows you to specify an XTREE column definition string:
**xcall SCRSTS, SCROP\_INIT, srow, scol, erow, ecol \{,parentid, sflags, title, closecmd, coldef\}**
The rest of the SCRSTS opcode formats are unchanged.
Although the XTREE version actually has more overhead (XTREE is a vastly more complex control than the multi-line edit control used by INFLD), here are some of the reasons why you might prefer it:
• It eliminates the 1600 char limit on the amount of text that can be left in the window. With XTREE, there is essentially no limit.
• You can access many of the advanced XTREE features, such as colors, popup menus, columns, even multiple levels. Note, however, that it is up to you to supply a text string (in the SCROP\_ADD or SCROP\_TMADD calls) that is formatted to match the _coldef_ specified with the SCROP\_INIT.
Also note that if any of the column header fields in _coldef_ are not blank, then the normal column header bar will be displayed. Otherwise it will not (making it more like a typical scrolling status window).
The sample program [TSTSCR.BP in SOSLIB:\[907,20\]](https://bitbucket.org/microsabio/soslib/src/master/907020/tstscr.bp) sample program has been updated to allow easy experimentation with the new version.