-----------------------------------------------------------------------
WORD.com    Acronym for 'Waveform Output, Recording, and Display. An
            executable '.com' file used for any of:

            Recording via A/D converter,
            Storing data from memory to '.wav' files
            Loading '.wav' files to memory,
            Replaying data out via D/A converter,
            Displaying / printing data in graph form.

    It is called by typing WORD [CR].
------------------------------------------------------------------------
It is not essential to have a working interface to observe the operation
of WORD. Type WORD [CR] and the front-panel will be seen.

Because like me, you want to see something happen without reading these
boring instructions, an example of the program operation can be seen as
follows. (Even without interface hardware).

Type the following from CP/M.

    WORD [CR]
        (Observe the front-panel menu...)
    Z
        (Request file handling...the available waveform files on the
        default disk are shown...there is only one, DEMO.WAV...)
    R
        (Request read file option...)
    DEMO
        (Response to filename prompt...)
    P
        (Request for plot from main menu.)

    This will show the file DEMO.WAV which  is a numerically synthesised
example out of the synthesis program GEN.BAS. Press the Z key whilst in
plot to keep zooming in until you can see the individual samples.

    When you have a working D/A converter, this shape can be seen on
your oscilloscope using the replay function. Whilst in the plot page,
use other cursor controls to zoom and pan.

    Then, you can read the instructions......

Description of the front-panel.

    Each of the facilities shown on the front-panel will be described in
detail.

[A] Replay timebase. <time>

    This function allows the adjustment of the timebase used for the
    replay of samples in the memory array. Upon replay, each sample is
    spaced apart by a time equal to the value shown as <time>.

    Selection of this function by pressing 'A' causes the prompt:

    'Enter '+' to advance, '-' to retard, else exit'

    Use of the '+' or '-' key causes the list of available time steps to
    advance or retard respectively will the current setting shown as
    <time>. When the required setting has been obtained, press any other
    key (eg space) to exit.

[B] Replay from: <address>

    This function displays, and allows the alteration of, the replay
    start address. The address is the memory address from which the
    replay of sample data will commence when the replay function is
    called.

    Pressing the 'B' key, will produce the prompt:

    'Enter the address in 4-digit hex:'

    whereupon the system expects a 4-digit hexadecimal address to take
    as the new address from which the replay will commence.

    Since the plotting routines allow cursor and margin movement around
    the sample array, and an option to retain these margins as the
    replay addresses on leaving the plot routines, this start address
    may be re-assigned at will without affecting the sample data.

    Note that the address shown at <address> is the actual memory
    address of the data and that manual setting of a lesser address is
    not validated and will produce strange replay data.

[C] - Block length: <address>

    This displays, and allows the alteration of, the replay sample size
    in 4-digit hexadecimal.

    To replay a block of 100 samples, press the 'B' key, and in response
    to the prompt 'Enter the address in 4-digit hex', enter the value
    0063 (the hexadecimal equivalent of 100 ).

File handling.

    Pressing the 'Z' key causes a screen display of all waveform files
    (extension '.WAV) found on the default directory and then a list of
    the file options :

    (R) Read file, (W) Write file, ('C) exit.

    Pressing the 'R' key causes the prompt 'Enter filename'. The user
    enters a valid filename in the usual CP/M form. If the  file is not
    found, the system bleeps and re-prompts the file options. If found
    the file is read into memory and the system returns to the front-
    panel with the replay and record addresses as follows:

    Replay start address: position of first file sample,
    Replay block size:    number of samples in file.

    Record start address: as replay,
    Record block size:    as replay.

    Pressing the 'W' key causes the prompt 'Enter filename'. The user
    enters a valid filename in the usual CP/M form. A file of this name
    is opened with the extension '.WAV' on the specified or default
    drive and samples written to it commencing from the replay start
    address for an amount equal to the replay block size.

    If an error occurs during writing the file (such as a full disk),
    the system beeps and reprompts the file menu, otherwise the system
    returns to the front panel.

    Note that use of an existing file name will overwrite the old
    version.

    See 'Waveform file format' for further details.

    The ('C) option (ALT and C or just the STOP key) will exit to the
    front panel.

[P] Graphics menu.

    Pressing the 'P' key will clear the screen and a screen plot of the 
    replay block commencing from the replay start address will appear.

    Each plot is accompanied by the following data and plot menu

    Plot data:

    Plot start address: <address>

        This is the hexadecimal memory address of the left margin of the
        plot. The first plot to appear after the 'P' key has this
        address equal to the replay start address, subsequent plots
        update this value.

    Plot data length: <size>

        This is the hexadecimal size of the  plot in samples. The first
        plot to appear after the 'P' key has this size equal to the
        replay size, subsequent plots update this value.

    Cursor at address: <address>

        This is the hexadecimal memory address of the plot cursor. Each
        new plot sets the cursor to the centre of the plot. Subsequent
        cursor operations update this value.

    Data at cursor: <data>

        This value in <data> is the 2-digit hexadecimal data of the
        sample byte at the address of the cursor. Cursor movement will
        update this value.

        Note that the cursor moves in steps of 1/256 of the plot width.
        Using it to examine individual sample data may require 'zooming
        in' until each step is one sample to avoid 'hidden samples'.

    Plot options:

    'Z' Zoom in, twice magnify.

        Pressing this key causes a new screen plot centered on the
        present cursor and with half the present sample length. Thus
        repeated operations using 'Z' will lead to individual samples
        becoming shown.

        The cursor may be moved at any time on any plot to 'steer' the
        zoom into a desired feature.

        The zoom operation has no effect when there are 4 samples or
        less.

    'P' Pan out to twice width.

        Pressing this key causes a new screen plot centered on the
        present cursor and with twice the present sample length. Thus
        repeated operations using 'P' will lead to more and more samples
        becoming shown.

        The cursor may be moved at any time on any plot to 'steer' the
        pan about a desired feature.

        Use the pan facility with care when the existing plot is  very
        large or a margin is approaching the memory limit, or strange
        plots can occur.

    'R' Right margin from cursor.

        This produces a new plot with the same left margin address but
        with a new right margin address taken from the cursor position.
        The new cursor position is at the centre of the new plot.

    'L' Left margin from cursor.

        This produces a new plot with the same right margin address but
        with a new left margin address taken from the cursor position.
        The new cursor position is at the centre of the new plot.

    'D' Redraw around cursor.

        This produces a new plot of the same sample length but centered
        around the present cursor, ie both margins are moved.

    'C Return to main menu.

        This return request produces the prompt:

            'Use plot as new replay addresses?'

        If 'Y' is selected, the existing plot margins are carried back
        to become the replay start address and its length. In this way,
        waveform 'hacking' or manipulation can be used for selective
        replay or for selective disk storage.

        If 'N' is selected the original replay addresses are retained.

[D] Start replay.

    This key causes the replay process to begin. All the 'block length'
    sample data comenceing at the 'replay from' address are sent to the
    D/A converter spaced apart in time by the replay timebase setting.
    External devices or monitoring will observe the data as a waveform
    at the D/A output.

    Additionally, the replay occurs in one of three modes set by the 'E'
    key as follows:

        Loop (default)                            All sample data is
                                                  repeated until the
                                                  user aborts the
                                                  replay.

        Single                                    The block of sample
                                                  data is replayed only
                                                  once with a return to
                                                  the front-panel when
                                                  the last sample has
                                                  been sent.

    In each case, the user may abort the replay at any time by pressing
    the D0 or D7 button on the interface. This returns to the front-
    panel.

[E] Replay mode: <mode>.

    This function allows the display and alteration of the replay mode.
    Two modes are possible, loop and single, and are explained fully
    under '[D] Start replay'.

    Each press of the 'E' key selects the next option, with the current
    mode shown as <mode>.

    The system defaults to the 'Loop' mode.

['C] Exit to CP/M.

    Clears the screen and produces the prompt:

        'Request exit, are you sure?'

    Press 'Y' to exit to CP/M, otherwise the front-panel will be
    reprinted. Note that all addresses and data will be lost.

[F] Record timebase <time>

    This function allows the adjustment of the timebase used for the
    recording  of samples into  the memory array. On record, each sample
    is taken spaced apart by a time equal to the value shown as <time>.

    Selection of this function by pressing 'F' causes the prompt:

    'Enter '+' to advance, '-' to retard, else exit'

    Use of the '+' or '-' key causes the list of available time steps to
    advance or retard respectively will the current setting shown as
    <time>. When the required setting has been obtained, press any other
    key (eg space) to exit.

Start address: <address>

    This function displays the recording data  start address. The
    address is the memory address from which the record of sample data
    will commence when the record function is called, and is for
    information only. It cannot be altered

    The address is shown in 4-digit hexadecimal.

Recording size: <size>

    This shows the size (in 4-digit hexadecimal) of the last recording
    that was made. It is for information only and cannot be changed.

Max store length: <size>

    The value shown in <size> is the maximum length in 4-digit
    hexadecimal form of the available free memory for recording. It is
    for information only.

    Recording will automatically be aborted if the recording size equals
    this value.

[J] Arm for recording.

    Pressing the 'J' key causes the screen to show a real-time
    'oscilloscope' plot of the value read from the A/D converter.
    Adjusting the offset or scale control, or the analogue input
    vopltage will cause the plot to move vertically on the screen whilst
    it moves with time horizontally.

    When the plot is complete on the screen it is erased and a new plot
    commences.

    The prompt 'press space to commence recording' is provided to
    initialte the actual recording process of reading samples into
    memory at a rate as set by the tmiebase. This a manual trigger only.

[K] Toggle background.

    Pressing the 'K' key causes the screen to toggle between inverse or
    normal video. The default mode is normal video, but for work on
    various plots the inverse mode can increase clarity. There is no
    change to the printer plot when inverse video is selected.

    Note: Due to a bug in CP/M, it is necessary to execute the command
    'palette 0 1' before running word for this function to work. (You
    could include this instruction in a file 'profile.sub' which copies
    'word' onto drive m: for convenience.)

Appendix I - Waveform Data File Format.

    Waveform data files are 'simple' sequential files in that each
waveform data value is stored as an integer from 0-255 inclusive. The
file may be of any length and this length value is stored in the first
two bytes of the file. To summarise:

    File format:    Byte #0:MSB of length value 0-255,
                    Byte #1                       LSB of length value 0-255,
                    Byte #3-n                     Waveform data 0-255 inc.

    Each file is assigned the extension '.WAV'.
    Note that although the file is a simple sequential file and may be
processed as if it were text, some utilities respond to 'cntrl-Z' (1A)
as an end-of-file character. In this case the file will be truncated.
BASIC responds to sequential files in this way during input and it is
necessary to read such waveform files as sequentially read random files
to avoid this problem. An example of this can be found in 'GEN.BAS' the
waveform generation program. Other utilities such as PIP, DUMP etc do
not present this problem.

Appendix II - Preparing a data disk.

    WORD.COM can conveniently be transferred to drive M: and the A:
drive used for data files. However, WORD's use of GSX graphics requires
the folowing drives to reamain on drive A:

    GSX.SYS
    ASSIGN.SYS
    DDSCREEN.PRL.

    Omitting any of these will produce a GSX error.