Macro Operand Formats
---------------------
  Numeric field: dwordReg=value,  [Field], Literal, (Field = address)
  Alpha field:   dwordReg=address, Field,  Literal
  All macro names are in lower case with an initial uppercase letter,
    and sometimes a final uppercase letter.
  All macro keywords, shown here in uppercase, may also be in lowercase.

Program Skeleton
----------------
  include '\Fasm\Include\win32ax.inc'
  include '\Fasm\Include\macro\masm.inc'
  include '\Fsm\Genmacros.inc'
  include '\Fsm\Winmacros.inc'     ; Win
  .data
  Gendata
  Windata                          ; Win
  {Program data}
  .code
  Start:
     Crefont                       ; Win
     Crewindow                     ; Win
     Crecontrol                    ; Win
     Runwindow                     ; Win
     Closewindow                   ; Win
     invoke ExitProcess,0
     {Program code}
  include '\Fsm\Routines.inc'
  .end Start

General Macros
--------------
  Gendata
    This macro should be at the start of the .data section in all programs.
    It defines all general data required by the program.
    The following fields may be used by the program.
      Asciz      A 128 byte field used by macros for general data conversion.
                 Do not leave data here.
      Exitcode   The exit code used by Exitprocess, initally 0.
      Sysparloc  This controls access to system parameters. Reset it to zero
                 if it is required to access the parameters again.
      Today      Set by the Gettoday macro (described later).

  Getparameter Buffer,Blen
    Return [next] parameter 0-terminated, space-filled or truncated,
    with length [before truncation] in eax, 0 if no more parameters.
    First parameter is the program's path.

File IO macros
--------------
Sequential files contain fixed length records.
Line text files contain variable length records ending with 0D0A.
Files may also be accessed directly as a string of bytes, by absolute location
and length.

Controls
  Fname  File handle, zero if not open
  Pathz  Asciz file path
  Rname  Record area
  Rlen   Record area length
  Rno    The current record number relative to zero, or -1 if no current record.
         Line text files do not use Rno.
         For direct access, Rno is the absolute file location relative to zero.

General rules
On entry to a macro, Rno indicates the number of the record in the record area
to be processed, and the current file pointer is the file location of the next
file record in sequence.
On exit from a macro, Rno indicates the record in the current record area.
                      eax contains the record length, or 0.

All files
  OpenC    Fname,Pathz,Rno
     Create a new file, overwriting any existing file. Omit Rno for text files.
  OpenR    Fname,Pathz,Rno
     Open an existing file, or create a new one if not found. Omit Rno for text
	files.
  Close    Fname
     Close the file.

Sequential files
  NextS    Fname,Rname,Rlen,Rno
     Read the next record in sequence, using the current record pointer,
     ignoring records starting with 7Fh, and update Rno to match.
     eax returns Rlen, or 0 at end of file.
  ReadS    Fname,Rname,Rlen,Rno
     Read the Rno record. eax = Rlen, or 0 if Rno is invalid.
  WriteS   Fname,Rname,Rlen,Rno
     Append the current record at the end of the file and return its
     record number in Rno.
  RewriteS Fname,Rname,Rlen,Rno
     Rewrite the current record at the current record location.
  DeleteS  Fname,Rname,Rlen,Rno
     Delete the current record by setting its first byte in the file to 7Fh.
     Rno and the record pointer and the data in Rname is not affected.

Text line files
  NextL    Fname,Rname,Rlen
     Read the next record in sequence up to Rlen, stopping on 0D0A.
     Rname must be long enough for 0D0A but this is not stored.
     eax returns the actual data length excluding 0D0A, or 0 at end of file.
  NextE    Fname,Rname,Rlen
     As for Nextl, but the 0D0A is stored, with a terminating '0'.
     This is more conmvenient for Editbox text lines.
  WriteL   Fname,Rname,Rlen
     Truncate trailing spaces in the Rname record, add 0D0A, and append the
     record to the end of the file. The Rname record is not affected by this.

Direct access
  ReadD    Fname,Rname,Rlen,Rno
     Read the file data at location Rno into Rname, length Rlen.
  RewriteD Fname,Rname,Rlen,Rno
     Rewrite the current record at location Rno, length Rlen.

File Operations
---------------
  Deletefile,Filepathz
     Delete the Filepathz file from disk.
     Return eax = 0 if failed.
  Getnextfile WfdHandle,Wfd,Pathz
     Return in Wfd the first (next) file matching the Pathz spec.
     The filename (no directory) is zero-terminated in Wfd.cFileName
     If it is greater than 8.3,0, it is also in Wfd.cAlternateFileName as 8.3,0
     eax returns its length, -1 if no file exists, 0 if no more exist.
     To restart before the last file, move 0 to WfdHandle.
     If pathz ends with '.' (no extension, only directories are returned,
     but including '.' and '..'
     
Printing
--------
These macros do not provide printing with Windows. Print lines are written to a
text file on disk which may then be printed, either with Notepad, or with a Dos
printing utility. The macros track the number of lines per page, and a new page
may be commenced at any point.
An end of page routine may be specified, which will automatically be called
immediately before the first line of each page is printed. This provides the
opportunity to print heading lines at the top of each page.

Using Notepad
  The font and size, as well as the page size must be set for Notepad to print
  the report correctly. There is an option for Notepad to be loaded and displayed
  for these parameters to be set before printing.
  The page size depends on the font, so this must be determined by the user. In
  addition unless a fixed font is used, the line length may cause problems with
  the page format. Using Fixedsys or Courier New font avoids this problem.
  As an indication, here are some values for the Fixedsys font with no Notepad
  header or footer. Selecting 'bold' does not alter these values.
    Top margin     10
    Bottom margin  10
    Left margin    15
    Right margin    0
    Font size      10: Lines per page 74, line length 90 characters
                   11                 65              82

Using Dos printing
  This uses the default printer font, and the page size may be any value within
  the limits of the physical page.

Printing macros
  Definep Reference,Path,Lpp,Eopproc
    This macro is used in the .data section for each print file.
      Reference  The user referecne for this file
      Path       The file path for the text file
      Lpp        The lines per page
      Eopproc    The optional routine to be called before printing the first
                 line on each page.
  Writep Reference,Line,Length
    If this is the first use of Writep for this Reference, the text file is
    created and opened automatically.
    Write the specifed line to the referenced text file.
    Any trailing spaces are truncated, and 0dh,0ah are appended to the line.
    If there is not enough truncated space within the specified Length,
    0dh,0ah omitted. If the line includes 0dh,0ah and there are truncated spaces
    beyond this, a further 0dh,0ah is appended, thus giving double spacing.
    On exit, eax contains the number of lines left on the current page.
  Eopwin Reference
    This macro is used to space down the current page to the top of the
    following page. It is used for a text file to be printed with Notepad
    because there is no way to end a page other than by spacing down the
    current page.
    If this macro is used at the top of a page, it is ignored.
  Eopdos Reference
    This macro is similar to Eopwind, but for files to be printed with the Dos
    utility. It uses the special character 0ch to indicate end of page to the
    printer.
  Printwin Reference,SHOW
    Print the referenced text file with Notepad after closing the file if it is
    open. An existing text file may also be printed if it is specified in Definep.
    SHOW is an optional parameter; if included, the file is loaded
    into Notepad which is then displayed on the screen. Notepad parameters amy
    then be set before the actual printing.
  Printdos Reference
    Print the referenced text file with the Dos utility after closing the file
    if it is open. An existing text file may also be printed if it is specified
    in Definep.
  Closep Reference
    This macro is used to close a text file if it is not to be printed at this
    stage. It is not required if Printwin or Printdos is to be used.

Dates
-----
The date field contains the date as 4 binary bytes, CYMD, allowing for string
compares. When loaded into a register, it becomes DMYC; use 'bswap reg' to
revert to CYMD in the register to use it for register compares.
  Gettoday
    Store the current date in [Today], CYMD format
  Date2days Date,Days
    Convert the CYMD date in Date [or DMYC in eax] to days in Days [or eax]
  Days2date Days,Date
    Convert the days in Days [or eax] to the CYMD date in Date [or DMYC in eax]
  Weekday Date,Day
    Return the weekday number (0-6 = Sun-Sat) in Day [or eax]
    from CYMD date in Date [or DMYC in eax]
  Editdate Date,String
    Edit the CYMD Date at [esi] to the 10c edited field at [edi]
  Getdate String,Date
    Extract edited 10c date in [esi] to a CYMD date in [edi]
    Uses C from [Today] if not included in the edited date

Strings and Values
------------------
  Movdata Sfield,Dfield,Slen[,Dlen]
    Move byte data from Sfield to Dfield with truncation, space fill,
      or appended binary '0'.
    Sfield may be literal, with Slen zero.
    Dlen may be omitted if the same as Slen.
    Slen is zero for an asciz field; if Dlen is also zero, Dfield is assumed
      to be long enough to contain Sfield including the zero.
    Saves esi,edi,eax,ecx,edx
  Clrdata Data,Len,Char
    Clear the Data field to all ascii Char characters.
  Cmpdata,Fromdata,Fromlen,Todata[,Tolen]
    Compare Fromdata to Todata and return eax 1< 2= 3> and cmp set.
    Dlen may be omitted if the same as Slen.
    Saves esi,edi,ecx,edx
  Upcase,Data,Len
    Convert Data to upper case. Saves esi,eax,ecx.
  Editvalue Value,Data,Len,Decp
    Convert the binary Value (or eax if omitted) to an edited result
    in Data with Len bytes an Decp decimal places.
  Getvalue Data,Len,Result
    Extract the numeric value from an edited numeric value in Data
    of Len bytes, and store the result in Result (or eax if omitted).
    The number of decimal plaves is returned in ebx.

Windows Procedures Overview
---------------------------
These procedures provide for a screen consisting of just one window.
The programming requirements are as follows.

.data section
-------------
Windata
This defines all the data definitions required in windows programs using these
procedures. It has three operands, specifying the maximum number of controls to
be defined, the maximum number of fonts to be defined, and the number of control
which are images.
Windata may be anywhere in the .data section, but should be towards the start
because it contains defined data entries.

.code section
-------------
Crefont
This macro defines a font required by the program, assigning a user-reference,
and specifying the font type and size, and whether it is to be bold, underlined,
or in italics. If more fonts are defined than allowed for in the Windata macro,
an error message is displayed and the assembly is abandoned.
Fonts must be defined before any reference is made to them, and should
therefore be towards the start of the .code section.

Crewindow
This macro defines all the initial processing that a general windows program
requires, and then defines the window itself. The operands define the window
title, and x,y,w,h in pixels. If x (and y) is omitted, the window is centred on
the screen, excluding the system tray at the bottom of the screen.
The window is not displayed on the screen at this time.

Crecontrol
There is one of these for each control contained in the window. There are
operands for the type of control, its user-reference, the associated process,
its title, position within the window, and optionally, the font.

All controls are defined as visible by default, but the window is not displayed
until the next macro is executed. Controls may be hidden at thisa stage if they
are not to be displayed at once, and data may be added to the editboxes,
comboboxes, listboxes.

Runwindow
This is specified to display the defined window and its controls, and to begin
processing. It retains control of the processing throughout, calling the user-
defined routines to process the functions required by the controls, which
always must return by the 'ret' instruction.

This macro has an optional parameter which is the reference of a user routine.
When this is specified, the routine is entered when the user clicks on the 'X'
button to exit from the program. Use this routine when you wish to to check
whether the user really wishes to exit the program. Return with the 'ret'
instruction, and with carry set (stc) to exit the program, or with carry unset
(clc) to continue processing.

Runwindow proceeds to the next instruction in sequence when the user specifies
exit from the process.

Closewindow
This macro closes the window and releases all defined facilites that were used
by windows, including the defined fonts which are indicated by an operand
pointing to the first font in the .data section.

It does not end the program; ExitProcess is still required to end the program.

Processing Windows Controls
There are two macros which provide control processing, Set and Get.

Set: Alter the properties or the contents of a control.
  SHOW	Make a control visible
  HIDE	Make a control hidden
  FONT	Change the font for this control
  FOCUS	Make this control have the focus
  TEXT	Change the text or title for the control
  LINE1 Set the cursor to line one in an Editbox
  POSITION  Change the position or size of a control in the window
  INSERT	Insert an item in a Listbox or Combobox
  DELETE	Delete a specified item from a Listbox or Combobox
  CHECK	Set a Checkbox or Radio as checked
  UNCHECK	Set a Checkbox or Radio as unchecked

Get: Return the state or contents of a control.
  TEXT	The text or title of the control
  TEXTLEN	The length of the text or title
  LINE	A specified Editbox, Listbox or Combobox line
  LINECOUNT	The number of lines in an Editbox,  Listbox or Combobox
  FIND	Find the item number for an item matching a given string
  SELECTION The currently selected Listbox or Combobox item
  CHECK	The current check state of a Checkbox or Radio

General rules
  All data strings are asciz strings unles otherwise stated.
  Item numbers are 0-based: The first item is item 0.
  Returned values are in eax, errors or exceptions are returned as -1.
  Ref is the control reference defined in Crecontrol.
  Operator words (SHOW, HIDE, etc) may be in upper or lower case. This reserf
    also to all control words shown here in upper case.

Bitmap images
  Bitmaps are .Bmp files which can be displayed within the screen window. The
  IMAGE Crecontrol defines the image are on the screen, and the Image macros
  control the display.
  An image may be resized to fit within the defined area or it may beshown with
  its actual size, truncated if required to fit within the defined area. In
  addition, the origin within the image for display may be specified.
  A defined image area may be specified as transparent; this means that the top
  left bit of the image - and all identical bits in the image - will be replaced
  by the gray default background.
  Image macro
  SHOW      Load and display a bitmap image
  LOAD      Load, but do not display, a bitmap image
  DISPLAY   Display a loaded bitmap image
  HIDE      Remove an image from the screen and from memory
  POSITION  Reposition an Image control, and the display if DISPLAYed
  SIZE      Return the pixel size of a loaded bitmap image

Timers
A timer counts down a specified number of milliseconds and call a specified
procedure if and when it times out.
The timer is set with the Timeset macro which optionally specifies the time in
milliseconds and the procedure to call when timed out. Both these values must
be non-zero for the timer to be effective.
The timer runs until it times out or until a user operation causes a user-
defined routine to be called. The timer is therefore never in progress when a
user-defined routine has control.
The timeset macro may be used before the Runwindow macro, or during any user-
defined routine. The timer need not be reset during any user routine; the
existing time and process routine will be used again automatically if they are
not reset.
If the latest Timeset macro has specified a period and a procedure, timing
commences when Runwindow is called, or when a user-defined routine returns with
the 'ret' instruction.

Windows macros
--------------
.data macros
  Windata Controls[,Fonts][,Images]
    Mandatory, define the Windows procedures data, the maximum number of
    controls - including images - the number of fonts to be defined in the
    .code section, and the number of images included in the controls.

.code macros
  Crefont Fontname,Font,Size,Wgt,I,U
    Create a font with user-reference 'Fontname'.
    Font is the font type, e.g. 'Times New Roman'
    Size in pixels, Wgt 100 - 900  is  light - very bold
    'I' for italics, or 0; 'U' for underlined, or 0
    Fonts are defined before they are used in control definitions.

  Crewindow Title,[X],[Y],W,H
    Define the main window with the specified title, and width and height in
    pixels. Include X and Y to locate the window on the screen, otherwise it is
    centred on the screen.

  Crecontrol Class,Reference,Process,Title,x,y,w,h,Font
    Define the required controls for the window.
    Class      The type of control: Button, Checkbox, Text, Number, Password,
               Edit, Readonly, Listbox, Combobox, Group, Radio, Image.
    Reference  The user-defined reference for this control.
    Process	   The process routine to be used with this control.
    Title	   The title or the text to be displayed.
    x,y,w,h	   The location and size of the control in the window.
    Font	   Optional, the reference of a font to be used for this control.

    If no title is required, use an empty literal ('')
    Control types:
    LABEL
      A static text label for information only. Text automatically wraps within
      its length. There is no process for this control.
    BUTTON
      A push button containing a text label that the user may click to call its
      routine.
    CHECKBOX
      A square box which contains a click that is toggled by clicking on it.
    TEXT
      A single-line input field. Its routine is called when its contents are
      changed.
    NUMBER
      A single-line input field which accepts only numeric data. Its routine is
      called when its contents are changed.
    PASSWORD
      A single-line input field in which a password may be entered, but only
      asterisks will be displayed on the screen.
    EDITBOX
      A multi-line input field in which data is automatically wrapped. Its
      routine is called when its contents are  changed.
    READONLY
      A multi-line filed like EDIT, but data is displayed only; it cannot be
      changed.
    LISTBOX
      A box containing a list of text strings. Its routine is entered when the
      user double-clicks an item in the list. The title is ignored.
    COMBOBOX
      A LISTBOX which shows only the currently selected item until the user
      clicks on the arrow beside the item. The title is ignored.
    GROUP
      This draws a border around the defined area in the window. It has a title
      and its only purpose is to contain RADIO buttons, described below.
    RADIO
      A small circle-shaped box containing a dot when selected by clicking on
      it. When a group of RADIO buttons are contained within a GROUP, all the
      other buttons are set off when one is selected.
    IMAGE
      A defined area in which a bitmap image may be displayed. It does not have
      a process or a title, and instead of a font, the word Transparent (or
      just the T) to indicate a transparent image.

  Runwindow[,Routine]
    Display the window on the screen and control all processing, calling the
    user-defined processes as required. This continues until the user clicks on
    the X at the top of the screen to exit from the process. The Program
    continues from the next instruction in sequence.
    If the optional routine is specified, this is called before exiting from the
    processing, for the user to decide whether to confirm the exit or to
    continue processing. Return with the 'ret' instruction, and with carry set
    (stc) to exit the program, or with carry unset (clc) to continue processing.

  Closewindow
    At the end of the program, release all windows controls and fonts
    prior to ending the program. This DOES NOT end the program.

  Timeset Msec,Proc
    Set timeout period in msec, no change if omitted
    Set timeout procedure, no change if omitted

Set macros
    These are used for all controls execpt the IMAGE control.
  Set Ref,SHOW
    All controls, make the control visible. They are created visible by default.
  Set Ref,HIDE
    All Controls, make the control hidden.
  Set Ref,FONT,Font
    All controls, assign this font, created with Crefont.
  Set Ref,FOCUS
    All except Labels and Groups, Set the focus to this control.
  Set Ref,TEXT,title
    All except Listboxes and Comboboxes, the text of Textboxes and Editboxes,
    the title of others.
  Set Ref,LINE1
    Editboxes, set the cursor to the start of line one.
  Set Ref,POSITION,x,y,w,h
    All controls, change the size or position of the control in the window.
  Set Ref,INSERT,Itemno,Stringz
    Listboxes and Comboboxes, insert Stringz at Itemno, or append if -1.
    For Editboxes, Stringz is always appended.
    Return the item number, or -1 if Itemno is invalid.
  Set Ref,DELETE,Itemno
    Listboxes and Comboboxes, delete the item at Itemno and return
    the remaining number of items, or -1 if Itemno is invalid.
  Set Ref,CHECK
    Checkboxes and Radios, set the control as checked.
  Set Ref,UNCHECK
    Checkboxes and Radios, set the control as unchecked.

Get macros
    These are used for all controls except the IMAGE control.
  Get Ref,TEXT,Dataz,Maxlen
    Textboxes and Editboxes, the total contents not exceeding Maxlen.
    Title of Labels, Buttons, Groups, Checkboxes and Radios.
    The Listbox title defined with Crecontrol (this is otherwise ignored).
  Get Ref,TEXTLEN
    Return the length of the data that would be returned by TEXT, above.
  Get Ref,LINE,Itemno,Dataz
    Editboxes, Listboxes and Comboboxes, return the item at Itemno, and in eax
    its length, or -1 if Itemno is invalid.
  Get Ref,LINECOUNT
    Editboxes, Listboxes and Comboboxes, return the current number of lines.
  Get Ref,FIND,Stringz
    Listboxes and Comboboxes, the item number of the string matching the
    whole or part string at Stringz (not case-sensitive), or -1 if not found.
  Get Ref,SELECTION
    Listboxes and Comboboxes, return item number of the current selected item,
    or -1 if none.
  Get Ref,CHECK
    Checkboxes and Radios, return 1 if the control is checked, otherwise 0.

Image macros
  Image Ref,SHOW,Filepath,ACTUAL
    Load and display the Filepath bitmap image, then delete from memory.
    The image is resized to the Control size Unless ACTUAL is included.
  Image Ref,LOAD,Filepath
    Load the Filepath bitmap image as the current image into memory, actual
    size. Unlike SHOW, the image is not displayed by this macro; this requires
    DISPLAY.
  Image Ref,DISPLAY,x,y
    Display the actual current image within the control size limits, starting
    from x,y in the image if included. The image must have been loaded with
    LOAD, and it may be repeated with differing values of x,y.
  Image Ref,HIDE
    Clear the displayed image from the screen. If it has been loaded with LOAD
    it is also removed from memory.
  Image Ref,POSITION,x,y,w,h
    Change the size or position of the control in the window. If there is an
    image which was loaded with LOAD, it will be redisplayed in the new
    position. If there is an image displayed with SHOW, it will be removed but
    not redisplayed.
  Image Ref,EXTENT
    Return the actual size of the current image which was loaded with LOAD; the
    width in eax and the height in ebx, in pixels. If there is no current image,
    eax and ebx are both returned as zero.

Common Dialog boxes
-------------------
  Getfilename OPEN|SAVE,Pathz,[Namez],[Titlez],[Filterz]
    Does NOT require Windata, only Gendata.
    Display the box to select a file and return its path in Pathz.
    Namez returns the name and extension only.
    Titlez is title bar, default is 'Open' or 'Save As'.
    Filter is file types, default is 'All Files',0,'*.*',0,0

  Message Title,Data,Len,Icon,Style
    Display a message box with the specified properties.
      Title may be a reference or a literal
      To display the value in eax, omit Data
      To display a dword field, omit Len
      To display a zero-terminated field, specify Len as 0
      Otherwise Data with a length of Len is displayed
      Icon:  X, ?, !, I, no icon if omitted
      Style: OK   OK button (default)
             OKC  OK     Cancel
             ARI  Abort  Retry  Ignore
             YNC  Yes    No     Cancel
             YN   Yes    No
             RC   Retry  Cancel
      Return value in eax: 0    1  2      3     4     5      6   7
                           None OK Cancel Abort Retry Ignore Yes No

  Checkmsg Title,Data,Len
    This macro is used mainly for program testing.
    A variation of Message where the parameters are the same,
    the Icon is is ?, and the button Style is  OK Cancel.
    If OK is clicked the program continues.
    If Cancel is clicked, the rpogram is immediately terminated.