DATAMANIP (ksegops) functions


LIBRARY ROUTINE

lkimportasc - import ASCII data into specified segment of data object

LIBRARY CALL

int 
lkimportasc(
   char   *ascii_file,
   kobject source_obj,
   char   *segment_name,
   int     dimension,
   char   *index_order,
   int    *size_vector,
   char   *data_type_string,
   int     start_offset,
   int     skip_factor,
   int     num_reads,
   kobject destination_obj)

INPUT

OUTPUT

RETURN VALUE

TRUE (1) on success, FALSE (0) otherwise

DESCRIPTION

This routine will import an ASCII data file, ascii_file, and insert it into a data object, source_obj, if it is specified. If there is no source object to insert the new segment into, pass NULL for source_obj and the data object specified by the parameter destination_obj, will be created. The segment specified by segment_name will be inserted into this data object. If a source_obj was specified, then all of its data segments and the global object attributes will be copied to the destination.

If the segment_name is one of the Polymorphic segments, the correct dimensionality must be provided :

.TS H
center tab(:) ;
lfB  lfB  
lf(CW) l .
Segment Name:Dimension
=
.TH
KDMS_SEGMENT_VALUE     :  5
KDMS_SEGMENT_MAP       :  5
KDMS_SEGMENT_MASK      :  5
KDMS_SEGMENT_LOCATION  :  4
KDMS_SEGMENT_TIME      :  1
.TE
There are four attributes of the new segment that must be passed in: dimension, index order, size and data type. The number of indices in the index order and the sizes specified must be equal to the dimension.

The parameter dimension must be greater than 0 and less than or equal to 5.

The parameter index_order is a string that contains the indices of the segment separated by spaces, "elements width height depth time" or "e w h d t". The only allowed values are :

.TS
center tab(:) ;
l l .
width (w)      :  mapwidth (mw)
height (h)     :  mapheight (mh)
depth (d)      :  mapdepth (md)
time (t)       :  maptime (mt)
elements (e)   :  mapelements (me)
dimension (n)  :
.TE
where the characters in the ()'s are accepted abbreviations.

The parameter, index_order, is used to specify the orientation of how data is stored and retrieved. For example, if the index_order is specified as "w h d t e", then data will be accessed along width first, followed by height, depth, time, and elements.

The parameter size_vector contains the size of the segment to create. All the values must be > 1.

The parameter data_type_string must contain one of the following strings to specify the data type of the segment:

.TS H
center tab(:) ;
lfB  lfB  lfB
l    l    lf(CW) .
Data Type:Abbreviation:Data Type
=
.TH
bit              :bi     : KBIT
byte             :by     : KBYTE
unsigned byte    :un by  : KUBYTE
ubyte            :uby    : KUBYTE
short            :sh     : KSHORT
unsigned short   :un sh  : KUSHORT
ushort           :ush    : KUSHORT
integer          :in     : KINT
unsigned integer :un in  : KUINT
uint             :ui     : KUINT
long             :lon    : KLONG
unsigned long    :un lon : KULONG
ulong            :ul     : KULONG
float            :fl     : KFLOAT
double           :do     : KDOUBLE
complex          :co     : KCOMPLEX
double complex   :do co  : KDCOMPLEX
dcomplex         :dc     : KDCOMPLEX
.TE
The parameter start_offset is the point in the ASCII source at which to start importing in the ASCII data. All points before this one are ignored. When start_offset is something other than zero, the offset will be with respect to the index order specified.

The parameter skip_factor is the number of points to skip in the ASCII data between reads.

The parameter num_reads specifies the number of data points to read before skipping. For example, if num_reads is 2 and skip factor is 3, two values will be read, three will be skipped, followed by two more reads, three skips, etc.

ADDITIONAL INFORMATION

none

EXAMPLES

Consider an ascii file which looks as follows:

 1 2 3 4
 1 2 3 4	
 1 2 3 4
 1 2 3 4
 1 2 3 4

Suppose you want create (x,y) data from column 1 and column 3 such that the output object will look as follows:

 1 3
 1 3
 1 3
 1 3
 1 3

with size "2x5x1x1x1" with index order "w h d t e". Also consider that the data will be stored in the value segment as integer data.

In this case, you would call "lkimportasc" as follows:

 char *ascii_file_string = "ascii_input_data";
 char *prog = "main";
 char *rtn = "my_program";
 char *segment_string = "value";
 char *data_type_string = "integer";
 char *index_order_string = "w h d t e";
 int  dimension_int = 5;
 int  size_vector_int[5];
 int  offset_int = 0;
 int  skip_int = 1;
 int  n_reads_int = 1;

size_vector_int[0] = 2; size_vector_int[1] = 5; size_vector_int[2] = 1; size_vector_int[3] = 1; size_vector_int[4] = 1;

if (!lkimportasc(ascii_file_string, segment_string, dimension_int, index_order_string, size_vector_int, data_type_string, offset_int, skip_int, n_reads_int, NULL)) { kexit(KEXIT_FAILURE); }

Suppose you want import the above ascii data as a single column of data and specifically the second column. In this case the data will be imported to the value segment as size "1x5x1x1x1", with data type integer, and index order "w h d t e". In this case, the output data will look as follows:

 2
 2
 2
 2
 2

In this case, it is necessary to specify a start_offset of 1, a skip_factor of 3, and num_reads should be 1. The following call of lkimportasc accomplishes this:

 int offset_int = 1;
 int skip_factor = 3;
 int n_reads_int = 1;

if (!lkimportasc(ascii_file_string, segment_string, dimension_int, index_order_string, size_vector_int, data_type_string, offset_int, skip_int, n_reads_int, NULL)) { kexit(KEXIT_FAILURE); }

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

$DATAMANIP/objects/library/ksegops/src/lkimportasc.c

SEE ALSO

ksegops(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.