[ Top ] [ package ]
Synopsis
This is a set of routines used to manage the "missing data" feature of the standard file package. These troutines can also be used by other packages, provided that the datatype indicator uses values that are the same as the standard file package.
INPUTS
to activate the package: set environment variable MISSING_VALUE_FLAGS (the order of the values is important) (real, integer, unsigned integer, 8 byte real, 2 byte integer, unsigned 2 byte integer) or call set_missing_value_flags example: export MISSING_VALUE_FLAGS="1.234E37 123456 9999 4.567E+300 -5432 65432"
Notes
if less than 6 values are given, the missing ones are set to internal default values
example:
export MISSING_VALUE_FLAGS=" "
would activate the package with the internal default values
the missing value flag for real numbers will also be used for the complex type
the missing value flag for real*8 numbers will also be used for the complex*16 type
There are C and FORTRAN callable routines/functions
This spackage does not implement full defensive coding. SAFE calls from the
standard file package are expected. USE WITH CARE.
[ Top ] [ type ]
TABLES
code data type 0: binary, transparent 1: packed real (float/double) 2: unsigned integer 3: character (R4A in an integer) 4: signed integer 5: IEEE floating point (no coding) 6: packed real (coding not the same as type 1) 7: character string 8: complex IEEE floating point (no coding) +128 = with second stage packer +64 = missing data flagging is used
[ Top ] [ Functions ]
Synopsis
this subroutine will replace all occurrences the largest value in array field by the "missing data" value for this kind (datatype) of data. it assumes that EncodeMissingValue / encode_missing_value has been called before to set the largest value in an adequate manner.
Arguments
C interface: void DecodeMissingValue(void *field,int nvalues,int datatype,int is_byte,int is_short,int is_double); FORTRAN interface: subroutine DecodeMissingValue(field,nvalues,datatype,is_byte,is_short,is_double) "any_type", intent(INOUT) :: field integer, intent(IN) :: nvalues,datatype,is_byte,is_short,is_double see EncodeMissingValue / encode_missing_value for the meaning and description of the arguments
SEE ALSO
EncodeMissingValue
[ Top ] [ Functions ]
Synopsis
this function copies data from field2 into field replacing values that have the "missing data" value with values that are non detrimental to further packing by the "standard file" packers. field 2 is left as is, field will contain the output. if proper encoding is not possible, the function returns zero immediately, leaving field untouched.
Arguments
C interface:
int EncodeMissingValue(void *field,void *field2,int nvalues,int datatype,int nbits,
int is_byte,int is_short,int is_double);
FORTRAN interface:
integer function EncodeMissingValue(field,field2,nvalues,datatype,nbits,is_byte,is_short,is_double)
"any_type", intent(OUT) :: field
"any_type", intent(IN) :: field2
integer, intent(IN) :: nvalues,datatype,nbits,is_byte,is_short,is_double
field2 : input array (unspecified type)
field : output array (assumed to have the same type as field2)
nvalues : number of elements in arrays field and field2
datatype : what kind of data is found in array (see DataTypeCodes)
nbits : number of bits per element to be used for packing (used to compute appropriate flag values)
is_byte : non zero if array element length is one byte
is_short : non zero if integer (signed or not) data element length is two bytes
is_double: non zero if real data element length is eight bytes (double / real *8)
RESULT
the return value of the function is the number of missing values found ( 0 if unsuccessful for any reason ) (see notes)
Notes
the missing value will be replaced by a value greater than the largest value in field2 and large enough not to create an after packing collision with the value of the actual largest useful value in field2 (nbits is needed for this calculation) if missing value processing is not active, or no missing value flag is detected, the function result is zero, and NO COPY will done into field
SEE ALSO
DecodeMissingValue DataTypeCodes
[ Top ] [ Functions ]
Synopsis
set the state of the missing values package and get previous state
Arguments
C interface: oldmode = ForceMissingValueUsage(flag) FORTRAN interface: oldmode = Force_Missing_ValueUsage(flag) flag: 0 to deactivate, 1 to activate package
RESULT
1 : package was active 0 : package was not active
[ Top ] [ Functions ]
Synopsis
this integer function is used to get the special values used to flag "missing" data for real, integer, unsigned integer, 8 byte real, 2 byte integer, unsigned 2 byte integer this integer function will return 0 if feature is not active, 1 if it is
Arguments
C interface:
int get_missing_value_flags(float *f, int *i, unsigned int *ui,
double *d, short *s, unsigned short *us,
signed char *b, unsigned char *ub)
FORTRAN interface:
integer function get_missing_value_flags(f,i,ui,d,s,us,b,ub)
real, intent(IN) :: f
integer, intent(IN) :: i, ui
real *8, intent(IN) :: d
integer *2, intent(IN) :: s, us
integer *1, intent(IN) :: b, ub
Notes
us, ui, us are of the unsigned type, which can be confusing in FORTRAN as the language has no explicit support for this.
SEE ALSO
set_missing_value_flags
[ Top ] [ Functions ]
Synopsis
get the state of the missing values package this integer function will return 0 if feature is not active, 1 if it is
Arguments
C interface: int missing_value_used() FORTRAN interface: integer, external :: missing_value_used
RESULT
1 : package is active 0 : package is not active
[ Top ] [ Functions ]
Synopsis
this subroutine is used to set the special values used to flag "missing" data for real, integer, unsigned integer, 8 byte real, 2 byte integer, unsigned 2 byte integer calling this soubroutine will also activate the package
Arguments
C interface:
void set_missing_value_flags(float *f, int *i, unsigned int *ui,
double *d, short *s, unsigned short *us,
signed char *b, unsigned char *ub)
FORTRAN interface:
subroutine set_missing_value_flags(f,i,ui,d,s,us,b,ub)
real, intent(OUT) :: f
integer, intent(OUT) :: i, ui
real *8, intent(OUT) :: d
integer *2, intent(OUT) :: s, us
integer *1, intent(OUT) :: b, ub
Notes
us, ui, us are of the unsigned type, which can be confusing in FORTRAN as the language has no explicit support for this.
SEE ALSO
get_missing_value_flags
[ Top ] [ Functions ]
Synopsis
override/reset the functions used for encoding missing values and/or decoding encoded fields
Arguments
C interface:
SetMissingValueMapping(int what, int datatype, void *processor, int is_byte, int is_short, int is_double)
FORTRAN interface:
call set_missing_value_mapping(what, datatype, processor, is_byte, is_short, is_double)
integer, intent(IN) :: what, datatype, is_byte, is_short, is_double
integer, external :: processor
what : tell whether processor function is for encoding or decoding
1 set decoding function to processor
-1 reset decoding function to default function
2 set encoding function to processor
-2 reset encoding function to default function
11 deactivate selected decoder
is_byte : non zero for one byte data array processor
is_short : non zero for two byte integer (signed or not) data array processor
is_double: non zero for eight byte float (double / real *8) data array processor
processor is the address of the processing function called as
decode_function(void *data, int npoints) (what == 1)
or
n_missing_points = encode_function(void *dest, void *src, int npoints, int nbits) (what == 2)
if what is not equal to 1 or 2, processor is IGNORED
Notes
the npoints and nbits arguments are passed BY VALUE (Fortran beware, iso_c_binding necessary) when decoding, the largest value in the "data" array is assumed to be a "missing" value flag when encoding, the largest value in the "dest" array is assumed to be a "missing" value flag nbits is passed to the encoding routine to enable it to make an enlightened choice of flag value