Help for ACOPIN

PURPOSE

    ACOPIN converts an ascii file (that is organized in columns)
    into corresponding columns of an IBIS table file.

    ACOPIN requires that the ascii data be imported into a
    preexisting ibis file. Therefore, acopin is almost always
    preceeded by an ibis-gen command.

OPERATION

    The ASCII columns can be either numeric or ascii. Formats
    are controlled by the IBIS file column format. However,
    acopin only operates on ascii and DOUB data so on input 
    automatic numeric conversions of BYTE, HALF, FULL, REAL, 
    or COMP to DOUB will take place. ASCII text will be 
    imported into whatever the original format (A1-A255) that
    is in the preexisting IBIS file.

    NOTE: If the ASCII text contains embedded blanks, there
    will be problems since it is assumed that the column
    separator is one or more "blank" characters. 

    So 123 in the ascii file can become a numeric (DOUB) or
    or "123" alphabetic in the IBIS table.  Conversion errors,
    such as a letter in a numeric field (except for e, d, or E
    or D, as exponents) will abort the program.

    Only one execution of acopin is required to input both
    numeric and alphabetic data.

PARAMETERS

    Two input files are required, an ascii column table and
    a preformatted IBIS table.

    COLS are values given in integer format and  place the
    data into the IBIS file columns in the same order as the 
    data in the ascii file. The columns can be named using 
    the parameter COLS, or if COLS is omitted, all of the 
    columns will be used in order.
     
    Columns that are not listed in the COLS format will be 
    will be filled with zero's (Numeric) or blanks (ASCII).
     
    The last record of the ascii column file can end with 
    a newline, or can be abruptly ended at the last input field.

    Normally, the a column that is to be imported as an ASCII
    text column is left-justified. The keyword parameter, 
    RTJUST allows this convention to be reversed.

    It is also common for ascii column files to have one or
    more header records describing the table and/or its
    contents. The number in the parameter LEAD_RM allows you
    prevent these header records from being imported.
     
    Internally, the ascii column data is read into a giant buffer 
    and then written out to columns of the IBIS file.
    Conversions to DOUB and ascii are performed according to the
    type (Case 0 is ASCII) and Case 8 is Numeric) for the IBIS column.


TAE COMMAND LINE FORMAT

     acopin INP=(A,B) COLS=(c1,c2,...,cn) OPTIONS
     
     where

     A           is an ascii file of data in columns
     B		 is an update IBIS file, containing no data
     COLS        are the IBIS file columns (integers) that
                 receive the data in the same order as the
                 data in the ascii file.  
     OPTIONS     parameters for right justification of alphabetic
                 data and removal of header lines.
   

TIMING

     Should be able to read millions if IBIS records in less than
     five minutes.
     
RESTRICTIONS

   The maximum number of records is limited by IBIS table
   size (currently about 10 million?).  Internal to the program,
   dynamic memory allocation is used.  The number of columns
   is limited to 100.  The total virtual memory size (number of 
   columns times number of records times bytes per element)
   cannot exceed virtual memory size.

    The number of columns is limited to 20 in DOUB format.
    If you try to inport more than 20 columns you get
    the error message:

    acopin version 17-jun-00
    Partial record at end
    ** ABEND called **

    This occurs if you put in more than 20 cols in the cols
    parameter or if you try to import only 20 cols in the cols
    parameter and there are more than 20 columns in the ascii
    file.

    Thus, if you have to import more than 20 columns you must
    divide the ascii columnar file into 20 column parcels.
    Import each of the 20-column parcels into an IBIS file.
    At the end join each of the IBIS 20-column files using
    the IBIS program icat with the 'h keyword.

    Columns in the ascii column file that are to be imported
    into an ASCII formatted column must not contain embedded
    blanks, since a blank or multiple blanks, signify a
    column separator.


    If the last column is an ascii text column, there must be
    an entry and not just a blank field. If the first few
    records have an ascii string and then one record is missing
    it, then you will get an error message of the form:

    Number of input cols = 6
        Col 6 is ASCII width = 41
        ??E character = Cloud in numeric col 0  record 258
        ??E Are there blanks in ASCII field?
    ??E Case 8 (DOUBLE): Non-numeric data in a numeric field
     ** ABEND called **

    What is actually happening here is that this is the first record
    beyond the missing last ascii column and it is trying to interpret
    your text as a number.

    Example:
    256  23.0 40.0 15.6 Cloud
    257  10.0 38.1 14.2                 <---missing ascii text
    258  14.2 33.7 19.6 Cloud 

Note: 1-28-2010

If you have a non-existent IBIS file, it does not report File not found.
Instead it crashes with the following:

[TAE-PRCSTRM] Abnormal process termination; process status code = 10.

This is an error in the IBISFileOpen routine that has to be fixed.


WRITTEN BY:            A. L. Zobrist, 29 may 2000

COGNIZANT PROGRAMMER:  R. J. Bambery

REVSIONS:
        A. L. Zobrist, 14 Nov 2001 - starting version
        R. J. Bambery, 9 Sep 2007 - Documentation of limitations;
        R. J. Bambery, 21 Sep 2007 - Updated documentation and error
                            messages in code; 
        W. Bunch, 3 Jan 2008 - Modifications to fix ANSI Std C 
                            warnings on Linux, added to svn 
        R. J. Bambery, 26 Feb 2008 - Integrated Walt Bunch's changes
                            with my changes 
        R. J. Bambery, 28 Jul 2008 - Made compatible with Linux afids 5b
        R. J. Bambery, 03 Dec 2009 - Made compatible with new 64-bit afids
                            (removed cartoVicarProtos.h) (Makefile.acopin)
        R. J. Bambery, 28 Jan 2010 - Made compatible with 64-bit afids Build 793
                            Linux, MacOSX (both Intel/PowerPC)
                            removed 99 character limit on inp 
                            both the preexisting program and this modification still give   
                            [TAE-PRCSTRM] Abnormal process termination; process status code = 10.
                            when no ibis file exists.
        R. J. Bambery, 08 Feb 2010 - fixed call to IBISFileClose(ibis,NULL);
        R. J. Bambery, 23 Jul 2010 - Improved error detection and messaging after
                            problems with files which gave 
                            [TAE-PRCSTRM] Abnormal process termination; process status code = 11.
        R. J. Bambery, 13 Aug 2010 - Improved error detection for failure to report missing ASCII files
                            gives [TAE-PRCSTRM] Abnormal process termination; process status code = 11.

        R. J. Bambery, 29 Apr 2011 - Fixed prototype declaration warning with gcc44 compiler
        R. J. Bambery, 19 Jun 2011 - Fixed "warning: array subscript is below array bounds" and
                            other warnings with gcc4.4.4                           
	W. Bunch, 5 Dec 2014 - Added imake and fiddled includes to build in mipl.

PARAMETERS: