Several new optional keywords have been added to some of the RTL routines.
These are listed and described below. They are valid in both the Fortran
and C calling sequences.
- HOST, string: The type of computer used to generate the image. The
value for HOST appears in the system image label. It is used only for
documentation; the RTL uses the INTFMT and REALFMT label items to determine
the representation of the pixels in the file. HOST will default to the type
of computer the program is running on, so it normally will not be needed. It
is used to write a file in a host format other than the native one. While
this is not recommended (the general rule is read anything, write native
format), it is allowed. See Section , Data Types and Host
Representations, for more information. HOST is available in the routines
x/ zvadd, x/ zvopen, and x/ zvget. For output files, the HOST optional
to x/ zvopen or x/ zvadd unconditionally sets the output's HOST label.
For input files, the HOST optional to x/ zvopen or x/ zvadd has no effect
unless the input file is unlabeled (i.e. the HOST in the input file overrides).
New values for HOST will appear every time the RTL is ported to a new
machine, so no checking is done on the string. However, the currently
accepted values, and what they represent, are listed in Table .
In addition, the following values are also accepted:
- NATIVE
- : The host type of the currently running machine
- LOCAL
- : Same as NATIVE
- INTFMT, string: The format used to represent integers in the file.
INTFMT, REALFMT, and HOST should all match, so if you change one please
change all three. INTFMT is a system label item in the image used by the
RTL to automatically convert data read in, via x/ zvread, to the native
integer representation. It defaults to the representation of the machine
the program is running on, so it only needs to be set when writing in a
non-native format. If you are reading a file in such a way that the RTL
does not automatically convert data types, such as Array I/O or
CONVERT OFF, you must pay attention to the INTFMT label (via x/ zvget)
and use the x/ zvtrans family of routines to translate to the native
representation (for binary labels see BINTFMT below). See
Section ,Data Types and Host Representations, for
more information. INTFMT is available in the routines x/ zvadd,
x/ zvopen, and x/ zvget. For output files, the INTFMT optional
to x/ zvopen or x/ zvadd unconditionally sets the output's INTFMT
label. For input files, the INTFMT optional to x/ zvopen or x/ zvadd has no
effect unless the input file is unlabeled (i.e. the INTFMT in the input file
overrides).
The valid values of INTFMT may change as the RTL is ported to new machines.
However, the currently valid values are listed in Table .
In addition, the following values are also accepted:
- NATIVE
- : The integer format of the currently running machine.
- LOCAL
- : Same as NATIVE.
The valid values of REALFMT may change as the RTL is ported to new machines.
However, the currently valid values are listed in Table .
In addition, the following values are also accepted:
- NATIVE
- : The floating point format of the currently running machine.
- LOCAL
- : Same as NATIVE.
- BHOST, string: The type of computer used to generate the binary labels.
The value for BHOST appears in the system image label. It is used only for
documentation; the RTL uses the BINTFMT and BREALFMT label items to determine
the representation of the binary labels in the file. For input (or update)
files, the BHOST optional is used if the BHOST label is not present in the
file (if neither are present it defaults to VAX-VMS). For output files, the
BHOST optional is used if BIN_CVT is OFF (if not present the file's BHOST
comes from the primary input, or defaults to VAX-VMS). If BIN_CVT is ON,
the BHOST optional is ignored since the file's BHOST gets set to the native
host. See Section , Data Types and Host Representations, for
more information. BHOST is available in the routines x/ zvadd, x/ zvopen,
and x/ zvget.
The valid values for BHOST are exactly the same as for HOST above (including
NATIVE and LOCAL).
- BINTFMT, string: The format used to represent integers in the binary
label. BINTFMT, BREALFMT, and BHOST should all match, so if you change one
please change all three. BINTFMT is a system label item in the image made
available by the RTL to help applications to convert binary labels read or
written to the file. For input (or update) files, the BINTFMT optional is
used if the BINTFMT label is not present in the file (if neither are present
it defaults to the integer format for VAX-VMS). For output files, the BINTFMT
optional is used if BIN_CVT is OFF (if not present the file's BINTFMT comes
from the primary input, or defaults to the integer format for VAX-VMS).
If BIN_CVT is ON, the BINTFMT optional is ignored since the file's BINTFMT
gets set to the native host integer format. See Section ,
Data Types and Host Representations, for more information. BINTFMT is
available in the routines x/ zvadd, x/ zvopen, and x/ zvget.
Applications using binary labels should pay close attention to BINTFMT,
as they are responsible for doing their own data format conversions.
The valid values for BINTFMT are exactly the same as for INTFMT above
(including NATIVE and LOCAL).
- BREALFMT, string: The format used to represent real numbers in the
binary label. BREALFMT, BINTFMT, and BHOST should all match, so if you change
one please change all three. BREALFMT is a system label item in the image made
available by the RTL to help applications to convert binary labels read or
written to the file. For input (or update) files, the BREALFMT optional is
used if the BREALFMT label is not present in the file (if neither are present
it defaults to the floating-point format for VAX-VMS). For output files, the
BREALFMT optional is used if BIN_CVT is OFF (if not present the file's
BREALFMT comes from the primary input, or defaults to the floating-point format
for VAX-VMS). If BIN_CVT is ON, the BREALFMT optional is ignored since the
file's BREALFMT gets set to the native host floating-point format. See
Section , Data Types and Host Representations, for more
information. BREALFMT is available in the routines x/ zvadd, x/ zvopen,
and x/ zvget.
Applications using binary labels should pay close attention to BREALFMT,
as they are responsible for doing their own data format conversions.
The valid values for BREALFMT are exactly the same as for REALFMT above
(including NATIVE and LOCAL).
- BLTYPE, string: The type of the binary label. The value for BLTYPE
appears in the system image label. This is not type in the sense of data
type, but is a string identifying the kind of binary label in the file.
The RTL does not do any interpretation or checking of BLTYPE. It is intended
mainly for documentation, so people looking at the image will know what
kind of binary label is present. It may also be used by application programs
to make sure they can process the given type of binary label, or to make sure
it is processed correctly. For input (or update) files, the BLTYPE optional
is used if the BLTYPE label is not present in the file (not that ``used'' in
this sense means only being made available to x/ zvget). For output files,
the BLTYPE optional is used for the BLTYPE system label of the file (regardless
of the BIN_CVT setting). If the optional is not present, the file's BLTYPE
comes from the primary input. See Section , Data Types and
Host Representations, for more information. BLTYPE is available in the
routines x/ zvadd, x/ zvopen, and x/ zvget.
The valid values of BLTYPE are maintained in a name registry, so that all
possible kinds of binary labels can be documented in one place. Although
the RTL does no checking on the given name, only names that are registered
should be used in BLTYPE. See Section , Binary Label Type, for
more details.
- CONVERT, string: The valid values for CONVERT are ``ON'' and ``OFF''.
The default is ``ON''. Normally, the RTL will automatically convert pixels
that are read from a file to the native host representation, and to the data
type specified in U_FORMAT. Setting CONVERT to ``OFF'' turns off both of
these conversions, giving you the bit patterns that are in the file directly.
When writing a file, host conversion is possible (although not normally used),
but the U_FORMAT data type conversion is normally performed. Setting CONVERT
to ``OFF'' turns off both of these conversions as well, writing the bit patterns
that are in memory directly to the file. Note: Be careful! If you turn
CONVERT OFF, you are responsible for doing your own data type conversions.
Any given program should be able to read files written on any machine, so if
you turn off CONVERT you should make use of the x/ zvtrans family of routines.
See Section , Data Types and Host Representations, for details.
CONVERT is available in the routines x/ zvadd and x/ zvopen.
- BIN_CVT, string: The valid values for BIN_CVT are ``ON'' and ``OFF''.
The default is ``OFF''. BIN_CVT is used to inform the RTL whether or not
you will be converting binary labels to the native host representation.
If BIN_CVT is ON, then the host formats in the output file (BHOST, BINTFMT,
and BREALFMT) will be set to the native machine's host formats. This will
be the standard case for applications that know how to interpret the binary
label. Since the binary label type is known, the application can convert
the data to the native format before writing the file.
If the application does not know the binary label type, however (such as a
general-purpose application), then it cannot convert the host format. In
this case, set BIN_CVT to OFF. This means the output file will receive the
binary label host types of the primary input file, defaulting to VAX-VMS if
not available. The general-purpose application may then simply transfer the
binary labels over to the output file without re-formatting them. The BHOST,
BINTFMT, and BREALFMT optional arguments will override this setting, but
only if BIN_CVT is OFF (they are ignored if BIN_CVT is on).
BIN_CVT is available in the routines x/ zvopen and x/ zvadd. BIN_CVT is
ignored for input files. See Section , Dealing with Binary
Labels, for more information.
- PROPERTY, string: The name of the property set that the label routine
is accessing. PROPERTY is available on x/ zladd, x/ zldel, x/ zlget, and
x/ zlinfo. The PROPERTY optional argument is only valid if the TYPE argument
of the above routines is set to ``PROPERTY''. See Section ,
Property Labels, for more information.
Several previously existing optionals for the label routines are now valid
in other routines. The new combinations are: