User's Guide

ASC2TAB

Converts an ASCII data file to a Labeled Table (LT)

Function:

Converts an ASCII data file to a Labeled Table (LT).

Parameters:

INFILE
Input file. The input file is a free-formatted ASCII file arranged in rows and columns.

OUTLT
Output labeled table. The name of the main labeled table file that is created as specified by the parameters LTTYPE, COMMENT, ATRNAME, ATRDESC, and IDTYPE. The names of the subfiles will be created from the value specified in OUTLT.

LTTYPE
Labeled table type. This is the type(s) of labeled table file(s) to be created. It is used as a check by other functions to verify that they can read the labeled table file(s). See the users guide of the function that this labeled table file will be input to for valid labeled table types. The number of values specified in LTTYPE and COMMENT must equal the maximum value specified in FILENUM.

COMMENT
Description of labeled table. This is the description(s) of the labeled table file(s) to be created. The number of values specified in LTTYPE and COMMENT must equal the maximum value specified in FILENUM.

ATRNAME
Attribute name. This is the attribute name(s) given to each of the field(s) in the labeled table file(s). The number of values specified in ATRNAME, ATRDESC, IDTYPE, FILENUM, and INCOL must be equal.

ATRDESC
Attribute description. This is the attribute description given to each of the fields in the output labeled table file(s). The number of values specified in ATRNAME, ATRDESC, IDTYPE, FILENUM, and INCOL must be equal.

IDTYPE
Input data type. This is the data type in which the values of each of the columns of the input file are read. The number of values specified in ATRNAME, ATRDESC, IDTYPE, FILENUM, and INCOL must be equal.


  = CHAR:  Character (8-bit signed integer)
  = BYTE:  INTEGER*1 (8-bit unsigned integer)
                     (0 through 255)
  = I*2:  INTEGER*2  (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:  INTEGER*4  (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:  REAL*4     (32-bit signed real)
                     (System dependent)
  = R*8:  REAL*8     (64-bit signed real)
                     (System dependent)

NCOLS
Number of columns. The total number of columns in the input file.

ODTYPE(--)
Output data type. This is the data type that each of the fields of the output labeled table will be. The default is to store each field as specified in IDTYPE. If ODTYPE is specified, the number of values specified in IDTYPE and ODTYPE must be equal.


  = CHAR:  Character (8-bit signed integer)
  = BYTE:  INTEGER*1 (8-bit unsigned integer)
                     (0 through 255)
  = I*2:  INTEGER*2  (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:  INTEGER*4  (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:  REAL*4     (32-bit signed real)
                     (System dependent)
  = R*8:  REAL*8     (64-bit signed real)
                     (System dependent)

INCOL(--)
Input columns. The columns in INFILE that will be read and written to the output labeled table. If null is specified, INCOL will have the sequential values of 1 up to NCOLS. If null is not specified, the number of values specified in ATRNAME, ATRDESC, IDTYPE, FILENUM, and INCOL must be equal.

FILENUM(1)
File number of output fields. This is the number of the output labeled table file in which the corresponding output field will be placed. The number of values specified in ATRNAME, ATRDESC, IDTYPE, FILENUM, and INCOL must be equal. The maximum value specified for FILENUM must be equal to the number of values specified for LTTYPE and COMMENT.

COLNUM(--)
Column number of shared data. This is the number of the column whose values will be in the main labeled table file as well as all of its subfiles. The main value will contain only one record for each distinct value of this column; therefore, the value of any other column which is to be written to the main file will be the value of the first row of each distinct value of COLNUM.

SROW(1)
Starting row. This is the row in the input ASCII file which will be the first record in the output labeled table file.

NROWS(--)
Number of rows. The total number of rows to be read from the input file. If null is specified, all the rows starting at SROW to the end of file will be read and written to the output labeled table.

Examples:

  1. LAS> asc2tab infile=in.dat outlt=out.dat lttype="coordinates" comment="input coordinates" atrname=("id","lat","lon") atrdesc=("identification number","latitude","longitude"), idtype=(i*4,r*8,r*8) ncols=5 incol=(1,3,5) filenum=(1,1,1) nrows=20

    The ASCII file IN.DAT which contains five columns of data is opened for read. The output file will have a type of COORDINATES and a description of INPUT COORDINATES. Column 1 of IN.DAT will be written to the first field of OUT.DAT and will have an attribute name of ID, a description of IDENTIFICATION NUMBER, and a data type of INTEGER*4. Column 3 of IN.DAT will be written to the second field of OUT.DAT and will have an attribute name of LAT, a description of LATITUDE, and a data type of REAL*8. Column 5 of IN.DAT will be written to the third field of OUT.DAT and will have an attribute name of LON, a description of LONGITUDE, and a data type of REAL*8. When 20 rows have been read and written to OUT.DAT, the files are closed and the completion message is displayed.

  2. LAS> asc2tab infile=in.dat outlt=out.dat lttype="coordintes" comment="input coordinates" atrname=("x","y") atrdesc=("xcoord","ycoord") idtype=(r*4,r*4) ncols=2 incol=-- filenum=(1,1) srow=10 nrows=--

    The ASCII file IN.DAT contains two columns of data. Both columns are read and written to OUT.DAT. OUT.DAT will have a type of COORDINATES and a description of INPUT COORDINATES. Column 1 of IN.DAT will be written to the first field of OUT.DAT and will have an attribute name of X, a description of XCOORD, and a data type of REAL*4. Column 2 of IN.DAT will be written to the second field of OUT.DAT and will have an attribute name of Y, a description of YCOORD, and a data type of REAL*4. When all the rows starting at row 10 have been read and written to OUT.DAT, the files are closed and the completion message is displayed.

  3. LAS> asc2tab infile=in.dat outlt=(out;dat) lttype=("regatt","regxy") comment=("region numbers","region x y coordinates") atrname=("regnum","x","y","label") atrdesc=("region number","x coordinate","y coordinate", "label of region") idtype=(i*4,r*4,r*4,char) ncols=6 incol=(2 4 5 6) filenum=(1,2,2,1) colnum = 2 srow=1 nrows=8

    The ASCII file IN.DAT contains six columns of data. Four columns are read from IN.DAT. OUT.DAT will have a type of REGATT and a description of REGION NUMBERS. OUT.DAT1 will have a type of REGXY and a description of REGION X Y COORDINATES. Because COLNUM is set to 2, column 2 of IN.DAT will be written to the first field of OUT.DAT and OUT.DAT1. This field will have an attribute name of REGNUM, a description of REGION NUMBER, and a data type of INTEGER*4. Column 4 of IN.DAT will be written to the second field of OUT.DAT1 and will have an attribute name of X, a description of X COORDINATE, and a data type of REAL*4. Column 5 of IN.DAT will be written to the third field of OUT.DAT1 and will have an attribute name of Y, a description of Y COORDINATE, and a data type of REAL*4. Column 6 of IN.DAT will be written to the second field of OUT.DAT and will have an attribute name of LABEL, a description of LABEL OF REGION, and a data type of CHARACTER. The second field of OUT.DAT will contain only those values which correspond with each distinct value of column 2. When 8 rows starting at row 1 have been read and written to OUT.DAT and OUT.DAT1, the files are closed and the completion message is displayed.

    	IN.DAT file
    	-----------
    	0 1 0 1 1 FIRST
    	0 1 0 100 1 FIRST
    	0 1 0 100 100 FIRST
    	0 1 0 1 100 FIRST
    	0 2 0 150 150 SECOND
    	0 2 0 200 150 SECOND
    	0 2 0 200 200 S
    	0 2 0 150 200 THIRD
    
            OUT.DAT file
    	------------
    	out.dat1;
    	"REGATT","REGION NUMBERS";
    	"REGNUM","I4","REGION NUMBER",1,1
    	"LABEL","C","LABEL OF REGION",1,1
    	1,"FIRST";
    	2,"SECOND";
    
    	OUT.DAT1 file
    	-------------
    	;
    	"REGXY","REGION X Y COORDINATES";
    	"REGNUM","I4","REGION NUMBER",1,1
    	"X","R4","X COORDINATE",1,1
    	"Y","R4","Y COORDINATE",1,1;
    	1,1,1;
    	1,100,1;
    	1,100,100;
    	1,1,100;
    	2,150,150;
    	2,200,150;
    	2,200,200;
    	2,150,200;
    

Description/Algorithm:

After reading and parsing the parameter values, the input ASCII file and output labeled table file(s) are opened for read and write, respectively. The LTTYPE, COMMENT, ATRNAME, ATRDESC, and IDTYPE are written to the header of the output file. The columns specified by INCOL are read in row by row as specified by IDTYPE and written to the output labeled table as specified by ODTYPE. After all the rows that were specified have been written to the output labeled table, the files are closed and the completion message is displayed.

Nonfatal Error Messages:

    None.

Fatal Error Messages:

  1. [asc2tab-equal] ATRNAME, ATRDESC, IDTYPE, FILENUM, and INCOL are not equal

    The number of values specified in the parameters ATRNAME, ATRDESC, INCOL, and IDTYPE are not equal. Respecify one or more of the parameters.

  2. [asc2tab-fatal] Fatal error encountered

    A fatal error was encountered during processing. The output file may or may not be valid. The message that is displayed immediately preceding this message is the specific error that was encountered.

  3. [asc2tab-open] Error opening <XXXXX> file

    An error was encountered while trying to open the specified file. Verify that the file exists.

  4. [asc2tab-read] Error encountered reading input file

    An error was encountered while trying to read the input file. Verify the format of the file.

  5. [asc2tab-value] Value too large for specified data type

    The value read from the input file is too large for the data type specified in the output file. Respecify the data type.

  6. [asc2tab-dtype] IDTYPE and ODTYPE are not equal

    The number of values specified in IDTYPE and ODTYPE are not equal. Respecify one of the parameters.

User Notes:

  1. A related function is TAB2ASC.