Help for TOIBIS

PURPOSE
The TOIBIS program converts a file with an arbitrary line count, sample 
count, and format into an IBIS graphics or interface file.

TAE COMMAND LINE FORMAT
                       [ { 'BYTE } ]  [ {'GRAPHICS [NDIM=n] } ]
    toibis INP=a OUT=b [ { 'HALF } ]  [ {                   } ]
                       [ { 'FULL } ]  [ {'INTERFACE [NCOL=n]} ]
                       [ { 'REAL } ]

where
    INP		    The file with some line count, sample count, and data
		    format  (string).
    OUT		    The IBIS graphics or interface file produced  (string).
    IFORM	    A switch indicating how the INP file's data format should
		    be interpreted; default is to use data format as specified
		    in file's label. The following switches ignore the label:
	'BYTE	    Read INP file's data as if it were one-byte integers
	'HALF	    Read INP file's data as if it were two-byte integers
	'FULL	    Read INP file's data as if it were four-byte integers
	'REAL	    Read INP file's data as if it were four-byte reals
    OFORM	    A switch indicating the type of IBIS file desired; default
		    is to create an INTERFACE file.
	'GRAPHICS   IBIS graphics file
	'INTERFACE  IBIS interface file
    NDIM	    Dimension of file's coordinate sets if OFORM=GRAPHICS;
		    not used otherwise
    NCOL	    Number of columns in file if OFORM=INTERFACE; not used 
		    otherwise

    []  signifies an option (e.g., argument "NDIM=n" is optional)
    {}  signifies a mutually exclusive choice (e.g., if one of the
	format switches is used, only one of the set {BYTE, HALF, FULL,
	REAL} may be chosen)

EXECUTION
The input file is a stream of numbers in binary (as opposed to ASCII) format;
TOIBIS provides the means for breaking the stream up into a stream of rows
of data or of coordinate sets. For example, given the stream 
    a, b, c, d, e, f, g, h, i, j, k, l

in file "a", one can create a set of 2D coordinates in file "b" with TOIBIS:
   toibis a b 'GRAPHICS
    result: (a,b), (c,d), (e,f), (g,h), (i,j), (k,l)

or one can create a set of 3D coordinates:
    toibis a b 'GRAPHICS NDIM=3
    result: (a,b,c), (d,e,f), (g,h,i), (j,k,l)

or one can create rows of 3 columns:
    toibis a b 'INTERFACE NCOL=3
    result:    a    b    c
               d    e    f
               g    h    i
               j    k    l

or one can create rows of 6 columns:
    toibis a b 'INTERFACE NCOL=6
    result:    a    b    c    d    e    f
               g    h    i    j    k    l

The line and sample counts are only used to determine the total length of
the stream of values.

In some cases, the label of the input file will claim that the data format
is BYTE, but the bits forming the data should really be interpreted as
reals for them to make sense. It is for these cases that the IFORM switch
is provided. IFORM causes TOIBIS to ignore the data format label and to 
read the data as if the label matched the specified switch. If the switch
matches the label, then the switch could be left out.


RESTRICTIONS
 1. The graphics file has a maximum dimension of 40.
 2. The interface file has a maximum dimension of 40.
 3. The number of pixels used to represent data in the input file must be
    1, 2, or 4 if using the switches 'BYTE, 'HALF, 'FULL, or 'REAL.
 4. The number of samples in the original file is limited by
     a. If not using format switch: maximum number of samples is 10000.
     b. If using format switch:
	    ns * pix_size/new_pix_size  <=  10000
	where
	    ns		is the count of samples as written in the input
			file header.
	    pix_size	is the number of bytes used to represent one
			element of the input file (e.g., HALF format
			has pix_size=2, and FULL format has pix_size=4).
	    new_pix_size
			is the number of bytes used to represent one
			element of the output file.
NOTE:(FR87138)
Currently (1995) when the IBIS-2 Graphics subroutine software (IBISGR.COM)
creates a IBIS graphics file, the default format is IBIS-1 graphics.  This
allows compatability with unported IBIS programs as well as interchange of
files between various machines.  Eventually the default format of the
graphics files will become IBIS-2


HISTORY:
           6 MAR 1995 Made portable for UNIX  CRS  (CRI)
          25 AUG 1995 Added note to PDF as per FR87138

PARAMETERS: