ascii_read

Reads freely-formatted ASCII files.

Synopsis

#include <imsls.h>

int imsls_ascii_read (char *filename, …, 0)

Required Arguments

char *filename (Input)
A string containing the pathname and filename of the file containing the data.

NOTE: In addition to filename, at least one data type, array length, and array name triplet optional argument is required. A Terminal error will be issued when the triplet is missing. See Optional Arguments for more information.

Return Value

The return value is the status of the read operation. The return value is set to 0 for success and 1 for failure.

Synopsis with Optional Arguments

#include <imsls.h>

int *imsls_ascii_read (char *filename,

IMSLS_SHORT, long *n_vals, short **var,

IMSLS_SHORT_USER, long *n_vals, short var[],

IMSLS_INT, long *n_vals, int **var,

IMSLS_INT_USER, long *n_vals, int var[],

IMSLS_LONG, long *n_vals, long **var,

IMSLS_LONG_USER, long *n_vals, long var[],

IMSLS_FLOAT, long *n_vals, float **var,

IMSLS_FLOAT_USER, long *n_vals, float var[],

IMSLS_DOUBLE, long *n_vals, double **var,

IMSLS_DOUBLE_USER, long *n_vals, double var[],

IMSLS_CHAR, long *n_vals, char ***var,

IMSLS_CHAR_USER, long *n_vals, char var[][],

IMSLS_DATETIME, long *n_vals, struct tm**var,

IMSLS_DATETIME_USER, long *n_vals, struct tmvar[],

IMSLS_TIME_VAL, long *n_vals, Imsls_time_val **var,

IMSLS_TIME_VAL_USER, long *n_vals, Imsls_time_val var[],

IMSLS_COLUMNS, or

IMSLS_ROWS,

IMSLS_DELIM, int n_delimiters, char delimiters[],

IMSLS_DATETIME_FORMAT, int n_formats, int datetime_format[],

IMSLS_FILTERS, int n_filters, char filters[],

IMSLS_COLUMN_INDEX, int n_columns, int columns[],

IMSLS_IGNORE, int n_ignore, char *ignore[],

IMSLS_IGNORE_BAD_DATETIME,

IMSLS_REPLACEMENT_NUMBERS, int n_repl_nums, char *miss_vals[], float repl_nums[],

IMSLS_REPLACEMENT_STRINGS, int n_repl_strs, char *miss_vals[],char *repl_strs[],

IMSLS_NRECS, int n_recs,

IMSLS_NSKIP, int n_skip,

IMSLS_VALS_PER_REC, int vals_per_rec,

IMSLS_NO_BINARY_CHECK,

IMSLS_ALLOW_CHARS, int n_allow, char allow_chars[],

Optional Arguments

IMSLS_SHORT, long *n_vals, short **var (Output)

IMSLS_INT, long *n_vals, int **var (Output)

IMSLS_LONG, long *n_vals, long **var (Output)

IMSLS_FLOAT, long *n_vals, float **var (Output)

IMSLS_DOUBLE, long *n_vals, double **var (Output)

IMSLS_CHAR, long *n_vals, char ***var (Output)

IMSLS_DATETIME, long *n_vals, struct tm **var (Output)

IMSLS_TIME_VAL, long *n_vals, Imsls_time_val **var (Output)

The above optional argument triplets are used to read data from an ASCII file. Each optional argument is a comma‑separated list of data type, array length, and array name describing the output variable to read from filename. At least one triplet is required. In each of the above cases, n_vals is output only and is the number of elements read.

NOTE: As many as 1024 variables can be read from an input data file. Optional arguments may be repeated to read the same type of data from multiple columns.

IMSLS_SHORT_USER, long *n_vals, short var[] (Output)

IMSLS_INT_USER, long *n_val, int var[] (Output)

IMSLS_LONG_USER, long *n_vals, long var[] (Output)

IMSLS_FLOAT_USER, long *n_vals, float var[] (Output)

IMSLS_DOUBLE_USER, long *n_vals, double var[] (Output)

IMSLS_CHAR_USER, long *n_vals, char var[][] (Output)

IMSLS_DATETIME_USER, long *n_vals, struct tm var[] (Output)

IMSLS_TIME_VAL_USER, long *n_vals, Imsls_time_val var[] (Output)
The above optional argument triplets allow users to provide storage for variables to be read from an ASCII file. In each of the above cases, n_vals is the length of var on input and is the number of elements read on output.

IMSLS_COLUMNS, (Input)

IMSLS_ROWS, (Input)
Specifies the file format organization. IMSLS_COLUMNS indicates that the data is column‑oriented (processing of the file is done reading down columns in the file). IMSLS_ROWS indicates that the data is row‑oriented (processing of the file is done reading left to right).

Default: It is assumed that the data is column‑oriented.

IMSLS_DELIM, int n_delimiters, char delimiters[] (Input)
An array of length n_delimiters containing single-character field delimiters used to delineate columns or rows in the data file. If character fields contain delimiter characters, the string will be interpreted as more than one string, and the data in the file will not match the variable list. Use the decimal value 9 or “\t” to identify the TAB character.

Default: A comma ‑ or space‑ delimited file is assumed.

IMSLS_DATETIME_FORMAT, int n_formats, int datetime_format[] (Input)
An array of length n_formats containing the date and time formats to be used for interpreting date or time data within the file. A single value is used for each datetime_format variable. Based on the data within the file, positive datetime_format numbers refer to date formats; negative datetime_format numbers refer to time formats. For a table of valid date and time formats see the discussion in the Description and Example 5.

Default: It is assumed that the data is in neither date nor time format.

IMSLS_FILTERS, int n_filters, char filters[] (Input)
An array of length n_filters containing the one-character strings that imsls_ascii_read should check and filter out as it reads the data. Any character found on the keyboard can be used. For example, to filter characters “,” and “;” specify

int n_filters = 2;

char filters[] = {',', ';'};

A special character not found on the keyboard is specified by ASCII code.

Default: Nothing is filtered out.

IMSLS_COLUMN_INDEX, int n_columns, int columns[] (Input)
An array of length n_columns containing integers indicating column numbers to read from the file. IMSLS_COLUMN_INDEX defines an array of column numbers (starting with the first column as column 1) that corresponds with data type variable name pairs supplied in the optional argument. For example, if an array, columns=[5, 1, 3], is supplied with the list of variables a1, a2, a3, then the values in the IMSLS_COLUMN_INDEX array are automatically sorted before reading the columns, resulting in a1 = column #1, a2 = column #3, a3 = column #5.

Default: All columns are read.

IMSLS_IGNORE, int n_ignore, char *ignore[] (Input)
An array of length n_ignore containing strings to be ignored. If any of these strings are encountered, imsls_ascii_read skips the entire line and starts reading data from the next line. Any character is allowed. For example, to skip lines containing either of the character strings “abc” or “def” specify

int n_ignore = 2;

char *ignore[] = {"abc", "def"};

Adding the special string $BAD_DATE_TIME in the ignore array has the effect of skipping lines where invalid date/time data is found.

Default: Nothing is ignored.

IMSLS_IGNORE_BAD_DATETIME, (Input)
Skip lines where invalid date/time data is found.

Default: Do not ignore invalid date/time data.

IMSLS_REPLACEMENT_NUMBERS, int n_repl_nums, char *miss_vals[], float repl_nums[] (Input)
n_repl_nums is the length of arrays miss_vals and repl_nums. miss_vals contains strings representing missing data in the file. Each value in the repl_nums array corresponds to a string in the miss_vals array. As the input data file is read, occurrences of values that match those in miss_vals are replaced by the corresponding element of repl_nums for numerical output. If the output variable is of type IMSLS_CHAR, repl_nums is ignored. See Example 3.

Default: Nothing is replaced.

IMSLS_REPLACEMENT_STRINGS, int n_repl_strs, char *miss_vals[], char *repl_strs[] (Input)
n_repl_strs is the length of arrays miss_vals and repl_strs. miss_vals contains strings representing missing data in the file. Each of the strings in repl_strs corresponds to a string in the miss_vals array. As the input data file is read, occurrences of strings that match those in miss_vals are replaced by the corresponding string in repl_strs for IMSLS_CHAR output. If the output variable is not of type IMSLS_CHAR, repl_strs is ignored. See Example 8.

Default: Nothing is replaced.

NOTE: IMSLS_REPLACEMENT_NUMBERS and IMSLS_REPLACEMENT_STRINGS may be used simultaneously when reading data written into output variables of mixed types such as IMSLS_CHAR and IMSLS_INT.

IMSLS_NRECS, int n_recs (Input)
Number of records to read for row or column oriented data. If n_recs is not provided or is set to zero (0), the entire file is read. For more information about records, see the Physical Records versus Logical Records topic in Description.

Default: n_recs = 0.

IMSLS_NSKIP, int n_skip (Input)
Number of physical records in the file to skip before data is read. If n_skip is not provided or is set to zero (0), no records are skipped.

Default: n_skip = 0.

IMSLS_VALS_PER_REC, int vals_per_rec (Input)
An integer that specifies how many values comprise a single record in the input data file. If not provided, each line of data in the file is treated as a new record. See Example 4.

Default: vals_per_rec = 0.

IMSLS_NO_BINARY_CHECK (Input)
ASCII decimal or hex values 0 to 127 are allowed. If binary characters above the 127 decimal value are found, the file is considered binary and reading is terminated. If IMSLS_NO_BINARY_CHECK is specified, the check for binary characters is omitted.

Default: A check for binary characters is performed.

IMSLS_ALLOW_CHARS, int n_allow, char allow_chars[] (Input)
allow_chars is an array of length n_allow, containing the octal representation of ASCII values outside of the 0 to 127 decimal range preceded with a backwards slash. Characters specified in allow_chars are treated as ASCII characters instead of binary characters. For example, to allow imsls_ascii_read to accept characters 130 and 150 (octal values 202 and 226), set the allow_chars array as follows:

char allow_chars[2] = {"\202\226"};

Default: Binary characters are not allowed.

Description

Function imsls_ascii_read is adept at reading both row‑oriented and column‑oriented data files. The steps that imsls_ascii_read performs when reading a file include:

Open the file.

Assign the file a file descriptor.

Compose a format string that describes the organization of the data.

Close the file when reading of the data has been completed.

imsls_ascii_read needs to know which delimiters to expect in the file; comma and space are the default delimiters. imsls_ascii_read easily reads data values separated by any combination of commas and spaces or any other delimiters one explicitly defines using IMSLS_DELIM.

If neither IMSLS_ROWS nor IMSLS_COLUMNS is provided, the file is assumed to be organized by columns.

Physical Records versus Logical Records

In an ASCII text file, the end-of-line is signified by the presence of either a CTRL-J (linefeed) or a CTRL‑M (return) character, and a record extends from one end-of-line character to the next. However, there are actually two kinds of records; physical records and logical records.

For column‑oriented files, the amount of data in a physical record is often sufficient to provide exactly one value for each element in the data array, and then it is a logical record, as well. For row-oriented files, the concept of logical records is not relevant, since data is read as contiguous values separated by delimiters, and the end‑of‑line is interpreted as another delimiter.

NOTE: IMSLS_NRECS counts by logical records, if IMSLS_VALS_PER_REC has been defined. IMSLS_NSKIP, on the other hand, counts by physical records, regardless of any logical record size that has been defined.

Changing the Logical Record Size

IMSLS_VALS_PER_REC can be used to explicitly define a different logical record size; In most cases, this optional argument does not need to be provided. For an example of how to use IMSLS_VALS_PER_REC, see Example 4.

NOTE: By default, imsls_ascii_read considers the physical record to be one line in the file, and the concept of a logical record is not needed. When using logical records, the physical records in the file must all contain the same number of values. IMSLS_VALS_PER_REC can be specified only with column-oriented data files.

Filtering and Substitution While Reading Data

IMSLS_FILTERS can be used to filter certain characters from the data as it is read. Each character (or sequence of digits that represents the ASCII code for a character) must be enclosed with single quotes. For example, either of the following is a valid specification:

‘,’ or ‘44’

Furthermore, the two specifications shown above are equivalent to one another. For an example of using filters, see Example 4.

NOTE: Do not filter characters that are used as delimiters. The delimiters enable imsls_ascii_read to discern where one data value ends and another one begins.

Characters that match one of the values in filters are treated as if they are not present; in other words, these characters are not treated as data and do not contribute to the size of the logical record, if one has been defined using IMSLS_VALS_PER_REC.

NOTE: IMSLS_IGNORE can be used to supply multi-character strings instead of individual characters. However, a character that matches filters is simply discarded, and filtering resumes from that point, while a string that matches ignore causes that entire line to be skipped.

When reading a data file that contains a value such as #$*10.00**, and it is preferred that the entire line be skipped, filter the characters individually with filters = [‘#’,’$’,’*’] instead of collectively with ignore = [‘#$*’,’**’].

Delimiters in the Input File

Values in the file can be separated by commas, spaces, and any other delimiter characters specified with IMSLS_DELIM. Characters not specified with IMSLS_DELIM are treated as data and type conversion is attempted. If type conversion is not possible, imsls_ascii_read results in a terminal error.

NOTE: Date and time data, such as months, days, hours, and minutes, may only contain the separation characters slash ( / ), colon (:), hyphen (-), and comma (,). These four characters may not be used as delimiters for data containing dates and times.

Reading Row‑Oriented Files

When reading row‑oriented data (IMSLS_ROWS) provide only a single data triplet. The file is read using the delimiter (or the default delimiters if IMSLS_DELIM is omitted) to return an array of length n, where n is the number of values in the file. Providing IMSLS_NRECS allows the control of how many rows (lines) in the file are transferred into the returned array.

Using IMSLS_ROWS and a single data triplet is an easy way to read the entire content of the file and the result is a single array of data that contains all valid data found within the file.

Reading Column‑Oriented Files

When IMSLS_COLUMNS is used, imsls_ascii_read views the data file as a series of columns with a one-to-one correspondence between columns in the file and variables. For example, for a file containing three columns of data values and with three output arrays defined as var1, var2, and var3; the values from the first record of the file will be transferred to var1[0], var2[0], and var3[0]. The three values from the second record of the file will be transferred to var1[1], var2[1], and var3[1], and so forth, until all of the data in the file has been read. The exception is if IMSLS_NRECS is provided in which case transfer of data stops when imsls_ascii_read reaches the number of records to be read.

The length of the individual output arrays is specified by n_vals.

Date and Time Formats

IMSLS_DATETIME_FORMAT is used to describe the format of the input string data by specifying a format to use as the data is read. These formats are:

Table 1 – Date/Time Formats
datetime_format[i]	Date Format	Time Format
–1	NA	HHMnMnSS[.SSSS]
–2	NA	HHMnMn
1	MMDDYY[YY]	NA
2	DDMMYY[YY]	NA
3	ddd*YY[YY]	NA
4	DDmmm[mmmmmm]YY[YY]	NA
5	[YY]YYMMDD	NA
6	MMDDYY[YY]	HHMnMnSS[.SSSS]
7	MMDDYY[YY]	HHMnMn
8	DDMMYY[YY]	HHMnMnSS[.SSSS]
9	DDMMYY[YY]	HHMnMn
10	ddd*YY[YY]	HHMnMnSS[.SSSS]
11	ddd*YY[YY]	HHMnMn
12	DDmmm[mmmmmm]YY[YY]	HHMnMnSS[.SSSS]
13	DDmmm[mmmmmm]YY[YY]	HHMnMn
14	[YY]YYMMDD	HHMnMnSS[.SSSS]
15	[YY]YYMMDD	HHMnMn

The abbreviations used in the format descriptions in the Date and Time Formats table are:

Abbreviations	Description
MM	The numerical month. The month does not need to occupy two spaces. For example, you can enter a 1 for the month of January.
DD	The numerical day of the month. The day does not need to occupy two spaces. For example, for May 5, the numerical day can be 5.
[YY]YY	The numerical year. For example, 1992 can be entered as 92 or 1992.
Ddd	The numerical day of the year. The day does not need to occupy three spaces. For example, February 1 is 32.
mmm[mmmmmm]	The full name of the month or its three character abbreviation.
*	Represents a delimiter that separates the different fields of datetime_format data. The valid datetime_format delimiters can be a slash (/), a colon (:), a hyphen (–), period (.), or a comma (,).
HH	The numerical hour based on a 24-hour clock. For example, 14 is 2 o’clock in the afternoon. For the –1 format, both spaces do not need to be occupied. However, the −2 format requires that both spaces be occupied. For example, 1:00 in the morning must be entered as 01.
Mn	The number of minutes in the hour. For the –1 format, both spaces do not need to be occupied. However, the –2 format requires that both spaces be occupied. For example, 6 minutes must be entered as 06.
SS[.SSS]	The number of seconds in the minute. A decimal part of a second is optional.

imsls_ascii_read supports two time value structures. The standard struct tm C type is obtained with optional argument IMSLS_DATETIME. A time structure that includes a Julian value is accessible with optional argument IMSLS_TIME_VAL. A description of IMSLS_TIME_VAL follows.

Imsls_time_val

imsls_ascii_read uses the structure Imsls_time_val, provided in the standard header <imsls.h>, to represent an Imsls_time_val variable and is declared as follows:

struct Imsls_time_val {

short year;

unsigned char month;

unsigned char day;

unsigned char hour;

unsigned char minute;

float second ;

double julian_dt;

unsigned char recalc;

};

Examples

Example 1

The data file shown below is a freely-formatted ASCII file named monotonic.dat:

1 2 3 4 5

6 7 8 9 10

11 12 13 14 15

16 17 18 19 20

To read the entire contents of the file into a single array, the simplest approach is:

#include <imsls.h>

int main()

{

int status;

float *var;

long n_vals;

status = imsls_ascii_read("monotonic.dat",

IMSLS_FLOAT, &n_vals, &var,

IMSLS_ROWS,

0);

imsls_f_write_matrix("var", 1, (int) n_vals, var, 0);

}

Output

var

1 2 3 4 5 6

7 8 9 10 11 12

13 14 15 16 17 18

19 20

Example 2

Using the same data file (monotonic.dat), our goal in this example is to read only the second and fourth column of data from the file. This time we use the default column-organized format. The code is:

#include <imsls.h>

int main()

{

int i, status, getcols[2] = {2, 4};

int *var1, *var2;

long n_vals1, n_vals2;

status = imsls_ascii_read("monotonic.dat",

IMSLS_INT, &n_vals1, &var1,

IMSLS_INT, &n_vals2, &var2,

IMSLS_COLUMN_INDEX, 2, getcols,

0);

imsls_i_write_matrix("var1", 1, (int) n_vals1, var1, 0);

imsls_i_write_matrix("var2", 1, (int) n_vals2, var2, 0);

}

Output

var1

1 2 3 4

2 7 12 17

var2

1 2 3 4

4 9 14 19

Example 3

The data file shown below is a freely-formatted ASCII file named intake.dat:

151-182-BADX-214-515

316-197-BADY-199-206

This example replaces “BADX” and “BADY” with float type numbers ‑9999.0 and 9999.0, respectively.

#include <imsls.h>

#include <stdio.h>

int main()

{

int status, i;

long n_vals, *var;

char *miss_vals[] = {"BADX", "BADY"}, delimiters[] = "-";

float repl_nums[] = {-9999.0, 9999.0};

status = imsls_ascii_read("intake.dat",

IMSLS_LONG, &n_vals, &var,

IMSLS_REPLACEMENT_NUMBERS, 2, miss_vals, repl_nums,

IMSLS_ROWS,

IMSLS_DELIM, 1, delimiters,

0);

for (i = 0; i < n_vals; i++)

printf("var[%d] = %ld\n", i, var[i]);

}

Output

var[0] = 151

var[1] = 182

var[2] = -9999

var[3] = 214

var[4] = 515

var[5] = 316

var[6] = 197

var[7] = 9999

var[8] = 199

var[9] = 206

Example 4

The data file shown below is a freely-formatted ASCII file named level.dat. This data file uses the semicolon (;) and the slash (/) as delimiters, and the comma (,) to separate the thousands digit from the hundreds digit. This file has three logical records on every line; at the end of each logical record is a slash:

5,992;17,121/8,348;17,562/5,672;19,451/

5,459;18,659/7,088;17,052/8,541;13,437/

6,362;15,894/8,992;17,509/7,785;14,796/

Optional argument IMSLS_FILTERS is provided to filter the commas out of the data.

#include <imsls.h>

#include <stdio.h>

int main()

{

int status, i;

long n_vals1, n_vals2, *gap, *bar;

char delimiters[] = ";/", filter[] = {','};

status = imsls_ascii_read("level.dat",

IMSLS_LONG, &n_vals1, &gap,

IMSLS_LONG, &n_vals2, &bar,

IMSLS_COLUMNS,

IMSLS_DELIM, 2, delimiters,

IMSLS_FILTERS, 1, filter,

IMSLS_VALS_PER_REC, 2,

0);

for (i = 0; i < n_vals1; i++)

printf("gap[%d] = %ld\n", i, gap[i]);

printf("\n");

for (i = 0; i < n_vals2; i++)

printf("bar[%d] = %ld\n", i, bar[i]);

}

Output

gap[0] = 5992

gap[1] = 8348

gap[2] = 5672

gap[3] = 5459

gap[4] = 7088

gap[5] = 8541

gap[6] = 6362

gap[7] = 8992

gap[8] = 7785

bar[0] = 17121

bar[1] = 17562

bar[2] = 19451

bar[3] = 18659

bar[4] = 17052

bar[5] = 13437

bar[6] = 15894

bar[7] = 17509

bar[8] = 14796

Example 5

Assume that you have a file, events.dat, that contains some data values and also some chronological information about when those data values were recorded:

01/01/92 5:45:12 10 01-01-92 3276

02/01/92 10:10:10 15.89 06-15-91 99

05/15/91 2:02:02 14.2 12-25-92 876

The date/time formats used to transfer this data have the following definitions:

•

Format Number = 6— MM*DD*YY (* = any delimiter) HH*MM*SS (* = any delimiter)

•

Format Number = 1— MM*DD*YY (* = any delimiter)

To read the date and time from the first and third column into Imsls_ time_val variable and read the fourth column of floating point data into another variable:

#include <imsls.h>

#include <stdio.h>

int main()

{

int status, j, datetimeformat[1] = {6};

long n_vals1, n_vals2;

float *var;

char delimiters[] = " ";

Imsls_time_val *date;

status = imsls_ascii_read("events.dat",

IMSLS_TIME_VAL, &n_vals1, &date,

IMSLS_FLOAT, &n_vals2, &var,

IMSLS_DATETIME_FORMAT, 1, datetimeformat,

IMSLS_DELIM, 1, delimiters,

0);

imsls_f_write_matrix("var", 1, (int) n_vals2, var, 0);

printf("\n");

for (j=0; j<n_vals1; j++){

printf("var[%d] year: %d\n", j, date[j].year);

printf("date[%d].month: %d\n", j, date[j].month);

printf("date[%d].day: %d\n", j, date[j].day);

printf("date[%d]a.hour: %d\n", j, date[j].hour);

printf("date[%d].minute: %d\n", j, date[j].minute);

printf("date[%d].second: %f\n\n", j, date[j].second);

}

Output

var

1 2 3

10.00 15.89 14.20

var[0] year: 1992

date[0].month: 1

date[0].day: 1

date[0]a.hour: 5

date[0].minute: 45

date[0].second: 12.000000

var[1] year: 1992

date[1].month: 2

date[1].day: 1

date[1]a.hour: 10

date[1].minute: 10

date[1].second: 10.000000

var[2] year: 1991

date[2].month: 5

date[2].day: 15

date[2]a.hour: 2

date[2].minute: 2

date[2].second: 2.000000

Example 6

To read the first, third, and fourth columns of events.dat, define an integer array and a second Imsls_time_val variable, and change the call to imsls_ascii_read as shown below.

Notice there are two different date/time formats for column 1 and column 3 in the events.dat file. For column 1, format 6 is used to read the date data into date1. For column 3, format 1 is used to read date data into date2. In the case where the date/time format is the same for all columns, provide only one date/time format to be reused by all columns.

#include <imsls.h>

#include <stdio.h>

int main()

{

int status, j, *calib, datetimeformat[2] = {6, 1},

getcolumns[4] = {1, 3, 4};

long n_vals1, n_vals2, n_vals3;

char delimiters[] = " ";

char* ignore[] = {"$BAD_DATE_TIME"};

Imsls_time_val *date1, *date2;

status = imsls_ascii_read("events.dat",

IMSLS_TIME_VAL, &n_vals1, &date1,

IMSLS_TIME_VAL, &n_vals2, &date2,

IMSLS_INT, &n_vals3, &calib,

IMSLS_DELIM, 1, delimiters,

IMSLS_COLUMN_INDEX, 3, getcolumns,

IMSLS_DATETIME_FORMAT, 2, datetimeformat,

0);

for (j=0; j<n_vals1; j++){

printf("date1[%d] year: %d\n", j, date1[j].year);

printf("date1[%d].month: %d\n", j, date1[j].month);

printf("date1[%d].day: %d\n", j, date1[j].day);

printf("date1[%d].hour: %d\n", j, date1[j].hour);

printf("date1[%d].minute: %d\n", j, date1[j].minute);

printf("date1[%d].second: %f\n\n", j, date1[j].second);

}

for (j=0; j<n_vals2; j++){

printf("date2[%d] year: %d\n", j, date2[j].year);

printf("date2[%d].month: %d\n", j, date2[j].month);

printf("date2[%d].day: %d\n", j, date2[j].day);

printf("date2[%d].hour: %d\n", j, date2[j].hour);

printf("date2[%d].minute: %d\n", j, date2[j].minute);

printf("date2[%d].second: %f\n\n", j, date2[j].second);

}

imsls_i_write_matrix("calib", 1, (int) n_vals3, calib, 0);

}

Output

date1[0] year: 1992

date1[0].month: 1

date1[0].day: 1

date1[0].hour: 5

date1[0].minute: 45

date1[0].second: 12.000000

date1[1] year: 1992

date1[1].month: 2

date1[1].day: 1

date1[1].hour: 10

date1[1].minute: 10

date1[1].second: 10.000000

date1[2] year: 1991

date1[2].month: 5

date1[2].day: 15

date1[2].hour: 2

date1[2].minute: 2

date1[2].second: 2.000000

date2[0] year: 1992

date2[0].month: 1

date2[0].day: 1

date2[0].hour: 0

date2[0].minute: 0

date2[0].second: 0.000000

date2[1] year: 1991

date2[1].month: 6

date2[1].day: 15

date2[1].hour: 0

date2[1].minute: 0

date2[1].second: 0.000000

date2[2] year: 1992

date2[2].month: 12

date2[2].day: 25

date2[2].hour: 0

date2[2].minute: 0

date2[2].second: 0.000000

calib

1 2 3

3276 99 876

Example 7

The following data file is a freely‑formatted ASCII file named num.dat in which a value is missing:

0,1,,3,4

5,6,7,8,9

The missing value is replaced with 99.0.

#include <imsls.h>

int main()

{

int status, *var, getcol[1] = {3};

long n_vals;

char *miss_str[] = {""};

float repl_nums[] = {99.0};

status = imsls_ascii_read("num.dat",

IMSLS_INT, &n_vals, &var,

IMSLS_COLUMN_INDEX, 1, getcol,

IMSLS_REPLACEMENT_NUMBERS, 1, miss_str, repl_nums,

0);

imsls_i_write_matrix("var", 1, (int) n_vals, var, 0);

}

Output

var

1 2

99 7

Example 8

The data file shown below is a freely-formatted ASCII file named char.dat:

a,b,c,d

e,BAD,g,h

The string GOOD is substituted for the missing value represented as BAD.

#include <imsls.h>

#include <stdio.h>

int main()

{

int status, i, getcol[1] = {2};

long n_vals;

char *miss_val[] = {"BAD"}, *rep_str[] = {"GOOD"}, **var;

status = imsls_ascii_read("char.dat",

IMSLS_CHAR, &n_vals, &var,

IMSLS_COLUMN_INDEX, 1, getcol,

IMSLS_REPLACEMENT_STRINGS, 1, miss_val, rep_str,

0);

for(i=0; i<n_vals; i++)

printf("var[%d] = %s\n", i, var[i]);

}

Output

var[0] = b

var[1] = GOOD

Example 9

The data file shown below is a freely-formatted ASCII file named chemicals.dat:

Elemental Carbon

Sulfate

Benzo[e]pyrene

Indeno[1,2,3-cd]pyrene

n-Heptadecanoic acid

Note that the first and fourth lines contain a space and commas respectively. Since the default delimiters are comma and space, in order to read the first and fourth lines of the data as single entities, a delimiter which does not occur as a character in the data file must be specified using IMSLS_DELIM. For this example, we know that there are no TAB characters, so TAB is specified as the delimiter (ASCII byte value 9 specified as a hex value). However, another single character could be specified, such as ‘$’ or ‘Q’.

#include <imsls.h>

#include <stdio.h>

int main()

{

int status,i;

long n_vals;

char **var, delimiters[] = {"\x9"};

status = imsls_ascii_read("chemicals.dat",

IMSLS_CHAR, &n_vals, &var,

IMSLS_ROWS,

IMSLS_DELIM, 1, delimiters,

0);

for (i=0; i<n_vals; i++)

printf("var[%d] = %s\n", i, var[i]);

}

Output

var[0] = Elemental Carbon

var[1] = Sulfate

var[2] = Benzo[e]pyrene

var[3] = Indeno[1,2,3-cd]pyrene

var[4] = n-Heptadecanoic acid

Warning Errors

IMSLS_M_INVALID_BINARY_CHAR

A binary character may have been detected.