6.2 Translation
API
Below
are the ten subroutines that comprise the Translation API.
6.2.1 x/zvhost—Integer
and real data representations of a host given the host type name
call xvhost(host, intfmt, realfmt, status)
status = zvhost(host, intfmt, realfmt);
Returns
the integer and real data representations of a host given the host type name.
The returned values may be used with the translation routines or the INTFMT and
REALFMT system label items. This routine can also return the host type name,
for use with the HOST system label.
This
routine is rarely needed, as the normal case is to read any type of file (where
you get INTFMT and REALFMT from the file), and to write in native format (where
you don't need to specify the formats). However, this routine is useful in the
rare case that a program needs to write in a non-native format. The user can
select the machine type for output, and this routine will return the data
representations needed for that machine type.
Arguments:
- HOST:
string, input
HOST
is the type name of the host you want information about. It is not the name of
a particular machine, rather, it is the name of a type of machine. HOST
corresponds to the HOST system label. The HOST system label is intended for
documentation only, however, the same values are valid in this parameter.
Normally, the HOST parameter will come from user input. The valid values will
change as VICAR is ported to more machines, so the program should allow any
value as user input, then check the status from
x/zvhost
to see if the machine name is valid. The currently valid values are listed. See
Table 1: Valid VICAR HOST Labels and Machine Types.
In addition, the following values are accepted:
- NATIVE
: Returns the INTFMT and REALFMT for the machine currently running.
- LOCAL
: Same as NATIVE.
- HOSTNAME
: Special, see below.
The
value “HOSTNAME” is special. If this value is given for HOST, then
the return values change. The parameter INTFMT returns the host type name for
the machine currently running. The parameter REALFMT is undefined on output.
The value returned in INTFMT could then be used in another call to
x/zvhost
(which wouldn't gain much since “NATIVE” or “LOCAL” do
the same thing), or it could be used in a HOST label. This should be needed
only from FORTRAN. A C program should use the “ NATIVE _HOST_LABEL”
macro defined in x/zvmaininc.h instead. Similarly, “NATIVE” and
“LOCAL” will be mainly useful in a FORTRAN program, as a C program
should use the NATIVE_INTFMT and NATIVE_REALFMT macros.
- INTFMT:
string, output
The
integral host representation for the machine in question is returned in INTFMT.
It corresponds to the INTFMT label item in a file, and the related parameters
to the translation routines. The returned value will be one of the supported
integer data types, which are listed. See
Table 2: Valid VICAR Integer Formats.
If
the special host name “HOSTNAME” is given, then INTFMT instead
returns the host type name (HOST label) of the native machine.
- REALFMT:
string, output
The
floating-point host representation for the machine in question is returned in
REALFMT. It corresponds to the REALFMT label item in a file, and the related
parameters to the translation routines. The returned value will be one of the
supported floating-point data types, which are listed. See
Table 3: Valid VICAR Real Number Formats.
If
the special host name “HOSTNAME” is given, then the value returned
in REALFMT is undefined and should not be used.
- STATUS:
integer, output
The
returned status value. It is an argument in FORTRAN and the function return
value in C. Any value other than SUCCESS indicates that the value given for
HOST was invalid.
6.2.2 x/zvpixsize—Size
of a pixel in bytes given the data type and host representation
status = xvpixsize(pixsize, type, ihost, rhost)
status = zvpixsize(pixsize, type, ihost, rhost);
Returns
the size of a pixel in bytes given the data type and host representation. One
of the
pixsize
routines should be used to figure out the size of a pixel. Do
not
assume any particular size, like 4 bytes for a REAL. It may be different on
other machines. It is valid to use
sizeof()
in C to get the size of a pixel in the native representation
only,
but
the
pixsize
routines are the only valid way to get the size of a pixel on any other hosts.
Arguments:
- PIXSIZE:
integer, output
Returns
the size of a pixel in bytes. If an error occurs (such as an invalid data
type), PIXSIZE is returned as 0.
- TYPE:
string, input
TYPE
is the data type of the pixel. It corresponds to the FORMAT label item in a
file. It may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”,”DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- IHOST:
string, input
IHOST
is the integral host representation for the pixel. It corresponds to the INTFMT
label item in a file. It may be any of the supported integer data types, which
are listed. See
Table 2: Valid VICAR Integer Formats.
It may also be “NATIVE” or “LOCAL”, both of which mean
the native host INTFMT. IHOST should be given even if you are dealing with
floating-point data types.
- RHOST:
string, input
RHOST
is the floating-point host representation for the pixel. It corresponds to the
REALFMT label item in a file. It may be any of the supported floating-point
data types, which are listed. See
Table 3: Valid VICAR Real Number Formats.
It may also be “NATIVE” or “LOCAL”, both of which mean
the native host REALFMT. RHOST should be given even if you are dealing with
integral datatypes.
6.2.3 x/zvpixsizeb—Size
of a binary label value in bytes from a file
status = xvpixsizeb(pixsize, type, unit)
status = zvpixsizeb(pixsize, type, unit);
Return
the size of a binary label value in bytes from a file. This routine is exactly
like
x/zvpixsize
except that the IHOST and RHOST values are obtained for binary labels from the
file specified by UNIT, which must be open. It is provided merely as a shortcut
to get the size of a binary label value for a file.
Arguments:
- PIXSIZE:
integer, output
Returns
the size of a pixel in bytes. If an error occurs (such as an invalid data
type), PIXSIZE is returned as 0.
- TYPE:
string, input
TYPE
is the data type of the binary label value. It corresponds to the FORMAT label
item in a file, although binary label values are not restricted to FORMAT and
maybe any data type. TYPE may be one of the standard VICAR data types:
“BYTE”, “HALF”,”FULL”, “REAL”,
“DOUB”, or “COMP”. The types “WORD”,
“LONG”, and “COMPLEX” are also accepted, but are
obsolete and should not be used.
- UNIT:
integer, input
UNIT
is the unit number of an open file, which is used to obtain the source BINTFMT
and INTFMT. The values obtained from the file are used exactly like the
x/zvpixsize
IHOST and RHOST.
6.2.4 x/zvpixsizeu—Size
of a pixel in bytes from a file
status = xvpixsizeu(pixsize, type, unit)
status = zvpixsizeu(pixsize, type,unit);
Return
the size of a pixel in bytes from a file. This routine is exactly like
x/zvpixsize
except that the IHOST and RHOST values are obtained from the file specified by
UNIT, which must be open. It is provided merely as a shortcut to get the pixel
size of a file.
Arguments:
- PIXSIZE:
integer, output
Returns
the size of a pixel in bytes. If an error occurs (such as an invalid data
type), PIXSIZE is returned as 0.
- TYPE:
string, input
TYPE
is the data type of the pixel. It corresponds to the FORMAT label item in a
file. It may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”,”DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- UNIT:
integer, input
UNIT
is the unit number of an open file, which is used to obtain the source INTFMT
and REALFMT. The values obtained from the file are used exactly like the
x/zvpixsize
IHOST and RHOST.
6.2.5 x/zvtrans—Translate
pixels from one format to another
call xvtrans(buf, source, dest, npix)
zvtrans(buf, source, dest, npix);
Translate
pixels from one format to another. One of the translation setup routines must
have been called first to set up the translation buffer. This routine is the
only standard way to translate data in the VICAR system, both between host
representations ( e. g. VAX to IEEE) and between data types (e.g. integer to
real).
This
routine is coded to be very efficient, so it may be called inside a tight loop
with very little performance penalty
.
Arguments:
- BUF:
integer-array(12), input
BUF
is the translation buffer that describes the translation to be performed. It is
initialized by one of the translation setup routines. The internals of this
buffer are unknown to the application program, with one exception, described
below.
Any
other access to the internals of the buffer may cause your program to break in
the future, as the structure may change without notice.
If
the first integer in the translation buffer is NULL (0), then
x/zvtrans
merely moves the data from the source to the destination, without any
conversion. This can happen often when reading a file, where you don't know
ahead of time what host representation the input data is in. If it turns out to
be the native representation, no translation is necessary, and the first
integer of the buffer will be 0. This fact can sometimes be used to avoid
copying the data, making the program more efficient.
- SOURCE:
pixel-buffer, input
SOURCE
is the source data buffer.
- DEST:
pixel-buffer, output
DEST
is the destination data buffer. It may
not
be the same as SOURCE, i.e. you can't translate in place or with overlapping
buffers.
- NPIX:
integer, input
NPIX
is the number of pixels (not bytes!) to translate. Both SOURCE and DEST must be
large enough to hold NPIX pixels; no checking is done.
6.2.6 x/zvtrans_in—Create
translation buffer for input
call xvtrans_in(buf, stype, dtype, sihost, srhost, status)
status = zvtrans_in(buf, stype, dtype, sihost, srhost);
Create
translation buffer for input. The data will be converted from a host
representation of (SIHOST, SRHOST) and data type of STYPE into the machine's
native representation and data type DTYPE. So, it converts from foreign to
local format. Since all processing must be done in native format on the machine
the program is running on, this translation is most often needed for input from
a file
.
Arguments:
- BUF:
integer-array(12), output
BUF
is the translation buffer that this routine will setup, describing the
translation to be performed.
- STYPE:
string, input
STYPE
is the source data type. It corresponds to the FORMAT label item in a file. It
may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”,”DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- DTYPE:
string, input
DTYPE
is the desired destination data type. It corresponds to the FORMAT label item
in a file. It may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”, “DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- SIHOST:
string, input
SIHOST
is the host representation for the source of integral data types. It
corresponds to the INTFMT label item in a file. It may be any of the supported
integer data types, which are listed. See
Table 2: Valid VICAR Integer Formats.
It may also be “ NATIVE” or “LOCAL”, both of which mean
the native host INTFMT. SIHOST should be given even if you are dealing only
with floating-point data types. See also
x/zvhost.
- SRHOST:
string, input
SRHOST
is the host representation for the source of floating-point data types. It
corresponds to the REALFMT label item in a file. It may be any of the supported
floating-point data types, which are listed. See
Table 3: Valid VICAR Real Number Formats.
It may also be “NATIVE” or “LOCAL”, both of which mean
the native host REALFMT. SRHOST should be given even if you are dealing only
with integral data types. See also
x/zvhost.
- STATUS:
integer, output
The
returned status value. It is an argument in FORTRAN and the function return
value in C. Any value other than SUCCESS indicates that the translation is
invalid for some reason, and the translation buffer should not be used.
6.2.7 x/zvtrans_inb—Create
translation buffer for input from binary labels of a file
call xvtrans_inb(buf, stype, dtype, unit, status)
status = zvtrans_inb(buf,stype, dtype, unit);
Create
translation buffer for input from the binary labels of a file. This routine is
exactly like
x/zvtrans_in
except that the SIHOST and SRHOST values are obtained for binary labels from
the file specified by UNIT, which must be open. It is provided merely as a
shortcut for the common case of reading binary label data from a labeled file
.
Arguments:
- BUF:
integer-array(12), output
BUF
is the translation buffer that this routine will setup, describing the
translation to be performed.
- STYPE:
string, input
STYPE
is the source data type. It corresponds to the FORMAT label item in a file,
although binary label values are not restricted to FORMAT and may be of any
datatype. STYPE may be one of the standard VICAR data types:
“BYTE”, “HALF”, “FULL”,
“REAL”,”DOUB”, or “COMP”. The types
“WORD”, “LONG”, and “COMPLEX” are also
accepted, but are obsolete and should not be used.
- DTYPE:
string, input
DTYPE
is the desired destination data type. It corresponds to the FORMAT label item
in a file, although binary label values are not restricted to FORMAT and may be
of any data type. DTYPE may be one of the standard VICAR data types:
“BYTE”, “HALF”, “FULL”, “REAL”,
“DOUB”, or “COMP”. The types “WORD”,
“LONG”, and “COMPLEX” are also accepted, but are
obsolete and should not be used.
- UNIT:
integer, input
UNIT
is the unit number of an open file, which is used to obtain the source BINTFMT
and INTFMT. The values obtained from the file are used exactly like the
x/zvtrans_in
SIHOST and SRHOST.
- STATUS:
integer, output
The
returned status value. It is an argument in FORTRAN and the function return
value in C. Any value other than SUCCESS indicates that the translation is
invalid for some reason, and the translation buffer should not be used.
6.2.8 x/zvtrans_inu—Create
translation buffer for input from a file
call xvtrans_inu(buf, stype, dtype, unit, status)
status = zvtrans_in u(buf,stype, dtype, unit);
Create
translation buffer for input from a file. This routine is exactly like
x/zvtrans_in
except that the SIHOST and SRHOST values are obtained from the file specified
by UNIT, which must be open. It is provided as a shortcut for the common case
of reading image data from a labeled file
.
Arguments:
- BUF:
integer-array(12), output
BUF
is the translation buffer that this routine will setup, describing the
translation to be performed.
- STYPE:
string, input
STYPE
is the source data type. It corresponds to the FORMAT label item in a file. It
may be one of the standard VICAR data types: “ BYTE”,
“HALF”, “FULL”, “REAL”,”DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- DTYPE:
string, input
DTYPE
is the desired destination data type. It corresponds to the FORMAT label item
in a file. It may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”, “DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- UNIT:
integer, input
UNIT
is the unit number of an open file, which is used to obtain the source INTFMT
and REALFMT. The values obtained from the file are used exactly like the
x/zvtrans_in
SIHOST and SRHOST.
- STATUS:
integer, output
The
returned status value. It is an argument in FORTRAN and the function return
value in C. Any value other than SUCCESS indicates that the translation is
invalid for some reason, and the translation buffer should not be used.
6.2.9 x/zvtrans_out—Create
translation buffer for output
call xvtrans_out(buf, stype, dtype, dihost, drhost, status)
status =zvtrans_out(buf, stype, dtype, dihost, drhost);
Create
translation buffer for output. The data will be converted from the machine's
native representation and data type of STYPE into a host representation of
(DIHOST, DRHOST) and data type of DTYPE. So, it converts from local to foreign
format. Since all processing must be done in native format on the machine the
program is running on, this translation is most often needed for output to a
file.
This
routine is less commonly used than the input routines. The general rule for
applications is to read any format, but write the native format. Translation on
output is not needed in this case. However,
x/zvtrans_out
is provided for special cases where the data must be written in a different
host representation
.
Arguments:
- BUF:
integer-array(12), output
BUF
is the translation buffer that this routine will create, describing the
translation to be performed.
- STYPE:
string, input
STYPE
is the source data type. It corresponds to the FORMAT label item in a file. It
may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”,”DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- DTYPE:
string, input
DTYPE
is the desired destination data type. It corresponds to the FORMAT label item
in a file. It may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”, “DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- DIHOST:
string, input
DIHOST
is the host representation for the destination of integral data types. It
corresponds to the INTFMT label item in a file. It may be any of the supported
integer data types, which are listed. See
Table 2: Valid VICAR Integer Formats.
It may also be “NATIVE” or “LOCAL”, both of which mean
the native host INTFMT. DIHOST should be given even if you are dealing only
with floating-point data types. See also
x/zvhost.
- DRHOST:
string, input
DRHOST
is the host representation for the destination of floating-point data types. It
corresponds to the REALFMT label item in a file. It may be any of the supported
floating-point data types, which are listed. See
Table 3: Valid VICAR Real Number Formats.
It may also be “NATIVE” or “LOCAL”, both of which mean
the native host REALFMT. DRHOST should be given even if you are dealing only
with integral data types. See also
x/zvhost.
- STATUS:
integer, output
The
returned status value. An argument in FORTRAN or the function return value in
C. Any value other than SUCCESS indicates that the translation is invalid, and
the translation buffer should not be used.
6.2.10 x/zvtrans_set—Create
translation buffer for data types only
call xvtrans_set(buf, stype, dtype, status)
status = zvtrans_set(buf, stype, dtype);
Create
translation buffer for data types only. Both the source and the destination
must be in the native host representation. It is useful for converting internal
buffers from one data type to another. Don't use it with data direct from a
file, however, as files are not guaranteed to be in the native host
representation
.
Arguments:
- BUF:
integer-array(12), output
BUF
is the translation buffer that this routine will setup, describing the
translation to be performed.
- STYPE:
string, input
STYPE
is the source data type. It corresponds to the FORMAT label item in a file. It
may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”,”DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- DTYPE:
string, input
DTYPE
is the desired destination data type. It corresponds to the FORMAT label item
in a file. It may be one of the standard VICAR data types: “BYTE”,
“HALF”, “FULL”, “REAL”, “DOUB”,
or “COMP”. The types “WORD”, “LONG”, and
“COMPLEX” are also accepted, but are obsolete and should not be
used.
- STATUS:
integer, output
The
returned status value. It is an argument in FORTRAN and the function return
value in C. Any value other than SUCCESS indicates that the translation is
invalid for some reason, and the translation buffer should not be used.