Program ASMPIC
                               2 April 2007

asmpic <source file> <opt1> ... <optN>

This program is a wrapper around the Microchip MPASMWIN assembler.  The
assembler always sets the program status code to zero, whether errors were
encountered or not.  It does, however, produce a .ERR file which is empty
if all went well and contains error messages when all did not go well.
This file is used to set the exit status of ASMPIC.

The first command line argument must be the name of the source file to
assemble.  The source file name must end in ".asm" if it is in native
Microchip PIC assembler format, or ".aspic" if it is in preprocessor
format.  In the latter case, the preprocessor is run to produce the .asm
file, which is then passed to the Microchip assembler.  The input file
name suffix may be omitted, in which case a .aspic file is used in
preference to a .asm file if both are present.

The /q switch is always passed to the assembler, and should not be passed
on the command line.  This causes the assembler to run in "batch" mode
without requiring user input.

The /e switch is always passed to the assembler, and should not be passed
on the command line.  This causes the assembler to create an error output
file if errors are encountered.  This program will not function correctly
if the error output file is disabled.  The error output file is the only
evidence the assembler provides as to whether assembly was successful or
not.  The return status from ASMPIC is derived from the error output file,
which is always deleted before ASMPIC returns.

The assembler will be run in the directory containing the source file.
This is also where output files will be put by default.  If errors are
found, they will be listed to standard output and the program exit status
will be set to ERROR.  If no errors are encountered, the program exit
status will be OK.  The .ERR file is deleted in any case.

The environment variable MPLABDir is assumed to be set to the directory
containing the Microchip executables.  If this variable is not present or
empty, then the Microchip executables are assumed to be in the executables
search path, in other words they can be run directly without having to
specify the full path name.

Note that the directory containing the Microchip executables has changed
from version 5 of MPLAB to version 6.  In MPLAB version 5 or earlier, the
MPLABDir environment variable had to be set to the MPLAB installation
directory pathname.  In version 6 it must be set to the pathname of the
MCHIP_Tools subdirectory within the MPLAB installation directory.

All the command line options after the source file name are passed to the
assembler up to but non including the -P command line option.  Options
after -P are passed to PREPIC if it is run.  If the input file is a MPASM
source file and not a preprocessor source file (.ASM suffix instead of
.ASPIC suffix), then any preprocessor command line options are ignored.

With MPASMWIN version 4.0, the useable command line options thru this
pogram are:

  /a <hex format>

       Set the HEX output file format.  HEX output files are only produced
       by the assembler in absolute mode.  In relocatable mode the linker
       produces the HEX file.  Choices of HEX file format are INHX8M,
       INHX8S, and INHX32.  The default is INHX8M.

  /c+
  /c-

       Enable (+) or disable (-) case sensitivity.  Case sensitivity is
       enabled by default.  Note that most of the symbols in the Microchip
       processor-specific include files are upper case.  This means they
       have to be entered in the source code in upper case when case
       sensitivity is enabled.

  /d<symbol>[=<value>]

       Define a symbolic constant.  This has the same effect as an EQU
       directive defining the same constant at the beginning of the file.

  /l+
  /l-
  /l <filename>

       Enable, disable, or set listing output file.  The default is to
       produce a listing file with the same generic pathname as the input
       file.

  /m+
  /m-

       Enable or disable macro expansion in the listing file.  Macro
       expansion is enabled by default.

  /o+
  /o-
  /o <filename>

       Enable, disable, or set object output file.  Enabling object file
       output also sets relocatable, as apposed to absolute, mode.  Object
       file output is disabled by default (absolute mode).

  /p<processor>

       Set processor type.  The processor types are the PIC model names,
       like "PIC16C54" for example.

  /r<radix>

       Set the default radix for numeric constants.  Choices are HEX, DEC,
       or OCT.  The default is HEX.

  /t<size>

       Set listing file tab column widths.

  /w<level>

       Set output messages level.  Choices of LEVEL are:

       0 - Show all messages.

       1 - Show only error and warning messages.

       2 - Show only error messages.

       The default is 0.

  /x+
  /x-
  /x <filename>

       Enable, disable, or set cross reference file.  Cross reference file
       output is disabled by default.

  -P opt ... opt

       The -P command line option indicates that subsequent options are
       passed to PREPIC, if run, as apposed to MPASMWIN.  -P and any
       options following it are ignored if PREPIC is not run.  The -P
       keyword is case-insensitive.  See the PREPIC documentation file for
       the list of command line options it supports.