# Extensions

> [HTML Version](apexextensions.htm)

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. 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:

| | |
|------|------|
| **Value** | **Description** |
| \&h0080 | routine was called by APEX |
| \&h0100 | print debug flag was set |




**History**

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