Content
*******
Purpose of the command line compiler library
Features of the library
Files in this archive
Command line syntax
Description of the provided 16bit-Assembler functions (model COMPACT)
Programming in 16-Bit-Assembler
Disclaimer
Contacting the author



Purpose of the command line compiler library
********************************************

This library is intended for the facility of writing applications
which configurations shall depend on parameters on the command line
at program start. It prevents the programmer from inventing
recurrending algorithms again and again but keeps him free to use the
library functions in many ways.
Unlike the simple high level language parameter conversion by string,
this library performs a syntax check, sorts parameters by usability
and filters switches, strings, numbers, boolean values and drive
statements. Moreover it only takes about 800 bytes in code.
The full version is available in 16- and 32-bit-modes for C, Delphi
and Pascal.
Complex but comprehensible commandlines like this one from an
imaginable archive program can be handled easily:

"pack a -r test.pak /x=*.bak,*.log,*.gid /overwrite+
 /numberoffiles=100 -fastcompress:yes /tempdrive=d:"

However,  horrifying and disgusting parameters, taken  from  a  known
repulsive  C-compiler  program  which  obviously  gives  away   awful
programming techniques, should be history:

"Usage: e:/bin/prog.exe [-[abcDhilLsTvwxyz]]
 [-[ACeEfFJnNOpPqQZ][name]] [-I dirs]"



Features of the library
***********************

- Provides three functions for a complete analysis of complex
  commandlines
- All options are case-insensitive and can be designed very
  legible for users who have to work with the program
  (therefore not intended for UNX/LNX-programmers)

- Completely written in 80486-Assembler taking about 800 bytes
  code and at most 2 Kbyte memory
- Handles up to 126 different options (switches)
- Requires at least a 80486 processor

Features of the trial version:
- Available for 16-Bit-Assembler only, model COMPACT
- 24 byte intermediate memory buffer for compiled data
  (see "Description of the 16bit Assembler functions")

Additional features of the full version:
- Available for all Intel platforms in 16- and 32-bit-modes
  (not 16Bit protected mode)
- Interfaces available for Assembler, C, Delphi/Pascal
  or from a compiled WIN32-DLL-file
- 512 Byte intermediate memory buffer for compiled data

Files in this archive
*********************
README.TXT                     This Documentation
                               The 16-bit-library (16Bit,
CMDLIN16.LIB                   model COMPACT, OMF-Format)
CMDLINE.INC                    Assembler header include file
                               (16Bit, model COMPACT)
CMDLDEMO.EXE                   Interpreter demonstration
                               program
CMDLDEMO.ASM                   Interpreter demonstration
                               source


Command line syntax
*******************

General rules:
To get correct results for strings starting with figures (such as
"0001.gif") or genuine strings (such as "PassWordXyz" instead of
"PASSWORDXYZ") they must be put between quotation marks '"' or "'".
It is up to the programmer to handle misspelled options which will be
represented as uppercase strings (e.g. the user entered "/op=yes"
instead of "/opt=yes": an uppercase string "/OP=YES" will be
returned).

Rules for non-user parameters:
Any numbers, drives and boolean values will be converted.
Any chars between quotation marks will be taken as strings.
Any commas will be converted to NUL-strings.
All other parameters will be converted to uppercase strings.

Rules for user options:
Any user option must be introduced with a dash or a slash.
Any user option without a parameter will be interpreted as a boolean
value TRUE.
To commit a parameter to a user option, it must be terminated by a
colon or an equals sign immediatly followed by a parameter. If a
blank follows instead, the option will not be recognized and
interpreted as a string parameter.
To commit additional parameters they must be separated by a comma
each. Blanks are optional.

Special boolean operators:
Expressions for TRUE:    "+", "ON", "YES", "JA", "EIN"
Expressions for FALSE:   "-", "OFF", "NO", "NEIN", "AUS"

Boolean syntax:
("OPT" is assumed to be an example user option)
/opt+ /opt:+ /opt=yes -opt    for TRUE-statement
/opt- -opt=- /opt:no          for FALSE-statement

Syntax examples which will achieve the same  results:
/opt=file1.dat,1,d:,123
-opt:file1.dat -opt=1 /opt:d: -opt=123

Syntax example which will return wrong results:
/opt= file1.dat,1,d:,123 Space after "=" produces
                    completely different results
                    than expected
/oppt=file1.dat,1,d:,123 Unknown option "oppt" results
                    in the string "/OPPT=FILE1.DAT"

Examples:
/files="Long File-Name.DAT", shrtname.dat,*.zip
-cache:yes,8192,4096
-login="UseR","PassWorD" /server=\\quack\sys: /domain:gamerez

For further examinations use the program CMDLDEMO.EXE.


Description of the provided 16bit-Assembler functions (model COMPACT)
*********************************************************************
                                  
                              Functions
                                  
CMDLINE              Interprets a string and puts compiled values
                     into a temporary buffer. CMDLINE or PSPCMDLINE
                     must be invoked before any other function can
                     be used.
                     
                     Input:         DS:SI=String (may not include a
                                    leading program name)
                     Output:        CS:PARAMCNT=Number of recognized
                                    parameters
                                    
PSPCMDLINE           Like CMDLINE; but gets the string from DOS-
                     program-segment-prefix (PSP). CMDLINE or
                     PSPCMDLINE must be invoked before any other
                     function can be used. Uses DOS INT 21h-62h
                     Input:         -
                     Output:        Same as CMDLINE
                                    
PARAPOS              Gets a parameter by position number
                     Input:         AL=Position (1..CS:PARAMCNT)
                     Output:        CARRY=1:Error, AH=0FFh
                                    CARRY=0:OK, registers valid
                                    AH=0:Non-User-parameter
                                    AH=(1..7Fh):User option defined
                                     from OPTIONTAB to OPTEND
                                    AL=Type of parameter;
                                     AL=TSTR:String in DS:SI (read
                                        only, zero terminated)
                                     AL=TNUM:Number in EBX, unsigned 32bit
                                     AL=TBOL:Boolean in BL (1=TRUE,
                                        0=FALSE)
                                     AL=TDRV:Drive in BL (0=A:,1=B:...)
                                    DL=Position of the returned
                                     parameter in the commandline
                                    
PARATYP              Gets a parameter by its type
                     Input:         AH<80h:Request a Non-User-parameter
                                    AH>80h:Request a user option;
                                     AH=81h for user option #1,
                                     AH=82h for user option #2...
                                    AL=Number of requested type parameter
                                     (not the number of position!)
                     Output:        Same as PARAPOS
                                  
                             Variables
                                  


OPTIONTAB            Near offset,   Marks the begin of the user
                     variable to    defined option string table
                     define in
                     CODE- segment
                                    
OPTEND               Near offset,   Marks the end of the user
                     variable to    defined option string table. If
                     define in      no strings are required,
                     CODE- segment  OPTIONTAB and OPTEND must be
                                    defined nevertheless and point
                                    to the same location in code
                                    segment
                                    
PARAMCNT             Byte,          Indicates the number of
                     Variable,      recognized parameters
                     defined in
                     code segment
                                    


WARNING FOR USERS OF THE TRIAL VERSION: Due to the limitation of the
intermediate buffer the length of the commandline string and the
number of parameters are restricted. Analyzing of longer command line
strings MAY CRASH YOUR PROGRAM at worst or CAUSE AN UNPREDICTABLE
BEHAVIOUR.
To calculate the maximum allowable length of a command line refer to
these facts:

Each compiled string consumes [length(string)+3] Bytes
Each compiled number consumes 6 Bytes
Each compiled boolean/drive statement consumes 3 Bytes

For example, the commandline

pack.exe  a -o+ arc.pak /ratio=80
          4 +3  +10     +6

would consume 23 Bytes (not included the program name, see chapter
"Command line syntax").


Programming in 16-Bit-Assembler
*******************************

The command line string to be analyzed must exclude a beginning
program name:

path\prog.exe para1 /opt1=para para2
              ^
              Begin of the command line string

After the conversation the whole command line string is converted to
uppercase (except quoted strings).

The user-option-strings have to be defined somewhere in the ASM-
source:

.code               ;strings must be in code segment
OPTIONTAB label byte
          db'USEROPT1',0 ;assigned to user option #1
          db'USEROPTA',0 ;assigned to user option #2
          db'USEROPTX',0 ;assigned to user option #3
OPTEND    label byte

Note: All strings must be uppercase and zero-terminated. At most 126
different entries are possible. No NUL-strings are allowed.
If a user-option-string table is given, the functions CMDLINE and
PSPCMDLINE convert these strings, which are preceded by a slash or a
dash on the commandline, to user options and assign them a number
according to their appearance in the string table between OPTIONTAB
and OPTEND.
Abbreviations are not supported. If you wish to use any, you could
assign more strings which increases the programming expense however.
For example, if you want the user to choose between a long form for
comprehensation and a short form for convenience, you could extend
the string table like this:

.code
OPTIONTAB label byte
          db'USEROPT1',0 ;assigned to user option #1
          db'U1',0       ;assigned to user option #2
          db'USEROPTA',0 ;assigned to user option #3
          db'UA',0       ;assigned to user option #4
          db'USEROPTX',0 ;assigned to user option #5
          db'UX',0       ;assigned to user option #6
OPTEND    label byte

But you have to plan the program in advance and have to manage the
assigned numbers by yourself. A good idea is to use macros to handle
the numbers.


Template commandline (referred to first OPTIONTAB):
CMDLDEMO.EXE -userOPT1- /userOPT2 /USERoptA=50,1 -useroptX:d:

PARAPOS and PARATYP will return these statements (also experiment
with CMDLDEMO.EXE):

-Parameter given at position 1
 type: user option #1, boolean, false
-Parameter given at position 2
 type: string="/USEROPT2"
-Parameter given at position 3
 type: user option #2, number, value:50(dez)
-Parameter given at position 4
 type: user option #2, number, value: 1(dez)
-Parameter given at position 5
 type: user option #3, drive letter, drive #3

Note: All not recognized parameters will be converted to uppercase
strings.


Example 1
To ask if the user properly entered two numbers for the option
"USEROPTA" (option #2 in the OPTIONTAB-stringtable):

          mov ah,80h+2   ;request user option #2
          mov al,1       ;request first value
loop1:    push ax        ;AX will be destroyed
          call paratyp   ;(DS:SI could be destroyed now
                    ; in case of a string occurence)
          jc error       ;param not available o.sth.
          cmp ah,2       ;is it our option #2?
          jnz error      ;no, error
          cmp al,tnum    ;is it a number?
          jnz error      ;no, error
          ;...here is the number in EBX
          pop ax
          inc al         ;request next value
          cmp al,2
          jna loop1

Example 2
To test if the second parameter is a string:

          mov al,2       ;request for parameter #2
          call parapos
          jc error       ;parameter not available
          or ah,ah       ;is it a non-user parameter?
          jnz error      ;no
          cmp al,tstr    ;is it a string?
          jnz error      ;no
          ;DS:SI now points to the reqd. string

Example 3
To ask if a the user entered a second string:

          mov ah,tstr    ;request for a string param.
          mov al,2       ;request for 2nd occurence
          call paratyp
          jc error       ;no matching param. found
          or ah,ah       ;is it a non-user-param?
          jnz error      ;no
          cmp al,tstr    ;is it a string?
          jnz error      ;no
          ;DS:SI points to the reqd. string
          ;DL indicates the parameter position in the cmdline


Disclaimer
**********

This trial version is free for non-commercial use. If you wish to use
it  in commercial products or if you want to receive the full version
for a fee, please contact the author.
The  author  is not responsible for any damages or data losses  which
could be caused by this software. Use it at your own risk.
Modifications of the library or the documentation are not permitted.


Contacting the author
*********************

For further suggestions, bug reports, problems, comments or how to
receive the full version the author can be contacted via email:

heinzel111(at)hotmail.com


Martin Vogler, in January 2001
