DC_WRITE_FIXED Function

Writes the contents of one or more variables (in ASCII fixed format) to a file using a format that you specify.

Usage

status = DC_WRITE_FIXED(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_FIXED; 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.

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 DC_WRITE_FREE, DC_WRITE_FREE Function. To see a complete list of date/time templates, see the PV‑WAVE Programmer’s Guide.

Format — A string containing the C- or FORTRAN-like format statement that will be used to write the data. The format string must contain at least one format code that transfers data; FORTRAN formats must be enclosed in parentheses. If not provided, C format(s) that match the data type(s) of the variables in var_list are assumed; for example %lf for float, %i for integer, and %s for string.

Miss_Str — An array of strings that specifies 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_FIXED is capable of interpreting either FORTRAN-or C-style formats, and is very adept at storing data in a column-oriented manner. Also, DC_WRITE_FIXED 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.

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.

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.

The format string is processed from left to right. Record terminators and format codes are processed until no variables are left in var_list or until an error occurs. In a FORTRAN format string, when a slash record terminator ( / ) is encountered, a new output record is started.

Format codes that transfer data are matched with the next available variable (or element of a multi-dimensional variable) in the variable list var_list. Data is written to the file and formatted according to the format code. If the data in the variable does not agree with the format code, or the format code does not agree with the type of the variable, a type conversion is performed. If no type conversion is possible, an error results and a nonzero status is returned.

Once all variables in the variable list have been stored in the file, DC_WRITE_FIXED stops writing data, and returns a status code of zero (0). This is true even if there are format codes in Format that did not get used. Even if an error occurs, and status is nonzero, the data that was 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.

If the format string does not contain any format codes that transfer data, an error occurs and a nonzero status is returned. The format codes that PV‑WAVE recognizes are listed in the PV‑WAVE Programmer’s Guide. If a format code that does not transfer data is encountered, it is processed as discussed in that appendix.

Format Reversion when Writing Data

If the last closing parenthesis of the format string is reached and there are still variables in var_list whose contents have not been written to the file, format reversion occurs. In format reversion, the current output record is terminated, a new one is started, and format string processing reverts to the first group repeat specification that does not have an explicit repeat count. If the format does not contain a group repeat specification, format processing reverts to the initial opening parenthesis of the format string.

For more information about format reversion and group repeat specifications, see the PV‑WAVE Programmer’s Guide.

Missing Data String Substitution while Writing Data

PV‑WAVE expects to substitute a string from Miss_Str whenever it encounters a value from Miss_Vals in the data. Conse-quently, if the number of elements in Miss_Str does not match the number of elements in Miss_Vals, a nonzero status is returned and no data is written to the file. The maximum number of values permitted in Miss_Str and Miss_Vals is 10.

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 Data

Storing Variables in Columnar Format shows how variables of any dimensions are stored in a columnar format:

Storing Variables in Columnar Format
Dimensions of Variable	Organization of Saved File
One-dimensional (1 × n)	One value from each variable written to each record (repeated n times)
Two-dimensional (m columns by n rows)	m values from each variable written to each record (repeated n times)
Three-dimensional (m × n × p)	m values from each variable written to each of n records (entire process repeated p times)
q-dimensional (m × n × p × q)	m values from each variable written to each of n records (above process repeated p times) (entire process repeated q times)

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_FIXED('outfile.dat', sara,  $
   tana, cora, Format='(5(1X, F7.4))')

create outfile.dat containing the following values:

..1.0000..1.0000..1.0000..1.0000..1.0000
..1.0000..1.0000..1.0000..1.0000..1.0000
..2.0000..2.0000..2.0000..2.0000..2.0000
..3.0000..3.0000..3.0000..3.0000..3.0000
..3.0000..3.0000..3.0000

The periods are used to represent blank spaces in the file.

Example 2

If variable bogus is a 2-by-4 integer array with values 1 through 4 in the first column and values 5 through 8 in the second, the commands:

bogus = TRANSPOSE(INDGEN(4, 2) + 1)
status = DC_WRITE_FIXED('intfile.dat', bogus, $
   /Column, Format='(I5)')

replicate that structure in the created file intfile.dat, as shown below:

....1....5
....2....6
....3....7
....4....8

The periods are used to represent blank spaces in the file.

On the other hand, the following function call:

status = DC_WRITE_FIXED('intfile.dat', $
   bogus(1,*), Format='(4I5)')

with a slightly different format string, results in four values all being written in the same record, using a row orientation:

   ....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. Without the “4” inside the parentheses of the format string, each value would have been written on a separate line in the file.

Example 3

If variable foo is a floating-point array with 6 elements all equal to 1.0, hoo is a floating-point array with 6 elements all equal to 2.0, doo is a floating-point array with 6 elements all equal to 3.0, and boo is a floating-point array with 6 elements all equal to 4.0, the commands:

foo = FLTARR(6) + 1.0
hoo = FLTARR(6) + 2.0
doo = FLTARR(6) + 3.0
boo = FLTARR(6) + 4.0
status = DC_WRITE_FIXED('omni.dat', foo,  $
   hoo, doo, boo, Format='%f, %f, %f, %f', /Column)

create an output file omni.dat that is organized as shown below:

   1.000000, 2.000000, 3.000000, 4.000000
   1.000000, 2.000000, 3.000000, 4.000000
   1.000000, 2.000000, 3.000000, 4.000000
   1.000000, 2.000000, 3.000000, 4.000000
   1.000000, 2.000000, 3.000000, 4.000000
   1.000000, 2.000000, 3.000000, 4.000000

The data is arranged in columns. The C format code '%f, ' causes a comma followed by a space to be inserted after every value written to the file.

Note: An even easier way to write this data is to use another “DC” function, DC_WRITE_FREE. The DC_WRITE_FREE function writes CSV (Comma Separated Values) data by default, or you can use the Delim keyword to specify some other delimiter besides the comma.

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.

The STR_TO_DT function creates a date/time variable date. For more information on the internal structure of date/time structure variables, see the PV‑WAVE Programmer’s Guide.

In this example, date/time Template 1 (MM/DD/YY) is used to transfer this data, which means the month, day, and year will be written as adjacent values separated by a slash ( / ).

If you enter the following commands:

date = STR_TO_DT(['10/10/92', '11/11/92', '12/12/92'], Date_Fmt=1)
float = [1.2, 3.4, 5.6]
status = DC_WRITE_FIXED("thymus.dat", date, float, /Column, $
   Dt_Template=[1], Format="(A10, 1X, F4.2)")

you create a file that looks like this:

10/10/1992 1.20
11/11/1992 3.40
12/12/1992 5.60

Notice that date data is written into the file thymus.dat as a series of strings. In each new output record, Template 1 is used to write the data from date, using the A10 character format, and a value from float is written, using the F4.2 format.

Note: If 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. For more details, see DC_READ_FREE, DC_WRITE_FREE Function.

Example 5

Suppose you have a number of variables that contain data about recent phone activity. The names of these variables are date, time, mins, type, ext, cost, and num_called. The DC_WRITE_FIXED command writes this information to a file and organizes the values by columns:

date = ['901002', '901002', '901002']
time = ['093200', '093600', '093700']
mins = [21.40, 51.56, 61.39]
type = [1,1,2]
ext = [311, 379, 435]
cost = [5.78, 13.92, 16.58]
num_called =['2158597430', '2149583711', '9137485920']
status = DC_WRITE_FIXED('phonedata.dat', date, time, mins, $
   type, ext, cost, num_called, /Column, $
   Format="%s  %s  %5.2f  %i  %i  %5.2f  %s")

In this example, date and time are variables with a data type of string. Because they are not defined as a date/time structure, such as the variable date that was part of the previous example, date and time are not stored using any of the date or time templates. Thus, there is no need to include the Dt_Template keyword as part of the function call.

The result is a file phonedata.dat that is organized as shown below:

901002  093200  21.40  1  311   5.78  2158597430
901002  093600  51.56  1  379  13.92  2149583711
901002  093700  61.39  2  435  16.58  9137485920

The following function call could be used instead of the one shown above if you prefer to use a FORTRAN-style format string:

status = DC_WRITE_FIXED('phonedata.dat', date, time, mins, $
   type, ext, cost, num_called, /Column, $
   Format='(A6,2X,A6,2X,F5.2,1X,I2,2X,' + $
          'I3,2X,F5.2,2X,A12)')

Note: If you wish to enter a format string similar to the FORTRAN one shown above, try to get the entire format string on the same line. Otherwise, use the string concatenation operator (+), as shown in the above example, to split the format string into two shorter strings.