Subversion Repositories NedoOS

Rev

Rev 539 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | Download

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
  4. <book>
  5.   <title>SjASMPlus 1.13.1 Documentation [2019-05-30]</title>
  6.  
  7.   <chapter>
  8.     <title>Introduction</title>
  9.  
  10.     <section>
  11.       <title>License</title>
  12.  
  13.       <para>SjASMPlus licensed under BSD license.</para>
  14.     </section>
  15.  
  16.     <section>
  17.       <title>What is it?</title>
  18.  
  19.       <para>SjASMPlus is Z80 Assembly Language Cross Compiler. It is available
  20.       for Win32, DOS and FreeBSD(mainly 5.x) systems. It is based on SjASM
  21.       source code by Sjoerd Mastijn (<ulink
  22.       url="http://xl2s.tk">http://xl2s.tk</ulink>)</para>
  23.     </section>
  24.  
  25.     <section>
  26.       <title>Main Features</title>
  27.  
  28.       <para><itemizedlist>
  29.           <listitem>
  30.             <para>Z80/R800/Z80N documented and undocumented opcodes support</para>
  31.           </listitem>
  32.  
  33.           <listitem>
  34.             <para>Very fast compilation: 1 million lines by 2-3 seconds on
  35.             modern computer</para>
  36.           </listitem>
  37.  
  38.           <listitem>
  39.             <para>Code inlining through colon (LD A,C:INC A:PUSH AF:IFDEF
  40.             FX:LD A,D:ENDIF…)</para>
  41.           </listitem>
  42.  
  43.           <listitem>
  44.             <para>Structures to define data structures in memory more easily
  45.             (use STRUCT pseudo-op)</para>
  46.           </listitem>
  47.  
  48.           <listitem>
  49.             <para>Conditional assembly</para>
  50.           </listitem>
  51.  
  52.           <listitem>
  53.             <para>Macro definitions</para>
  54.           </listitem>
  55.  
  56.           <listitem>
  57.             <para>Local labels</para>
  58.           </listitem>
  59.  
  60.           <listitem>
  61.             <para>User’s messages</para>
  62.           </listitem>
  63.  
  64.           <listitem>
  65.             <para>Temporary labels</para>
  66.           </listitem>
  67.  
  68.           <listitem>
  69.             <para>Virtual device mode for common machines: ZX 128, ZX Next, ... (pseudo op DEVICE)</para>
  70.           </listitem>
  71.  
  72.           <listitem>
  73.             <para>Defines and array of defines</para>
  74.           </listitem>
  75.  
  76.           <listitem>
  77.             <para>Fake instructions as LD HL,DE (LD H,D:LD L,E) and more</para>
  78.           </listitem>
  79.  
  80.           <listitem>
  81.             <para>Source and binary file inclusion</para>
  82.           </listitem>
  83.  
  84.           <listitem>
  85.             <para>Multiline block comments</para>
  86.           </listitem>
  87.  
  88.           <listitem>
  89.             <para>Multi file output and file updating</para>
  90.           </listitem>
  91.  
  92.           <listitem>
  93.             <para>ZX Spectrum specific directives and pseudo ops (SAVESNA, SAVETAP, SAVEHOB, INCHOB, INCTRD...)</para>
  94.           </listitem>
  95.  
  96.           <listitem>
  97.             <para>ZX Spectrum Next specific features and directives (Z80N, 8ki memory paging, SAVENEX)</para>
  98.           </listitem>
  99.  
  100.           <listitem>
  101.                           <para>Correctness is assured by <ulink url="https://cirrus-ci.com/github/z00m128/sjasmplus/master">
  102.                                           Cirrus-CI with 140+ automated tests</ulink> (report issues to grow it even more)</para>
  103.           </listitem>
  104.         </itemizedlist></para>
  105.     </section>
  106.  
  107.     <section>
  108.       <title>Credits</title>
  109.  
  110.       <para>Special thanks to <emphasis>Sjoerd Mastijn</emphasis>, the author
  111.       of SjASM.</para>
  112.  
  113.       <para><emphasis>Aprisobal </emphasis>- main programming, documentation,
  114.       etc.</para>
  115.  
  116.       <para>Thanks to:<itemizedlist>
  117.           <listitem>
  118.             <para><emphasis>Kurles/HS/CPU, Alexander Kovalenko, Ped7g</emphasis> - additional
  119.             programming;</para>
  120.           </listitem>
  121.  
  122.           <listitem>
  123.             <para><emphasis>Krystian Wlosek
  124.             &lt;kwlosek(at)gmail.com&gt;</emphasis> - bug fix patches, Linux
  125.             makefile;</para>
  126.           </listitem>
  127.  
  128.           <listitem>
  129.             <para><emphasis>Ric Horne &lt;Ric.Hohne@eads-ts.com&gt;</emphasis>
  130.             - bug fix patches.</para>
  131.           </listitem>
  132.  
  133.           <listitem>
  134.             <para><emphasis>breeze &lt;breeze@tut.by&gt;</emphasis> - bug fix
  135.             patches.</para>
  136.           </listitem>
  137.  
  138.           <listitem>
  139.             <para><emphasis>psndcj &lt;psndcj.tbk@gmail.com&gt;</emphasis> -
  140.             bug reporting, beta-testing.</para>
  141.           </listitem>
  142.  
  143.           <listitem>
  144.             <para><emphasis>elfh &lt;elphecy@gmail.com&gt;</emphasis> - bug
  145.             reporting.</para>
  146.           </listitem>
  147.  
  148.           <listitem>
  149.             <para><emphasis>bugsy &lt;bugsy@ya.ru&gt;</emphasis> - bug
  150.             reporting.</para>
  151.           </listitem>
  152.  
  153.           <listitem>
  154.             <para><emphasis>skrju &lt;sq-@mail.ru&gt;</emphasis> - bug
  155.             reporting.</para>
  156.           </listitem>
  157.  
  158.           <listitem>
  159.             <para><emphasis>Tygrys, UB880D, Cizo, mborik, z00m</emphasis> -
  160.             compilation errors and warnings clean up, makefiles, testing.</para>
  161.           </listitem>
  162.  
  163.           <listitem>
  164.             <para><emphasis>Antipod, boo_boo, PulkoMandy, Busy, Liniya</emphasis> -
  165.             bug fix patches, testing.</para>
  166.           </listitem>
  167.  
  168.         </itemizedlist></para>
  169.  
  170.       <para>Big thanks to all people, who helped on development of the
  171.       compiler!</para>
  172.     </section>
  173.  
  174.     <section>
  175.       <title><anchor id="feedback" />Feedback</title>
  176.  
  177.       <para>WWW: <ulink
  178.       url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink>
  179.       (original Aprisobal's source)</para>
  180.  
  181.      <para>WWW: <ulink
  182.      url="https://github.com/z00m128/sjasmplus">https://github.com/z00m128/sjasmplus</ulink>
  183.      (newer versions maintained by z00m and others)</para>
  184.  
  185.  
  186.      <para>E-Mail: my@aprisobal.by, zoom@centrum.sk</para>
  187.    </section>
  188.  
  189.    <section>
  190.      <title>What's new?</title>
  191.  
  192.       <para><variablelist>
  193.  
  194. <varlistentry>
  195.             <term>work in progress - 1.13.2</term>
  196.  
  197.             <listitem>
  198.               <synopsis>- <link linkend="po_opt">OPT</link> has now also "listoff" and "liston" commands
  199. - added to --syntax option: case insensitive instructions, "bB" implemented
  200. - new <ulink url="https://github.com/z00m128/sjasmplus/tree/master/tests/macro_examples">macro examples</ulink>, minor fixes and refactoring
  201. - <link linkend="po_savetrd">SAVETRD</link> implementation refactored (more checks, less bugs, "replace" file feature)
  202. - operators "{address}" and "{b address}" are now official and documented</synopsis>
  203.             </listitem>
  204.           </varlistentry>
  205.  
  206. <varlistentry>
  207.             <term>30.05.2019 - 1.13.1</term>
  208.  
  209.             <listitem>
  210.               <synopsis>- added <link linkend="s_cli">--syntax</link> command line option
  211. - added <link linkend="po_opt">OPT</link> directive (modifies some command line options)
  212. - added way to use <link linkend="st_usage">structure</link> at designed address
  213. - <link linkend="s_macros">MACRO</link> can be now named through label (optional syntax)
  214. - added <link linkend="po_defarray_plus">DEFARRAY+</link> directive (for splitting long list of DEFARRAY values)
  215. - added <link linkend="po_cspectmap">CSPECTMAP</link> directive for MAP files for CSpect emulator
  216. - added support for <link linkend="s_cli">SJASMPLUSOPTS</link> environment variable
  217. - Z80N new variants of syntax, now also "mul de : mul : pixelad hl : pixeldn hl" works
  218. - minor bugfixes, improvements and internal refactorings (error reporting)
  219. - updated syntax-highlight file for KDE5 editors (Kate)</synopsis>
  220.             </listitem>
  221.           </varlistentry>
  222.  
  223. <varlistentry>
  224.             <term>05.05.2019 - 1.13.0</term>
  225.  
  226.             <listitem>
  227.               <synopsis>- [may break old sources] DEVICE: each assembling pass resets also
  228.   "device". To work with "device" memory (savesna/savetap/...) you
  229.   must select the device (and slot and pages) before producing machine
  230.   code which you want to work with (SAVESNA/SAVETAP/...).
  231.   If only single DEVICE is used in whole source batch, then the setting
  232.   is "global" and will be applied to all lines of source (in 2nd+ pass).
  233. - [may break old sources] ZXSPECTRUM128 based devices map into slots
  234.   by default banks {7, 5, 2, 0}. (was {0, 5, 2, 7} in older versions)
  235. - [may break old sources] ZXSPECTRUM128 based devices have sysvars and
  236.   stack set up as in "USR 0" mode (ZXSPECTRUM48 system variables and
  237.   default stack content).
  238. - [may break old sources] MAP+FIELD directives removed (STRUCT is better and working)
  239. - <link linkend="po_mmu">MMU</link> directive (fusing SLOT + PAGE and extending them)
  240. - <link linkend="po_savedev">SAVEDEV</link> directive (similar to SAVEBIN)
  241. - <link linkend="c_savenex">SAVENEX</link> directive (for ZX Spectrum Next)
  242. - INCBIN: support for negative offset/length values, support for MMU wrapping
  243. - INCBIN: support for file chunks of 64+ki size (usable with MMU)
  244. - Fixed: INCTRD offset, binary STDOUT on windows, SAVETRD/SAVEHOB filenames
  245. - Fixed: LUA used inside macros, LUA get_word, LUA error reporting
  246. - parser: added C++(like) <link linkend="s_numeric">numeric literals</link>
  247. - <link linkend="s_realdevice">ZXSPECTRUMNEXT device</link> added
  248. - refactoring of label/define implementation = less memory leaks, more correct
  249.   "label.mem_page" values, "Unreal" labels dump is more correct too
  250. - docs: now the CSS file is actually used, and default style modified a bit
  251. - new MACRO examples, syntax-highlight file for KDE5 editors (Kate)</synopsis>
  252.             </listitem>
  253.           </varlistentry>
  254.  
  255. <varlistentry>
  256.             <term>07.04.2019 - 1.12.0</term>
  257.  
  258.             <listitem>
  259.               <synopsis>- Fixed parsing of expressions starting with string literal
  260. - Fixed listing of DS directive with negative values, added value check warning
  261. - Fixed possible wrong indexing of some arrays internally
  262. - Fixed parsing of single-word instructions in colon-packed-no-space macros
  263. - Making macro arguments substitution a bit more aggressive, to work also with
  264.   DEFINE/IFDEF/IFNDEF/DEFARRAY directives inside macro (this gives the coder
  265.   more macro power and freedom, but the error reporting may get lot more confused)
  266. - Refactoring substring substitution for macro-arguments and defines, now it
  267.   should work always. To prohibit some macro/define to substitute into middle
  268.   of the string, start its name with underscore, like "_VERSION".
  269. - THIS MAY BREAK SOME OLDER SOURCES, SORRY. Also the rules for substitutions
  270.   will be in the future further modified and documented, to make them more
  271.   intuitive and predictable, so there may be more breakage even later.
  272. - Adding fake instructions break and exit for CSpect emulator (--zxnext=cspect)</synopsis>
  273.             </listitem>
  274.           </varlistentry>
  275.  
  276. <varlistentry>
  277.             <term>01.04.2019 - 1.11.1</term>
  278.  
  279.             <listitem>
  280.               <synopsis>- Fixed global labels in MACRO and in IFUSED/IFNUSED
  281. - Fixed nested IF-DUP-IF
  282. - Fixed local labels fail when amount of lines did change between passes
  283. - Fixed Makefile to build when path to project contains space
  284. - Added macro-example: turn "DJNZ ." into "DJNZ $" (to fix Zeus syntax source)
  285. - Added --msg=lst and --msg=lstlab options to produce listing file to STDERR
  286. - Added options to read input file from STDIN and output "raw" binary to STDOUT</synopsis>
  287.             </listitem>
  288.           </varlistentry>
  289.  
  290. <varlistentry>
  291.             <term>22.03.2019 - 1.11.0</term>
  292.  
  293.             <listitem>
  294.               <synopsis>- Added ZX Spectrum Next instructions support
  295. - Added --msg option, directives DG and DH
  296. - Changed listing layout to fixed-width type
  297. - Errors, Warnings and similar are now channeled to STDERR
  298. - Fixed string literal parser, added two apostrophes and escaped zero
  299. - Fixed docs templates (HTML is now more valid)
  300. - Fixed nesting DUP issue
  301. - Fixed CRLF handling in parser
  302. - Fixed -D option for multiple asm files
  303. - Fixed address display when the 64kB limit exceeded
  304. - Fixed lost code when current memory leaves device slot in "disp" mode
  305. - Fixed IF inside MACRO, DUP and REPT
  306. - Fixed ALIGN behavior and docs wording
  307. - Fixed INCHOB/INCBIN (offset / length)
  308. - Fixed INCLUDE/INCLUDELUA system path priority ("" vs &lt;&gt;)
  309. - Fixed END behavior
  310. - Fixed DEFARRAY to work as documented
  311. - Fixed and refactored WORD/DWORD/D24
  312. - Fixed and extended STRUCT
  313. - Multiple bugfixes in listing generation
  314. - Multiple bugfixes of internal code
  315. - Refactored options parser, instruction parser and Warning/Error system
  316. - C++14 standard is now required minimum (to compile sjasmplus sources)
  317. - Added automated-testing scripts, with 50+ tests
  318. - GitHub connected with <ulink url="https://cirrus-ci.com/github/z00m128/sjasmplus">Cirrus Continuous Integration</ulink> service</synopsis>
  319.             </listitem>
  320.           </varlistentry>
  321.  
  322. <varlistentry>
  323.             <term>09.01.2019 - 1.10.4</term>
  324.  
  325.             <listitem>
  326.               <synopsis>- "Bytes lost" error reworked (and changed to warning)
  327. - Error/warning messages are displayed in last pass only (where possible)
  328. - Fixed 64k limit warnigs
  329. - BinIncFile reworked</synopsis>
  330.             </listitem>
  331.           </varlistentry>
  332.  
  333. <varlistentry>
  334.             <term>26.11.2018 - 1.10.3</term>
  335.  
  336.             <listitem>
  337.               <synopsis>- Fixed macro issue with commas inside quotes
  338. - Fixed IFUSED and IFNUSED directives
  339. - Fixed STRUCT directive
  340. - Added support of register operands for operators HIGH and LOW</synopsis>
  341.             </listitem>
  342.           </varlistentry>
  343.              
  344.           <varlistentry>
  345.             <term>09.08.2018 - 1.10.2</term>
  346.  
  347.             <listitem>
  348.               <synopsis>- Corrected bug in UNDEFINE directive
  349. - Corrected bug in parser line wrapping.</synopsis>
  350.             </listitem>
  351.           </varlistentry>            
  352.  
  353.           <varlistentry>
  354.             <term>15.05.2018 - 1.10.1</term>
  355.  
  356.             <listitem>
  357.               <synopsis>- Corrected bug of OUTPUT directive (bugfix of flushing buffer).
  358. - Implemented TAPOUT/TAPEND and OUTEND directives.</synopsis>
  359.             </listitem>
  360.           </varlistentry>
  361.  
  362.           <varlistentry>
  363.             <term>06.05.2018 - 1.10.0</term>
  364.  
  365.             <listitem>
  366.               <synopsis>- Implemented full featured SAVETAP and EMPTYTAP directives.</synopsis>
  367.             </listitem>
  368.           </varlistentry>
  369.  
  370.           <varlistentry>
  371.             <term>07.09.2017 - 1.09</term>
  372.  
  373.             <listitem>
  374.               <synopsis>- -D commandline parameter added, inchob / incbin bugfix.</synopsis>
  375.             </listitem>
  376.           </varlistentry>
  377.  
  378.           <varlistentry>
  379.             <term>23.12.2016 - 1.08</term>
  380.  
  381.             <listitem>
  382.               <synopsis>- compilation warnings cleanup, CMake installation method added.</synopsis>
  383.             </listitem>
  384.           </varlistentry>
  385.  
  386.           <varlistentry>
  387.             <term>11.10.2016 - 1.07 RC9</term>
  388.  
  389.             <listitem>
  390.               <synopsis>- some docs added and compilation warnings cleanup.</synopsis>
  391.             </listitem>
  392.           </varlistentry>
  393.  
  394.           <varlistentry>
  395.             <term>05.05.2016 - 1.07 RC8</term>
  396.  
  397.             <listitem>
  398.               <synopsis>- new makefile, compilation errors fixed and some warnings cleanup.</synopsis>
  399.             </listitem>
  400.           </varlistentry>
  401.  
  402.           <varlistentry>
  403.             <term>03.04.2008 - 1.07 Stable</term>
  404.  
  405.             <listitem>
  406.               <synopsis>- Added new SAVETAP pseudo-op. It's support up to 1024kb ZX-Spectrum's RAM.
  407. - Added new --nofakes commandline parameter.</synopsis>
  408.             </listitem>
  409.           </varlistentry>
  410.  
  411.           <varlistentry>
  412.             <term>02.04.2008 - 1.07 RC7</term>
  413.  
  414.             <listitem>
  415.               <synopsis>- Another fix of 48k SNA snapshots saving routine.
  416. - Added new UNDEFINE pseudo-op.
  417. - Added new IFUSED/IFNUSED pseudo-ops for labels (such IFDEF for defines).
  418. - Fixed labels list dump rountine (--lstlab command line parameter).</synopsis>
  419.             </listitem>
  420.           </varlistentry>
  421.  
  422.           <varlistentry>
  423.             <term>27.03.2008 - 1.07 RC6</term>
  424.  
  425.             <listitem>
  426.               <synopsis>- Applied bugfix patches for SAVEHOB/SAVETRD pseudo-ops by Breeze.
  427. - Fixed memory leak in line parsing routine.
  428. - Fixed 48k SNA snapshots saving routine.
  429. - Added missing INF instruction.
  430. - Fixed code parser's invalid addressing of temporary labels in macros.</synopsis>
  431.            </listitem>
  432.          </varlistentry>
  433.  
  434.          <varlistentry>
  435.            <term>31.05.2007 - 1.07 RC5bf</term>
  436.  
  437.            <listitem>
  438.              <synopsis>- Bugfix patches by Ric Hohne.
  439. - Important bugfix of memory leak.
  440. - Bugfix of strange crashes at several machines.
  441. - Added yet another sample for built-in LUA engine. See end of this file.
  442. - Added sources of CosmoCubes demo to the "examples" directory.</synopsis>
  443.            </listitem>
  444.          </varlistentry>
  445.  
  446.          <varlistentry>
  447.            <term>13.05.2007 - 1.07 RC5</term>
  448.  
  449.            <listitem>
  450.              <synopsis>- ALIGN has new optional parameter.
  451. - Corrected bug of RAM sizing.
  452. - Corrected bug of structures naming.</synopsis>
  453.            </listitem>
  454.          </varlistentry>
  455.  
  456.          <varlistentry>
  457.            <term>02.12.2006 - 1.07 RC4bf</term>
  458.  
  459.            <listitem>
  460.              <synopsis>- Corrected important bug in code generation functions of SjASMPlus.</synopsis>
  461.            </listitem>
  462.          </varlistentry>
  463.  
  464.          <varlistentry>
  465.            <term>28.11.2006 - 1.07 RC4</term>
  466.  
  467.            <listitem>
  468.              <synopsis>- Corrected bug with SAVEBIN, SAVETRD and possible SAVESNA.
  469. - Add Makefile to build under Linux, FreeBSD etc.
  470. </synopsis>
  471.            </listitem>
  472.          </varlistentry>
  473.  
  474.          <varlistentry>
  475.            <term>12.10.2006 - 1.07 RC3</term>
  476.  
  477.            <listitem>
  478.              <synopsis>- SAVESNA can save 48kb snapshots
  479. - Corrected DEFINE's bug.
  480. - Corrected bug of incorrect line numbering.</synopsis>
  481.             </listitem>
  482.           </varlistentry>
  483.  
  484.           <varlistentry>
  485.             <term>28.09.2006 - 1.07 RC2</term>
  486.  
  487.             <listitem>
  488.               <synopsis>- SAVESNA works and with device ZXSPECTRUM48
  489. - Added new device PENTAGON128
  490. - In ZXSPECTRUM48 device and others attributes has black ink and white paper by default.</synopsis>
  491.             </listitem>
  492.           </varlistentry>
  493.  
  494.           <varlistentry>
  495.             <term>23.09.2006 - 1.07 RC1bf</term>
  496.  
  497.             <listitem>
  498.               <synopsis>- Corrected bug with _ERRORS and _WARNINGS constants
  499. - Added error message, when SHELLEXEC program execution failed</synopsis>
  500.             </listitem>
  501.           </varlistentry>
  502.  
  503.           <varlistentry>
  504.             <term>17.09.2006 - 1.07 RC1</term>
  505.  
  506.             <listitem>
  507.               <synopsis>- 3-pass design
  508. - Built-in Lua scripting engine
  509. - Changed command line keys
  510. - Documentation converted to HTML.
  511. - Added new directives: DEVICE, SLOT, SHELLEXEC
  512. - Added predefined constanst: _SJASMPLUS=1, _ERRORS and other
  513. - Changed output log format.
  514. - And many many more.</synopsis>
  515.             </listitem>
  516.           </varlistentry>
  517.         </variablelist></para>
  518.  
  519.       <para>Old SjASMPlus 1.06 log was removed.</para>
  520.     </section>
  521.   </chapter>
  522.  
  523.   <chapter>
  524.     <title>Where to get and how to use</title>
  525.  
  526.     <section>
  527.       <title>Packages</title>
  528.  
  529.       <para>You can grab older (up to v1.07) binaries and sources at SourceForge project page:
  530.       <ulink
  531.       url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink></para>
  532.  
  533.       <para>Win32 package has:<itemizedlist>
  534.           <listitem>
  535.             <para>sjasmplus.exe - the Win32 executable.</para>
  536.           </listitem>
  537.  
  538.           <listitem>
  539.             <para>examples directory - some examples of use</para>
  540.           </listitem>
  541.  
  542.           <listitem>
  543.             <para>documentation directory - documentation in various
  544.             formats</para>
  545.           </listitem>
  546.         </itemizedlist></para>
  547.  
  548.       <para>DOS and FreeBSD versions has same files in their packages.</para>
  549.  
  550.       <para>Newer sources (v1.08 onwards) you can get on github project page:
  551.       <ulink
  552.       url="https://github.com/z00m128/sjasmplus/">https://github.com/z00m128/sjasmplus/</ulink></para>
  553.  
  554.       <para><emphasis>Linux, Unix, MacOS and BSD version</emphasis> you can compile using
  555.       <emphasis>GCC</emphasis> and <emphasis>Makefile</emphasis> from sources
  556.       package.</para>
  557.  
  558.       <para>Windows binaries you can compile with <emphasis>MinGW</emphasis>
  559.       environment and included <emphasis>Makefile.win</emphasis>. Precompiled
  560.       win32 binary is available on
  561.       <ulink
  562.       url="https://github.com/z00m128/sjasmplus/releases">https://github.com/z00m128/sjasmplus/releases</ulink></para>
  563.  
  564.       <para>There is an option to use CMake for compilation.
  565.       See <emphasis>INSTALL.md</emphasis> file for details.</para>
  566.     </section>
  567.  
  568.     <section>
  569.       <title><anchor id="s_cli"/>Command line</title>
  570.  
  571.       <para>Usage:</para>
  572.  
  573.       <synopsis>sjasmplus [options] sourcefile(s)</synopsis>
  574.  
  575.       <para>Option flags as follows:</para>
  576.  
  577.       <para><synopsis>  -h or --help             Help information
  578.   --zxnext[=cspect]        Enable ZX Next Z80 extensions (CSpect emulator has
  579.   extra "exit" DD00 and "break" DD01 fake instructions)
  580.   -i&lt;path&gt; or -I&lt;path&gt; or --inc=&lt;path&gt;
  581.                            Include path (later defined have higher priority)
  582.   --lst[=&lt;filename&gt;]       Save listing to &lt;filename&gt; (&lt;source&gt;.lst is default)
  583.   --lstlab                 Enable label table in listing
  584.   --sym=&lt;filename&gt;         Save symbols list to &lt;filename&gt;
  585.   --exp=&lt;filename&gt;         Save exports to &lt;filename&gt; (see EXPORT pseudo-op)
  586.   --raw=&lt;filename&gt;         Machine code saved also to &lt;filename&gt; (- is STDOUT)
  587.   Note: use OUTPUT,LUA/ENDLUA and other pseudo-ops to control output
  588.  Logging:
  589.   --nologo                 Do not show startup message
  590.   --msg=[all|war|err|none|lst|lstlab]  Stderr messages verbosity ("all" is default)
  591.   Note: "lst" or "lstlab" will turn STDERR into listing file (this will clash with
  592.   `--lst`, use only one of the options) and some diagnostic messages of "all"
  593.   are omitted, as they are not part of listing files.
  594.   --fullpath               Show full path to error file
  595.  Other:
  596.   -D&lt;NAME&gt;[=&lt;value&gt;]       Define &lt;NAME&gt; as &lt;value&gt;
  597.   -                        Reads STDIN as source (no other sourcefile allowed)
  598.   --reversepop             Enable reverse POP order (as in base SjASM version)
  599.   --dirbol                 Enable directives processing from the beginning of line
  600.   --nofakes                Disable fake instructions (obsolete, use --syntax=F)
  601.   --dos866                 Encode from Windows codepage to DOS 866 (Cyrillic)
  602.   --syntax=&lt;...&gt;           Adjust parsing syntax, read details below.</synopsis></para>
  603.  
  604.   <para>Value for <code>--syntax</code> option may consist of multiple letters, omitting letter
  605.         for particular feature will use the default setting:
  606.         <synopsis>  a A    Multi-argument delimiter: ",," / "``" (default = ",")
  607.   b B    Memory access brackets []: disabled / required (default = enabled)
  608.   f F    Fake instructions: warning / disabled (default = enabled)
  609.   i      Case insensitive instructions/directives (default = same case required)
  610. &dagger; <emphasis>l L    Keyword labels (registers, instructions, ...): warning / error (default = silent)</emphasis></synopsis>
  611.   &dagger; work in progress: currently only "aAbBfFi" options are implemented, labels not yet, following description of functionality is then not fully correct either.
  612.   </para>
  613.   <para>
  614.   I.e. <code>--syntax=faBil</code> will modify parser to process source line
  615.   <programlisting>hl:  Ld a,(hl),,de,hl</programlisting>
  616.   in a way to produce warnings about keyword "hl" being used for label, about fake instruction
  617.   being used (ld de,hl) and assemble <code>(hl)</code> as numeric expression, not memory access.
  618.   Warnings on fake instructions can be suppressed for particular line by adding any end-of-line
  619.   comment containing string "fake", i.e. "<code>ld de,hl ; fake DE=HL</code>" will assemble
  620.   without warning. The "F" option is identical to "--nofakes" and preferred.
  621.   </para>
  622.  
  623.   <para>
  624.           The assembler will also read the environment variable <code>SJASMPLUSOPTS</code> (if available),
  625.           and process its content as part of command line options (before the actual options), so you
  626.           can pre-configure certain options in your environment, for example:
  627.           <programlisting>export SJASMPLUSOPTS="--zxnext=cspect --msg=war"
  628. sjasmplus --lst --lstlab example.asm</programlisting>
  629.         will execute the assembling as if command line "<code>sjasmplus --zxnext=cspect --msg=war --lst --lstlab example.asm</code>"
  630.         was used. Known issue: parser of environment variable delimits each option on any white-space character, so
  631.         option containing space character will be incorrectly parsed (like "-Ifile-path with space" = fails and
  632.         there is no way to escape/quote the path in the SJASMPLUSOPTS variable to make it work).
  633.   </para>
  634.     </section>
  635.  
  636.     <section>
  637.       <title>Source file format</title>
  638.  
  639.       <para>Lines in the source file should have the following
  640.       form:<programlisting>Label Operator Operand Comment</programlisting>All
  641.       fields are optional. Lines without label should start with whitespace.
  642.       Operators and operands can be inlined:</para>
  643.  
  644.       <para><programlisting>      Operator Operand:Operator Operand:Operator Operand... Comment</programlisting>Comments
  645.       should start with ';' or '//'. Comment blocks start with '/*' and end
  646.       with '*/'.</para>
  647.  
  648.       <para><example>
  649.           <title></title>
  650.  
  651.           <para><programlisting>; comment
  652. // comment
  653.  ld /* comment */ a,80
  654. /*
  655.  comment
  656. */
  657.  ld /*
  658.  but this won't be ld a,3!
  659. */ a,3</programlisting></para>
  660.        </example></para>
  661.    </section>
  662.  </chapter>
  663.  
  664.  <chapter>
  665.    <title>Labels</title>
  666.  
  667.    <section>
  668.      <title>Labels</title>
  669.  
  670.      <para>Labels are case-sensitive and may be of any reasonable length,
  671.      that is: up to about 70 characters. Label definitions should start on
  672.      the beginning of a line, but don't have to be followed by a colon ':'.
  673.       Generally labels should start with a letter or a underscore ('_'), the
  674.       following characters may be chosen from letters, numbers and the
  675.       following special symbols: '_', '.', '!', '?', '#' and '@'. Note that
  676.       the '.' has special meaning, as it is used between module names, labels
  677.       and local labels. The following are all legal and distinct
  678.       labels:<programlisting>Kip
  679. KIP
  680. Kip@@
  681. MAIN.loop?</programlisting>It is possible to use mnemonics, pseudo-ops and
  682.       register names as labels but it is not advised to do so. Also note that
  683.       the identifiers defined with the DEFINE pseudo-op use another name
  684.       space.</para>
  685.     </section>
  686.  
  687.     <section>
  688.       <title>Local labels</title>
  689.  
  690.       <para>When there is a module definition (see module pseudo-op) all
  691.       labels (except those starting with a '@') are local to that module. To
  692.       use a label from outside the module use modulename.labelname, in this
  693.       example: 'vdp.Cls' Labels starting with a '.' are also local to the
  694.       previous non-local label.</para>
  695.  
  696.       <para><example>
  697.           <title></title>
  698.  
  699.           <para><programlisting>MODULE main
  700. Main:                           ; main.Main
  701.         CALL SetScreen          ; SetScreen
  702.         CALL vdp.Cls            ; vdp.Cls
  703. .loop:                          ; main.Main.loop
  704.         LD A,(.event)           ; main.Main.event
  705.         CALL ProcesEvent        ; label not found: main.ProcesEvent
  706.         DJNZ .loop              ; main.Main.loop
  707.  
  708.     MODULE vdp
  709. @SetScreen:               ; SetScreen
  710. .loop                     ; vdp.SetScreen.loop
  711.         RET
  712. Cls:                      ; vdp.Cls
  713. .loop                     ; vdp.Cls.loop
  714.         DJNZ .loop        ; vdp.Cls.loop
  715.         RET
  716.  
  717.     ENDMODULE
  718. Main.event                ; main.Main.event
  719.     BYTE 0</programlisting></para>
  720.         </example></para>
  721.     </section>
  722.  
  723.     <section>
  724.       <title>@ Labels</title>
  725.  
  726.       <para>Labels starting with a '@' are not touched by the label processing
  727.       and used 'as-is'. See 'SetScreen' in the previous example code. <example>
  728.           <title></title>
  729.  
  730.           <para><programlisting>    MODULE xxx
  731. Label      ; xxx.Label
  732. .Local     ; xxx.Label.Local
  733. @Label     ; Label
  734. .Local     ; xxx.Label.Local =&gt; duplicate label error
  735. @Label2    ; Label2
  736. .Local     ; xxx.Label2.Local
  737. @yyy.Local ; yyy.Local
  738. yyy.Local  ; xxx.yyy.Local</programlisting></para>
  739.         </example></para>
  740.     </section>
  741.  
  742.     <section>
  743.       <title>Temporary labels</title>
  744.  
  745.       <para>To keep the number of used labels reasonable it is possible to use
  746.       numbers as labels. These labels can only be used as labels to jump to.
  747.       To jump to these labels, use the number followed by an 'F' for forward
  748.       branches or a 'B' for backward branches. Temporary labels should not be
  749.       used within macro's.</para>
  750.  
  751.      <para><example>
  752.          <title></title>
  753.  
  754.          <para><programlisting>        ADD A,E
  755.        JR NC,1F
  756.        INC D
  757. 1       LD E,A
  758. 2       LD B,4
  759.        LD A,(DE)
  760.        OUT (152),A
  761.        DJNZ 2B</programlisting></para>
  762.        </example></para>
  763.    </section>
  764.  </chapter>
  765.  
  766.  <chapter>
  767.    <title>Constants, expressions and other features</title>
  768.  
  769.    <section>
  770.      <title><anchor id="s_numeric" />Numeric constants</title>
  771.  
  772.      <para>Numeric constants should always start with a digit or $, # or %.
  773.      The following formats are supported:</para>
  774.  
  775.      <para><programlisting>12     decimal
  776. 12d    decimal
  777. 0xc    hexadecimal
  778. $c     hexadecimal
  779. #c     hexadecimal
  780. 0ch    hexadecimal
  781. 0b1100 binary (v1.12.1)
  782. %1100  binary
  783. 1100b  binary
  784. 0q14   octal (v1.12.1)
  785. 14q    octal
  786. 14o    octal</programlisting></para>
  787.  
  788.      <para>(v1.12.1) Optional single quotes(') may be inserted between the digits as a separator
  789.       (example: <computeroutput> ld a,%11'01'11'00 </computeroutput>).
  790.      They are ignored by the assembler.</para>
  791.    </section>
  792.  
  793.    <section>
  794.      <title>Character and string constants</title>
  795.  
  796.      <para>Character constants are characters surrounded by single quotes. It
  797.      is possible to use double quotes in some cases, but in general it is
  798.      better to use single quotes. String constants are characters surrounded
  799.      by double quotes. When double quotes are used, the following escape
  800.      sequences are recognized:</para>
  801.      <para><programlisting>\\ 92
  802. \? 63
  803. \' 39
  804. \" 34
  805. \0 0     ; since v1.11
  806. \A 7
  807. \B 8
  808. \D 127
  809. \E 27
  810. \F 12
  811. \N 10
  812. \R 13
  813. \T 9
  814. \V 11</programlisting><para>Inside single quotes two quotes after each other are
  815.    parsed as the apostrophe itself (since v1.11).</para><example>
  816.          <title></title>
  817.  
  818.          <para><programlisting>    BYTE "stringconstant\n" ; escape sequence assembles to newline
  819.    BYTE 'stringconstant\n' ; \n assembles literally as two bytes: '\', 'n'
  820.    LD HL,'hl'  ; hl = 0x686C = 'l', 'h'
  821.    LD HL,"hl"  ; hl = 0x686C = 'l', 'h'
  822.    LD A,"7"    ; not recommended (but works)
  823.    LD A,'8'    ; recommended
  824.    LD A,'\E'   ; warning + truncating value to 'E' (0x45)
  825.    LD A,'"'    ; A = 0x22
  826.    LD A,"'"    ; A = 0x27
  827.    LD A,''''   ; A = 0x27 ; since v1.11</programlisting></para>
  828.        </example></para>
  829.    </section>
  830.  
  831.    <section>
  832.      <title>Expressions</title>
  833.  
  834.      <para>Expressions are evaluated in 32 bits in this version of
  835.      SjASMPlus.</para>
  836.  
  837.      <para>'$' represents the current program counter. '$$' represents the
  838.      current page in the current slot in the <link
  839.      linkend="s_realdevice">real device emulation mode</link> and '{address}' can be used
  840.      to read WORD from virtual device memory (but zero is read before last pass
  841.      of assembling) ('{b address}' to read only BYTE).</para>
  842.  
  843.      <para>It is possible to use parenthesis '(' and ')' to override the
  844.      precedence of the operators. The following operators may be used in
  845.      expressions:</para>
  846.  
  847.      <para><programlisting>!     !x       logical not
  848. ~     ~x       complement
  849. +     +x       does absolutely nothing :)
  850. -     -x       minus
  851. low   low x    low 8 bits of 16 bit value or lower part of register pair
  852. high  high x   high 8 bits of 16 bit value or higher part of register pair
  853. not   not x    logical not
  854.  
  855. *     x*y      multiplication
  856. /     x/y      division
  857. %     x%y      modulo
  858. mod   x mod y  modulo
  859.  
  860. +     x+y      addition
  861. -     x-y      subtraction
  862.  
  863. &lt;&lt;    x&lt;&lt;y     shift left
  864. &gt;&gt;    x&gt;&gt;y     shift right signed
  865. &gt;&gt;&gt;   x&gt;&gt;&gt;y    shift right unsigned
  866. shl   x shl y  shift left
  867. shr   x shr y  shift right signed
  868.  
  869. &lt;?    x&lt;?y     minimum
  870. &gt;?    x&gt;?y     maximum
  871.  
  872. &lt;     x&lt;y      less than
  873. &gt;     x&gt;y      greater than
  874. &lt;=    x&lt;=y     equal or less than
  875. &gt;=    x&gt;=y     equal or greater than
  876.  
  877. =     x=y      equal
  878. ==    x==y     equal
  879. !=    x!=y     not equal
  880.  
  881. &amp;     x&amp;y      bitwise and
  882. and   x and y  bitwise and
  883.  
  884. ^     x^y      bitwise xor
  885. xor   x xor y  bitwise xor
  886.  
  887. |     x|y      bitwise or
  888. or    x or y   bitwise or
  889.  
  890. &amp;&amp;    x&amp;&amp;y     logical and
  891.  
  892. ||    x||y     logical or</programlisting></para>
  893.    </section>
  894.  
  895.    <section>
  896.      <title>Assembly language</title>
  897.  
  898.      <para>This version only accepts Z80 mnemonics. There are some additions
  899.      to what I think is standard Z80: <itemizedlist>
  900.          <listitem>
  901.            <para>'[' and ']' can be used instead of '(' and ')' for
  902.            indirections. So LD A,[HL] is the same as LD A,(HL) (does not apply to IN/OUT ports,
  903.            those must use '(...)' form)</para>
  904.          </listitem>
  905.  
  906.          <listitem>
  907.            <para>IN F,(C) and OUT (C),0 and SLL/SLI can be used.</para>
  908.          </listitem>
  909.  
  910.          <listitem>
  911.            <para>IXL (or LX, XL), IYL (or LY, YL), IXH (or HX, XH) and IYH
  912.            (or HY, YH) registers are supported.</para>
  913.          </listitem>
  914.  
  915.          <listitem>
  916.            <para>Can write code throught colon: ORG 100h:LD A,10:LD B,10:SUB
  917.            B:RET:IFDEF AA:.....</para>
  918.          </listitem>
  919.  
  920.          <listitem>
  921.            <para>JP HL, JP IX and JP IY may be used instead of JP (HL),
  922.            etc.</para>
  923.          </listitem>
  924.  
  925.          <listitem>
  926.            <para>EX AF,AF or EX AF or EXA may be used instead of EX
  927.            AF,AF'.</para>
  928.          </listitem>
  929.  
  930.          <listitem>
  931.            <para>R800's MULUB and MULUW are recognised (but won't work on
  932.            Z80, of course:)</para>
  933.          </listitem>
  934.  
  935.          <listitem>
  936.            <para>RLC, RRC, RL, RR, SLA, SRA, SLL (SLI), RES, SET undocumented
  937.            instructions added.</para>
  938.          </listitem>
  939.        </itemizedlist><programlisting>    SET 4,(IX+4),C ; (aka LD C,SET 4,(IX+4)) is LD C,(IX+4) / SET 4,C / LD (IX+4),C
  940.    RRC (IY),A     ; (aka LD A,RRC (IY+0))   is LD A,(IY)   / RRC A   / LD (IY),A</programlisting><itemizedlist>
  941.          <listitem>
  942.            <para>PUSH and POP can take register lists:</para>
  943.          </listitem>
  944.        </itemizedlist><programlisting>    PUSH AF,BC  ; push af / push bc
  945.    POP  AF,BC  ; pop  af / pop  bc</programlisting><itemizedlist>
  946.          <listitem>
  947.            <para>and many other instructions support this "multi-argument" syntax:</para>
  948.          </listitem>
  949.        </itemizedlist><programlisting>    LD A,B,B,D,D,H
  950.   /* this is:
  951.     LD A,B
  952.     LD B,D
  953.     LD D,H
  954.   */
  955.   ;or you can write  LD A,B:LD B,D:LD D,H</programlisting></para>
  956.    </section>
  957.  
  958.    <section>
  959.      <title>Fake instructions</title>
  960.  
  961.      <para>Of course the Z80 is only an 8 bit cpu, but sometimes ld hl,de
  962.      would be nice. SjASMPlus now 'fakes' some instructions like that. This
  963.      improves the readability of the source, but it might not be the fastest
  964.      way to get the result. Also possibly some 'new' load instructions do
  965.      affect the flags in ways you wouldn't expect. Anyway, here's the
  966.      list:</para>
  967.  
  968.      <para><programlisting>  rl bc
  969.  rl de
  970.  rl hl
  971.  rr bc
  972.  rr de
  973.  rr hl
  974.  sla bc
  975.  sla de
  976.  sla hl
  977.  sll bc
  978.  sll de
  979.  sll hl
  980.  sli bc
  981.  sli de
  982.  sli hl
  983.  sra bc
  984.  sra de
  985.  sra hl
  986.  srl bc
  987.  srl de
  988.  srl hl
  989.  
  990.  ld bc,bc
  991.  ld bc,de
  992.  ld bc,hl
  993.  ld bc,ix
  994.  ld bc,iy
  995.  ld bc,(hl)
  996.  ld bc,(ix+nn)
  997.  ld bc,(iy+nn)
  998.  
  999.  ld de,bc
  1000.  ld de,de
  1001.  ld de,hl
  1002.  ld de,ix
  1003.  ld de,iy
  1004.  ld de,(hl)
  1005.  ld de,(ix+nn)
  1006.  ld de,(iy+nn)
  1007.  
  1008.  ld hl,bc
  1009.  ld hl,de
  1010.  ld hl,hl
  1011.  ld hl,ix
  1012.  ld hl,iy
  1013.  ld hl,(ix+nn)
  1014.  ld hl,(iy+nn)
  1015.  
  1016.  ld ix,bc
  1017.  ld ix,de
  1018.  ld ix,hl
  1019.  ld ix,ix
  1020.  ld ix,iy
  1021.  
  1022.  ld iy,bc
  1023.  ld iy,de
  1024.  ld iy,hl
  1025.  ld iy,ix
  1026.  ld iy,iy
  1027.  
  1028.  ld (hl),bc
  1029.  ld (hl),de
  1030.  
  1031.  ld (ix+nn),bc
  1032.  ld (ix+nn),de
  1033.  ld (ix+nn),hl
  1034.  
  1035.  ld (iy+nn),bc
  1036.  ld (iy+nn),de
  1037.  ld (iy+nn),hl
  1038.  
  1039.  ldi bc,(hl)
  1040.  ldi bc,(ix+nn)
  1041.  ldi bc,(iy+nn)
  1042.  
  1043.  ldi de,(hl)
  1044.  ldi de,(ix+nn)
  1045.  ldi de,(iy+nn)
  1046.  
  1047.  ldi hl,(ix+nn)
  1048.  ldi hl,(iy+nn)
  1049.  
  1050.  ldi (hl),bc
  1051.  ldi (hl),de
  1052.  
  1053.  ldi (ix+nn),bc
  1054.  ldi (ix+nn),de
  1055.  ldi (ix+nn),hl
  1056.  
  1057.  ldi (iy+nn),bc
  1058.  ldi (iy+nn),de
  1059.  ldi (iy+nn),hl
  1060.  
  1061.  ldi a,(bc)
  1062.  ldi a,(de)
  1063.  ldi a,(hl)
  1064.  ldi b,(hl)
  1065.  ldi c,(hl)
  1066.  ldi d,(hl)
  1067.  ldi e,(hl)
  1068.  ldi h,(hl)
  1069.  ldi l,(hl)
  1070.  ldi a,(ix+nn)
  1071.  ldi b,(ix+nn)
  1072.  ldi c,(ix+nn)
  1073.  ldi d,(ix+nn)
  1074.  ldi e,(ix+nn)
  1075.  ldi h,(ix+nn)
  1076.  ldi l,(ix+nn)
  1077.  ldi a,(iy+nn)
  1078.  ldi b,(iy+nn)
  1079.  ldi c,(iy+nn)
  1080.  ldi d,(iy+nn)
  1081.  ldi e,(iy+nn)
  1082.  ldi h,(iy+nn)
  1083.  ldi l,(iy+nn)
  1084.  
  1085.  ldd a,(bc)
  1086.  ldd a,(de)
  1087.  ldd a,(hl)
  1088.  ldd b,(hl)
  1089.  ldd c,(hl)
  1090.  ldd d,(hl)
  1091.  ldd e,(hl)
  1092.  ldd h,(hl)
  1093.  ldd l,(hl)
  1094.  ldd a,(ix+nn)
  1095.  ldd b,(ix+nn)
  1096.  ldd c,(ix+nn)
  1097.  ldd d,(ix+nn)
  1098.  ldd e,(ix+nn)
  1099.  ldd h,(ix+nn)
  1100.  ldd l,(ix+nn)
  1101.  ldd a,(iy+nn)
  1102.  ldd b,(iy+nn)
  1103.  ldd c,(iy+nn)
  1104.  ldd d,(iy+nn)
  1105.  ldd e,(iy+nn)
  1106.  ldd h,(iy+nn)
  1107.  ldd l,(iy+nn)
  1108.  
  1109.  ldi (bc),a
  1110.  ldi (de),a
  1111.  ldi (hl),a
  1112.  ldi (hl),b
  1113.  ldi (hl),c
  1114.  ldi (hl),d
  1115.  ldi (hl),e
  1116.  ldi (hl),h
  1117.  ldi (hl),l
  1118.  ldi (ix+nn),a
  1119.  ldi (ix+nn),b
  1120.  ldi (ix+nn),c
  1121.  ldi (ix+nn),d
  1122.  ldi (ix+nn),e
  1123.  ldi (ix+nn),h
  1124.  ldi (ix+nn),l
  1125.  ldi (iy+nn),a
  1126.  ldi (iy+nn),b
  1127.  ldi (iy+nn),c
  1128.  ldi (iy+nn),d
  1129.  ldi (iy+nn),e
  1130.  ldi (iy+nn),h
  1131.  ldi (iy+nn),l
  1132.  
  1133.  ldd (bc),a
  1134.  ldd (de),a
  1135.  ldd (hl),a
  1136.  ldd (hl),b
  1137.  ldd (hl),c
  1138.  ldd (hl),d
  1139.  ldd (hl),e
  1140.  ldd (hl),h
  1141.  ldd (hl),l
  1142.  ldd (ix+nn),a
  1143.  ldd (ix+nn),b
  1144.  ldd (ix+nn),c
  1145.  ldd (ix+nn),d
  1146.  ldd (ix+nn),e
  1147.  ldd (ix+nn),h
  1148.  ldd (ix+nn),l
  1149.  ldd (iy+nn),a
  1150.  ldd (iy+nn),b
  1151.  ldd (iy+nn),c
  1152.  ldd (iy+nn),d
  1153.  ldd (iy+nn),e
  1154.  ldd (iy+nn),h
  1155.  ldd (iy+nn),l
  1156.  
  1157.  ldi (hl),nn
  1158.  ldi (ix+nn),nn
  1159.  ldi (iy+nn),nn
  1160.  
  1161.  ldd (hl),nn
  1162.  ldd (ix+nn),nn
  1163.  ldd (iy+nn),nn
  1164.  
  1165.  sub hl,bc
  1166.  sub hl,de
  1167.  sub hl,hl
  1168.  sub hl,sp</programlisting>ldi increases the data pointer after the data
  1169.      access, so LDI A,(HL) is the same as LD A,(HL):INC HL. likewise, LDD
  1170.      A,(DE) is LD A,(DE):DEC DE.</para>
  1171.    </section>
  1172.  
  1173.    <section>
  1174.      <title><anchor id="s_realdevice" />Real device emulation mode</title>
  1175.  
  1176.      <para>To enable this mode you must use pseudo-op <link
  1177.      linkend="po_device">DEVICE</link>.</para>
  1178.  
  1179.      <para>In this mode the compiler compiling program to virtual memory (as
  1180.      at MSX's WB-ASS2, ZX-Spectrum's GENS, ZEUS, ALASM etc). After this all
  1181.      you can use new pseudo-ops as <link linkend="s_pseudoops">SAVEBIN, SAVEDEV
  1182.      SAVEHOB, SAVETRD, SAVETAP, PAGE, SLOT, MMU, LABELSLIST</link>, use special
  1183.      functions in <link linkend="c_lua_scripting">Lua scripts</link> and use operators
  1184.      <code>{address}, {b address}</code> to read WORD/BYTE from the virtual memory.</para>
  1185.  
  1186.      <para>If only single DEVICE is used in whole source batch, the device
  1187.      becomes "global" and will affect also source before of the DEVICE.
  1188.          <example>
  1189.          <title></title>
  1190.  
  1191.          <para><programlisting>    DEVICE ZXSPECTRUM128
  1192.    ;in this device, SLOT 3 enables to current by default.
  1193.  
  1194.    ORG 32768
  1195. StartProg:
  1196.    JP $
  1197.  
  1198.    DEVICE NONE
  1199.    ;do something, if you don't want to corrupt virtual
  1200.    ;memory with other code, for example, loader of code.
  1201.    ;...code...
  1202.  
  1203.    ;return to our virtual device:
  1204.    DEVICE ZXSPECTRUM128
  1205.  
  1206.    SAVESNA "snapshotname.sna",StartProg
  1207.  
  1208.    SAVETAP "tapefile.tap",StartProg
  1209. </programlisting></para>
  1210.        </example>Predefined devices:<variablelist>
  1211.          <varlistentry>
  1212.            <term>NONE</term>
  1213.  
  1214.            <listitem>
  1215.              <para>Disable real device emulation mode. By default.</para>
  1216.            </listitem>
  1217.          </varlistentry>
  1218.  
  1219.          <varlistentry>
  1220.            <term>ZXSPECTRUM48</term>
  1221.  
  1222.            <listitem>
  1223.              <para>Has 4 slots (0-3) with size 4000h, 4 pages (0-3) with size
  1224.              4000h. Slot 3 (it from 0C000h) enables to current by
  1225.              default.</para>
  1226.            </listitem>
  1227.          </varlistentry>
  1228.  
  1229.          <varlistentry>
  1230.            <term>ZXSPECTRUM128</term>
  1231.  
  1232.            <listitem>
  1233.              <para>Has 8 RAM pages (0-7) with size 4000h.</para>
  1234.            </listitem>
  1235.          </varlistentry>
  1236.  
  1237.          <varlistentry>
  1238.            <term>ZXSPECTRUM256</term>
  1239.  
  1240.            <listitem>
  1241.              <para>Same as russian clone Scorption 256. Has 16 RAM pages
  1242.              (0-15) with size 4000h.</para>
  1243.            </listitem>
  1244.          </varlistentry>
  1245.  
  1246.          <varlistentry>
  1247.            <term>ZXSPECTRUM512</term>
  1248.  
  1249.            <listitem>
  1250.              <para>Same as russian clones ATM Turbo 512 and Pentagon 512. Has
  1251.              32 RAM pages (0-31) with size 4000h.</para>
  1252.            </listitem>
  1253.          </varlistentry>
  1254.  
  1255.          <varlistentry>
  1256.            <term>ZXSPECTRUM1024</term>
  1257.  
  1258.            <listitem>
  1259.              <para>Same as russian clones ATM Turbo 2 and Pentagon 1024 SL.
  1260.              Has 64 RAM pages (0-63) with size 4000h.</para>
  1261.            </listitem>
  1262.          </varlistentry>
  1263.  
  1264.          <varlistentry>
  1265.            <term>ZXSPECTRUMNEXT</term>
  1266.  
  1267.            <listitem>
  1268.              <para>ZX Spectrum Next, has 8 slots (0-7) of size 0x2000 and 224
  1269.              RAM pages (0-223) totalling at 1.75MiB of memory. The default mapping
  1270.              is similar to ZX128, paging in: {14, 15, 10, 11, 4, 5, 0, 1} pages.
  1271.              The page 10 (bank 5) contains also ZX48 sysvars ("USR 0" mode) and
  1272.              clear ULA screen. (SAVESNA works only in ZX48 and ZX128 modes, in
  1273.              NEXT mode only SAVEBIN or saving specific TAP blocks work)</para>
  1274.            </listitem>
  1275.          </varlistentry>
  1276.        </variablelist></para>
  1277.  
  1278.      <para>If you want to see other devices you must write to us. See <link
  1279.      linkend="feedback">Feedback</link> chapter.</para>
  1280.    </section>
  1281.  
  1282.    <section>
  1283.      <title>Predefined defines</title>
  1284.  
  1285.      <para>SjASMPlus has predefined <link
  1286.      linkend="po_define">defines</link>.<variablelist>
  1287.          <varlistentry>
  1288.            <term>_SJASMPLUS = 1</term>
  1289.  
  1290.            <listitem>
  1291.              <para><example>
  1292.                  <title></title>
  1293.  
  1294.                  <para><programlisting>   IFDEF _SJASMPLUS
  1295.     ;code for sjasmplus
  1296.   ELSE
  1297.     ;code for other compiler
  1298.   ENDIF</programlisting></para>
  1299.                </example></para>
  1300.            </listitem>
  1301.          </varlistentry>
  1302.  
  1303.          <varlistentry>
  1304.            <term>_VERSION = "version"</term>
  1305.  
  1306.            <listitem>
  1307.              <para><example>
  1308.                  <title></title>
  1309.  
  1310.                  <para><programlisting>   IF _VERSION = "1.07"
  1311.     ;code for 1.07
  1312.   ELSE
  1313.     ;code for other version
  1314.   ENDIF</programlisting></para>
  1315.                </example></para>
  1316.            </listitem>
  1317.          </varlistentry>
  1318.  
  1319.          <varlistentry>
  1320.            <term>_RELEASE = releasenumber</term>
  1321.  
  1322.            <listitem>
  1323.              <para><example>
  1324.                  <title></title>
  1325.  
  1326.                  <para><programlisting>   IF _RELEASE = 1 ; 0 - is stable version
  1327.     ;code for Release Candidate 1
  1328.   ELSE
  1329.     ;code for other version
  1330.   ENDIF</programlisting></para>
  1331.                </example></para>
  1332.            </listitem>
  1333.          </varlistentry>
  1334.  
  1335.          <varlistentry>
  1336.            <term>_ERRORS = &lt;number&gt;</term>
  1337.  
  1338.            <listitem>
  1339.              <para>Number of errors.</para>
  1340.            </listitem>
  1341.          </varlistentry>
  1342.  
  1343.          <varlistentry>
  1344.            <term>_WARNINGS = &lt;number&gt;</term>
  1345.  
  1346.            <listitem>
  1347.              <para>Number of warnings.</para>
  1348.            </listitem>
  1349.          </varlistentry>
  1350.        </variablelist></para>
  1351.    </section>
  1352.  </chapter>
  1353.  
  1354.  <chapter>
  1355.    <title>Pseudo-ops (aka Pseudo-instructions, Directives etc)</title>
  1356.  
  1357.    <section>
  1358.      <title>Simple example of usage</title>
  1359.  
  1360.      <para><programlisting>     .SOMEPSEUDOOP ;or
  1361.     SOMEPSEUDOOP  ;or
  1362.     somepseudoop</programlisting></para>
  1363.    </section>
  1364.  
  1365.    <section>
  1366.      <title><anchor id="s_pseudoops" />Almost complete list</title>
  1367.  
  1368.      <para></para>
  1369.  
  1370.      <para><variablelist>
  1371.          <varlistentry>
  1372.            <term>.&lt;expression&gt; &lt;code&gt;</term>
  1373.  
  1374.            <listitem>
  1375.              <para>Repeat &lt;code&gt; &lt;expression&gt; once. Doesn't work
  1376.              in the beginning of line.<example>
  1377.                  <title></title>
  1378.  
  1379.                  <para><programlisting> .3        INC A    ;will be compiled to INC A:INC A:INC A
  1380. len        EQU 10
  1381. .(12-len) BYTE 0   ;will be compiled to BYTE 0,0</programlisting></para>
  1382.                </example></para>
  1383.            </listitem>
  1384.          </varlistentry>
  1385.  
  1386.          <varlistentry>
  1387.            <term><anchor id="po_abyte" />ABYTE &lt;offset&gt; &lt;bytes&gt;</term>
  1388.  
  1389.            <listitem>
  1390.              <para>Defines a byte or a string of bytes. The offset is added
  1391.              to each of the following bytes.<example>
  1392.                  <title></title>
  1393.  
  1394.                  <para><programlisting>    ABYTE 2 4,9    ; Same as BYTE 6,11
  1395.    ABYTE 3 "ABC"  ; Same as BYTE "DEF"</programlisting></para>
  1396.                </example></para>
  1397.            </listitem>
  1398.          </varlistentry>
  1399.  
  1400.          <varlistentry>
  1401.            <term><anchor id="po_abytec" />ABYTEC &lt;offset&gt; &lt;bytes&gt;</term>
  1402.  
  1403.            <listitem>
  1404.              <para>Defines a byte or a string of bytes, where the last byte
  1405.              of the string will have bit 7 set. The offset is added to each
  1406.              of the following bytes.<example>
  1407.                  <title></title>
  1408.  
  1409.                  <para><programlisting>    ABYTEC 0 "KIP"        ; Same as BYTE "KI",'P'|128
  1410.    ABYTEC 1 "ABC",0,"DE" ; Same as BYTE "BC",'D'|128,1,'E','F'|128</programlisting></para>
  1411.                </example></para>
  1412.            </listitem>
  1413.          </varlistentry>
  1414.  
  1415.          <varlistentry>
  1416.            <term><anchor id="po_abytez" />ABYTEZ &lt;offset&gt; &lt;bytes&gt;</term>
  1417.  
  1418.            <listitem>
  1419.              <para>Defines a byte or a string of bytes, followed by a zero.
  1420.              The offset is added to each of the following bytes.<example>
  1421.                  <title></title>
  1422.  
  1423.                  <para><programlisting>    ABYTEZ 0 "KIP"        ; Same as BYTE "KIP",0</programlisting></para>
  1424.                </example></para>
  1425.            </listitem>
  1426.          </varlistentry>
  1427.  
  1428.          <varlistentry>
  1429.            <term><anchor id="po_align" />ALIGN
  1430.            [&lt;expression equal to 1,2,4,8,16,32,64,128,256,512,1024,2048,4096,8192,16384 or
  1431.            32768&gt;[, &lt;byte&gt;]]</term>
  1432.  
  1433.            <listitem>
  1434.              <para>Align advances to nearest address where &lt;new address&gt; modulo &lt;expression&gt; (default 4)
  1435.                  equals zero (stays at current address if possible).</para>
  1436.              <para>If &lt;byte&gt; is specified, memory advanced over is set to it.
  1437.                  <example>
  1438.                  <title></title>
  1439.  
  1440.                  <para><programlisting>    ALIGN         ; =&gt; ALIGN 4 - simply align by 4
  1441.    ALIGN 2       ; by 2 (preserves value of "device" memory)
  1442.    ALIGN 2,0     ; + fills memory with zero</programlisting></para>
  1443.                </example></para>
  1444.            </listitem>
  1445.          </varlistentry>
  1446.  
  1447.          <varlistentry>
  1448.            <term><anchor id="po_assert" />ASSERT &lt;expression&gt;</term>
  1449.  
  1450.            <listitem>
  1451.              <para>An 'assertion failed' error is issued if the expression
  1452.              evaluates to zero.<example>
  1453.                  <title></title>
  1454.  
  1455.                  <para><programlisting>STACKPOINTER=0D500H
  1456.    ASSERT END_OF_PROGRAM &lt; STACKPOINTER
  1457. END_OF_PROGRAM
  1458.    END</programlisting></para>
  1459.                </example></para>
  1460.            </listitem>
  1461.          </varlistentry>
  1462.  
  1463.          <varlistentry>
  1464.            <term><anchor id="po_binary" />BINARY &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  1465.  
  1466.            <listitem>
  1467.              <para>Synonym of <link linkend="po_incbin">INCBIN</link>.</para>
  1468.            </listitem>
  1469.          </varlistentry>
  1470.  
  1471.          <varlistentry>
  1472.            <term><anchor id="po_block" />BLOCK &lt;length&gt;[,&lt;fill
  1473.            byte&gt;]</term>
  1474.  
  1475.            <listitem>
  1476.              <para>Defines space. Has to be followed by the number of byte to
  1477.              reserve, optionally followed by the value to fill these bytes
  1478.              with.<example>
  1479.                  <title></title>
  1480.  
  1481.                  <para><programlisting>    BLOCK 500     ; define a block of 500 bytes of zero
  1482.    BLOCK 500,0   ; define a block of 500 bytes of zero
  1483.    BLOCK 400,-1  ; define a block of 400 bytes of 255</programlisting></para>
  1484.                </example></para>
  1485.            </listitem>
  1486.          </varlistentry>
  1487.  
  1488.          <varlistentry>
  1489.            <term><anchor id="po_byte" />BYTE &lt;bytes&gt;</term>
  1490.  
  1491.            <listitem>
  1492.              <para>Defines a byte or a string of bytes. Each value should be
  1493.              between -129 and 256.<example>
  1494.                  <title></title>
  1495.  
  1496.                  <para><programlisting>    BYTE 0x56
  1497.    BYTE 1,-78,'@'
  1498.    BYTE "Format C:? ",0h</programlisting></para>
  1499.                </example></para>
  1500.            </listitem>
  1501.          </varlistentry>
  1502.  
  1503.          <varlistentry>
  1504.            <term><anchor id="po_cspectmap" />CSPECTMAP [&lt;filename&gt;]</term>
  1505.  
  1506.            <listitem>
  1507.              <para><emphasis>Useful for ZX-Spectrum Emulator
  1508.              #CSpect by Mike Dailly.</emphasis></para>
  1509.  
  1510.              <para><emphasis>Works only in real device emulation mode. See
  1511.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  1512.  
  1513.              <para>Saves labels list in format:</para>
  1514.  
  1515.              <para><synopsis>HEXA_16BIT_ADDRESS HEXA_LONG_ADDRESS TYPE LABELNAME</synopsis>
  1516.              where TYPE is: 00 = regular label, 01 = EQU or struct defined, 02 = DEFL defined.</para>
  1517.  
  1518.              <para>If no filename is provided, default is created by appending ".map" to source name.</para>
  1519.            </listitem>
  1520.          </varlistentry>
  1521.  
  1522.          <varlistentry>
  1523.            <term><anchor id="po_d24" />D24</term>
  1524.  
  1525.            <listitem>
  1526.              <para>Defines three bytes by 24b constant. Values should be between
  1527.              -16777217 and 16777216.<example>
  1528.                  <title></title>
  1529.  
  1530.                  <para><programlisting>    D24 0x123456   ; define three bytes 0x56, 0x34, 0x12</programlisting></para>
  1531.                </example></para>
  1532.            </listitem>
  1533.          </varlistentry>
  1534.  
  1535.          <varlistentry>
  1536.            <term><anchor id="po_db" />DB</term>
  1537.  
  1538.            <listitem>
  1539.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1540.            </listitem>
  1541.          </varlistentry>
  1542.  
  1543.          <varlistentry>
  1544.            <term><anchor id="po_dc" />DC</term>
  1545.  
  1546.            <listitem>
  1547.              <para>Same as <link linkend="po_byte">BYTE</link>, but every
  1548.              last character of a string will have bit 7 set.<example>
  1549.                  <title></title>
  1550.  
  1551.                  <para><programlisting>    DC "kip" ; same as BYTE "ki",'p'|128</programlisting></para>
  1552.                </example></para>
  1553.            </listitem>
  1554.          </varlistentry>
  1555.  
  1556.          <varlistentry>
  1557.            <term><anchor id="po_dd" />DD</term>
  1558.  
  1559.            <listitem>
  1560.              <para>Synonym of <link linkend="po_dword">DWORD</link>.</para>
  1561.            </listitem>
  1562.          </varlistentry>
  1563.  
  1564.          <varlistentry>
  1565.            <term><anchor id="po_defarray" />DEFARRAY &lt;id&gt; &lt;replacements&gt;</term>
  1566.  
  1567.            <listitem>
  1568.              <para>Array of DEFINEs<example>
  1569.                  <title></title>
  1570.  
  1571.                  <para><programlisting>    DEFARRAY myarray 10*20,"A",20,&lt;/D,40&gt;,50,70
  1572. CNT DEFL 0 ;or CNT=0
  1573.    DUP 6
  1574.    DISPLAY myarray[CNT]
  1575. CNT DEFL CNT+1 ;or CNT=CNT+1
  1576.    EDUP</programlisting></para>
  1577.                </example></para>
  1578.            </listitem>
  1579.          </varlistentry>
  1580.  
  1581.          <varlistentry>
  1582.            <term><anchor id="po_defarray_plus" />DEFARRAY+ &lt;id&gt; &lt;additional replacements&gt;</term>
  1583.  
  1584.            <listitem>
  1585.              <para>Appending more DEFINEs to already defined array<example>
  1586.                  <title></title>
  1587.  
  1588.                  <para><programlisting>    DEFARRAY   myarray 'A', 'B', 'C'
  1589.    DEFARRAY+  myarray 'D', 'E'            ; now "myarray" has 5 items
  1590.    DUP 3 : DEFARRAY+ myarray '!' : EDUP   ; "DEFARRAYFILL" adding 3x '!'</programlisting></para>
  1591.                </example></para>
  1592.            </listitem>
  1593.          </varlistentry>
  1594.  
  1595.          <varlistentry>
  1596.            <term><anchor id="po_defb" />DEFB</term>
  1597.  
  1598.            <listitem>
  1599.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1600.            </listitem>
  1601.          </varlistentry>
  1602.  
  1603.          <varlistentry>
  1604.            <term><anchor id="po_defd" />DEFD</term>
  1605.  
  1606.            <listitem>
  1607.              <para>Synonym of <link linkend="po_dword">DWORD</link>.</para>
  1608.            </listitem>
  1609.          </varlistentry>
  1610.  
  1611.          <varlistentry>
  1612.            <term><anchor id="po_defdevice" />DEFDEVICE
  1613.            &lt;deviceid&gt;</term>
  1614.  
  1615.            <listitem>
  1616.              <para>Sorry, not available yet. If you want to see new device in
  1617.              SjASMPlus, please, <link linkend="feedback">write
  1618.              us</link>.</para>
  1619.            </listitem>
  1620.          </varlistentry>
  1621.  
  1622.          <varlistentry>
  1623.            <term><anchor id="po_defg" />DEFG</term>
  1624.  
  1625.            <listitem>
  1626.              <para>Synonym of <link linkend="po_dg">DG</link>.</para>
  1627.            </listitem>
  1628.          </varlistentry>
  1629.  
  1630.          <varlistentry>
  1631.            <term><anchor id="po_defh" />DEFH</term>
  1632.  
  1633.            <listitem>
  1634.              <para>Synonym of <link linkend="po_dh">DH</link>.</para>
  1635.            </listitem>
  1636.          </varlistentry>
  1637.  
  1638.          <varlistentry>
  1639.            <term><anchor id="po_define" />DEFINE &lt;id&gt;
  1640.            &lt;replacement&gt;</term>
  1641.  
  1642.            <listitem>
  1643.              <para>The identifier &lt;id&gt; will be replaced with the
  1644.              &lt;replacement&gt;. The replacement could be omitted, in such
  1645.              case it is still possible to check if the identifier was defined
  1646.              with IFDEF or IFNDEF.<example>
  1647.                  <title></title>
  1648.  
  1649.                  <para><programlisting>    DEFINE str_honderd "Honderd"
  1650.    BYTE str_honderd,0             ; BYTE "Honderd",0</programlisting></para>
  1651.                </example></para>
  1652.            </listitem>
  1653.          </varlistentry>
  1654.  
  1655.          <varlistentry>
  1656.            <term><anchor id="po_defm" />DEFM</term>
  1657.  
  1658.            <listitem>
  1659.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1660.            </listitem>
  1661.          </varlistentry>
  1662.  
  1663.          <varlistentry>
  1664.            <term><anchor id="po_defs" />DEFS</term>
  1665.  
  1666.            <listitem>
  1667.              <para>Synonym of <link linkend="po_block">BLOCK</link>.</para>
  1668.            </listitem>
  1669.          </varlistentry>
  1670.  
  1671.          <varlistentry>
  1672.            <term><anchor id="po_defw" />DEFW</term>
  1673.  
  1674.            <listitem>
  1675.              <para>Synonym of <link linkend="po_word">WORD</link>.</para>
  1676.            </listitem>
  1677.          </varlistentry>
  1678.  
  1679.          <varlistentry>
  1680.            <term><anchor id="po_dephase" />DEPHASE</term>
  1681.  
  1682.            <listitem>
  1683.              <para>Synonym of <link linkend="po_ent">ENT</link>.</para>
  1684.            </listitem>
  1685.          </varlistentry>
  1686.  
  1687.          <varlistentry>
  1688.            <term><anchor id="po_device" />DEVICE &lt;deviceid&gt;</term>
  1689.  
  1690.            <listitem>
  1691.              <para>Enables <link linkend="s_realdevice">real device emulation
  1692.              mode</link> by it identifier. If there is only single DEVICE directive
  1693.              in whole source batch, it becomes "global" and the device affects all
  1694.              lines of source, otherwise the DEVICE is applied for lines following it.</para>
  1695.  
  1696.              <para>Predefined devices' identifiers list:</para>
  1697.  
  1698.              <synopsis> NONE ; off real device emulation mode
  1699. ZXSPECTRUM48  ; ZX-Spectrum 48 (4 slots, 4 pages, slot/page size 0x4000, default map: 0, 1, 2, 3)
  1700. ZXSPECTRUM128 ; ZX-Spectrum 128 (like 48 with 8 pages, default map: 7, 5, 2, 0)
  1701. ZXSPECTRUM256 ; e.g. Scorpion 256 (exUSSR clone of ZX-Spectrum 128)
  1702. ZXSPECTRUM512 ; e.g. ATM-Turbo 512 (another clone)
  1703. ZXSPECTRUM1024
  1704. ZXSPECTRUMNEXT ; ZX Spectrum Next (8 slots, 224 pages, slot size 0x2000 = 1.75MiB RAM)
  1705.                ;                  (default map: 14, 15, 10, 11, 4, 5, 0, 1)
  1706.  
  1707. ;disable:
  1708.   DEVICE NONE
  1709. ;enable:
  1710.   DEVICE ZXSPECTRUM128</synopsis>
  1711.            </listitem>
  1712.          </varlistentry>
  1713.  
  1714.          <varlistentry>
  1715.            <term><anchor id="po_dg" />DG &lt;data encoded in bits&gt;</term>
  1716.  
  1717.            <listitem>
  1718.              <para>Data comprises of characters in multiples of eight, each block
  1719.              is converted to a byte value.</para>
  1720.  
  1721.              <para>A hyphen '-' (also '.' and '_') represents 0 and any other non-whitespace character
  1722.              represents 1. It ignores spaces, use them for formatting if you like. Warning, "DG 10100001" is value 255, because character '0' is not a dash '-'. (since v1.11)<example>
  1723.                  <title></title>
  1724.                  <para><programlisting>    DG 1-1----1  ; store 161 at the current location
  1725.    DG ...# #... .##. .... ; store two bytes: 0x18, 0x60</programlisting></para>
  1726.              </example></para>
  1727.            </listitem>
  1728.          </varlistentry>
  1729.  
  1730.          <varlistentry>
  1731.            <term><anchor id="po_dh" />DH "&lt;data&gt;"[,"&lt;data2&gt;"...]</term>
  1732.  
  1733.            <listitem>
  1734.              <para>The data string comprises pairs of hexadecimal digits, each pair is converted to
  1735.              a byte value. You can add spaces between pairs as you like. (since v1.11)<example>
  1736.                  <title></title>
  1737.                  <para><programlisting>    DH "0123456789ABCDEF"   ; eight bytes #01 #23 ...
  1738.    DH "01 23  45 67"       ; four bytes #01 #23 #45 #67</programlisting></para>
  1739.              </example></para>
  1740.            </listitem>
  1741.          </varlistentry>
  1742.  
  1743.          <varlistentry>
  1744.            <term><anchor id="po_disp" />DISP &lt;address&gt;</term>
  1745.  
  1746.            <listitem>
  1747.              <para>Set the address in which the part of code should work.
  1748.              <link linkend="po_phase">PHASE</link> and <link
  1749.              linkend="po_textarea">TEXTAREA</link> are synonyms of DISP.
  1750.              <link linkend="po_ent">ENT</link> is restore current address.
  1751.              <link linkend="po_unphase">UNPHASE</link>, <link
  1752.              linkend="po_dephase">DEPHASE</link> and <link
  1753.              linkend="po_endt">ENDT</link> are synonyms of <link
  1754.              linkend="po_ent">ENT</link>. DISP blocks can NOT be nested, and to change
  1755.              the displacement address within current DISP block use the ordinary ORG.
  1756.              <example>
  1757.                  <title></title>
  1758.  
  1759.                  <para><programlisting>SCREEN EQU $4000
  1760.    ORG $8000
  1761.    LD HL,BEGIN
  1762.    LD DE,SCREEN
  1763.    LD BC,ENDOFPROG-BEGIN
  1764.    LDIR
  1765.    CALL SCREEN
  1766.    DI
  1767.    HALT
  1768. BEGIN  DISP SCREEN ;code will compile for address $4000, but to the current ORG
  1769. MARKA  DEC A
  1770.    HALT
  1771.    JP NZ,MARKA
  1772.    RET
  1773.       ENT
  1774. ENDOFPROG</programlisting></para>
  1775.                </example></para>
  1776.            </listitem>
  1777.          </varlistentry>
  1778.  
  1779.          <varlistentry>
  1780.            <term><anchor id="po_display" />DISPLAY &lt;bytes&gt;</term>
  1781.  
  1782.            <listitem>
  1783.              <para><emphasis>This pseudo-op comes from ZX-Spectrum assembler
  1784.              ALASM.</emphasis></para>
  1785.  
  1786.              <para>Out to console a string of bytes. Each value should be
  1787.              between -129 and 256. Keys /D, /H and /A set format of output of
  1788.              numbers:<synopsis>/D - out only in Decimal
  1789. /H - out only in Hexadecimal
  1790. /A - out both in Hexadecimal and Decimal</synopsis>
  1791.              <example>
  1792.                  <title></title>
  1793.  
  1794.                  <para><programlisting>    ORG 100h
  1795. TESTLABEL:
  1796.    ;...some code...
  1797.    RET
  1798.    DISPLAY "--the some program-- by me"
  1799.    DISPLAY "TESTLABEL address is:",/A,TESTLABEL
  1800. /*
  1801. will output to the console strings:
  1802. &gt; --the some program-- by me
  1803. &gt; TESTLABEL address is:0x100, 256
  1804. */</programlisting></para>
  1805.                </example></para>
  1806.            </listitem>
  1807.          </varlistentry>
  1808.  
  1809.          <varlistentry>
  1810.            <term><anchor id="po_dm" />DM</term>
  1811.  
  1812.            <listitem>
  1813.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1814.            </listitem>
  1815.          </varlistentry>
  1816.  
  1817.          <varlistentry>
  1818.            <term><anchor id="po_ds" />DS</term>
  1819.  
  1820.            <listitem>
  1821.              <para>Synonym of <link linkend="po_block">BLOCK</link>.</para>
  1822.            </listitem>
  1823.          </varlistentry>
  1824.  
  1825.          <varlistentry>
  1826.            <term><anchor id="po_dup" />DUP &lt;count&gt;</term>
  1827.  
  1828.            <listitem>
  1829.              <para>DUP specifies the number of times to generate the
  1830.              following lines until an EDUP pseudo-op is encountered. DUP can be used in macro's.<example>
  1831.                  <title></title>
  1832.  
  1833.                  <para><programlisting>    DUP 3
  1834.    NOP
  1835.    EDUP
  1836.  
  1837. /*this will expand to:
  1838.    NOP
  1839.    NOP
  1840.    NOP
  1841. */</programlisting></para>
  1842.                </example></para>
  1843.            </listitem>
  1844.          </varlistentry>
  1845.  
  1846.          <varlistentry>
  1847.            <term><anchor id="po_dw" />DW</term>
  1848.  
  1849.            <listitem>
  1850.              <para>Synonym of <link linkend="po_word">WORD</link>.</para>
  1851.            </listitem>
  1852.          </varlistentry>
  1853.  
  1854.          <varlistentry>
  1855.            <term><anchor id="po_dword" />DWORD</term>
  1856.  
  1857.            <listitem>
  1858.              <para>Defines a so called doubleword. Values should be between
  1859.              -2147483649 and 4294967296.<example>
  1860.                  <title></title>
  1861.  
  1862.                  <para><programlisting>    DWORD 4000h,0d000h
  1863.    DWORD 4</programlisting></para>
  1864.                </example></para>
  1865.            </listitem>
  1866.          </varlistentry>
  1867.  
  1868.          <varlistentry>
  1869.            <term><anchor id="po_dz" />DZ</term>
  1870.  
  1871.            <listitem>
  1872.              <para>Same as <link linkend="po_byte">BYTE</link>, but an extra
  1873.              zero will be added at the end.<example>
  1874.                  <title></title>
  1875.  
  1876.                  <para><programlisting>    DZ 1      ; same as BYTE 1,0
  1877.    DZ "kip"  ; same as BYTE "kip",0</programlisting></para>
  1878.                </example></para>
  1879.            </listitem>
  1880.          </varlistentry>
  1881.  
  1882.          <varlistentry>
  1883.            <term><anchor id="po_emptytap" />EMPTYTAP &lt;filenameoftapefile&gt;</term>
  1884.  
  1885.            <listitem>
  1886.              <para><emphasis>Useful only for ZX-Spectrum
  1887.              users</emphasis></para>
  1888.  
  1889.              <para>Create the new or truncate existing standard tape file
  1890.              for emulators of ZX-Spectrum. See example of
  1891.              <link linkend="po_savetap">SAVETAP</link>.</para>
  1892.            </listitem>
  1893.          </varlistentry>
  1894.  
  1895.          <varlistentry>
  1896.            <term><anchor id="po_emptytrd" />EMPTYTRD &lt;filenameoftrdimage&gt;</term>
  1897.  
  1898.            <listitem>
  1899.              <para><emphasis>Useful only for ZX-Spectrum
  1900.              users</emphasis></para>
  1901.  
  1902.              <para>Create the empty TRD image for emulators of ZX-Spectrum.
  1903.              See example of <link linkend="po_savetrd">SAVETRD</link>.</para>
  1904.            </listitem>
  1905.          </varlistentry>
  1906.  
  1907.          <varlistentry>
  1908.            <term><anchor id="po_encoding" />ENCODING &lt;encoding&gt;</term>
  1909.  
  1910.            <listitem>
  1911.              <para><emphasis>Useful only for non English
  1912.              users</emphasis></para>
  1913.  
  1914.              <para>Set the current encoding, i.e. if you set "DOS", SjASMPlus
  1915.              will automatically convert strings from ANSI to DOS-866.
  1916.              Encoding may be "DOS"(DOS-866) or "WIN"(ANSI/Win-1251). Default
  1917.              is "WIN". <example>
  1918.                  <title></title>
  1919.  
  1920.                  <para><programlisting>    ENCODING "WIN"
  1921.    DB "тексттекст" ;will be тексттекст
  1922.    ENCODING "DOS"
  1923.    DB "тексттекст" ;will be ⥪бв⥪бв</programlisting></para>
  1924.                </example></para>
  1925.            </listitem>
  1926.          </varlistentry>
  1927.  
  1928.          <varlistentry>
  1929.            <term><anchor id="po_end" />END [&lt;startaddress&gt;]</term>
  1930.  
  1931.            <listitem>
  1932.              <para>The assembler will stop at this point. The pseudo-op
  1933.              END does NOT work in the beginning of line (even with --dirbol).
  1934.              The optional argument is used by SAVESNA, SAVETAP and SAVENEX.</para>
  1935.            </listitem>
  1936.          </varlistentry>
  1937.  
  1938.          <varlistentry>
  1939.            <term><anchor id="po_endlua" />ENDLUA</term>
  1940.  
  1941.            <listitem>
  1942.              <para>See <link linkend="po_lua">LUA</link> for more
  1943.              information.</para>
  1944.            </listitem>
  1945.          </varlistentry>
  1946.  
  1947.          <varlistentry>
  1948.            <term><anchor id="po_endmod" />ENDMOD</term>
  1949.  
  1950.            <listitem>
  1951.              <para>Synonym of <link
  1952.              linkend="po_endmodule">ENDMODULE</link>.</para>
  1953.            </listitem>
  1954.          </varlistentry>
  1955.  
  1956.          <varlistentry>
  1957.            <term><anchor id="po_endmodule" />ENDMODULE</term>
  1958.  
  1959.            <listitem>
  1960.              <para>To indicate the end of a module (see <link
  1961.              linkend="po_module">MODULE</link>), and use the previous
  1962.              modulename.<example>
  1963.                  <title></title>
  1964.  
  1965.                  <para><programlisting>    MODULE M1
  1966. A                 ; M1.A
  1967.    MODULE M2
  1968. A                 ; M2.A
  1969.    ENDMODULE
  1970. B                 ; M1.B
  1971.    ENDMODULE</programlisting></para>
  1972.                </example></para>
  1973.            </listitem>
  1974.          </varlistentry>
  1975.  
  1976.          <varlistentry>
  1977.            <term><anchor id="po_endt" />ENDT</term>
  1978.  
  1979.            <listitem>
  1980.              <para>Synonym of <link linkend="po_ent">ENT</link>.</para>
  1981.            </listitem>
  1982.          </varlistentry>
  1983.  
  1984.          <varlistentry>
  1985.            <term><anchor id="po_ent" />ENT</term>
  1986.  
  1987.            <listitem>
  1988.              <para>Restore current address. See <link
  1989.              linkend="po_disp">DISP</link> for more information.</para>
  1990.            </listitem>
  1991.          </varlistentry>
  1992.  
  1993.          <varlistentry>
  1994.            <term><anchor id="po_equ" />EQU</term>
  1995.  
  1996.            <listitem>
  1997.              <para>To give a label a value other than the current program
  1998.              counter. '=' can be used instead of 'EQU'. The label should not
  1999.              already exist.<example>
  2000.                  <title></title>
  2001.  
  2002.                  <para><programlisting>Label EQU 3
  2003. Kip=3</programlisting></para>
  2004.                </example></para>
  2005.            </listitem>
  2006.          </varlistentry>
  2007.  
  2008.          <varlistentry>
  2009.            <term><anchor id="po_export" />EXPORT label</term>
  2010.  
  2011.            <listitem>
  2012.              <para>The named label will be written to the export-file, in the
  2013.              form 'label: EQU value'. This way the export-file can be
  2014.              included in other sources.<example>
  2015.                  <title></title>
  2016.  
  2017.                  <para><programlisting>DRIE=3
  2018.    EXPORT DRIE</programlisting></para>
  2019.                </example></para>
  2020.            </listitem>
  2021.          </varlistentry>
  2022.  
  2023.          <varlistentry>
  2024.            <term><anchor id="po_fpos" />FPOS &lt;position&gt;</term>
  2025.  
  2026.            <listitem>
  2027.              <para>The FPOS directive makes it possible to set the file
  2028.              position to anywhere in the output file.</para>
  2029.  
  2030.              <para>In combination with <link
  2031.              linkend="po_output">OUTPUT</link> &lt;filename&gt;,r it is
  2032.              possible to update existing files.</para>
  2033.  
  2034.              <para><example>
  2035.                  <title></title>
  2036.  
  2037.                  <para><programlisting>; This example will result in a file with a length of one byte:
  2038.    BYTE 0
  2039.    FPOS 0
  2040.    BYTE 1
  2041.    END</programlisting></para>
  2042.                </example></para>
  2043.            </listitem>
  2044.          </varlistentry>
  2045.  
  2046.          <varlistentry>
  2047.            <term><anchor id="po_hex" />HEX</term>
  2048.  
  2049.            <listitem>
  2050.              <para>Synonym of <link linkend="po_dh">DH</link>, usually used without quotes around data.</para>
  2051.            </listitem>
  2052.          </varlistentry>
  2053.  
  2054.          <varlistentry>
  2055.            <term><anchor id="po_incbin" />INCBIN
  2056.            &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2057.  
  2058.            <listitem>
  2059.              <para>To include a binary file into the outputfile. The offset
  2060.              and length are optional. Added in v1.12.1: if negative offset or length is provided,
  2061.              it counts relatively from the end of the file.<example>
  2062.                  <title></title>
  2063.  
  2064.                  <para><programlisting>    INCBIN "gfx.scc",7        ; include gfx.scc, skip first 7 bytes
  2065.    INCBIN "rantab.com",3,256 ; include 256 bytes from offset 3
  2066.    INCBIN gfx.scc ,,7        ; 7 bytes from offset 0 (unquoted filename must end with space)
  2067.    INCBIN "48.rom",-768,-256 ; include (from 16kiB file) 512 bytes 15616..16127</programlisting></para>
  2068.                </example></para>
  2069.            </listitem>
  2070.          </varlistentry>
  2071.  
  2072.          <varlistentry>
  2073.            <term><anchor id="po_inchob" />INCHOB &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2074.  
  2075.            <listitem>
  2076.              <para>To include a data from a hobeta file into the outputfile.
  2077.              The offset and length are optional.<example>
  2078.                  <title></title>
  2079.  
  2080.                  <para><programlisting>    INCHOB "gfx.$c",7        ; include gfx.scc, skip first 7 bytes
  2081.    INCHOB "sprs.$c",3,256   ; include 256 bytes from offset 3
  2082.    INCHOB gfx.$c ,7        ; note the space between the filename and the ',7' here :)</programlisting></para>
  2083.                </example></para>
  2084.            </listitem>
  2085.          </varlistentry>
  2086.  
  2087.          <varlistentry>
  2088.            <term><anchor id="po_include" />INCLUDE &lt;filename&gt;</term>
  2089.  
  2090.            <listitem>
  2091.              <para>To include another sourcefile into the current.
  2092.              Sourcefiles can be nested 20 levels deep. If the file cannot be
  2093.              found in the current directory (the current directory is the
  2094.              directory the current file comes from) the file will be searched
  2095.              for in the directories specified at the commandline. When angle
  2096.              brackets are used, the commandline directories are searched
  2097.              before the current directory.<example>
  2098.                  <title></title>
  2099.  
  2100.                  <para><programlisting>    INCLUDE &lt;VDP.I&gt;
  2101.    INCLUDE MORE.I
  2102.    INCLUDE "MORE.I"</programlisting></para>
  2103.                </example></para>
  2104.            </listitem>
  2105.          </varlistentry>
  2106.  
  2107.          <varlistentry>
  2108.            <term><anchor id="po_includelua" />INCLUDELUA &lt;filename&gt;</term>
  2109.  
  2110.            <listitem>
  2111.              <para>To include another LUA script in first pass(!). If the
  2112.              file cannot be found in the current directory (the current
  2113.              directory is the directory the current file comes from) the file
  2114.              will be searched for in the directories specified at the
  2115.              commandline. When angle brackets are used, the commandline
  2116.              directories are searched before the current directory.<example>
  2117.                  <title></title>
  2118.  
  2119.                  <para><programlisting>    INCLUDELUA &lt;mylibrary1.lua&gt;
  2120.    INCLUDELUA mylibrary2.lua
  2121.    INCLUDELUA "library_for_zx.lua"</programlisting></para>
  2122.                </example></para>
  2123.            </listitem>
  2124.          </varlistentry>
  2125.  
  2126.          <varlistentry>
  2127.            <term><anchor id="po_inctrd" />INCTRD
  2128.            &lt;filenameoftrdimage&gt;,&lt;filenameintrdimage&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2129.  
  2130.            <listitem>
  2131.              <para>To include a file from a TRD image into the outputfile.
  2132.              The offset and length are optional.<example>
  2133.                  <title></title>
  2134.  
  2135.                  <para><programlisting>    INCTRD "test.trd","mygfx.C" ; include mygfx.C from test.trd
  2136.    INCTRD "test.trd","mygfx.C",12 ; include mygfx.C from test.trd, skip first 12 bytes</programlisting></para>
  2137.                </example></para>
  2138.            </listitem>
  2139.          </varlistentry>
  2140.  
  2141.          <varlistentry>
  2142.            <term><anchor id="po_insert" />INSERT &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2143.  
  2144.            <listitem>
  2145.              <para>INSERT is a synonym of <link
  2146.              linkend="po_incbin">INCBIN</link>. See above.</para>
  2147.            </listitem>
  2148.          </varlistentry>
  2149.  
  2150.          <varlistentry>
  2151.            <term><anchor id="po_labelslist" />LABELSLIST &lt;filename&gt;</term>
  2152.  
  2153.            <listitem>
  2154.              <para><emphasis>Useful only for ZX-Spectrum Emulator
  2155.              UNREALSPECCY.</emphasis></para>
  2156.  
  2157.              <para><emphasis>Work only in real device emulation mode. See
  2158.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2159.  
  2160.              <para>Save labels list in format:</para>
  2161.  
  2162.              <para><synopsis>NN:ADDRESS LABELNAME</synopsis>
  2163.              where NN is number of RAM page and ADDRESS is truncated to 0000..3FFF range</para>
  2164.  
  2165.              <para><example>
  2166.                  <title></title>
  2167.  
  2168.                  <para><programlisting>    LABELSLIST "x:/somepath/user.l"</programlisting></para>
  2169.                </example></para>
  2170.            </listitem>
  2171.          </varlistentry>
  2172.  
  2173.          <varlistentry>
  2174.            <term>LUA [pass]<anchor id="po_lua" /></term>
  2175.  
  2176.            <listitem>
  2177.              <para>Using pseudo-ops LUA and ENDLUA you can insert Lua
  2178.              scripts. See more in the chapter "<link
  2179.               linkend="c_lua_scripting">Lua scripting</link>".</para>
  2180.  
  2181.              <para>Parameter is optional. It may be:<synopsis>PASS1   -  interpret Lua script in first pass only.
  2182. PASS2   -  interpret Lua script in second pass only.
  2183. PASS3   -  interpret Lua script in third pass only. By default.
  2184. ALLPASS -  interpret Lua script in all passes. It is need, if you generate some Z80 code.</synopsis></para>
  2185.  
  2186.              <para><example>
  2187.                  <title></title>
  2188.  
  2189.                  <para><programlisting>    LUA
  2190. -- some comments
  2191.        print "Hi, man! This is Lua!"
  2192.    ENDLUA
  2193. ; some code now:
  2194.    LUA ALLPASS
  2195.        _pl("LABEL LD A,10")
  2196.        _pc("RET")
  2197.    ENDLUA</programlisting></para>
  2198.                </example></para>
  2199.            </listitem>
  2200.          </varlistentry>
  2201.  
  2202.          <varlistentry>
  2203.            <term><anchor id="po_memorymap" />MEMORYMAP</term>
  2204.  
  2205.            <listitem>
  2206.              <para>Not available yet.</para>
  2207.            </listitem>
  2208.          </varlistentry>
  2209.  
  2210.          <varlistentry>
  2211.            <term><anchor id="po_mmu" />MMU &lt;first slot number&gt; [&lt;last slot number&gt;|&lt;single slot option&gt;], &lt;page number&gt;</term>
  2212.  
  2213.            <listitem>
  2214.              <para>Maps memory page(s) to slot(s), similar to SLOT + PAGE combination, but allows
  2215.              to set up whole range of consecutive slots (with consecutive memory pages). Or when
  2216.              only single slot is specified, extra option can be used to extend particular slot
  2217.              functionality. The slot behaviour will stay set in the current DEVICE until reset
  2218.              by another MMU specifying same slot (even as part of range, that will clear the option
  2219.              to "default").</para>
  2220.  
  2221.              <para>Single slot option (default state is: no error/warning and no wrap = nothing special):
  2222.                <synopsis>e = error on writing beyond last byte of slot
  2223. w = warning on writing beyond last byte of slot
  2224. n = wrap address back to start of slot, map next page</synopsis>
  2225.                <example>
  2226.                  <title></title>
  2227.  
  2228.                  <para><programlisting>    DEVICE ZXSPECTRUM128 : LABELSLIST "po_mmu.lbl"  ; to check label pages
  2229.    MMU 1 3, 5      ; maps slots 1, 2, 3 with pages 5, 6, 7
  2230.    ORG 0xBFFF
  2231. label1_p6: scf      ; last byte of page 6 (in slot 2)
  2232. label2_p7: scf      ; first byte of page 7 (in slot 3)
  2233.  
  2234.    MMU 3 e, 0      ; page 0 into slot 3, write beyond slot will cause error
  2235.    ORG 0xFFFF
  2236.    ld  a,1         ; error: Write outside of memory slot: 65536 (65536 = address outside)
  2237.  
  2238.    MMU 3 n, 1      ; page 1 into slot 3, make it wrap + map next page automatically
  2239.    ORG 0xFFFF      ; ! also the $ address was truncated by MMU from $10001 to $0001 !
  2240. label3_p1: scf      ; last byte of page 1, then wrapping back to 0xC000 with page 2
  2241. label4_p2: scf      ; first byte of page 2 at 0xC000</programlisting></para>
  2242.                </example></para>
  2243.            </listitem>
  2244.          </varlistentry>
  2245.  
  2246.          <varlistentry>
  2247.            <term><anchor id="po_module" />MODULE &lt;name&gt;</term>
  2248.  
  2249.            <listitem>
  2250.              <para>Labels are to be unique only in the current module. Also
  2251.              note the use of '@' to suppress all this label-processing. (The
  2252.              '@' is NOT part of the label name though!)<example>
  2253.                  <title></title>
  2254.  
  2255.                  <para><programlisting>    MODULE xxx
  2256. Kip                ; label xxx.Kip
  2257.    CALL Kip         ; call xxx.Kip
  2258.    CALL yyy.Kip     ; call yyy.Kip
  2259.    CALL Kop         ; call xxx.Kop
  2260.    CALL @Kop        ; call Kop
  2261.    Call @Kip        ; call Kip
  2262.  
  2263.    MODULE yyy
  2264. Kip                ; label yyy.Kip
  2265. @Kop               ; label Kop
  2266. @xxx.Kop           ; label xxx.Kop
  2267.  
  2268.    MODULE           ; no modulename
  2269. Kip                ; label Kip</programlisting></para>
  2270.                </example></para>
  2271.            </listitem>
  2272.          </varlistentry>
  2273.  
  2274.          <varlistentry>
  2275.            <term><anchor id="po_opt" /><para>OPT [push] [reset] [listoff] [liston] [&lt;command line options&gt;]</para>
  2276.                         <para>OPT pop</para></term>
  2277.  
  2278.            <listitem>
  2279.              <para>Allows to reset and modify <link linkend="s_cli">options</link> affecting syntax and
  2280.                                   parsing (for lines of source following the OPT). The options allowed for OPT
  2281.                                   are: <code>--nofakes</code>, <code>--syntax</code>, <code>--zxnext</code>,
  2282.                                   <code>--reversepop</code> and <code>--dirbol</code>.
  2283.                           </para>
  2284.                           <para>
  2285.                                   Ahead of options you can use OPT commands: push, pop, reset, listoff, liston.
  2286.                                   The "push" command will make OPT to preserve current state of options. The "reset"
  2287.                                   command will reset OPT-related options to default state. The "listoff" command will
  2288.                                   suspend the listing for following lines until "liston" command is used (listing
  2289.                                   availibility is part of the push/pop state, so to "nest" listing-off you can use
  2290.                                   "OPT push listoff : ... code ... : OPT pop" code sequence.
  2291.                           </para>
  2292.                           <para>Then the provided options are applied. The default values are: fake instructions
  2293.                                   enabled (no warning), multi-argument delimiter is ",", both () and [] brackets
  2294.                                   can be used to access memory, labels can have any name, ZX Next instructions are OFF,
  2295.                                   POP with multiple arguments doesn't reverse them and pseudo-ops at beginning of
  2296.                                   line are OFF (to just reset to these defaults you can use <code>OPT reset</code>).
  2297.              </para>
  2298.                           <para>The "pop" command: the previously preserved state of options is restored (states
  2299.                                   are preserved in "stack" way, so further OPT with "pop" will restore older states).
  2300.                           </para>
  2301.                           <example>
  2302.                  <title></title>
  2303.  
  2304.                  <programlisting>    POP bc, hl   ; pops BC first
  2305.    OPT push reset --reversepop --syntax=af
  2306.    POP bc,,hl   ; pops HL first
  2307.    LD  bc,hl    ; warning about Fake instruction
  2308.    LD  bc,hl    ; warning supressed by lowercase "fake" in this comment
  2309.    OPT reset --syntax=A
  2310.    POP bc `` hl ; pop BC first (--reversepop was reset)
  2311.    OPT pop      ; restoring syntax to original state</programlisting>
  2312.                           </example>
  2313.            </listitem>
  2314.          </varlistentry>
  2315.  
  2316.          <varlistentry>
  2317.            <term><anchor id="po_org" />ORG &lt;address&gt;[,&lt;page_number&gt;]</term>
  2318.  
  2319.            <listitem>
  2320.              <para>Set the program counter to a specific address. If the second argument is
  2321.              provided, it will change memory page in the current slot, see
  2322.              <link linkend="po_page">PAGE</link>.
  2323.                  <example>
  2324.                  <title></title>
  2325.  
  2326.                  <para><programlisting>    ORG 100h ; or 0x100, or $100, or #100
  2327.  
  2328.    ; useful macro that padding code
  2329.    MACRO PADORG addr
  2330.         ; add padding
  2331.         IF $ &lt; addr
  2332.         BLOCK addr-$
  2333.         ENDIF
  2334.         ORG addr
  2335.    ENDM
  2336.  
  2337.    MACRO PADORG2 addr
  2338.         ; add padding + display warning
  2339.         IF $ &gt; addr
  2340.           ; no padding
  2341.           DISPLAY /L, "Warning! PADORG failed! ", $, " is more than ", addr
  2342.         ELSE
  2343.           ; add padding
  2344.           BLOCK addr-$
  2345.         ENDIF
  2346.         ORG addr
  2347.    ENDM</programlisting></para>
  2348.                </example></para>
  2349.            </listitem>
  2350.          </varlistentry>
  2351.  
  2352.          <varlistentry>
  2353.            <term><anchor id="po_outend" />OUTEND</term>
  2354.  
  2355.            <listitem>
  2356.              <para>Ends generating compiler output to file specified in OUTPUT and resets
  2357.              <link linkend="po_size">SIZE</link> value to default "none".</para>
  2358.            </listitem>
  2359.          </varlistentry>
  2360.  
  2361.          <varlistentry>
  2362.            <term><anchor id="po_output" />OUTPUT
  2363.            [&lt;filename&gt;[,&lt;mode&gt;]]</term>
  2364.  
  2365.            <listitem>
  2366.              <para>With OUTPUT it is possible to create multiple files from
  2367.              one source. All following instructions will be assembled to this
  2368.              file. It will also <link linkend="po_outend">close (OUTEND)</link>
  2369.              and finalize any previously opened output.</para>
  2370.  
  2371.              <para>There are three possible output modes: truncate (overwrite
  2372.              existing files, this is the default), rewind (open and execute
  2373.              FPOS 0) and append (open and leave the file pointer at the end
  2374.              of the file).<synopsis>OUTPUT &lt;filename&gt;,t  ; truncate (default)
  2375. OUTPUT &lt;filename&gt;,r  ; rewind
  2376. OUTPUT &lt;filename&gt;,a  ; append</synopsis>
  2377.              <example>
  2378.                  <title>bigfile.asm</title>
  2379.  
  2380.                  <para><programlisting>    OUTPUT loader.com
  2381.    ORG 100H
  2382.    INCLUDE loader.asm
  2383.    INCLUDE bios.asm
  2384.  
  2385.    OUTPUT bigfile.dat
  2386.    ORG 4000H
  2387.    INCLUDE main.asm
  2388.    ORG 8000H
  2389.    INCLUDE data.asm
  2390.    OUTEND
  2391.    INCLUDE next.asm</programlisting></para>
  2392.                </example>This will create two files: loader.com and
  2393.              bigfile.dat.</para>
  2394.  
  2395.            </listitem>
  2396.          </varlistentry>
  2397.  
  2398.          <varlistentry>
  2399.            <term><anchor id="po_page" />PAGE &lt;number&gt;</term>
  2400.  
  2401.            <listitem>
  2402.              <para><emphasis>Work only in real device emulation mode. See
  2403.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2404.  
  2405.              <para>Set the current memory page to current slot.</para>
  2406.  
  2407.              <para><example>
  2408.                  <title></title>
  2409.  
  2410.                  <para><programlisting>    PAGE 7 ;set 7 page
  2411.    SAVEBIN "ram7.bin",$C000,$4000 ;- save $4000 begin from $C000 of RAM to file</programlisting></para>
  2412.                </example></para>
  2413.            </listitem>
  2414.          </varlistentry>
  2415.  
  2416.          <varlistentry>
  2417.            <term><anchor id="po_phase" />PHASE</term>
  2418.  
  2419.            <listitem>
  2420.              <para>Synonym of <link linkend="po_disp">DISP</link>.</para>
  2421.            </listitem>
  2422.          </varlistentry>
  2423.  
  2424.          <varlistentry>
  2425.            <term><anchor id="po_rept" />REPT &lt;count&gt;</term>
  2426.  
  2427.            <listitem>
  2428.              <para>Synonym of <link linkend="po_dup">DUP</link>. There is also synonym ENDR to end REPT block (EDUP works too).</para>
  2429.            </listitem>
  2430.          </varlistentry>
  2431.  
  2432.          <varlistentry>
  2433.            <term><anchor id="po_savebin" />SAVEBIN
  2434.            &lt;filename&gt;,&lt;startadress&gt;,&lt;lengthofcode&gt;</term>
  2435.  
  2436.            <listitem>
  2437.              <para><emphasis>Works only in real device emulation mode. See
  2438.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2439.  
  2440.              <para>Save the block of RAM.</para>
  2441.  
  2442.              <para><example>
  2443.                  <title></title>
  2444.  
  2445.                  <para><programlisting>    PAGE 7 ;set 7 page to current slot
  2446.    SAVEBIN "ram7.bin",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
  2447.    SAVEBIN "ram2.bin",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</programlisting></para>
  2448.                </example></para>
  2449.            </listitem>
  2450.          </varlistentry>
  2451.  
  2452.          <varlistentry>
  2453.            <term><anchor id="po_savedev" />SAVEDEV
  2454.            &lt;filename&gt;,&lt;startPage&gt;,&lt;startOffset&gt;,&lt;length&gt;</term>
  2455.  
  2456.            <listitem>
  2457.              <para><emphasis>Works only in real device emulation mode. See
  2458.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2459.  
  2460.              <para>Like <link linkend="po_savebin">SAVEBIN</link>, saves the block of device RAM.</para>
  2461.  
  2462.              <para>But it allows lengths over 64ki, and the offset value goes directly into device
  2463.              virtual memory (where pages are allocated consecutively), ignoring current slot
  2464.              "mapping". I.e. page=2,offset=0 will start saving data from page 2 at its beginning,
  2465.              going through pages 3, 4, 5, ... until the requested length of data is saved.</para>
  2466.  
  2467.              <para>The offset is not limited to page size, i.e. arguments page=1,offset=0x500 are equal
  2468.              to arguments page=0,offset=0x4500 for ZXSPECTRUM128 device (has page size 0x4000).</para>
  2469.  
  2470.              <example>
  2471.                  <title></title>
  2472.  
  2473.                  <programlisting>    DEVICE ZXSPECTRUM128 : SAVEDEV "fullram.bin",0,0,0x20000 ; save full 128kiB</programlisting>
  2474.                </example>
  2475.            </listitem>
  2476.          </varlistentry>
  2477.  
  2478.          <varlistentry>
  2479.            <term><anchor id="po_savehob" />SAVEHOB
  2480.            &lt;filename&gt;,&lt;filename_in_trdos&gt;,&lt;startadress&gt;,&lt;lengthofcode&gt;</term>
  2481.  
  2482.            <listitem>
  2483.              <para><emphasis>Work only in real device emulation mode. See
  2484.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2485.  
  2486.              <para>Save the block of RAM in Hobeta format.</para>
  2487.  
  2488.              <para><example>
  2489.                  <title></title>
  2490.  
  2491.                  <para><programlisting>    PAGE 7 ;set 7 page to current slot
  2492.    SAVEHOB "ram7.$c","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
  2493.    SAVEHOB "ram2.$c","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</programlisting></para>
  2494.                </example></para>
  2495.            </listitem>
  2496.          </varlistentry>
  2497.  
  2498.          <varlistentry>
  2499.            <term><anchor id="po_savenex" />SAVENEX &lt;command&gt; &lt;command arguments&gt;</term>
  2500.  
  2501.            <listitem>
  2502.              <para>Commands to build NEX file, for details check <link linkend="c_savenex">SAVENEX
  2503.              </link> chapter.</para>
  2504.  
  2505.              <para><emphasis>Works only in ZXSPECTRUMNEXT device emulation mode. See
  2506.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2507.            </listitem>
  2508.          </varlistentry>
  2509.  
  2510.          <varlistentry>
  2511.            <term><anchor id="po_savesna" />SAVESNA &lt;filename&gt;[,&lt;startadressofprogram&gt;]</term>
  2512.  
  2513.            <listitem>
  2514.              <para><emphasis>Work only in real device emulation mode. See
  2515.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2516.  
  2517.              <para>Save the snapshot for emulators of ZX-Spectrum. (If start address is omitted,
  2518.              the one provided by <link linkend="po_end">END</link> is used)<example>
  2519.                  <title></title>
  2520.  
  2521.                  <para><programlisting>    DEVICE ZXSPECTRUM128
  2522.    ORG $8000
  2523. START  .... ;something code
  2524.    RET
  2525.    SAVESNA "game.sna",START ;save snapshot to file game.sna. Start address is START ($8000)</programlisting></para>
  2526.                </example></para>
  2527.            </listitem>
  2528.          </varlistentry>
  2529.  
  2530.          <varlistentry>
  2531.            <term><anchor id="po_savetap" /><para>SAVETAP &lt;filename&gt;,BASIC,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;autorunline&gt;[,&lt;lengthwithoutvars&gt;]]</para>
  2532.            <para>SAVETAP &lt;filename&gt;,CODE,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;customstartaddress&gt;[,&lt;optional3rdparam&gt;]]</para>
  2533.            <para>SAVETAP &lt;filename&gt;,NUMBERS,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;variableletter(A..Z)&gt;]</para>
  2534.            <para>SAVETAP &lt;filename&gt;,CHARS,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;variableletter(A..Z)&gt;]</para>
  2535.            <para>SAVETAP &lt;filename&gt;,HEADLESS,&lt;start&gt;,&lt;length&gt;[,&lt;customblockflag(0..255)&gt;]</para></term>
  2536.  
  2537.            <listitem>
  2538.              <para><emphasis>Work only in real device emulation mode. See
  2539.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2540.  
  2541.              <para>Append the tape header or block of data to the end of the
  2542.              standard tape file for emulators of ZX-Spectrum.<example>
  2543.                  <title></title>
  2544.  
  2545.                  <para><programlisting>    DEVICE ZXSPECTRUM48
  2546.    ...
  2547.    EMPTYTAP "output.tap"
  2548.  
  2549.    SAVETAP "output.tap",BASIC,"noAutorun",label,100
  2550.    SAVETAP "output.tap",BASIC,"w/Autorun",label,100,9999
  2551.    SAVETAP "output.tap",BASIC,"withVars",label,123,9999,100
  2552.    SAVETAP "output.tap",CODE,"bank17",screen,6912
  2553.    SAVETAP "output.tap",CODE,"screen",demo,length,org
  2554.    SAVETAP "output.tap",NUMBERS,"dimArray",label,100      ; a()
  2555.    SAVETAP "output.tap",NUMBERS,"othernum",label,200,'b'  ; b()
  2556.    SAVETAP "output.tap",CHARS,"charArray",label,300       ; a$()
  2557.    SAVETAP "output.tap",CHARS,"nextone",label,400,'m'     ; m$()
  2558.    SAVETAP "output.tap",HEADLESS,start,length</programlisting></para>
  2559.                </example></para>
  2560.            </listitem>
  2561.          </varlistentry>
  2562.  
  2563.          <varlistentry>
  2564.            <term>SAVETAP &lt;filename&gt;[,&lt;startadressofprogram&gt;]</term>
  2565.  
  2566.            <listitem>
  2567.              <para><emphasis>Work only in real device emulation mode. See
  2568.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2569.  
  2570.              <para>Save the tape file for emulators of ZX-Spectrum as a
  2571.              "snapshot" of whole memory. Generated tape file supports the
  2572.              ZX-Spectrum clones with extended RAM such as ATM Turbo 512, etc.
  2573.              (If start address is omitted, the one provided by <link linkend=
  2574.              "po_end">END</link> is used)<example>
  2575.                  <title></title>
  2576.  
  2577.                  <para><programlisting>    DEVICE ZXSPECTRUM48
  2578.    ORG $8000
  2579. START  .... ;something code
  2580.    RET
  2581.    SAVETAP "game.tap",START ; save tape-snapshot to file game.tap. Start address is START ($8000)</programlisting></para>
  2582.                </example></para>
  2583.            </listitem>
  2584.          </varlistentry>
  2585.  
  2586.          <varlistentry>
  2587.            <term><anchor id="po_savetrd" />SAVETRD
  2588.            &lt;filename_of_trd_image&gt;,[|]&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;[,&lt;autostart_BASIC_line&gt;]</term>
  2589.  
  2590.            <listitem>
  2591.              <para><emphasis>Works only in real device emulation mode. See
  2592.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2593.  
  2594.              <para>Save the device memory into TRD disk image. Adding pipe character "|" ahead of file
  2595.                                   name will make sjasmplus to delete old file(s) with the same name, before writing
  2596.                                   the new one =&gt; replace-like functionality. If the deleted file did occupy all
  2597.                                   sectors till the free space position in disc info, sjasmplus will salvage those sectors
  2598.                                   back and save new file over them (but it will not do full reshuffle/defrag in more
  2599.                                   complex cases, sjasmplus is just assembler, not full featured TRD images manipulation tool).
  2600.  
  2601.                                 <example><title></title>
  2602.                  <para><programlisting>    EMPTYTRD "test.trd" ;create empty TRD image
  2603.    PAGE 7 ;set 7 page to current slot
  2604.    SAVETRD "test.trd","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file to TRD image
  2605.    SAVETRD "test.trd","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file to TRD image
  2606.    SAVETRD "test.trd",|"myfile1.C",$B000,$400 ;- replace "myfile1.C" with new file</programlisting></para>
  2607.                </example>
  2608.                           </para>
  2609.            </listitem>
  2610.          </varlistentry>
  2611.  
  2612.          <varlistentry>
  2613.            <term><anchor id="po_shellexec" />SHELLEXEC &lt;filename&gt;[,&lt;parameters&gt;]</term>
  2614.  
  2615.            <listitem>
  2616.              <para>Execute external program &lt;filename&gt; using optional
  2617.              command line &lt;parameters&gt;.<example>
  2618.                  <title></title>
  2619.  
  2620.                  <para><programlisting>    OUTPUT "mybin.bin"
  2621.    ;some code
  2622.    IF ((_ERRORS = 0) + (_WARNINGS = 0))
  2623.        SHELLEXEC "x:/somepath/bin2tap.exe mybin.bin mytap.tap"
  2624.       ; or SHELLEXEC "x:/somepath/bin2tap.exe","mybin.bin mytap.tap"
  2625.    ENDIF</programlisting></para>
  2626.                </example></para>
  2627.            </listitem>
  2628.          </varlistentry>
  2629.  
  2630.          <varlistentry>
  2631.            <term><anchor id="po_size" />SIZE &lt;filesize in bytes&gt;</term>
  2632.  
  2633.            <listitem>
  2634.              <para>If the resulting file is less than the given length, as
  2635.              many zero bytes are added as necessary. See <link
  2636.              linkend="po_output">OUTPUT</link> for more.<example>
  2637.                  <title></title>
  2638.  
  2639.                  <para><programlisting>    SIZE 32768       ; make sure file will be 32K</programlisting></para>
  2640.                </example></para>
  2641.            </listitem>
  2642.          </varlistentry>
  2643.  
  2644.          <varlistentry>
  2645.            <term><anchor id="po_slot" />SLOT &lt;number&gt;</term>
  2646.  
  2647.            <listitem>
  2648.              <para><emphasis>Work only in real device emulation mode. See
  2649.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2650.  
  2651.              <para>Set current slot. Slot's defined by MEMORYMAP pseudo-op.
  2652.              Use pseudo-op <link linkend="po_page">PAGE</link> to change page
  2653.              in the current slot.</para>
  2654.  
  2655.              <para><example>
  2656.                  <title></title>
  2657.  
  2658.                  <para><programlisting>    DEVICE ZXSPECTRUM128
  2659.    SLOT 3 ;from 0C000h to 0FFFFh
  2660.    PAGE 1 ;set page 1 to slot 3
  2661.    ORG 0C000h
  2662.    ;your program here
  2663.    PAGE 2
  2664.    INCBIN "somegfx.bin"
  2665.    ;....</programlisting></para>
  2666.                </example></para>
  2667.            </listitem>
  2668.          </varlistentry>
  2669.  
  2670.          <varlistentry>
  2671.            <term><anchor id="po_tapend" />TAPEND</term>
  2672.  
  2673.            <listitem>
  2674.              <para>Ends generating compiler output to tape file block specified in TAPOUT.</para>
  2675.            </listitem>
  2676.          </varlistentry>
  2677.  
  2678.          <varlistentry>
  2679.            <term><anchor id="po_tapout" />TAPOUT &lt;filename&gt;[,&lt;flagbyte&gt;]</term>
  2680.  
  2681.            <listitem>
  2682.              <para>Appends one tape block at the end of specified file.
  2683.              All following code will be assembled to this tape file block.</para>
  2684.  
  2685.              <para>Default value of flagbyte is 255.<example>
  2686.                  <title>bigfile.asm</title>
  2687.  
  2688.                  <para><programlisting>    EMPTYTAP screen.tap
  2689.  
  2690.    TAPOUT screen.tap,0
  2691.    DB 3
  2692.    DB 'ScreenName'
  2693.    DW 6912
  2694.    DW 16384
  2695.    DW 32768
  2696.    TAPEND
  2697.  
  2698.    TAPOUT screen.tap
  2699.    INCBIN screen.bin
  2700.    TAPEND</programlisting></para>
  2701.                </example>This will create tap file with the screen.</para>
  2702.            </listitem>
  2703.          </varlistentry>
  2704.  
  2705.  
  2706.          <varlistentry>
  2707.            <term><anchor id="po_textarea" />TEXTAREA &lt;address&gt;</term>
  2708.  
  2709.            <listitem>
  2710.              <para>Synonym of <link linkend="po_disp">DISP</link>.</para>
  2711.            </listitem>
  2712.          </varlistentry>
  2713.  
  2714.          <varlistentry>
  2715.            <term><anchor id="po_undefine" />UNDEFINE &lt;id&gt;</term>
  2716.  
  2717.            <listitem>
  2718.              <para>Removes the identifier defined by <link
  2719.              linkend="po_define">DEFINE</link></para>
  2720.  
  2721.              <para><example>
  2722.                  <title></title>
  2723.  
  2724.                  <para><programlisting>    DEFINE Release 1
  2725.  
  2726.    IFDEF Release
  2727.      DISPLAY "Building release version"
  2728.    ENDIF
  2729.  
  2730.    UNDEFINE Release
  2731.  
  2732.    IFNDEF Release
  2733.      DISPLAY "It's works!"
  2734.    ENDIF
  2735.  
  2736.    IFDEF _SJASMPLUS
  2737.      DISPLAY "Yes, it's the sjasmplus!"
  2738.    ENDIF
  2739.  
  2740.    UNDEFINE *  ; undefine all identifiers
  2741.  
  2742.    IFNDEF _SJASMPLUS
  2743.      DISPLAY "It's not the sjasmplus??"
  2744.    ENDIF</programlisting></para>
  2745.                </example></para>
  2746.            </listitem>
  2747.          </varlistentry>
  2748.  
  2749.          <varlistentry>
  2750.            <term><anchor id="po_unphase" />UNPHASE</term>
  2751.  
  2752.            <listitem>
  2753.              <para>Synonym of <link linkend="po_ent">ENT</link>.</para>
  2754.            </listitem>
  2755.          </varlistentry>
  2756.  
  2757.          <varlistentry>
  2758.            <term><anchor id="po_word" />WORD &lt;words&gt;</term>
  2759.  
  2760.            <listitem>
  2761.              <para>Defines a word. Values should be between -32787 and
  2762.              65536.<example>
  2763.                  <title></title>
  2764.  
  2765.                  <para><programlisting>    WORD 4000h,0d000h
  2766.    WORD 4,"HA"</programlisting></para>
  2767.                </example></para>
  2768.            </listitem>
  2769.          </varlistentry>
  2770.        </variablelist></para>
  2771.    </section>
  2772.  
  2773.    <section>
  2774.      <title>Conditional assembly</title>
  2775.  
  2776.      <para>It may be useful to assemble a part or not based on a certain
  2777.      condition.</para>
  2778.  
  2779.      <para><variablelist>
  2780.          <varlistentry>
  2781.            <term><anchor id="ca_if" />IF &lt;expression&gt;</term>
  2782.  
  2783.            <listitem>
  2784.              <para>If &lt;expression&gt; is non-zero the following lines are
  2785.              assembled until an ELSE or ENDIF.</para>
  2786.            </listitem>
  2787.          </varlistentry>
  2788.  
  2789.          <varlistentry>
  2790.            <term><anchor id="ca_ifn" />IFN &lt;expression&gt;</term>
  2791.  
  2792.            <listitem>
  2793.              <para>If &lt;expression&gt; is zero the following lines are
  2794.              assembled until an ELSE or ENDIF.</para>
  2795.            </listitem>
  2796.          </varlistentry>
  2797.  
  2798.          <varlistentry>
  2799.            <term><anchor id="ca_ifdef" />IFDEF &lt;id&gt;</term>
  2800.  
  2801.            <listitem>
  2802.              <para>The condition is true if there is an id defined. These are
  2803.              NOT labels.</para>
  2804.  
  2805.              <para><example>
  2806.                  <title>Example</title>
  2807.  
  2808.                  <para><programlisting>    IFDEF MSX_LEAN_AND_MEAN
  2809.        CALL InitOwnMM
  2810.    ELSE
  2811.        CALL InitDos2MemMan
  2812.    ENDIF</programlisting></para>
  2813.                </example></para>
  2814.            </listitem>
  2815.          </varlistentry>
  2816.  
  2817.          <varlistentry>
  2818.            <term><anchor id="ca_ifndef" />IFNDEF &lt;id&gt;</term>
  2819.  
  2820.            <listitem>
  2821.              <para>The condition is true if there isn't an id defined. These
  2822.               are NOT labels.</para>
  2823.  
  2824.               <para><example>
  2825.                   <title>Example</title>
  2826.  
  2827.                   <para><programlisting>1   IN A,(0C4H)
  2828.     AND 2
  2829.     IFNDEF DEBUG
  2830.         JR NC,1B
  2831.     ENDIF</programlisting></para>
  2832.                 </example></para>
  2833.             </listitem>
  2834.           </varlistentry>
  2835.  
  2836.           <varlistentry>
  2837.             <term><anchor id="ca_ifused" />IFUSED &lt;label&gt;</term>
  2838.  
  2839.             <listitem>
  2840.               <para>The condition is true if there is an label used somewhere
  2841.               in the code. You can create libraries of useful functions using
  2842.               IFUSED pseudo-op</para>
  2843.  
  2844.               <para><example>
  2845.                   <title>Example</title>
  2846.  
  2847.                   <para><programlisting>    OUTPUT "TEST.OUT"
  2848.  
  2849.     CALL LABEL3 ; LABEL3 - yes
  2850.     LD A,(LABEL1) ; LABEL1 - yes
  2851.  
  2852.     IFUSED LABEL1
  2853. LABEL1:
  2854.     DB 1
  2855.     ENDIF
  2856.  
  2857.     IFUSED LABEL2
  2858. LABEL2:
  2859.     DB 2
  2860.     ENDIF
  2861.  
  2862.     IFUSED LABEL3
  2863. LABEL3:
  2864.     DB 3
  2865.     ENDIF
  2866.  
  2867.     IFUSED LABEL4
  2868. LABEL4:
  2869.     DB 4
  2870.     ENDIF
  2871.  
  2872.     LD A,LABEL2 ; LABEL2 - yes
  2873.  
  2874.     RET
  2875.  
  2876. ; Output will contain bytes from LABEL1 to LABEL3 (1, 2, 3), but not contain from LABEL4, because this label is not used.
  2877.  
  2878. ; Alternative syntax:
  2879. LABEL5:
  2880.     IFUSED ; sjasmplus will use name of previous label, i.e. LABEL5
  2881.  
  2882.     ENDIF
  2883.     </programlisting></para>
  2884.                 </example></para>
  2885.             </listitem>
  2886.           </varlistentry>
  2887.  
  2888.           <varlistentry>
  2889.             <term><anchor id="ca_ifnused" />IFNUSED &lt;label&gt;</term>
  2890.  
  2891.             <listitem>
  2892.               <para>The condition is true if there is an label
  2893.               <emphasis>not</emphasis> used somewhere in the code.</para>
  2894.             </listitem>
  2895.           </varlistentry>
  2896.  
  2897.           <varlistentry>
  2898.             <term><anchor id="ca_else" />ELSE</term>
  2899.  
  2900.             <listitem>
  2901.               <para>See <link linkend="ca_if">IF</link>. If the condition is
  2902.               not true, the else-part is assembled.</para>
  2903.             </listitem>
  2904.           </varlistentry>
  2905.  
  2906.           <varlistentry>
  2907.             <term><anchor id="ca_endif" />ENDIF</term>
  2908.  
  2909.             <listitem>
  2910.               <para>Every <link linkend="ca_if">IF</link> should be followed
  2911.               by an ENDIF.</para>
  2912.             </listitem>
  2913.           </varlistentry>
  2914.         </variablelist></para>
  2915.     </section>
  2916.  
  2917.     <section>
  2918.       <title><anchor id="s_macros"/>Macros</title>
  2919.  
  2920.       <para>The MACRO pseudo-op defines a macro. It should be followed by the
  2921.       name of the macro, optionally followed by the parameters. The following
  2922.       lines will be stored as the macro-body until an ENDM pseudo-op is
  2923.       encountered. Macro's have to be defined before their use.<example>
  2924.          <title>Macro without parameters</title>
  2925.  
  2926.          <para><programlisting>  MACRO ADD_HL_A
  2927.    ADD A,L
  2928.    JR NC,.hup
  2929.    INC H
  2930. .hup
  2931.    LD L,A
  2932.  ENDM</programlisting></para>
  2933.        </example></para>
  2934.  
  2935.      <para>Labels in a macro starting with a dot are local to each macro
  2936.      expansion.<example>
  2937.          <title>A macro with parameters</title>
  2938.  
  2939.          <para><programlisting>  MACRO WAVEOUT reg, data
  2940.    LD A,reg
  2941.    OUT (7EH),A
  2942.    LD A,data
  2943.    OUT (7FH),A
  2944.  ENDM
  2945. ; this macro will make
  2946.  WAVEOUT 2,17
  2947. ; expand to:
  2948.  LD A,2
  2949.  OUT (7EH),A
  2950.  LD A,17
  2951.  OUT (7FH),A</programlisting></para>
  2952.        </example><example>
  2953.          <title>Another example</title>
  2954.  
  2955.          <para><programlisting>    MACRO LOOP
  2956.      IF $-.lus&lt;127
  2957.        DJNZ .lus
  2958.      ELSE
  2959.        DEC B
  2960.        JP NZ,.lus
  2961.      ENDIF
  2962.    ENDM
  2963.  
  2964. Main
  2965. .lus
  2966.    CALL DoALot
  2967.    LOOP
  2968. ; This will expand to:
  2969. Main
  2970. .lus                  ; Main.lus
  2971.    CALL DoALot
  2972.    DJNZ .lus         ; Main.lus</programlisting></para>
  2973.        </example></para>
  2974.  
  2975.      <para>Angle brackets can be used when the arguments contain
  2976.      commas.<example>
  2977.          <title></title>
  2978.  
  2979.          <para><programlisting>    MACRO UseLess data
  2980.      DB data
  2981.    ENDM
  2982.  
  2983.    UseLess &lt;10,12,13,0&gt;
  2984. ; expands to:
  2985.    DB 10,12,13,0
  2986.  
  2987. ; use '!' to include '!' and '&gt;' in those strings.
  2988.  
  2989.    UseLess &lt;5, 6 !&gt; 3&gt;
  2990. ; expands to:
  2991.    DB 5, 6 &gt; 3
  2992.  
  2993.    UseLess &lt;"Kip!!",3&gt;
  2994. ; expands to:
  2995.    DB "Kip!",3</programlisting></para>
  2996.        </example></para>
  2997.  
  2998.                 <para>If there is label defined on the line with MACRO pseudo-op, the label will
  2999.                         be used as macro name (current MODULE is NOT applied to macro name).
  3000.                         It was added as compatibility convenience to make porting
  3001.                         from different assemblers somewhat easier.
  3002.                         <example><title></title>
  3003.                                 <programlisting>LabelAsMacroName    MACRO  arg1?, arg2?
  3004.                        ld  a,arg1?
  3005.                        ld  hl,arg2?
  3006.                    ENDM
  3007.  
  3008.                LabelAsMacroName 1,$1234
  3009.            ; expands to:
  3010.                ld a,1 : ld hl,$1234</programlisting>
  3011.                         </example>
  3012.                 </para>
  3013.  
  3014.      <para></para>
  3015.    </section>
  3016.  </chapter>
  3017.  
  3018.  <chapter>
  3019.    <title><anchor id="c_structures" />Structures</title>
  3020.  
  3021.    <section>
  3022.      <title>What is it?</title>
  3023.  
  3024.      <para>Structures can be used to define data structures in memory more
  3025.      easily. The name of the structure is set to the total size of the
  3026.      structure.</para>
  3027.    </section>
  3028.  
  3029.    <section>
  3030.      <title>Defining structure</title>
  3031.  
  3032.      <para>A structure definition starts with: <code>STRUCT
  3033.      &lt;name&gt;[,&lt;initial offset&gt;]</code> and ends with
  3034.      <code>ENDS</code>. Structure definitions are local to the current
  3035.      module, but, as with labels, '@' can be used to override this.</para>
  3036.  
  3037.      <para>Lines between STRUCT and ENDS should have the following
  3038.      format:</para>
  3039.  
  3040.      <para><code>membername pseudo-operation operands</code></para>
  3041.  
  3042.      <para>All fields are optional. Lines without label should start with
  3043.      whitespace.</para>
  3044.  
  3045.      <para>When non zero <code>offset</code> is used, it acts as if
  3046.       <link linkend="st_block">BLOCK</link> with <code>length</code> equal to
  3047.       <code>offset</code> was defined as first member of structure.</para>
  3048.    </section>
  3049.  
  3050.    <section>
  3051.      <title>Instructions</title>
  3052.  
  3053.      <para>Between the STRUCT and ENDS pseudo-instructions the following
  3054.      instructions can be used:</para>
  3055.  
  3056.      <para><variablelist>
  3057.          <varlistentry>
  3058.            <term><anchor id="st_byte" />BYTE [&lt;defaultvalue&gt;]</term>
  3059.  
  3060.            <listitem>
  3061.              <para>To define a one byte member. The defaultvalue is used when
  3062.              no initialisation value is given when the structure is declared.
  3063.              (DB and DEFB may be used instead of BYTE).</para>
  3064.            </listitem>
  3065.          </varlistentry>
  3066.  
  3067.          <varlistentry>
  3068.            <term><anchor id="st_word" />WORD [&lt;defaultvalue&gt;]</term>
  3069.  
  3070.            <listitem>
  3071.              <para>To define a two byte member. The defaultvalue is used when
  3072.              no initialisation value is given when the structure is declared.
  3073.              (DW and DEFW may be used instead of WORD).</para>
  3074.            </listitem>
  3075.          </varlistentry>
  3076.  
  3077.          <varlistentry>
  3078.            <term><anchor id="st_d24" />D24 [&lt;defaultvalue&gt;]</term>
  3079.  
  3080.            <listitem>
  3081.              <para>To define a three byte member. The defaultvalue is used
  3082.              when no initialisation value is given when the structure is
  3083.              declared.</para>
  3084.            </listitem>
  3085.          </varlistentry>
  3086.  
  3087.          <varlistentry>
  3088.            <term><anchor id="st_dword" />DWORD [&lt;defaultvalue&gt;]</term>
  3089.  
  3090.            <listitem>
  3091.              <para>To define a four byte member. The defaultvalue is used
  3092.              when no initialisation value is given when the structure is
  3093.              declared. (DD and DEFD may be used instead of DWORD).</para>
  3094.            </listitem>
  3095.          </varlistentry>
  3096.  
  3097.          <varlistentry>
  3098.            <term><anchor id="st_block" />BLOCK &lt;length&gt;[,&lt;fillbyte&gt;]]</term>
  3099.  
  3100.            <listitem>
  3101.              <para>To define a member of the specified number of bytes. Arguments are set
  3102.                  when defining the current structure, and are not part of init values when
  3103.                  the structure is later used.
  3104.              ('#', DS and DEFS may be used instead of BLOCK).</para>
  3105.  
  3106.              <para>(since v1.11) If <code>fillbyte</code> is omitted, the device memory
  3107.                  content in the block area is preserved (not zeroed).</para>
  3108.            </listitem>
  3109.          </varlistentry>
  3110.  
  3111.          <varlistentry>
  3112.            <term><anchor id="st_align" />ALIGN [&lt;expression&gt;[, &lt;byte&gt;]]</term>
  3113.  
  3114.            <listitem>
  3115.              <para>To <link linkend="po_align">align</link> the offset. If the expression
  3116.                  is omitted, 4 is assumed. ('##' May be used instead of ALIGN).</para>
  3117.  
  3118.              <para>(since v1.11) If the byte is omitted, device memory content is preserved (not zeroed).</para>
  3119.            </listitem>
  3120.          </varlistentry>
  3121.  
  3122.          <varlistentry>
  3123.            <term>&lt;structure name&gt; [&lt;init values&gt;]</term>
  3124.  
  3125.            <listitem>
  3126.              <para>It is possible to nest structures, and give new defaults
  3127.              for the BYTE and WORD members.</para>
  3128.            </listitem>
  3129.          </varlistentry>
  3130.        </variablelist></para>
  3131.    </section>
  3132.  
  3133.    <section>
  3134.      <title><anchor id="st_usage" />Usage of defined structure</title>
  3135.  
  3136.      <para><code>[&lt;label&gt;] &lt;struct_name&gt; [&lt;initial values&gt;]</code> will emit full
  3137.                 structure into machine code, either using default values from structure definition,
  3138.                 or overriding them with explicit value from the &lt;initial values&gt; list. In initial
  3139.                 values you can use curly brackets {} to group particular initial values for particular
  3140.                 sub-structure, any missing values in particular sub-structure init-list are set up by
  3141.                 default values of particular field. See "SDOT" example below or tests/struct asm files
  3142.                 for more examples.</para>
  3143.  
  3144.      <para><code>&lt;label&gt; &lt;struct_name&gt; = &lt;expression&gt;</code> will only set up
  3145.                 &lt;label&gt;.&lt;struct_field&gt; labels starting from designed address provided by
  3146.                 expression, but there will be no machine code emitted (and current address "$" will not
  3147.                 advance).</para>
  3148.  
  3149.    </section>
  3150.  
  3151.    <section>
  3152.      <title>Examples</title>
  3153.  
  3154.      <example>
  3155.          <title></title>
  3156.  
  3157.           <para><programlisting>        STRUCT SCOLOR
  3158. RED     BYTE 4
  3159. GREEN   BYTE 5
  3160. BLUE    BYTE 6
  3161.         ENDS</programlisting></para>
  3162.  
  3163.          <para>This is identical to:</para>
  3164.  
  3165.           <synopsis>SCOLOR              EQU 3 ; length
  3166. SCOLOR.RED      EQU 0 ; offset
  3167. SCOLOR.GREEN    EQU 1 ; offset
  3168. SCOLOR.BLUE     EQU 2 ; offset</synopsis>
  3169.           </example>
  3170.           <example>
  3171.          <title></title>
  3172.  
  3173.           <para><programlisting>        STRUCT SDOT
  3174. X       BYTE
  3175. Y       BYTE
  3176. C       SCOLOR 0,0,0 ; use new default values
  3177.         ENDS
  3178. </programlisting></para>
  3179.  
  3180.          <para>This is identical to:</para>
  3181.  
  3182.           <synopsis>SDOT                EQU 5 ; length
  3183. SDOT.X          EQU 0 ; offset
  3184. SDOT.Y          EQU 1 ; offset
  3185. SDOT.C          EQU 2 ; offset
  3186. SDOT.C.RED      EQU 2 ; offset
  3187. SDOT.C.GREEN    EQU 3 ; offset
  3188. SDOT.C.BLUE     EQU 4 ; offset
  3189. </synopsis>
  3190.           </example>
  3191.           <example>
  3192.          <title></title>
  3193.  
  3194.           <para><programlisting>        STRUCT SPOS,4
  3195. X       WORD
  3196. Y       BYTE
  3197.         ALIGN 2
  3198. AD      WORD
  3199.         ENDS</programlisting></para>
  3200.  
  3201.          <para>This is identical to:</para>
  3202.  
  3203.           <synopsis>SPOS        EQU 10 ; length
  3204. SPOS.X  EQU  4 ; offset
  3205. SPOS.Y  EQU  6 ; offset
  3206. SPOS.AD EQU  8 ; offset</synopsis>
  3207.           </example>
  3208.           <example>
  3209.          <title></title>
  3210.  
  3211.          <para>When a structure is defined it is possible to declare labels
  3212.          with it<programlisting>COLOR SCOLOR</programlisting>This is
  3213.          identical to:<synopsis>COLOR
  3214. COLOR.RED   BYTE 4
  3215. COLOR.GREEN BYTE 5
  3216. COLOR.BLUE  BYTE 6
  3217. </synopsis>Note the default values.</para>
  3218.  
  3219.          <para>Or without label:<programlisting>COLORTABLE
  3220.  SCOLOR 0,0,0
  3221.  SCOLOR 1,2,3
  3222.  SCOLOR ,2
  3223.  ; etc.</programlisting>This is identical to:<synopsis>COLORTABLE
  3224.  BYTE 0,0,0
  3225.  BYTE 1,2,3
  3226.  BYTE 4,2,6
  3227.  ; etc.</synopsis>
  3228.  
  3229. <programlisting>DOT1 SDOT 0,0, 0,0,0     ; or 0,0,0,0,0 or {0,0,{0,0,0}}</programlisting>Only
  3230.          BYTE and WORD members can be initialised.</para>
  3231.  
  3232.          <para>The resulting labels can be used as any other
  3233.          label:<programlisting>  ld b,(ix+SCOLOR.RED)
  3234.  ld a,(COLOR.GREEN)
  3235.  ld de,COLOR
  3236.  ; etc.</programlisting></para>
  3237.  
  3238.           </example>
  3239.      <example>
  3240.          <title></title>
  3241.  
  3242.           <para><programlisting>        STRUCT BIN_FILE_MAP, 256
  3243. value1  BYTE
  3244. value2  WORD
  3245.         ENDS
  3246.  
  3247.        ORG  0x8000
  3248. binData BIN_FILE_MAP = $        ; set up label values only (no bytes)
  3249.        INCBIN "some_data.bin"  ; load the bytes from file instead
  3250.  
  3251.        ; using the data through struct definition
  3252.        ld  a,(binData.value1)
  3253.        ld  hl,(binData.value2)</programlisting></para>
  3254.  
  3255.          <para>This is identical to:</para>
  3256.  
  3257.          <synopsis>BIN_FILE_MAP            EQU 259      ; length
  3258. BIN_FILE_MAP.value1     EQU 256      ; offset
  3259. BIN_FILE_MAP.value2     EQU 257      ; offset
  3260. ; labels to access binary data loaded by INCBIN
  3261. binData                 EQU 0x8000   ; address
  3262. binData.value1          EQU 0x8100   ; address
  3263. binData.value2          EQU 0x8101   ; address</synopsis>
  3264.           </example>
  3265.  
  3266.           <warning>
  3267.                 <para>Do not use the offset labels in indirections
  3268.                 like:<programlisting>LD A,(SDOT.X)</programlisting>This will
  3269.                 conflict with futher 'improvements' ;-)</para>
  3270.  
  3271.                 <para>If this is absolutely necessary (why?) use something like
  3272.                 this:<programlisting>LD A,(+SDOT.X)</programlisting></para>
  3273.           </warning>
  3274.    </section>
  3275.  </chapter>
  3276.  
  3277.  <chapter>
  3278.    <title><anchor id="c_lua_scripting" />Lua scripting</title>
  3279.  
  3280.    <section>
  3281.      <title>Why?</title>
  3282.  
  3283.      <para><graphic align="left" fileref="lua.gif" />Why is scripting engine
  3284.      as Lua embedded to the compiler? Answer is simple: It need to add extra
  3285.      features by users. And to whole other Lua is enough small, fast and
  3286.      powerful scripting engine.</para>
  3287.    </section>
  3288.  
  3289.    <section>
  3290.      <title>How to use?</title>
  3291.  
  3292.      <para>You must use <link linkend="po_lua">LUA</link> and <link
  3293.      linkend="po_endlua">ENDLUA</link> pseudo-ops.<example>
  3294.          <title>Hello World!</title>
  3295.  
  3296.          <para><programlisting>    LUA
  3297.        print ("Hello World!")
  3298.    ENDLUA</programlisting></para>
  3299.        </example></para>
  3300.    </section>
  3301.  
  3302.    <section>
  3303.      <title>SjASMPlus binded functions</title>
  3304.  
  3305.      <para>From Lua you can control some variables and use functions of the
  3306.      compiler. Complete list:</para>
  3307.  
  3308.      <para><variablelist>
  3309.          <varlistentry>
  3310.            <term><anchor id="lua__c" />[integer] _c("expression")</term>
  3311.  
  3312.            <listitem>
  3313.              <para>Calculate expression using calculator of the compiler.
  3314.              Example: <code>val = _c("SOMELABEL+12")</code>.</para>
  3315.            </listitem>
  3316.          </varlistentry>
  3317.  
  3318.          <varlistentry>
  3319.            <term><anchor id="lua__pc" />[void] _pc("code")</term>
  3320.  
  3321.            <listitem>
  3322.              <para>Parse string of Z80 assembly. Example: <code>_pc("ADD
  3323.              A,B")</code></para>
  3324.            </listitem>
  3325.          </varlistentry>
  3326.  
  3327.          <varlistentry>
  3328.            <term><anchor id="lua__pl" />[void] _pl("label code")</term>
  3329.  
  3330.            <listitem>
  3331.              <para>Parse line of Z80 assembly. Example: <code>_pc("SOMELABEL
  3332.              ADD A,B")</code></para>
  3333.            </listitem>
  3334.          </varlistentry>
  3335.  
  3336.          <varlistentry>
  3337.            <term>[integer] sj.calc("expression")</term>
  3338.  
  3339.            <listitem>
  3340.              <para>See <link linkend="lua__c">_c</link></para>
  3341.            </listitem>
  3342.          </varlistentry>
  3343.  
  3344.          <varlistentry>
  3345.            <term>[void] sj.parse_code("code")</term>
  3346.  
  3347.            <listitem>
  3348.              <para>See <link linkend="lua__pc">_pc</link></para>
  3349.            </listitem>
  3350.          </varlistentry>
  3351.  
  3352.          <varlistentry>
  3353.            <term>[void] sj.parse_line("label code")</term>
  3354.  
  3355.            <listitem>
  3356.              <para>See <link linkend="lua__pl">_pl</link></para>
  3357.            </listitem>
  3358.          </varlistentry>
  3359.  
  3360.          <varlistentry>
  3361.            <term>[void] sj.error("message")</term>
  3362.  
  3363.            <listitem>
  3364.              <para>Print error message.</para>
  3365.            </listitem>
  3366.          </varlistentry>
  3367.  
  3368.          <varlistentry>
  3369.            <term>[void] sj.warning("message")</term>
  3370.  
  3371.            <listitem>
  3372.              <para>Print warning message.</para>
  3373.            </listitem>
  3374.          </varlistentry>
  3375.  
  3376.          <varlistentry>
  3377.            <term>[boolean] sj.file_exists("filename")</term>
  3378.  
  3379.            <listitem>
  3380.              <para>Check for file exists.</para>
  3381.            </listitem>
  3382.          </varlistentry>
  3383.  
  3384.          <varlistentry>
  3385.            <term>[string] sj.get_define("name")</term>
  3386.  
  3387.            <listitem>
  3388.              <para>Get define value.</para>
  3389.            </listitem>
  3390.          </varlistentry>
  3391.  
  3392.          <varlistentry>
  3393.            <term>[boolean] sj.insert_define("name", "value")</term>
  3394.  
  3395.            <listitem>
  3396.              <para>Add new define.</para>
  3397.            </listitem>
  3398.          </varlistentry>
  3399.  
  3400.          <varlistentry>
  3401.            <term>[integer] sj.get_label("name")</term>
  3402.  
  3403.            <listitem>
  3404.              <para>Get label address.</para>
  3405.            </listitem>
  3406.          </varlistentry>
  3407.  
  3408.          <varlistentry>
  3409.            <term>[boolean] sj.insert_label("name", address)</term>
  3410.  
  3411.            <listitem>
  3412.              <para>Add new label.</para>
  3413.            </listitem>
  3414.          </varlistentry>
  3415.  
  3416.          <varlistentry>
  3417.            <term><anchor id="lua_sj_current_address" />[integer]
  3418.            sj.current_address</term>
  3419.  
  3420.            <listitem>
  3421.              <para>Variable. Current address.</para>
  3422.            </listitem>
  3423.          </varlistentry>
  3424.  
  3425.          <varlistentry>
  3426.            <term>[integer] sj.error_count</term>
  3427.  
  3428.            <listitem>
  3429.              <para>Variable. Count of Errors.</para>
  3430.            </listitem>
  3431.          </varlistentry>
  3432.  
  3433.          <varlistentry>
  3434.            <term>[integer] sj.warning_count</term>
  3435.  
  3436.            <listitem>
  3437.              <para>Variable. Count of Warnings.</para>
  3438.            </listitem>
  3439.          </varlistentry>
  3440.  
  3441.          <varlistentry>
  3442.            <term>[void] sj.exit(errorcode)</term>
  3443.  
  3444.            <listitem>
  3445.              <para>Shutdown the compiler.</para>
  3446.            </listitem>
  3447.          </varlistentry>
  3448.  
  3449.          <varlistentry>
  3450.            <term>[void] sj.add_byte(byte)</term>
  3451.  
  3452.            <listitem>
  3453.              <para>Add byte to output (or to memory) and increase <link
  3454.              linkend="lua_sj_current_address">sj.current_address</link></para>
  3455.            </listitem>
  3456.          </varlistentry>
  3457.  
  3458.          <varlistentry>
  3459.            <term>[void] sj.add_word(word)</term>
  3460.  
  3461.            <listitem>
  3462.              <para>Add word to output (or to memory) and twice increase <link
  3463.              linkend="lua_sj_current_address">sj.current_address</link></para>
  3464.            </listitem>
  3465.          </varlistentry>
  3466.  
  3467.          <varlistentry>
  3468.            <term>[integer] sj.get_byte(address)</term>
  3469.  
  3470.            <listitem>
  3471.              <para>Get byte from memory. <emphasis>Work only in real device
  3472.              emulation mode.</emphasis></para>
  3473.            </listitem>
  3474.          </varlistentry>
  3475.  
  3476.          <varlistentry>
  3477.            <term>[integer] sj.get_word(address)</term>
  3478.  
  3479.            <listitem>
  3480.              <para>Get word from memory. <emphasis>Work only in real device
  3481.              emulation mode.</emphasis></para>
  3482.            </listitem>
  3483.          </varlistentry>
  3484.  
  3485.          <varlistentry>
  3486.            <term>[string] sj.get_device()</term>
  3487.  
  3488.            <listitem>
  3489.              <para>Return current emulating device's identifier. Returns
  3490.               "NONE" if no emulation mode.</para>
  3491.             </listitem>
  3492.           </varlistentry>
  3493.  
  3494.           <varlistentry>
  3495.             <term>[boolean] sj.set_device("id")</term>
  3496.  
  3497.             <listitem>
  3498.               <para>Set current emulating device's identifier. Returns false
  3499.              if no device found.</para>
  3500.            </listitem>
  3501.          </varlistentry>
  3502.  
  3503.          <varlistentry>
  3504.            <term>[boolean] sj.set_page(number)</term>
  3505.  
  3506.            <listitem>
  3507.              <para>Set page with number "number" to the current slot. Works
  3508.              as pseudo-op PAGE.</para>
  3509.            </listitem>
  3510.          </varlistentry>
  3511.  
  3512.          <varlistentry>
  3513.            <term>[boolean] sj.set_slot(number)</term>
  3514.  
  3515.            <listitem>
  3516.              <para>Set current slot with number "number". Works as pseudo-op
  3517.              SLOT.</para>
  3518.            </listitem>
  3519.          </varlistentry>
  3520.  
  3521.          <varlistentry>
  3522.            <term>[void] sj.shellexec("programname")</term>
  3523.  
  3524.            <listitem>
  3525.              <para>See pseudo-op SHELLEXEC.</para>
  3526.            </listitem>
  3527.          </varlistentry>
  3528.  
  3529.          <varlistentry>
  3530.            <term>[void] zx.trdimage_create("filename")</term>
  3531.  
  3532.            <listitem>
  3533.              <para>Creates emptry TRD image file.</para>
  3534.            </listitem>
  3535.          </varlistentry>
  3536.  
  3537.          <varlistentry>
  3538.            <term>[void] zx.trdimage_add_file("filename", "somenameC",
  3539.            startaddress, length, autostart, replace)</term>
  3540.  
  3541.            <listitem>
  3542.              <para>Save block of memory to TRD image file. <emphasis>Work
  3543.              only in real device emulation mode.</emphasis></para>
  3544.            </listitem>
  3545.          </varlistentry>
  3546.  
  3547.          <varlistentry>
  3548.            <term>[void] zx.save_snapshot_sna("filename.sna",
  3549.            startaddressofprogram)</term>
  3550.  
  3551.            <listitem>
  3552.              <para>Save snapshot of memory in SNA format. <emphasis>Work only
  3553.              in real device emulation mode and only for ZXSPECTRUM48 and
  3554.              ZXSPECTRUM128..</emphasis></para>
  3555.            </listitem>
  3556.          </varlistentry>
  3557.        </variablelist></para>
  3558.    </section>
  3559.  
  3560.    <section>
  3561.      <title>Third-party embedded library(ies)</title>
  3562.  
  3563.      <para><emphasis>lpack.c</emphasis></para>
  3564.  
  3565.      <para>a Lua library for packing and unpacking binary data</para>
  3566.  
  3567.      <para>by Luiz Henrique de Figueiredo
  3568.      &lt;lhf(at)tecgraf.puc-rio.br&gt;</para>
  3569.  
  3570.      <para>The library adds two functions to the string library:
  3571.      <emphasis>string.pack</emphasis> and
  3572.      <emphasis>string.unpack</emphasis>.</para>
  3573.  
  3574.      <para>pack is called as follows: string.pack(F,x1,x2,...), where F is a
  3575.      string describing how the values x1, x2, ... are to be interpreted and
  3576.      formatted. Each letter in the format string F consumes one of the given
  3577.      values. Only values of type number or string are accepted. pack returns
  3578.      a (binary) string containing the values packed as described in F. The
  3579.      letter codes understood by pack are listed in lpack.c (they are inspired
  3580.      by Perl's codes but are not the same). Numbers following letter codes in
  3581.       F indicate repetitions.</para>
  3582.  
  3583.       <para>unpack is called as follows: string.unpack(s,F,[init]), where s is
  3584.       a (binary) string containing data packed as if by pack, F is a format
  3585.       string describing what is to be read from s, and the optional init marks
  3586.       where in s to begin reading the values. unpack returns one value per
  3587.       letter in F until F or s is exhausted (the letters codes are the same as
  3588.       for pack, except that numbers following 'A' are interpreted as the
  3589.       number of characters to read into the string, not as
  3590.       repetitions).</para>
  3591.  
  3592.       <para>The first value returned by unpack is the next unread position in
  3593.       s, which can be used as the init position in a subsequent call to
  3594.       unpack. This allows you to unpack values in a loop or in several steps.
  3595.       If the position returned by unpack is beyond the end of s, then s has
  3596.       been exhausted; any calls to unpack starting beyond the end of s will
  3597.       always return nil values.</para>
  3598.  
  3599.       <para>List of types for F string:<variablelist>
  3600.           <varlistentry>
  3601.             <term>z</term>
  3602.  
  3603.             <listitem>
  3604.               <para>zero-terminated string</para>
  3605.             </listitem>
  3606.           </varlistentry>
  3607.  
  3608.           <varlistentry>
  3609.             <term>p</term>
  3610.  
  3611.             <listitem>
  3612.               <para>string preceded by length byte</para>
  3613.             </listitem>
  3614.           </varlistentry>
  3615.  
  3616.           <varlistentry>
  3617.             <term>P</term>
  3618.  
  3619.             <listitem>
  3620.               <para>string preceded by length word</para>
  3621.             </listitem>
  3622.           </varlistentry>
  3623.  
  3624.           <varlistentry>
  3625.             <term>a</term>
  3626.  
  3627.             <listitem>
  3628.               <para>string preceded by length size_t</para>
  3629.             </listitem>
  3630.           </varlistentry>
  3631.  
  3632.           <varlistentry>
  3633.             <term>A</term>
  3634.  
  3635.             <listitem>
  3636.               <para>string</para>
  3637.             </listitem>
  3638.           </varlistentry>
  3639.  
  3640.           <varlistentry>
  3641.             <term>f</term>
  3642.  
  3643.             <listitem>
  3644.               <para>float</para>
  3645.             </listitem>
  3646.           </varlistentry>
  3647.  
  3648.           <varlistentry>
  3649.             <term>d</term>
  3650.  
  3651.             <listitem>
  3652.               <para>double</para>
  3653.             </listitem>
  3654.           </varlistentry>
  3655.  
  3656.           <varlistentry>
  3657.             <term>n</term>
  3658.  
  3659.             <listitem>
  3660.               <para>Lua number</para>
  3661.             </listitem>
  3662.           </varlistentry>
  3663.  
  3664.           <varlistentry>
  3665.             <term>c</term>
  3666.  
  3667.             <listitem>
  3668.               <para>char</para>
  3669.             </listitem>
  3670.           </varlistentry>
  3671.  
  3672.           <varlistentry>
  3673.             <term>b</term>
  3674.  
  3675.             <listitem>
  3676.               <para>byte = unsigned char</para>
  3677.             </listitem>
  3678.           </varlistentry>
  3679.  
  3680.           <varlistentry>
  3681.             <term>h</term>
  3682.  
  3683.             <listitem>
  3684.               <para>short = word</para>
  3685.             </listitem>
  3686.           </varlistentry>
  3687.  
  3688.           <varlistentry>
  3689.             <term>H</term>
  3690.  
  3691.             <listitem>
  3692.               <para>unsigned short</para>
  3693.             </listitem>
  3694.           </varlistentry>
  3695.  
  3696.           <varlistentry>
  3697.             <term>i</term>
  3698.  
  3699.             <listitem>
  3700.               <para>int</para>
  3701.             </listitem>
  3702.           </varlistentry>
  3703.  
  3704.           <varlistentry>
  3705.             <term>I</term>
  3706.  
  3707.             <listitem>
  3708.               <para>unsigned int</para>
  3709.             </listitem>
  3710.           </varlistentry>
  3711.  
  3712.           <varlistentry>
  3713.             <term>l</term>
  3714.  
  3715.             <listitem>
  3716.               <para>long</para>
  3717.             </listitem>
  3718.           </varlistentry>
  3719.  
  3720.           <varlistentry>
  3721.             <term>L</term>
  3722.  
  3723.             <listitem>
  3724.               <para>unsigned long</para>
  3725.             </listitem>
  3726.           </varlistentry>
  3727.  
  3728.           <varlistentry>
  3729.             <term>&lt;</term>
  3730.  
  3731.             <listitem>
  3732.               <para>little endian</para>
  3733.             </listitem>
  3734.           </varlistentry>
  3735.  
  3736.           <varlistentry>
  3737.             <term>&gt;</term>
  3738.  
  3739.             <listitem>
  3740.               <para>big endian</para>
  3741.             </listitem>
  3742.           </varlistentry>
  3743.  
  3744.           <varlistentry>
  3745.             <term>=</term>
  3746.  
  3747.             <listitem>
  3748.               <para>native endian</para>
  3749.             </listitem>
  3750.           </varlistentry>
  3751.         </variablelist></para>
  3752.     </section>
  3753.  
  3754.     <section>
  3755.       <title>Example</title>
  3756.  
  3757.       <para></para>
  3758.  
  3759.       <para><example>
  3760.           <title>Variables doesn't clear in new passes of the compiler</title>
  3761.  
  3762.          <para><programlisting>    LUA PASS1
  3763.       v = 1
  3764.    ENDLUA
  3765.  
  3766.    LUA PASS2
  3767.       print (v)
  3768. -- out to console: 1
  3769.       v++
  3770.    ENDLUA
  3771.  
  3772.    LUA PASS3
  3773.       print (v)
  3774. -- out to console: 2
  3775.    ENDLUA</programlisting></para>
  3776.        </example><example>
  3777.          <title>To generate some code you need to generate it in all
  3778.          passes</title>
  3779.  
  3780.          <para><programlisting>    LUA ALLPASS
  3781.        _pl("ClearScreen LD (.savesp+1),SP")
  3782.        _pc("LD SP,16384+6144")
  3783.        _pc("LD HL,0")
  3784.        for i = 32768, 38912, 2 do
  3785.            _pc("PUSH HL")
  3786.        end
  3787.        _pl(".savesp: LD SP,0")
  3788.        _pc("RET")
  3789.    ENDLUA</programlisting></para>
  3790.        </example><example>
  3791.          <title>Declare function and use it</title>
  3792.  
  3793.          <para><programlisting>     LUA
  3794.         function savetape_mytype(filename, startaddress)
  3795.             local fp
  3796.             fp = assert(io.open(fname, "wb"))
  3797.             for i = 16384, 32767, 4 do
  3798.                 assert(fp:write( string.pack("bbbb",
  3799.                                sj.get_byte(i),
  3800.                                sj.get_byte(i+1),
  3801.                                sj.get_byte(i+2),
  3802.                                sj.get_byte(i+3)) ))
  3803.             end
  3804.             assert(fp:flush())
  3805.             assert(fp:close())
  3806.         end
  3807.     ENDLUA
  3808.  
  3809. ;somewhere in your program
  3810.     LUA
  3811.         savetape_mytype("tapefiles/myprogram.tape", _c("StartGameLabel"))
  3812.     ENDLUA</programlisting></para>
  3813.        </example><example>
  3814.          <title>Simple sample :)</title>
  3815.  
  3816.           <para><programlisting>        LUA
  3817. -- Function reads number from file &lt;fname&gt;, increases it, creates define "BUILD" with the number and saves the number to &lt;fname&gt;.
  3818. -- With this function you can control count of compilations.
  3819.         function increase_build(fname)
  3820.                 local fp
  3821.                 local build
  3822.                 fp = assert(io.open(fname, "rb"))
  3823.                 build = tonumber(fp:read("*all"))
  3824.                 assert(fp:close())
  3825.                 if type(build) == "nil" then
  3826.                     build = 0
  3827.                 end
  3828.                 build = build + 1;
  3829.                 sj.insert_define("BUILD", build)
  3830.                 fp = assert(io.open(fname, "wb"))
  3831.                 assert(fp:write( build ))
  3832.                 assert(fp:flush())
  3833.                 assert(fp:close())
  3834.         end
  3835.  
  3836. -- Before using you must create empty file "build.txt"!
  3837.         increase_build("build.txt")
  3838.  
  3839. -- Creates define "TIME" with current time
  3840.         sj.insert_define("TIME", '"' .. os.date("%Y-%m-%d %H:%M:%S") .. '"')
  3841.         ENDLUA
  3842.  
  3843. ; print to console our time and build number
  3844.         DISPLAY "Build time: ", TIME
  3845.         DISPLAY "Build number: ", /D, BUILD</programlisting></para>
  3846.        </example></para>
  3847.  
  3848.      <para></para>
  3849.  
  3850.      <para></para>
  3851.    </section>
  3852.  </chapter>
  3853.  
  3854.  <chapter>
  3855.    <title><anchor id="c_savenex" />SAVENEX guide</title>
  3856.        
  3857.    <section>
  3858.      <title><anchor id="s_savenex_file_format" />NEX File Format</title>
  3859.  
  3860.      <para>NEX is binary format for ZX Spectrum Next, aiming to provide simple delivery of software
  3861.      for the platform. For file format details check <ulink url="https://specnext.dev/wiki/NEX_file_format">
  3862.      https://specnext.dev/wiki/NEX_file_format</ulink>. In short it is header + loading screen +
  3863.      like-snapshot binary and remaining resources appended after.</para>
  3864.  
  3865.  <para>As such, the SAVENEX commands are available only in ZXSPECTRUMNEXT device emulation mode,
  3866.           see <link linkend="po_device">DEVICE</link>.</para>
  3867.  
  3868.  <para>As the file is designed for self-contained distribution of whole applications/games,
  3869.           its configuration and assembling is a bit too complex for single directive, and the
  3870.           configuration is instead divided into multiple commands, and the assembling goes
  3871.           through multiple stages, so some commands must be used in correct sequence.</para>
  3872.  
  3873.  <para>While the format technically allows to include multiple screen types data, they are all
  3874.           loaded at the beginning over each other, so it makes sense to provide only single loading
  3875.           screen (sjasmplus enforces that).</para>
  3876.  </section>
  3877.  
  3878.  <section>
  3879.           <title><anchor id="s_savenex_commands" />Detailed description of each SAVENEX command</title>
  3880.           <variablelist>
  3881.                  
  3882.                   <varlistentry>
  3883.                           <term><anchor id="nex_open" />
  3884.                                   SAVENEX OPEN &lt;filename&gt;[,&lt;startAddress&gt;[,&lt;stackAddress&gt;[,&lt;entryBank 0..111&gt;]]]
  3885.                           </term>
  3886.                           <listitem>
  3887.                                   <para>
  3888.                                           Opens a NEX file, defines start address, stack address and 16k bank to be mapped
  3889.                                           at 0xC000 before code is executed (if values are omitted, start address is zero
  3890.                                           = no start, stack address is 0xFF2D, entryBank is zero).
  3891.                                   </para>
  3892.                                   <para>
  3893.                                           Only single NEX file can be open at the same time, and to finalize the header
  3894.                                           content the command CLOSE has to be used (does auto-close if source ends).
  3895.                                   </para>
  3896.                                   <para>
  3897.                                           Entry bank is number of 16k bank (0..111), not native 8k page, default is zero,
  3898.                                           i.e. the default memory map is identical to ZX 128 (ROM, RAM banks 5, 2 and 0).
  3899.                                   </para>
  3900.                                   <para>
  3901.                                           Make sure your new stack has at least tens of bytes available as those will be
  3902.                                           used already by the NEX loader before executing your entry point (although
  3903.                                           released back).
  3904.                                   </para>
  3905.                           </listitem>
  3906.                   </varlistentry>
  3907.                  
  3908.                   <varlistentry>
  3909.                           <term><anchor id="nex_core" />
  3910.                                   SAVENEX CORE &lt;major 0..15&gt;,&lt;minor 0..15&gt;,&lt;subminor 0..255&gt;
  3911.                           </term>
  3912.                           <listitem>
  3913.                                   <para>
  3914.                                           Set minimum required Next core version, can be set any time before <link
  3915.                                                   linkend="nex_close">CLOSE</link>.
  3916.                                   </para>
  3917.                           </listitem>
  3918.                   </varlistentry>
  3919.                  
  3920.                   <varlistentry>
  3921.                           <term><anchor id="nex_cfg" />
  3922.                                   SAVENEX CFG &lt;border 0..7&gt;[,&lt;fileHandle 0/1/$4000+&gt;[,&lt;PreserveNextRegs 0/1&gt;[,&lt;2MbRamReq 0/1&gt;]]]
  3923.                           </term>
  3924.                           <listitem>
  3925.                                   <para>
  3926.                                           Set border colour (during loading), whether the machine should be set to default
  3927.                                           state (PreserveNextRegs = 0 = default), if the app requires extended RAM
  3928.                                           (224 8k pages) and how the file handle of the NEX file should be treated:
  3929.                                           0 = default = close, 1 = keep open and pass in BC, $4000..$FFFE = keep open,
  3930.                                           and write into memory at provided address (after entry bank is paged in). This
  3931.                                           can be set any time before <link linkend="nex_close">CLOSE</link>.
  3932.                                   </para>
  3933.                           </listitem>
  3934.                   </varlistentry>
  3935.                  
  3936.                   <varlistentry>
  3937.                           <term><anchor id="nex_bar" />
  3938.                                   SAVENEX BAR &lt;loadBar 0/1&gt;,&lt;barColour 0..255&gt;[,&lt;startDelay 0..255&gt;[,&lt;bankDelay 0..255&gt;]]
  3939.                           </term>
  3940.                           <listitem>
  3941.                                   <para>
  3942.                                           Loading-bar related setup ("colour" usage depends on screen mode), can be set
  3943.                                           any time before <link linkend="nex_close">CLOSE</link>.
  3944.                                   </para>
  3945.                           </listitem>
  3946.                   </varlistentry>
  3947.                  
  3948.                   <varlistentry>
  3949.                           <term><anchor id="nex_screen" />
  3950.                                   SAVENEX SCREEN L2 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]
  3951.                           </term>
  3952.                           <listitem>
  3953.                                   <para>
  3954.                                           Layer 2 loading screen, can be used between <link linkend="nex_open">OPEN</link>
  3955.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  3956.                                   </para>
  3957.                                   <para>
  3958.                                           Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
  3959.                                           format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
  3960.                                           for Layer 2 colours).
  3961.                                   </para>
  3962.                                   <para>
  3963.                                           Image data are 48kiB block of memory, the loader will use always banks 9..11 to display
  3964.                                           it (8k pages 18..23), but if you will prepare the data there, it will be also re-saved
  3965.                                           by <link linkend="nex_auto">AUTO</link> command, so either use other banks, and overwrite
  3966.                                           them with valid data/code after using the SCREEN command, or reset pages 18..23 to zero
  3967.                                           after SCREEN.
  3968.                                   </para>
  3969.                                   <para>
  3970.                                           If no memory address is specified, the pages 18..23 are stored in file, and if
  3971.                                           no palette address is specified, no-palette flag is set in NEX file.
  3972.                                   </para>
  3973.                           </listitem>
  3974.                   </varlistentry>
  3975.                  
  3976.                   <varlistentry>
  3977.                           <term>
  3978.                                   SAVENEX SCREEN LR [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]
  3979.                           </term>
  3980.                           <listitem>
  3981.                                   <para>
  3982.                                           LoRes (128x96) loading screen, can be used between <link linkend="nex_open">OPEN</link>
  3983.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  3984.                                   </para>
  3985.                                   <para>
  3986.                                           Palette is similar to Layer 2 mode, just LoRes mode doesn't have priority bit.
  3987.                                   </para>
  3988.                                   <para>
  3989.                                           Image data are 12288 bytes memory block - either consecutive block if specific
  3990.                                           address is provided, or without address the actual bank 5 memory is stored
  3991.                                           (taking 6144 bytes from address 0x4000 and 6144 bytes from address 0x6000).
  3992.                                   </para>
  3993.                           </listitem>
  3994.                   </varlistentry>
  3995.                  
  3996.                   <varlistentry>
  3997.                           <term>
  3998.                                   SAVENEX SCREEN (SCR|SHC|SHR) [&lt;hiResColour 0..7&gt;]
  3999.                           </term>
  4000.                           <listitem>
  4001.                                   <para>
  4002.                                           ULA/Timex modes loading screen, can be used between <link linkend="nex_open">OPEN</link>
  4003.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  4004.                                   </para>
  4005.                                   <para>
  4006.                                           The actual bank 5 memory (pages 10..11) is stored as if the image is displayed,
  4007.                                           in these modes the palette can't be specified.
  4008.                                   </para>
  4009.                                   <para>
  4010.                                           SCR is classic ZX 6912 bytes long screen from address 0x4000 (page 10 is used,
  4011.                                           even if the slot 1 is modified to other page, so you must prepare the image "in place").
  4012.                                   </para>
  4013.                                   <para>
  4014.                                           SHC and SHR are Timex HiColor (8x1 attribute) and HiRes (512x192 bitmap) modes,
  4015.                                           prepare data "in place", i.e. 6144 bytes into page 10 and 6144 bytes into page
  4016.                                           11 (0x4000 and 0x6000 addresses in default memory setup). For HiRes mode you
  4017.                                           should specify ink colour (the paper is complement of ink).
  4018.                                   </para>
  4019.                           </listitem>
  4020.                   </varlistentry>
  4021.                  
  4022.                   <varlistentry>
  4023.                           <term><anchor id="nex_bank" />
  4024.                                   SAVENEX BANK &lt;bank 0..111&gt;[,...]
  4025.                           </term>
  4026.                           <listitem>
  4027.                                   <para>
  4028.                                           Can be used after <link linkend="nex_open">OPEN</link> or <link linkend="nex_screen">
  4029.                                                   SCREEN</link> and before <link linkend="nex_close">CLOSE</link>, but the 16ki
  4030.                                           banks must be saved in correct order: 5, 2, 0, 1, 3, 4, 6, 7, 8, 9, 10, ..., 111
  4031.                                   </para>
  4032.                           </listitem>
  4033.                   </varlistentry>
  4034.                  
  4035.                   <varlistentry>
  4036.                           <term><anchor id="nex_auto" />
  4037.                                   SAVENEX AUTO [&lt;fromBank 0..111&gt;[,&lt;toBank 0..111&gt;]]
  4038.                           </term>
  4039.                           <listitem>
  4040.                                   <para>
  4041.                                           Can be used after <link linkend="nex_open">OPEN</link> or <link linkend="nex_screen">
  4042.                                                   SCREEN</link> and before <link linkend="nex_close">CLOSE</link>. The sjasmplus
  4043.                                           will save every non-zero 16k bank detected in the correct order (automatically
  4044.                                           starting from first possible bank after previous BANK/AUTO commands, or from
  4045.                                           provided "fromBank").
  4046.                                   </para>
  4047.                                   <para>
  4048.                                           For "fromBank" value use the specified order above in <link linkend="nex_bank">BANK
  4049.                                                   </link> command, i.e. 5, 2, 0, ...
  4050.                                   </para>
  4051.                                   <para>
  4052.                                           Keep in mind the <link linkend="po_device">DEVICE</link> ZXSPECTRUMNEXT will
  4053.                                           automatically adjust content of banks 5 and 0 (ULA screen, sysvars and fake ZX48
  4054.                                           stack), so unless you clear those banks to zero, or skip saving them by saving
  4055.                                           first set of banks explicitly with <link linkend="nex_bank">BANK</link> command,
  4056.                                           they will be saved by AUTO.
  4057.                                   </para>
  4058.                           </listitem>
  4059.                   </varlistentry>
  4060.                  
  4061.                   <varlistentry>
  4062.                           <term><anchor id="nex_close" />
  4063.                                   SAVENEX CLOSE [&lt;fileToAppend&gt;]
  4064.                           </term>
  4065.                           <listitem>
  4066.                                   <para>
  4067.                                           Can be used after <link linkend="nex_open">OPEN</link>. The currently open NEX
  4068.                                           file will be finalized (header adjusted), and optional extra file just appended
  4069.                                           to the end of NEX file.
  4070.                                   </para>
  4071.                           </listitem>
  4072.                   </varlistentry>
  4073.                  
  4074.           </variablelist>
  4075.  
  4076.  </section>
  4077.          
  4078.  <section>
  4079.           <title><anchor id="s_savenex_examples" />Examples</title>
  4080.  
  4081.           <example>
  4082.          <title></title>
  4083.                   <para>
  4084.                           Creating NEX file which will have Layer2 loading screen (stripes), progress bar, and will
  4085.                           enter infinite loop with calling stack (used by IM 1 interrupt handler) visible on the
  4086.                           Layer 2 screen.
  4087.                   </para>
  4088.                   <programlisting>    DEVICE ZXSPECTRUMNEXT
  4089.    ORG $7E00
  4090. start:  ei : jr $           ; app code entry point, BC = NEX file handle
  4091.    ; Layer2 screen (top 1/3 defined, bottom of it will be used also as "visible" stack)
  4092.    ORG $C000 : DUP 64*32 : DB $90,$91,$92,$93,$94,$95,$96,$97 : EDUP
  4093.  
  4094.    ; write everything into NEX file
  4095.    SAVENEX OPEN "example.nex", start, $FFFE, 9  ; stack will go into Layer2
  4096.    SAVENEX CORE 2, 0, 0        ; Next core 2.0.0 required as minimum
  4097.    SAVENEX CFG 4, 1            ; green border, file handle in BC
  4098.    SAVENEX BAR 1, $E0, 50, 25  ; do load bar, red colour, start/load delays 50/25 frames
  4099.    SAVENEX SCREEN L2 0, 0      ; store the data from C000 (page 0, offset 0), no palette
  4100.    SAVENEX BANK 5, 100, 101    ; store the 16ki banks 5 (contains the code at 0x7E00), 100, 101
  4101.    SAVENEX CLOSE               ; (banks 100 and 101 are added just as example)
  4102.                   </programlisting>
  4103.           </example>
  4104.  </section>
  4105.  
  4106.  </chapter>
  4107. </book>
  4108.