NAP Library: bin

Binary Input/Output Procedures

Introduction
Reading and Writing Simple Binary Files
1. Procedure get_nao [fileName [dataType [shape]]]
2. Procedure put_nao [nap_expr [fileName]]
Reading and Writing Fortran Unformatted Files
Reading and Writing cif Files
Miscellaneous Procedures
1. Procedure size_of dataType

Procedure `get_bin` `dataType` [`fileId` [`mode`]]

Procedure `put_bin` `nap_expr` [`fileId` [`mode`]]

Write Fortran binary (unformatted) record.
nap_expr: NAP expression to be evaluated in caller namespace
fileId: Tcl file handle (default: stdout)
mode: binary (default) or swap

Example

The following example creates a NAO called squares, writes it to a file, then reads the data from this file into a NAO called in.

% nap "squares = (0 .. 4)**2"
::NAP::66-66
% $squares all
::NAP::66-66  f32  MissingValue: NaN  References: 1  Unit: (NULL)
Dimension 0   Size: 5      Name: (NULL)    Coordinate-variable: (NULL)
Value:
0 1 4 9 16
% set file [open tmp.bin w]; # open file "tmp.bin" for writing
file5
% put_bin squares $file; # write data from squares
% close $file
% set file [open tmp.bin]; # open file "tmp.bin" for reading
file5
% nap "in = [get_bin f32 $file]"; # read data into in
::NAP::78-78
% close $file
% $in all
::NAP::78-78  f32  MissingValue: NaN  References: 1  Unit: (NULL)
Dimension 0   Size: 5      Name: (NULL)    Coordinate-variable: (NULL)
Value:
0 1 4 9 16

Reading and Writing `cif` Files

The cif (conmap input file) format is one which originated in the Melbourne University Department of Meteorology in the days before netCDF and HDF. It is now rather obsolete but is still used within CSIRO and other Australian organisations. A cif is a Fortran unformatted file consisting of one or more frames, each of which consists of six records as follows:

number of rows
vertical coordinate variable (often latitude)
number of columns
horizontal coordinate variable (often longitude)
title
main data (matrix)

The main input procedure is get_cif, which reads one or more matrices from each of one or more cif files. The main output procedure is put_cif, which writes a NAO as an entire cif. These procedures call the low-level procedures get_cif1 or put_cif1 for each frame.

Procedure `get_cif` [`options`] `pattern` [`pattern` ...]

Read one or more matrices from each of one or more cif files (whose names are specified by one or more glob patterns). The result is 2D if only one frame is read, otherwise it is 3D. Check whether byte swapping is needed by examining 1st word in file.
Options:
-g 0|1: 1 (default) for geographic mode, 0 for non-geographic mode
-m real: Input missing value (default: -7777777.0)
-um text: Units for matrix (default: none)
-ux text: Units for x (default: if geographic mode then degrees_east, else none)
-uy text: Units for y (default: if geographic mode then degrees_north, else none)
-x text: Name of dimension x (default: if geographic mode then longitude else x)
-y text: Name of dimension y (default: if geographic mode then latitude else x)

The following example reads a single-frame cif named 7.cif into a NAO called in, then displays it (including the coordinate variables).

% nap "in = [get_cif 7.cif]"
::NAP::357-357
% $in all
::NAP::357-357  f32  MissingValue: NaN  References: 1  Unit: (NULL)
This data originated from ascii conmap input file 'acif.7'
Dimension 0   Size: 3      Name: latitude  Coordinate-variable: ::NAP::236-236
Dimension 1   Size: 4      Name: longitude  Coordinate-variable: ::NAP::308-308
Value:
 1  1  2 -3
 1  _  3 -4
 2  0  4  5
% [nap "coordinate_variable(in,0)"]
-60 30 60
% [nap "coordinate_variable(in,1)"]
-90 30 90 180

Procedure `put_cif` `nap_expr` [`fileName` [`mode`]]

Write NAO as entire cif.
nap_expr: NAP expression to be evaluated in caller namespace
fileName: file name (default: stdout)
mode: binary (default) or swap

Procedure `get_cif1` [`options`] `fileId`

The following example reads the first frame of a cif named 7.cif into a NAO called in, then displays it (including the coordinate variables).

% set f [open 7.cif]
file5
% nap "in = [get_cif1 $f]"
::NAP::218-218
% close $f
% $in all
::NAP::218-218  f32  MissingValue: NaN  References: 1  Unit: (NULL)
This data originated from ascii conmap input file 'acif.7'
Dimension 0   Size: 3      Name: latitude  Coordinate-variable: ::NAP::97-97
Dimension 1   Size: 4      Name: longitude  Coordinate-variable: ::NAP::169-169
Value:
 1  1  2 -3
 1  _  3 -4
 2  0  4  5
% ::NAP::97-97
-60 30 60
% ::NAP::169-169
-90 30 90 180

% size_of i16
2

Author: Harvey Davies © 2002, CSIRO Australia. Legal Notice and Disclaimer
CVS Version Details: $Id: bin_io.html,v 1.3 2003/03/17 05:12:27 dav480 Exp $

Binary Input/Output Procedures

Table of Contents

Introduction

Reading and Writing Simple Binary Files

Procedure `get_nao` [`fileName` [`dataType` [`shape`]]]

Procedure `put_nao` [`nap_expr` [`fileName`]]

Reading and Writing Fortran Unformatted Files