===============================================================================
CRD2Elem - a MicroStation BASIC macro for general purpose coordinate input.

CRD2Elem generates elements from XYZ coordinate files.  It reads coordinate
files and sends the coordinate stream to MicroStation as data points.  The
macro can use the active command, place SmartLine, place B-spline, a
user-defined default or a user-entered command for element placement.

CRD2Elem works with 3-D and 2-D coordinate files with XY(Z) in any order.

CRD2Elem works in 3-D and 2-D design files.
- In 3D design files, the user has the option to override one of X, Y or Z, or
  replace a missing value with a constant.
- In 2D design files, if Z is present in the coordinate file it is ignored (the
  user can specify any of the three fields as Z).
 
 The XYZ delimiter can be user-defined.  The default is a space, " ".
 
Comments are supported in coordinate files.  The comment prefix can be
user-defined, and defaults to a single quote, " ' ".
 
Element separators are supported in coordinate files.  The element separator
record can be user-defined and defaults to a null or empty record.  Element
separators allow multiple elements to be drawn from the coordinate stream of a
single input file.  
 
MicroStation commands are supported in command files.  The command prefix can
be user-defined and defaults to "CMD:".  This allows commands to be embedded in
the coordinate stream.
 
The use can choose to send a final reset at the end of the coordinate stream or
leave the final command active.  The user can start or finish element placement
manually.
 
All options can be set to user-defined default values through configuration
variables, even to the point of bypassing the input dialog box completely.
 
 --------------
 
CRD2Elem can be used to take coordinate data from software applications or data
collection devices and generate MicroStation elements.  Think of CRD2Elem as a
add-on to the XYZ Text tool box found in the Annotation tool frame, except with
CRD2Elem, any reasonable MicroStation command is now supported (place
SmartLine, place curve, place block, etc.).
 
CRD2Elem is also sort of a scripting tool since it supports comments and
commands as well as coordinates.  The following are some benefits of CRD2Elem
over XYZ Text and Script files.
 
- There is a higher probability of being able to use the coordinate stream
  as-is without having to edit it, since the input format of CRD2Elem is quite
  flexible. 
 
- Multiple elements can be created from a single input file.
 
- Support of virtually any MicroStation command is provided.
 
- Ability to change commands mid-stream is provided. 

One of the most practical commands to embed in a coordinate file is to set the
active level, weight, style, and/or color.  This can be accomplished very
effectively using settings groups and the active settings command.  The
following line could be added to the coordinate stream at the beginning of each
group of coordinates that represent an individual element:

cmd:active settings <component_type> <group_name>:<component_name>

(Settings Manager and the appropriate settings file must be loaded.)

The macro code has been written in such a way as to allow new record types to
be included in the coordinate stream.  All that would be necessary is to edit
the input parsing function of the macro to trap the new record type, and add a
corresponding function to process the new record as desired.  Some examples
include adding data base attributes to the elements as they are drawn,
execution of non-key-in in operations like getting mouse input or sending a
data points and resets, or setting application variables (things that can't be
done easily through key-ins).  Modifications are not recommended unless
sustained productivity gains are to be expected.

Defaults and Command Line Switches
Most inputs can be specified as defaults by using configuration variables.
Defaults can also be controlled by command line switches.  Information about
the configuration variables and command line switches can be found in the About
CRD2Elem Dialog (Press the "About" button in the CRD2Elem dialog to open the
About CRD2Elem Dialog).  All configuration variables start with "c2e_".
Configuration variables and command line switches are not case sensitive.
Command line switches take precedence over configuration variables.