A-Shell Consolidated Reference

You can add your own extensions to APEX, which are accessed as buttons on the toolbar and which call your own ASB code, by defining them in the APEX configuration file, ashcfg:apex.cfg. The configuration file, if present, is scanned for commands of the following form:

BUTTON=prog, iconspec, tooltip {,msgno, inifile}

prog

indicates the subroutine which implements the extension. In theory it wouldn't have to be an SBX, but currently that is the only format supported, so prog must be in the form of "SBX:name", e.g. "SBX:PRTXLS". The corresponding subroutine (e.g. PRTXLS.SBX) must be in the BAS: directory (e.g. c:\ate\dsk0\007006\prtxls.sbx). See Comments, below.

iconspec

specifies the icon to display in the button that will be added to the toolbar. Supports the same syntax as for AUI_CONTROL icon buttons.

tooltip

is a short tooltip to display when the mouse hovers over the button.

msgno (optional)

may specify a message number in the file <inifile.lng>, where lng is the current language extension, e.g. USA, to supply the tooltip text. If present, it overrides the tooltip parameter above. Note that within the specified <inifile.lng> message file, the specified msgno value is assumed to be in the 000,### message group. In other words, if msgno = 001, then it will look for the line starting with 000,001,... Some message files, like PRTXLS.USA, may contain multiple groups of messages.

inifile (optional)

may specify an initialization file used by the extension, although the details of how is is used are up to the custom code in prog. Note that because commas are used as a delimiter in the BUTTON directive, the inifile parameter cannot contain a [p,pn] component. Use an ersatz instead, e.g. bas:prtxls.ini.

The file may also contain any number of comment lines, each beginning with a semicolon in the first position. Here's , for example:

;APEX customization

;BUTTON=prog,icon,tip{,msgno,ini}

;If msgno>0, is expected to be msg 002,### in inifile.lng

BUTTON=SBX:PRTXLS,ashico1::document_out,Export to Excel,38,BAS:PRTXLS.INI

BUTTON=SBX:PXLCFG,ashico1::preferences,Configuration Options For Export,0,BAS:PRTXLS.INI

There are no particular limitations on what the subroutine (prog) may do, other than that it cannot delete or replace the file being previewed, and must eventually return so that APEX can resume control.

Comments

In order for an SBX subroutine to work as an APEX custom extension, it must be written according to the A-Shell print filter interface requirements; see the printer initialization command line COMMAND=SBX... for details. In addition to the mandatory parameters passed to all print filters, APEX will always pass two additional arguments, inifile and xeflags, i.e. the entire interface is:

xcall <sbxname>, sts, fspec, printer, switches, copies, form, {inifile, xeflags}

where inifile will be the inifile specified in the apex.cfg BUTTON command line, and xeflags will contain zero or more of the following bits:

 

History

2017 August, A-Shell 6.5.1612:  Custom buttons can now use PNG format.