The labeled table (LT) file format has been developed as a hub for various data file transfers. Originally, the LT files were not cataloged; therefore, the user was required to specify the LT filename in terms of the host computer filenaming convention. This was done because labeled table format was used mainly as a temporary file. It is now used as a format for other files including the GCTP parameter file, and therefore, it will now be cataloged within the LAS system -- Version 5.0 and subsequent versions.
A program can access the LT routines by linking in the following object library:
$LASLIB/world.a
The LT consists of one or multiple files (maximum of twenty). If
there are multiple files, the first record of the master LT file
contains a list of the subfiles associated with it. By convention,
subfilenames are generated by appending an ascending numeric value to
the master LT filename.Since all data in the LT is stored as ASCII, the LT is transportable among computer systems and the user is allowed to edit the LT files with a text editor. The following data types may be stored in an LT:
1. Character data
2. 8-bit integer
3. 16-bit integer
4. 32-bit integer
5. 32-bit real
6. 64-bit real
7. Date
8. Time
The user should note that precision may be lost by converting a real
number into an ASCII string.The LT is a selfdefining file in which the first three records define the file, and the remaining records are the actual data records. The first record contains a list of LT subfilenames that are associated with the current LT file. The second record contains the LT file type and description. The third record (called the label vector) defines the actual data in the LT. The LT uses special characters to define records and fields within an LT record. Special characters may be embedded in a character string as long as the character string is delimited by quotes.
Special Character Description
Double quotes Character string delimiter
Comma LT record field separator
New line LT record field separator
Semicolon LT record separator
Each component of the label vector contains the following five record
fields:
1. Attribute name
2. Attribute data type
3. Attribute description
4. Number of rows in matrix
5. Number of columns in matrix
If an attribute is a scalar value, it is stored as a 1 x 1 matrix.
Character data cannot be matrix data. For character data, the number
of rows should be set to 1 and the number of columns should be set to
the maximum character string length. The matrix size specified in
the label vector is required to be assigned the maximum matrix size.
A smaller matrix will be written to the upperleft corner and filled
with null values.The following is an example of an LT generated from a GOF containing polygon data (line numbers are for documentation purposes):
1 "poly.dat1";
2 "REGATT","File generated from #SCITEST.PHOENIX";
3 "REGNUM","I4","unique region number",1,1
4 "LABEL","C","user defined label",1,16
5 "CLASS","C","",1,13
6 "SITE","C","",1,13;
7 1,"agri 1","AGR","LOMAX";
8 2,"urban 1","URBAN","DOWNTWN";
9 ;<
10 "REGXY","File generated from #SCITEST.PHOENIX";
11 "REGNUM","I4","unique region number",1,1
12 "X","I4","column number",1,1
13 "Y","I4","row number",1,1;
14 1,2184,704;
15 1,2232,848;
16 1,2240,768;
17 2,400,720;
18 2,368,848;
19 2,432,856;
20 2,480,792;
Description of each line number:
1 First record of the master LT file poly.dat.
2 A record containing two fields. The first field defines
the LT file type to be REGATT (attribute file for polygon
data). The second field is a short description indicating
that this LT was created from #SCITEST.PHOENIX.
3 Start of the label vector record. It defines an attribute
named REGNUM to be a 32-bit scalar integer value.
4 Part of the label vector record. It defines an attribute
named LABEL to be a character text string with a maximum length
of 16 characters.
5 Part of the label vector record. It defines an attribute
named CLASS to be a character text string with a maximum length
of 13 characters.
6 End of the label vector record. It defines an attribute
named SITE to be a character text string with a maximum length
of 13 characters.
7 First data record containing a record field for each attribute
defined in the label vector. The value of each attribute is:
REGNUM = 1
LABEL = agri 1
CLASS = AGR
SITE = LOMAX
8 Second data record containing a record field for each
attribute defined in the label vector. The value of each
attribute is:
REGNUM = 2
LABEL = urban 1
CLASS = URBAN
SITE = DOWNTWN
9 First record of LT subfile poly.dat1 subfiles.
10 A record containing two fields. The first field defines
the LT file type to be REGXY (data file for polygon data).
The second field is a short description indicating that
this LT was created from #SCITEST.PHOENIX.
11 Start of the label vector record. It defines an attribute
named REGNUM to be a 32-bit scalar integer value.
12 Part of the label vector record. It defines an attribute
named X to be a 32-bit scalar integer value.
13 End of the label vector record. It defines an attribute
named Y to be a 32-bit scalar integer value.
14 Through 20 are data records of the polygon points. Each
record consists of three fields: region number, X point,
and the Y point.
The following functions are utility routines to manipulate a labeled table (LT). The utility routines allow the application program to read or write an ASCII character string or a numeric matrix. The utility routines ensure that the LT has the correct format.
The C callable routines include:
close_tab(): Close the LT
get_field_ptr(): Return pointer to LT record field
get_lt_date(): Get date field
get_lt_time(): Get time field
get_matrix(): Get an I*1, I*2, I*4, R*4, or R*8 matrix
get_record(): Read a record from the LT
get_vector(): Read the label vector and set up record structure
make_lt_name(): Make an associated LT filename
open_tab(): Open the LT
put_lt_date(): Put date field
put_lt_time(): Put time field
put_matrix(): Put an I*1, I*2, I*4, R*4, or R*8 matrix
put_record(): Write a record to the LT
put_vector(): Write the label vector and set up record structure
The sequence of calls to read a LT would be as follows:
call open_tab to open the LT with read access
call get_vector to read label vector and set up record pointers
do for each row in the LT
call get_record to read record from the LT
do for each column in the LT
if data type is character then
access the character string
else if data type is date then
call get_lt_date
else if data type is time then
call get_lt_time
else if data type is numeric
call get_matrix to get I*1, I*2, I*4, R*4, or R*8 matrix
end do
end do
call close_tab to close the LT
The sequence of calls to write a LT would be as follows:
call open_tab to open the LT with write access
do for each column to be defined in the LT
call put_vector to write label vector and set up record pointers
end do
do for each row in the LT
do for each column in the LT
if data type is character then
access the character string
else if data type is date then
call put_lt_date
else if data type is time then
call put_lt_time
else if data type is numeric then
call put_matrix to put I*1, I*2, I*4, R*4, or R*8 matrix
end do
call put_vector to write record to the LT
end do
call close_tab to close the LT
There is an include file named ltable.h which contains
variable definitions used in the LT utilities. The following tables
explain each variable definition.LT File Constants:
MAX_SUB Maximum number of associated LT files
MAX_FIELD_LEN Maximum number of characters in a record field
NDTYPE Total number of valid LT field data types
LT Logical Record Identifiers:
FIELD_SEP1 Field separator one (comma)
FIELD_SEP2 Field separator two (new line)
RECORD_SEP Record separator (semicolon)
CHAR_DEL Delimit character strings (double quotes)
LT Record Field Data Types:
C Character string (less than 1024 characters)
I1 8-bit integer
I2 16-bit integer
I4 32-bit integer
R4 32-bit real
R8 64-bit real
LTDATE Date field (mm/dd/yy)
LTTIME Time field (hr:min:sec)
Structure defining date field:
struct LT_DATE
{
long month
long day
long year
}
Structure defining time field:
struct LT_TIME
{
long hour
long minute
long second
}
Structure defining matrix size:
struct MATRIX
{
long nrow number of rows in matrix
long ncol number of columns in matrix
}
Structure defining record field:
struct VECTOR
{
char *label Label name for this field
long dtype Data type for this field
char *desc Label description for this field
union Variant record depending on dtype
{
char *c Record value for character data
char *i1 Record value for 8bit integer data
short *i2 Record value for 16bit integer data
long *i4 Record value for 32bit integer data
float *r4 Record value for 32bit real data
double *r8 Record value for 64bit real data
} ptr
struct MATRIX lt_size Matrix size written to the LT
struct MATRIX size Matrix size of actual data
long null Null fields detected on read
char sep Separator to be used on write
long flag Boolean to validate label vector
struct VECTOR *next Pointer to next record structure
}
Structure defining the LT:
struct TAB_DEF
{
char *hname; Host filename of the LT
char *subfile[MAX_SUB]; List of files associated to this LT
long nsubs; Number of files associated to this LT
long fd; File descriptors for LT file
long access; Access the LT file was opened for
char *ftype; File type of the LT
char *fdesc; File description of the LT
struct DESC buf; LT data I/O buffer
long ncol; Number of columns in the LT file
struct VECTOR *vector; LT record field structure
long nbytes; Number of bytes in data I/O buffer
long cur; Current byte offset in data I/O buffer
long label_flag Boolean indicating label vector exists
}
The LT utilities has a fatal error handling capability that can be
set by the application program. The programmer may allow the LT
utility routine to output an error message and abort or may set a
flag to output an error message and return to the calling routine.
The default is to have the LT utility routine to output an error
message and abort. There are two extern long variables defined to
implement the error handling:
Name Description
tabmode Defines whether the LT utility routine should
abort the program or if control is to be returned
to the calling routine on a fatal error condition.
The default is for the LT utility routine to
abort. Valid values are:
= 1 => Utility aborts the process
<> 1 => Utility returns to calling routine
tabstat Defines the status of the LT utility routine. If
tabmode is set to 1 (i.e., LT utility routine
aborts on fatal error conditions), the status may
be ignored. Valid values are:
= 1 => Utility completed successfully
< 0 => Utility encountered an error
This is a list of available Label Services Routines: