DC_WRITE_FREE Function

Writes the contents of one or more variables to a file in ASCII free format.

Usage

status = DC_WRITE_FREE(filename, var_list)

Input Parameters

filename — A string containing the pathname and filename of the file where the data will be stored.

var_list — The list of variables containing the values to be written. Note that variables of type structure are not supported. An exception to this is the !DT, or date/time, structure. It is possible to transfer date/time data using this routine.

Returned Value

status — The value returned by DC_WRITE_FREE; expected values are:

< 0 — Indicates an error, such as an invalid filename or an I/O error.
0 — Indicates a successful write.

Keywords

Column — A flag that signifies filename is to be written as a column-organized file.

Delim — A single-character string that will be placed between values in the output data file. If not provided, commas are used as delimiters in the file.

Double_exp — For double-precision and double-precision complex datatypes, writes the output using “e” (exponential) formatting rather than “g” (general) formatting. This allows more significant digits to be written.

Dt_Template — An array of integers indicating the data/time templates that are to be used for interpreting date/time data. Positive numbers refer to date templates; negative numbers refer to time templates. For more details, see Example 4. To see a complete list of date/time templates, see the PV‑WAVE Programmer’s Guide.

Miss_Str — An array of strings that are substituted in the output file (to represent missing data) for each value in Miss_Vals. If not provided, no strings are substituted for missing data.

Miss_Vals — An array of integer or floating-point values, each of which corresponds to a string in Miss_Str. As PV‑WAVE writes the data, it checks for values that match Miss_Vals; whenever it encounters one, it substitutes the corresponding value from Miss_Str.

Row — A flag that signifies filename is to be written as a row-organized file. If neither Row nor Column is present, Row is the default.

Discussion

DC_WRITE_FREE is very adept at storing data in a column-oriented manner. Also, DC_WRITE_FREE handles many steps that you have to do yourself when using other PV‑WAVE functions and procedures. These steps include: 1) opening the file, 2) assigning it a logical unit number (LUN), and 3) closing the file when you are done writing the data.

DC_WRITE_FREE relieves you of the task of composing a format string to describe the organization of the data in the output file. By default, DC_WRITE_FREE generates CSV (Comma Separated Values) files. However, you can override this default by using the Delim keyword to provide a different delimiter, if you wish.

If neither the Row or Column keywords are provided, the data is stored in rows. If both keywords are used, the Row keyword is assumed.

Note: This function can be used to write data from date/time structures, but not from any other kind of structures.

How the Data is Written to the File

As many as 2048 variables can be included in the output argument var_list. You can use the continuation character ($) to continue the function call onto additional lines, if needed. The entire contents of each variable in var_list is written to the specified file. If an error occurs, a nonzero status is returned.

Note: Any variable you include in var_list must have been previously created; otherwise, an error occurs.

The values in the output file are separated with the character specified with the Delim keyword. If no Delim keyword is provided, a comma delimiter is used by default.

As data is being transferred from multi-dimensional variables, those variables are treated as collections of scalar variables, meaning the first subscript of the export variable varies the fastest. For two-dimensional export variables, this implies that the column index varies faster than the row index. In other words, data transfer is row major; it occurs one row at a time. For more details about storing multi-dimensional variables in a column-oriented manner, see Writing Column-Oriented Data.

Once all variables in the variable list have been stored in the file, DC_WRITE_FREE stops writing data, and returns a status code of zero (0). Even if an error occurs, and status is nonzero, the data that has been written successfully (prior to the error) is left intact in the file.

Note: If an error does occur, view the contents of the file (using an operating system command) to see how much data was transferred. This will enable you to isolate the portion of the variable list in which the error occurred.

Formatting in the Output File

When writing row-organized files, output lines are formatted to be no more than 80 characters. When writing column-organized files, the output line length depends on the number, type, and dimensions of the variables in var_list.

The various data types are stored using the default formats shown in Data Type Storage:

Data Type Storage
Data Type	Output Formats used by DC_WRITE_FREE
BYTE	I4
INT	I8
INT32	I12
LONG	I12 on 32-bit systems l21 on 64-bit systems
FLOAT	G13.6
DOUBLE	G16.8
COMPLEX	(G13.6, G13.6)
DCOMPLEX	(G16.8, G16.8)
STRING	A (character data)

Note: When writing data of type string, each string is written to the file, flanked with a delimiter on each side. This implies that the strings should not contain delimiter characters if you intend to read the file later with the DC_READ_FREE function.

Writing Row-Oriented Data

If the Row keyword has been provided, each variable in var_list is written to the file in its entirety before any data is transferred from the next variable.

If you are interested in an illustration showing what row-oriented data can look like inside a file, see the PV‑WAVE Programmer’s Guide.

Writing Column-Oriented Files

Refer to the PV‑WAVE Programmer’s Guide for examples and information on writing column-oriented files.

For more information about how data from multi-dimensional export variables is stored in a columns in the output file, see Writing Column-Oriented Data.

If you are interested in an illustration demonstrating what column-oriented data can look like inside a file, see the PV‑WAVE Programmer’s Guide.

Example 1

If variable sara is a floating-point array with 10 elements all equal to 1.0, tana is a floating-point array with 5 elements all equal to 2.0, and cora is a floating-point array with 8 elements all equal to 3.0, the commands:

sara = FLTARR(10) + 1.0
tana = FLTARR(5) + 2.0
cora = FLTARR(8) + 3.0
status = DC_WRITE_FREE('outfile.dat', sara, tana, cora, /Row)

create outfile.dat containing the following values:

1,            1,            1,            1,            1
1,            1,            1,            1,            1
2,            2,            2,            2,            2
3,            3,            3,            3,            3
3,            3,            3

A comma is used by default to separate the values in the output file.

Example 2

If variable bogus is a 4-by-4 integer array with values 1 through 4 in the first column, values 5 through 8 in the second column, values 9 through 12 in the third column, and values 13 through 16 in the fourth column, the following commands:

bogus = TRANSPOSE(INDGEN(4, 4) + 1)
status = DC_WRITE_FREE('intfile.dat', bogus, Delim=',', /Column)

create a file intfile.dat, as shown below:

1,       5,       9,      13
2,       6,      10,      14
3,       7,      11,      15
4,       8,      12,      16

Notice that the organization of values in the output file mimics that of the variable, bogus.

On the other hand, the function call:

status = DC_WRITE_FREE('intfile.dat',  $
   bogus(1,*), /Row, Delim='*')

results in the following organization in intfile.dat, as shown below:

5*       6*       7*       8

Because of the array subscripting notation used in the function call, only the second column of data values is written to the file.

Example 3

Suppose you have three variables that contain data taken from an electronic sensor. The names of these variables are date, time, and phase_shift. date and time are strings, and phase_shift is a vector of complex (floating-point) values. The commands:

date = ['921002', '921002', '921002', '921002', '921002', '921002'] 
time = ['091200', '091205', '091210', '091215', '091220', '091225']
phase_shift = COMPLEXARR(6)
phase_shift(0) = COMPLEX(0.139528, 0.983407)
phase_shift(1) = COMPLEX(-0.149962, 0.407378)
phase_shift(2) = COMPLEX(1.002340, -0.039187)
phase_shift(3) = COMPLEX(1.130523, 0.983482)
phase_shift(4) = COMPLEX(-0.947966, 0.171492)
phase_shift(5) = COMPLEX(1.275390, 0.789446)
status = DC_WRITE_FREE('day539.dat', date, $
   time, phase_shift, Delim='/', /Column)

result in a file day539.dat that is organized as shown below:

921002/091200/(     0.139528,     0.983407)
921002/091205/(    -0.149962,     0.407378)
921002/091210/(      1.00234,    -0.039187)
921002/091215/(      1.13052,     0.983482)
921002/091220/(    -0.947966,     0.171492)
921002/091225/(      1.27539,     0.789446)

The complex numbers are stored as two floating-point values, separated with a comma and enclosed in parentheses.

Example 4

Assume that you have two variables, float and date, that contain some data values and also some chronological information about when those data values were recorded:

date = STR_TO_DT(['10/10/92', '11/11/92', '12/12/92'], $
       ['05:45:12', '10:10:51', '23:03:19'], $
       Date_Fmt=1, Time_Fmt=-1)
float = [1.2, 3.4, 5.6]

Note: The variable date is shown above as a series of strings, even though it is actually stored in a date/time structure as a series of integer and floating-point values.

The variable date is a date/time structure, and holds both date and time data. For more information on the internal structure of date/time structure variables, see the PV‑WAVE Programmer’s Guide.

When you have date and time data stored in the same variable, the variable must be listed twice in the variable list in order to extract both the date and time data. The date/time templates that will be used to transfer this data have the following definitions:

1 — MM/DD/YY (/ = delimiter)
–1 — HH:MM:SS (: = delimiter)

If you enter the following commands:

date = STR_TO_DT(['10/10/92', '11/11/92', '12/12/92'], $
       ['05:45:12', '10:10:51', '23:03:19'], $
       Date_Fmt=1, Time_Fmt=-1)
float = [1.2, 3.4, 5.6]
status = DC_WRITE_FREE("thymus.dat", date,  $
   float, date, /Column, Dt_Template=[1,-1])

you create a file that looks like this:

10/10/1992,          1.2,05:45:12.000
11/11/1992,          3.4,10:10:51.000
12/12/1992,          5.6,23:03:19.000

Notice that data is written from date two different times. In each new output record, Template 1 is used first to write the date data from date. Next, a value from float is written, and finally, Template –1 is used to write the time data from date.