3.2 Image
I/O API
The
nine routines for image I/O (line I/O and array I/O) are described below. A
description of the optional arguments follows each subroutine description.
3.2.1 x/zvadd—Add
information to control block
call xvadd(unit, status, <optionals>, ' ')
status = zvadd(unit, <optionals>, 0);
x/zvadd
updates the internal control block information describing the file associated
with UNIT. Each item of information is identified by a key word and is followed
by a value which holds the update information. The keyword-value pairs are
optional and may be entered in any order. To process the file,
x/zvadd
must be called before opening (with
x/zvopen)
the file.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
- STATUS:
output, integer
Error
status code. A value of one indicates success. The error codes are listed in
10
Appendix B: Error Messages.
See also the optional arguments OPEN_ACT, IO_ACT, LAB_ACT, and ERR_ACT.
Optional
arguments:
- U_NL:
input, integer
Indicates
that the Executive is to create an output file capable of holding NL lines. If
the file associated with the unit number already exists but is too small, it
will be enlarged.
- U_NS:
input, integer
As
in NL but for samples.
- U_NB:
input, integer
As
in NL but for bands.
- U_NBB:
input, integer
For
output files, indicates the number of bytes of binary prefix that will precede
each image line. The binary prefix will be stored in an area before each image
line. It will be hidden from subsequent programs unless the program opens the
file with a COND value that includes BINARY. Subsequent reads of a file with
COND including BINARY will return the binary prefix to each line ahead of the
line in the read buffer. An output file with a non-zero U_NBB will expect the
binary prefix to precede the image line in the
x/zvwrit
buffer. For input files U_NBB is ignored. Defaults to 0.
- U_NLB:
input, integer
For
output files, indicates the number of lines of binary header information that
is to precede the image lines in an image file. The image I/O subsystem will
expect these lines to be written with
x/zvwrit
prior to the writing of the image lines. The image header will remain hidden
from subsequent programs unless those programs open the file with a value of
COND that includes the substring, BINARY. For input files,
U_NLB
is ignored. Defaults to 0.
- U_N1,
U_N2, U_N3
:
input, integers
Indicate
that the Executive is to ensure that the output file will have the dimensions
specified by the values associated with the respective arguments. U_N1 refers
to the first file dimension, U_N2 the second, and U_N3 the third. These
arguments are useful for the program which does not care about the file
organization, and simply wants to deal with records and pixels. The relation
between these arguments and the normal NL, NS, NB arguments are as follows:
|
ORG
|
N1
|
N2
|
N3
|
|
BSQ
|
NS
|
NL
|
NB
|
|
BIL
|
NS
|
NB
|
NL
|
|
BIP
|
NB
|
NS
|
NL
|
Table
10: File Organization
- U_ORG:
input, string
Indicates
the file organization that the programmer expects or desires for the file. The
acceptable organizations are band sequential, band interleaved by pixel, and
band interleaved by line. The respective values that represent these states
are, 'BSQ', 'BI P', and 'BIL'. If the file is being created by the
x/zvopen,
then the indicated organization will become the new file organization. If the
file is an existing file that is not to be deleted and created again, then the
Executive will check the indicated organization against that of the existing
file. If they are not the same then an error condition will be raised. If the
image file has less than three dimensions, this argument will be ignored.
- U_DIM:
input, integer
Number
of dimensions of dimensions the file has. Current default if U_DIM not
specified is 3. 4 is permitted but not supported.
- METHOD:
input, string
Indicates
the access method for the file.
Valid
values are 'SEQ' (sequential) or 'RANDOM'. The default is 'SEQ'. 'SEQ' and
'RANDOM' only effect the internal buffering used by the executive; if the
method is 'SEQ', then a larger buffer will be used for I/O, resulting in more
efficient processing. If 'RANDOM' is given, a smaller buffer will be used to
avoid reading unnecessary data.
If
the file is a tape file, an error condition will be raised if 'RANDOM' is
specified. The specification of 'RANDOM' for a file with OP equal to 'WRITE' is
equivalent to 'SEQ'.
- OP:
input, string
Indicates
the intended operation. Valid values are 'READ', 'WRITE', and 'UPDATE'. Default
is 'READ'.
Output
files must have OP equal to WRITE.
- OPEN_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of the open. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings:
- A:
an error will cause an immediate program abort. Otherwise, the routine will
return an error number in STATUS.
- U:
an error will cause the string that the user has specified with the OPEN_MES
optional to be printed.
- S:
an error will cause a system message to be printed.
The
three values are independent. Thus 'SA' will cause a system message to be
printed and the program to abort if an error occurs. If OPEN_ACT consists only
of blanks, an error will cause the
x/zvopen
to return an error number in STATUS. Default is the action specified with
x/zveaction.
- IO_ACT:
input, string
As
in OPEN_ACT but for
x/zvread
and
x/zvwrit.
Default is specified with
x/zveaction.
- LAB_ACT:
input, string
Specified
as is OPEN_ACT, LAB_ACT defines a default error action to be taken by the XL
routines. It can be overridden in a call to an XL routine with the ERR_ACT
optional. The message given if a 'U' is given is specified by LAB_MESS. The
default for LAB_ACT is given by
x/zveaction.
- CLOS_ACT:
input, string
Indicates
an action to be taken when the file is closed. If the string contains one of
the substrings listed below, the corresponding action will be taken. More than
one action may be specified.
- DELETE:
Causes the file to be deleted. Default is to retain the file.
- FREE:
Frees up the unit number so it can be used again. If this action is specified,
then the file can no longer be accessed using this unit number. If you want to
access the file again, x/zvunit must be called again. Since there are a limited
number of unit slots available, FREE is most useful when processing large
numbers of files. It allows VICAR to re-use this unit slot. If FREE is not
specified (the default), then the file may be opened again via x/zvopen without
calling x/zvunit, but VICAR cannot assign this unit number to another file.
- FORMAT:
output, string, maximum length 32
The
format of the pixel in an existing file. Possibilities are BYTE, HALF, FULL,
REAL, DOUB, COMP. WORD and COMPLEX are equivalent to HALF and COMP, but are
non-standard.
- O_FORMAT:
input, string
For
input files this argument is ignored. For output files, O_FORMAT becomes the
format of the output file. Valid values are 'BYTE', 'HALF', 'FULL', 'REAL',
'DOUB', and 'COMP'. 'WORD' and 'COMPLEX' are equivalent to 'HALF' and 'COMP',
respectively, but for consistency are no longer to be used. The Executive will
ensure that the output pixels have the indicated FORMAT by converting if
necessary. A related argument is U_FORMAT which is the format of the pixels
returned or passed to
x/zvread
or
x/zvwrit.
Default is the primary input FORMAT, that is, the format of the pixels in the
input file.
- U_FORMAT:
input, string
Indicates
the format of pixels in the buffer returned by
x/zvread
or the format of the pixels the program will pass to
x/zvwrit.
If for input files U_FORMAT is not equal to the input file format, then VICAR
will convert. On output, if U_FORMAT is not equal to O_FORMAT then VICAR will
convert. Default for input files is the input file format; for output files, it
is the primary input U_FORMAT.
- I_FORMAT:
input, string, maximum length 8
If
an input file is unlabeled and does not have the default pixel format of
'BYTE', then this optional may be used to set the proper format; valid values
are ' BYTE', 'HALF', 'FULL','REAL', 'DOUB', and 'COMP'. 'WORD' and 'COMPLEX'
are equivalent to 'HALF' and 'COMP', respectively, but for consistency should
no longer be used.
- OPEN_MES:
input, string, maximum length 132
OPEN_MES
holds the user message that is issued when the OPEN_ACT argument contains the
substring 'U' and an error occurs. Default is specified by
x/zveaction.
- IO_MESS:
input, string, maximum length 132
Holds
the user message that is issued under certain settings of the IO_ACT argument
when I/O errors occur. Default is specified by
x/zveaction.
- LAB_MESS:
input, string, maximum length 132
Holds
the user message that is issued when the ERR_ACT optional is not given to an XL
routine, and the LAB_ACT optional contains the substring 'U'. Default is
specified by
x/zveaction.
- TYPE:
input, string, maximum length 8
With
this argument, the programmer can designate the type of the output file
desired. If the file already exists the Executive will alter any file name and
label items that indicate the file type. On input, the file will be checked for
type. If a mismatch occurs between the TYPE argument and the actual file type,
an error status condition will be raised. Currently supported values are:
- IMAGE:
The file contains image data.
- PARM:
The file contains parameters for input to a program via the PARAMS parameter on
the command line.
- PARAM:
Same as PARM, but an older file type.
- GRAPH1:
The file is an IBIS Graphics-1 file.
- GRAPH2:
The file is an IBIS Graphics-2 file.
- GRAPH3:
The file is an IBIS Graphics-3 file.
- TABULAR:
The file is an IBIS Tabular file.
- COND:
input, string, maximum length 132
If
the string is null or contains only blanks, this argument will have no effect.
If the string contains one of the substrings listed below, the indicated
condition will be set for the specified file.
- NOLABELS:
Indicates that no label processing will be done for the file.
- NOBLOCK:
Indicates that if the file is an output file (OP=WRITE), the file will not be
blocked (RECSIZE=BUFSIZ).
- BINARY:
indicates
that the binary prefix and binary header, if they exist, will be unhidden to
the program (see U_NLB and U_NBB)
- VARREC:
Indicates that the file is a tape containing variable length records. NOLABELS
and NOBLOCK must also be specified with this argument.
The
string may contain more than one substring, such as 'COND', 'NOBLOCK NOLABELS'.
Default is to label and block files and hide the binary areas of the file.
- U_FILE:
input, integer
Used
to specify the file number to be accessed on a tape. If U_FILE = 0, the tape
advances to the next file (the default). If U_FILE > 0, the tape is moved to
the absolute file number given. U_FILE may not be less than zero. The first
file on a tape is file number one; thus if U_FILE = 1, the tape will be rewound.
- 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
1.3
Data Types and Host Representations,
for more information. 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. See
Table 1: Valid VICAR HOST Labels and Machine Types
.
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 datatypes, such as Array I/O or CONVERT OFF, pay
attention to the INTFMT label (via
x/zvget
)
and use the
x/zvtrans
representation (for binary labels see BINTFMT below). See
1.3
Data Types and Host Representations,
for more information. The valid values of INTFMT may change as the RTL is
ported to new machines. However, the currently valid values are listed. See
Table 2: Valid VICAR Integer Formats.
In addition, the following values are also accepted:
- NATIVE:
The host type of the currently running machine
- LOCAL:
Same as NATIVE
- REALFMT,
string
:The format used to represent floating point numbers in the file. INTFMT,
REALFMT, and HOST should all match, so if you change one please change all
three. REALFMT is a system label item in the image used by the RTL to
automatically convert data read in, via
x/zvread,
to the native floating point representation. It defaults to the representation
of the machine the program is running on, so it only need s 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
a
utomatically
convert data types, such as Array I/O or CONVERT OFF, pay attention to the
REALFMT label (via
x/zvget)
and use the
x/zvtrans
family of routines to translate to the native representation (for binary labels
see INTFMT below). See
1.3
Data Types and Host Representations,
for more information. The valid values of REALFMT may change as the RTL is
ported to new machines. However, the currently valid values are listed. See
Table 3: Valid VICAR Real Number Formats.
In addition, the following values are also accepted:
- NATIVE:
The host type 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 INTFMT 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 INTFMT 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 is OFF
(if not present the file's BHOST comes from the primary input, or defaults to
VAX-VMS). If is ON, the BHOST optional is ignored since the file's INTFMT gets
set to the native host. See
1.3
Data Types and Host Representations,
for more information. 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 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 is OFF (if not present the
file's BINTFMT comes from the primary input, or defaults to the integer format
for VAX-VMS). If is ON, the BINTFMT optional is ignored since the file's
BINTFMT gets set to the native host integer format. See
1.3
Data Types and Host Representations,
for more information. 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 change all three.
INTFMT 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 is OFF
(if not present the file's INTFMT comes from the primary input, or defaults to
the floating-point format for VAX-VMS). If is ON, the BREALFMT optional is
ignored since the file's BREALFMT is set to the native host floating-point
format. See
1.3
Data Types and Host Representations,
for more information. 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 datatype, 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 setting). If the optional is not present, the
file's BLTYPE comes from the primary input. See
1.3
Data Types and Host Representations,
for more information. 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
1.7.2
Programming and Binary Labels,
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/ztvtrans
family of routines. See
1.3
Data Types and Host Representations,
for details.
- 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 if BIN_CVT is
OFF (they are ignored if BIN_CVT is on). BIN_CVT is ignored for input files. See
1.7.2
Programming and Binary Labels,
for more details.
- UPD_HIST,
string: The valid values for UPD_HIST are ON and OFF. Default is OFF. UPD_HIST
controls whether or not to write a history label when the file is opened in
UPDATE mode. If it is ON, a label is written; if OFF (the default), no label is
written. UPD_HIST is only used in UPDATE mode, not in READ or WRITE. In WRITE
mode, a history label is always created).
3.2.2 x/zvclose—Close
a file
call xvclose(unit, status, <optionals>, ' ')
status = zvclose(unit, <optionals>, 0);
x/zvclose
will close an open image file. The use of
x/zvclose
is required in an application program.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
- STATUS:
output, integer
Error
status code. A value of one indicates success. See the optional arguments
OPEN_ACT, and IO_ACT under
x/zvopen
.
Optional
arguments:
- CLOS_ACT:
input, string, maximum length 132
Indicates
an action to be taken when the file is closed. If the string contains one of
the substrings listed below, the corresponding action will be taken. More than
one action may be specified.
- DELETE:
Causes the file to be deleted. Default is to retain the file.
- FREE:
Frees up the unit number so it can be used again. If this action is specified,
then the file can no longer be accessed using this unit number. If you want to
access the file again, x/zvunit must be called again. Since there are a limited
number of unit slots available, FREE is most useful when processing large
numbers of files. It allows VICAR to re-use this unit slot. If FREE is not
specified (the default), then the file may be opened again via
x/zvopen
without calling
x/zvunit,
but VICAR cannot assign this unit number to another file.
3.2.3 x/zveaction—Set
the default error handling action
call
xveaction (action, message)
status
= zveaction (action, message)
x/zveaction
sets the default error handling action for the entire VICAR job. It is used as
a default for all the error handling optionals such as OPEN_ACT, IO_ACT,
LAB_ACT, and ERR_ACT, and it is used directly by routines that do not have
their own independent error action arguments.
The
default if
x/zveaction
is not called is a null string for both the action and the message.
Arguments:
- ACTION:
input, string, maximum length 8
Indicates
the action to be taken by the Executive when an error condition is raised. A
valid string may contain one or more of three characters in any order, 'A',
'U', 'S'. The presence of each character has the following meanings:
- A:
an
error will cause an immediate program abort.
Otherwise,
the routine will return an error number in a status variable (if available).
- U:
an error will cause the string that is specified with the MESSAGE argument to
be printed.
- S:
an error will cause a system message to be printed.
The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ACTION
consists only of blanks, or if
x/zveaction
has never been called, an error will cause the Executive to return an error
number in a status variable (if one is available on the particular subroutine
that had the error).
- MESSAGE:
input, string, maximum length 132
MESSAGE
holds the user message that is issued when the ACTION argument contains the
substring 'U' and an error occurs. Even if ACTION is overridden by a action
optional (such as OPEN_ACT), the message specified by this argument may still
be used if the optional contains the substring 'U', unless,, it is overridden
by the corresponding message optional (such as OPEN_MES).
- STATUS:
output, integer
Error
status code. A value of one indicates success. See the optional arguments
OPEN_ACT, and IO_ACT under
x/zvopen
.
3.2.4 x/zvget—Retrieve
control block information
call xvget(unit, status, <optionals>, ' ')
status = zvget(unit, <optionals>, 0);
x/zvget
permits the programmer to request file information stored in the executive's
internal control block associated with a unit number. The item of information
is identified by an input key word field. The information is returned by
x/zvget
in the variable following the key word argument. The keyword-value pairs are
optional and may be entered pairwise in any order.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
- STATUS:
output, integer
Error
status code. A value of one indicates success. See the optional arguments
OPEN_ACT and IO_ACT under
x/zvopen
.
Optional
arguments:
- FORMAT:
output, string, maximum length 32
The
format of the pixel in an existing file. Possibilities are BYTE, HALF, FULL,
REAL, DOUB, COMP. WORD and COMPLEX are equivalent to HALF and COMP, but are
non-standard.
- NL:
output, integer
The
number of lines in the image
- NS:
output, integer
The
number of samples in the image.
- NB:
output, integer
The
number of bands in the image.
- N1,
N2, or N3
:
output, integer
The
number of pixels in the first, second and third dimensions of the image. The
values returned refer to the physical dimensions of the file and are
independent of file organization.
- DIM:
output, integer
The
dimension of the image. Valid values are 2 or 3. Currently, all new files
created by the executive have a DIM of 3. If DIM is 3 and NB is 1, then the
file effectively has a DIM of 2.
- ORG:
output, string, maximum length 32
The
file organization; organizations may be: BSQ (band sequential), BIP (band
interleaved by pixel), or BIL (band interleaved by line).
- NAME:
output, string, maximum length 132.
The
host system file name. For a display, the display id is returned.
- TYPE:
output, string, maximum length 32
The
type of file. Currently supported values are:
- IMAGE:
The file contains image data.
- PARM:
The file contains parameters for input to a program via the PARAMS parameter on
the command line.
- PARAM:
Same as PARM, but an older file type.
- GRAPH1:
The file is an IBIS Graphics-1 file.
- GRAPH2:
The file is an IBIS Graphics-2 file.
- GRAPH3:
The file is an IBIS Graphics-3 file.
- TABULAR:
The file is an IBIS Tabular file.
- PIX_SIZE:
output, integer
The
size of a pixel in bytes.
- BUFSIZ:
output, integer
The
size of the internal buffer being used for the I/O operations. If the file is a
tape, BUFSIZ will be equivalent to the block size of the tape in bytes.
- RECSIZE:
output, integer
The
record size in bytes. Equal to PIX_SIZE x N1.
- VARSIZE:
output, integer
The
record size of the last read for variable length records. VARSIZE is only valid
if COND VARREC was given in
x/zvopen
or
x/zvadd.
If VARREC was not specified, the value of VARSIZE is undefined.
- FLAGS:
output,
integer
FLAGS
is an integer whose bits represent various attributes of the unit in question.
To test a value in FLAGS, perform a bit-wise AND with it. For example, in the C
language you could test to see if a file is open with the code
int flags;
xvget(&unit, &stat, "FLAGS", &flags);
if (flags & OPEN) {. . .The
various flags listed here are predefined for applications written in C. Only
the names should be used, to protect against changes in future versions of the
executive.
- OPEN
indicates that the unit has already been opened by
x/zvopen.
- NO_LABELS
indicates that the file was opened with the COND, NOLABELS option.
- LABELS_MODIFIED
indicates that the label I/O routines have been called, modifying the image
label.
- UNIT_TAPE
indicates that the unit is a tape file.
- DATA_WRITTEN
indicates that the first logical data record was written. For internal use only.
- NOBLOCK
indicates that COND, NOBLOCK was specified at open time, and that tapes will be
unblocked (one logical record per physical record).
- BINARY
indicates
that COND, BINARY was specified at open time, causing binary labels, if
present, to be available to the application.
- VARREC
indicates
that COND, VARREC was specified at open time, allowing variable length records
on a tape.
- SEQUENTIAL_DEVICE
indicates that the device only allows sequential access, such as a magnetic
tape.
- 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
1.3
Data Types and Host Representations,
for more information. 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. See
Table 1: Valid VICAR HOST Labels and Machine Types.
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 datatypes, such as Array I/O or CONVERT OFF, pay
attention to the INTFMT label (via
x/zvget
)
and use the
x/zvtrans
representation (for binary labels see BINTFMT below). See
Data Types and Host Representations
(page 9), for more information. The valid values of INTFMT may change as the
RTL is ported to new machines. However, the currently valid values are listed.
See
Table 2: Valid VICAR Integer Formats.
In addition, the following values are also accepted:
- NATIVE:
The host type of the currently running machine
- LOCAL:
Same as NATIVE
- REALFMT,
string
:The format used to represent floating point numbers in the file. INTFMT,
REALFMT, and HOST should all match, so if you change one please change all
three. REALFMT is a system label item in the image used by the RTL to
automatically convert data read in, via
x/zvread,
to the native floating point representation. It defaults to the representation
of the machine the program is running on, so it only need s 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
a
utomatically
convert data types, such as Array I/O or CONVERT OFF, pay attention to the
REALFMT label (via
x/zvget)
and use the
x/zvtrans
family of routines to translate to the native representation (for binary labels
see INTFMT below). See
Data Types and Host Representations
(page 9), for more information. The valid values of REALFMT may change as the
RTL is ported to new machines. However, the currently valid values are listed.
See
Table 2: Valid VICAR Integer Formats.
In addition, the following values are also accepted:
- NATIVE:
The host type 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 INTFMT 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 INTFMT 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 is OFF
(if not present the file's BHOST comes from the primary input, or defaults to
VAX-VMS). If is ON, the BHOST optional is ignored since the file's INTFMT gets
set to the native host. See
1.3
Data Types and Host Representations,
for more information. 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 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 is OFF (if not present the
file's BINTFMT comes from the primary input, or defaults to the integer format
for VAX-VMS). If is ON, the BINTFMT optional is ignored since the file's
BINTFMT gets set to the native host integer format. See
1.3
Data Types and Host Representations,
for more information. 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 (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 datatype, 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 setting). If the optional is not present, the
file's BLTYPE comes from the primary input. See
1.3
Data Types and Host Representations,
for more information. 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
1.7.2
Programming and Binary Labels,
for more details.
- 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 change all three.
INTFMT 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 is OFF
(if not present the file's INTFMT comes from the primary input, or defaults to
the floating-point format for VAX-VMS). If is ON, the BREALFMT optional is
ignored since the file's BREALFMT is set to the native host floating-point
format. See
1.3
Data Types and Host Representations,
for more information. 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(including NATIVE
and LOCAL).
- IMG_REC:
output, integer
The
number of the last record read or written using x/zvread and x/zvwrit. In BSQ
this is the last line.
- UPD_HIST,
string: The valid values for UPD_HIST are ON and OFF. Default is OFF. UPD_HIST
controls whether or not to write a history label when the file is opened in
UPDATE mode. If it is ON, a label is written; if OFF (the default), no label is
written. UPD_HIST is only used in UPDATE mode, not in READ or WRITE. In WRITE
mode, a history label is always created).
3.2.5 x/zvopen—Open
a file
call xvopen(unit, status, <optionals>, ' ')
status = zvopen(unit, <optionals>, 0);
x/zvopen
prepares the file for I/O processing. If the file is an input file, it verifies
the file's existence and the existence and form of its label.
For
output files,
x/zvopen
will ensure that the file is the right size, that being either the size
indicated by the programmer on the call to
x/zvopen,
the size field for the file, or the input file, in that order. If the file does
not exist,
x/zvopen
will create it. If the file exists but is too small,
x/zvopen
will expand it. If the file is a tape file, it will be positioned to the
desired file.
For
all output files,
x/zvopen
will create, unless the programmer negates this default function, an output
label for the file.
A
call to
x/zvopen
is required before I/O processing can take place on the file.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
- STATUS:
output, integer
Error
status code. A value of one indicates success. The error codes are listed in
10
Appendix B: Error Messages
.
See also the optional arguments OPEN_ACT, IO_ACT, LAB_ACT, and ERR_ACT.
Optional
arguments:
- U_NL:
input, integer
Indicates
that the Executive is to create an output file capable of holding NL lines. If
the file associated with the unit number already exists but is too small, it
will be enlarged.
- U_NS:
input, integer
As
in NL but for samples.
- U_NB:
input, integer
As
in NL but for bands.
- U_NBB:
input, integer
For
output files, indicates the number of bytes of binary prefix that will precede
each image line. The binary prefix will be stored in an area before each image
line. It will be hidden from subsequent programs unless the program opens the
file with a COND value that includes BINARY. Subsequent reads of a file with
COND including BINARY will return the binary prefix to each line ahead of the
line in the read buffer. An output file with a non-zero U_NBB will expect the
binary prefix to precede the image line in the
x/zvwrit
buffer. For input files U_NBB is ignored. Defaults to 0.
- U_NLB:
input, integer
For
output files, indicates the number of lines of binary header information that
is to precede the image lines in an image file. The image I/O subsystem will
expect these lines to be written with
x/zvwrit
prior to the writing of the image lines. The image header will remain hidden
from subsequent programs unless those programs open the file with a value of
COND that includes the substring, BINARY. For input files,
U_NLB
is ignored. Defaults to 0.
- U_N1,
U_N2, U_N3
:
input, integers
Indicate
that the Executive is to ensure that the output file will have the dimensions
specified by the values associated with the respective arguments. U_N1 refers
to the first file dimension, U_N2 the second, and U_N3 the third. These
arguments are useful for the program which does not care about the file
organization, and simply wants to deal with records and pixels. The relation
between these arguments and the normal NL, NS, NB arguments are as follows:
|
ORG
|
N1
|
N2
|
N3
|
|
BSQ
|
NS
|
NL
|
NB
|
|
BIL
|
NS
|
NB
|
NL
|
|
BIP
|
NB
|
NS
|
NL
|
Table
11: File Organization
- ADDRESS
output, pointer (integer for FORTRAN)
ADDRESS
is a special argument which instructs the executive to cause the image file to
be treated as an array of memory, and returns to the program the address of the
beginning of the image data. The program may then use this address to
manipulate the image data. No calls to
x/zvread
or
x/zvwrit
are needed, although they will still function. See the examples Section for
details of how to use this argument in FORTRAN and C.
Note:
There is a VMS memory management flaw that occasionally surfaces when using the
ADDRESS optional. If you are opening and closing very large array I/O files,
you might get a VASFULL (Virtual Address Space Full) error message, even though
there should be plenty of virtual memory left. If this happens (and you're
programming in C), try doing a large malloc () immediately followed by a free
() call for the same memory area before opening any array I/O files. It is best
to put the calls at the top of the program. This solution sounds like a
no-operation, and from the programmer's point of view it is, but it causes VMS
to do things that get around the problem. The amount of memory you allocate
should enough to cover all dynamic memory allocated by your program, plus about
100K or so. Try a megabyte to start with, and adjust it upwards or downwards as
needed.
Example:
free (malloc (1024*1024)); /* Fix Virtual Address Space Full error */
- U_ORG:
input, string
Indicates
the file organization that the programmer expects or desires for the file. The
acceptable organizations are band sequential, band interleaved by pixel, and
band interleaved by line. The respective values that represent these states
are, 'BSQ', 'BI P', and 'BIL'. If the file is being created by the
x/zvopen,
then the indicated organization will become the new file organization. If the
file is an existing file that is not to be deleted and created again, then the
Executive will check the indicated organization against that of the existing
file. If they are not the same then an error condition will be raised. If the
image file has less than three dimensions, this argument will be ignored.
- U_DIM:
input, integer
Number
of dimensions of dimensions the file has. Current default if U_DIM not
specified is 3. 4 is permitted but not supported.
- METHOD:
input, string
Indicates
the access method for the file. Valid values are 'SEQ' (sequential) or
'RANDOM'. The default is 'SEQ'. 'SEQ' and 'RANDOM' only effect the internal
buffering used by the executive; if the method is 'SEQ', then a larger buffer
will be used for I/O, resulting in more efficient processing. If 'RANDOM' is
given, a smaller buffer will be used to avoid reading unnecessary data.
If
the file is a tape file, an error condition will be raised if 'RANDOM' is
specified. The specification of 'RANDOM' for a file with OP equal to 'WRITE' is
equivalent to 'SEQ'.
- OP:
input, string
Indicates
the intended operation. Valid values are 'READ', 'WRITE', and 'UPDATE'. Default
is 'READ'.
Output
files must have OP equal to WRITE.
- OPEN_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of the open. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings:
- A:
an error will cause an immediate program abort. Otherwise, the routine will
return an error number in STATUS.
- U:
an error will cause the string that the user has specified with the OPEN_MES
optional to be printed.
- S:
an error will cause a system message to be printed.
The
three values are independent. Thus 'SA' will cause a system message to be
printed and the program to abort if an error occurs. If OPEN_ACT consists only
of blanks, an error will cause the
x/zvopen
to return an error number in STATUS. Default is the action specified with
x/zveaction.
- IO_ACT:
input, string
As
in OPEN_ACT but for
x/zvread
and
x/zvwrit.
Default is specified with
x/zveaction.
- LAB_ACT:
input, string
Specified
as is OPEN_ACT, LAB_ACT defines a default error action to be taken by the XL
routines. It can be overridden in a call to an XL routine with the ERR_ACT
optional. The message given if a 'U' is given is specified by LAB_MESS. The
default for LAB_ACT is given by
x/zveaction.
- CLOS_ACT:
input, string
Indicates
an action to be taken when the file is closed. If the string contains one of
the substrings listed below, the corresponding action will be taken. More than
one action may be specified.
- DELETE:
Causes the file to be deleted. Default is to retain the file.
- FREE:
Frees up the unit number so it can be used again. If this action is specified,
then the file can no longer be accessed using this unit number. If you want to
access the file again, x/zvunit must be called again. Since there are a limited
number of unit slots available, FREE is most useful when processing large
numbers of files. It allows VICAR to re-use this unit slot. If FREE is not
specified (the default), then the file may be opened again via x/zvopen without
calling x/zvunit, but VICAR cannot assign this unit number to another file.
- O_FORMAT:
input, string
For
input files this argument is ignored. For output files, O_FORMAT becomes the
format of the output file. Valid values are 'BYTE', 'HALF', 'FULL', 'REAL',
'DOUB', and 'COMP'. 'WORD' and 'COMPLEX' are equivalent to 'HALF' and 'COMP',
respectively, but for consistency are no longer to be used. The Executive will
ensure that the output pixels have the indicated FORMAT by converting if
necessary. A related argument is U_FORMAT which is the format of the pixels
returned or passed to
x/zvread
or
x/zvwrit.
Default is the primary input FORMAT, that is, the format of the pixels in the
input file.
- U_FORMAT:
input, string
Indicates
the format of pixels in the buffer returned by
x/zvread
or the format of the pixels the program will pass to
x/zvwrit.
If for input files U_FORMAT is not equal to the input file format, then VICAR
will convert. On output, if U_FORMAT is not equal to O_FORMAT then VICAR will
convert. Default for input files is the input file format; for output files, it
is the primary input U_FORMAT.
- I_FORMAT:
input, string, maximum length 8
If
an input file is unlabeled and does not have the default pixel format of
'BYTE', then this optional may be used to set the proper format; valid values
are ' BYTE', 'HALF', 'FULL','REAL', 'DOUB', and 'COMP'. 'WORD' and 'COMPLEX'
are equivalent to 'HALF' and 'COMP', respectively, but for consistency should
no longer be used.
- OPEN_MES:
input, string, maximum length 132
OPEN_MES
holds the user message that is issued when the OPEN_ACT argument contains the
substring 'U' and an error occurs. Default is specified by
x/zveaction.
- IO_MESS:
input, string, maximum length 132
Holds
the user message that is issued under certain settings of the IO_ACT argument
when I/O errors occur. Default is specified by
x/zveaction.
- LAB_MESS:
input, string, maximum length 132
Holds
the user message that is issued when the ERR_ACT optional is not given to an XL
routine, and the LAB_ACT optional contains the substring 'U'. Default is
specified by
x/zveaction.
- TYPE:
input, string, maximum length 8
With
this argument, the programmer can designate the type of the output file
desired. If the file already exists the Executive will alter any file name and
label items that indicate the file type. On input, the file will be checked for
type. If a mismatch occurs between the TYPE argument and the actual file type,
an error status condition will be raised. Currently supported values are:
- IMAGE:
The file contains image data.
- PARM:
The file contains parameters for input to a program via the PARAMS parameter on
the command line.
- PARAM:
Same as PARM, but an older file type.
- GRAPH1:
The file is an IBIS Graphics-1 file.
- GRAPH2:
The file is an IBIS Graphics-2 file.
- GRAPH3:
The file is an IBIS Graphics-3 file.
- TABULAR:
The file is an IBIS Tabular file.
- COND:
input, string, maximum length 132
If
the string is null or contains only blanks, this argument will have no effect.
If the string contains one of the substrings listed below, the indicated
condition will be set for the specified file.
- NOLABELS:
Indicates that no label processing will be done for the file.
- NOBLOCK:
Indicates that if the file is an output file (OP=WRITE), the file will not be
blocked (RECSIZE=BUFSIZ).
- BINARY:
indicates
that the binary prefix and binary header, if they exist, will be unhidden to
the program (see U_NLB and U_NBB)
- VARREC:
Indicates that the file is a tape containing variable length records. NOLABELS
and NOBLOCK must also be specified with this argument.
The
string may contain more than one substring, such as 'COND', 'NOBLOCK NOLABELS'.
Default is to label and block files and hide the binary areas of the file.
- U_FILE:
input, integer
Used
to specify the file number to be accessed on a tape. If U_FILE = 0, the tape
advances to the next file (the default). If U_FILE > 0, the tape is moved to
the absolute file number given. U_FILE may not be less than zero. The first
file on a tape is file number one; thus if U_FILE = 1, the tape will be rewound.
- 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
1.3
Data Types and Host Representations,
for more information. 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. See
Table 1: Valid VICAR HOST Labels and Machine Types
.
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 datatypes, such as Array I/O or CONVERT OFF, pay
attention to the INTFMT label (via
x/zvget
)
and use the
x/zvtrans
representation (for binary labels see BINTFMT below). See
1.3
Data Types and Host Representations,
for more information. The valid values of INTFMT may change as the RTL is
ported to new machines. However, the currently valid values are listed. See
Table 2: Valid VICAR Integer Formats.
In addition, the following values are also accepted:
- NATIVE:
The host type of the currently running machine
- LOCAL:
Same as NATIVE
- REALFMT,
string
:The format used to represent floating point numbers in the file. INTFMT,
REALFMT, and HOST should all match, so if you change one please change all
three. REALFMT is a system label item in the image used by the RTL to
automatically convert data read in, via
x/zvread,
to the native floating point representation. It defaults to the representation
of the machine the program is running on, so it only need s 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
a
utomatically
convert data types, such as Array I/O or CONVERT OFF, pay attention to the
REALFMT label (via
x/zvget)
and use the
x/zvtrans
family of routines to translate to the native representation (for binary labels
see INTFMT below). See
1.3
Data Types and Host Representations,
for more information. The valid values of REALFMT may change as the RTL is
ported to new machines. However, the currently valid values are listed. See
Table 3: Valid VICAR Real Number Formats.
In addition, the following values are also accepted:
- NATIVE:
The host type 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 INTFMT 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 INTFMT 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 is OFF
(if not present the file's BHOST comes from the primary input, or defaults to
VAX-VMS). If is ON, the BHOST optional is ignored since the file's INTFMT gets
set to the native host. See
1.3
Data Types and Host Representations,
for more information. 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 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 is OFF (if not present the
file's BINTFMT comes from the primary input, or defaults to the integer format
for VAX-VMS). If is ON, the BINTFMT optional is ignored since the file's
BINTFMT gets set to the native host integer format. See
1.3
Data Types and Host Representations,
for more information. 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 change all three.
INTFMT 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 is OFF
(if not present the file's INTFMT comes from the primary input, or defaults to
the floating-point format for VAX-VMS). If is ON, the BREALFMT optional is
ignored since the file's BREALFMT is set to the native host floating-point
format. See
1.3
Data Types and Host Representations,
for more information. 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 datatype, 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 setting). If the optional is not present, the
file's BLTYPE comes from the primary input. See
1.3
Data Types and Host Representations,
for more information. 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
1.7.2
Programming and Binary Labels,
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/ztvtrans
family of routines. See
1.3
Data Types and Host Representations,
for details.
- 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 if BIN_CVT is
OFF (they are ignored if BIN_CVT is on). BIN_CVT is ignored for input files. See
1.7.2
Programming and Binary Labels,
for more details.
- UPD_HIST,
string: The valid values for UPD_HIST are ON and OFF. Default is OFF. UPD_HIST
controls whether or not to write a history label when the file is opened in
UPDATE mode. If it is ON, a label is written; if OFF (the default), no label is
written. UPD_HIST is only used in UPDATE mode, not in READ or WRITE. In WRITE
mode, a history label is always created).
3.2.6 x/zvread—Read
a line
call
xvread(unit, buffer, status, <optionals>, ' ')
status
= zvread(unit, buffer, <optionals>, 0);
x/zvread
will read a single line from the file associated with the UNIT. The data will
be returned in BUFFER and the status indicator will be returned in STATUS.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
- BUFFER:
output, array of anything
Array
to receive input data.
- STATUS:
output, integer
Error
status code. A value of one indicates success. The error codes are listed in
10
Appendix B: Error Messages.
See also the optional arguments OPEN_ACT, IO_ACT, LAB_ACT, and ERR_ACT.
Optional
arguments:
- LINE:
input, integer
Indicates
the starting line for the read. For BSQ images, by default the starting line is
incremented from its position in the last read until each band is exhausted
(after NL reads), at which time it resets to the first line for the new band.
For BIL images, the line number increments after NB reads, and for BIP images
the line number increments after NS x NB reads.
- SAMP:
input, integer
Indicates
the starting sample (starting pixel in the SAMP dimension) for the read. For
BSQ and BIL images, the default is 1. For BIP images, the starting sample is
incremented from the last read by default.
- BAND:
input, integer
Indicates
the starting band for the read. For BIP images, the default is 1. For BIL
images, the starting band is incremented from the last read by default. For BSQ
images, the starting band increments when each band is exhausted, that is,
every NL lines.
- NSAMPS:
input, integer
Indicates
the number of samples to be accessed in a single operation. Defaults to the
number of pixels in an image line if the file organization is BSQ or BIL. Not
yet available for BIP images.
- NBANDS:
input, integer
As
in NLINES but for the band dimension. Currently only available for a file
organization of BIP.
- NLINES:
input, integer
Indicates
the number of lines to be accessed in a single operation. Defaults to 1.
- IO_MESS:
input, string, maximum length 132
Holds
the user message that is issued under certain settings of the IO_ACT argument
when I/O errors occur. Default is specified by
x/zveaction.
- OP:
input, string
Indicates
the intended operation. Valid values are 'READ', 'WRITE', and 'UPDATE'. Default
is 'READ'.
Output
files must have OP equal to WRITE.
- OPEN_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of the open. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings:
- A:
an error will cause an immediate program abort. Otherwise, the routine will
return an error number in STATUS.
- U:
an error will cause the string that the user has specified with the OPEN_MES
optional to be printed.
- S:
an error will cause a system message to be printed.
The
three values are independent. Thus 'SA' will cause a system message to be
printed and the program to abort if an error occurs. If OPEN_ACT consists only
of blanks, an error will cause the
x/zvopen
to return an error number in STATUS. Default is the action specified with
x/zveaction.
- U_FORMAT:
input, string
Indicates
the format of pixels in the buffer returned by
x/zvread
or the format of the pixels the program will pass to
x/zvwrit.
If for input files U_FORMAT is not equal to the input file format, then VICAR
will convert. On output, if U_FORMAT is not equal to O_FORMAT then VICAR will
convert. Default for input files is the input file format; for output files, it
is the primary input U_FORMAT.
3.2.7 x/zvsignal—Signal
an error
call xvsignal (unit, status, abend_flag)
status = zvsignal (unit, status, abend_flag)
x/zvsignal
will signal an error if one has occurred in any of the image I/O routines
(x/zv...) or label I/O routines (x/zl...). It uses the same internal routines
that the OPEN_ACT, IO_ACT, LAB_ACT, and ERR_ACT optionals use, so no error
checking is duplicated.
Arguments:
- UNIT:
input, integer
The
unit number of a file.
x/zvsignal
will use this unit number to determine routine in which an error may have
occured, and if it was a read or write, the line number in the image.
- STATUS:
input, integer
The
status returned from a previous subroutine call to be checked.
- ABEND_FLAG:
input, logical*4 or integer
Flag
to indicate whether ABEND (abnormal program terminator) should be called to
terminate execution of the program. If ABEND_FLAG is TRUE (non-zero) and an
error has occurred,
x/zvsignal
will not return and the program will terminate abnormally.
3.2.8 x/zvunit—Assign
a unit number to a file
call xvunit(unit, name, instance, status, <optionals>, ' ')
status = zvunit(unit, name, instance, <optionals>, 0);
x/zvunit
will return an unused file unit number. The programmer may use this number in
any of the above routines. This routine must be called to obtain a unit number
for every file that is to be accessed by the VICAR image and label I/O
subroutine package.
Under
UNIX, filenames accepted by the RTL (via
x/zvunit,
either the U_NAME optional or the INP or OUT parameters) can contain
environment variables andusernames. A reference of the form $
var
will be replaced with the value of the environment variable
var.
The name of the environment variable (but not the dollar sign) may optionally
be enclosed in curly braces (${
var}).
A tilde (
~)
followed by a username will be replaced with the home directory of that user. A
tilde without a username will be replaced with the home directory of the
current account. Both of these expansions exactly mimic the behavior of the
C-shell, so they should be familiar to most UNIX users.
Arguments:
- UNIT:
output, integer
An
unused file unit number that may be used with any of the image I/O routines.
- NAME:
input, string, maximum length 32
Indicates
which file is to be associated with the returned unit number. By convention,
the string 'INP' denotes the input files, and the string, 'OUT', the output
files that appear on the command line. If NAME is any other string other than
'INP' or 'OUT',
x/zvunit
will create a new file for output and return the unit number for that file. The
size and other attributes of the file will be determined by
x/zvopen
as for any output file asociated with 'OUT'.
- INSTANCE:
input, integer
Indicates
which file of possibly several 'INP' or 'OUT' files is to be selected.
- STATUS:
output, integer
Error
status indicator. A value of one indicates success. Errors are handled in the
manner specified by
x/zveaction
.
Optional
arguments:
- U_NAME:
input, string, maximum length 132
If
the NAME argument is not 'INP' or 'OUT' then
x/zvunit
will return the unit number of a file not associated with any file name
appearing on the command line. This argument is used to name that file. It may
take any form that a command line file name may take. To get back unit numbers
for more than one file, increment the INSTANCE argument for each file.
3.2.9 x/zvwrit—Write
an image line
call xvwrit(unit, buffer, status, <optionals>, ' ')
status = zvwrit(unit, buffer, <optionals>, 0);
x/zvwrit
will
write a single line of pixels to the image file associatedwith the UNIT. The
data will be written from BUFFER and the status indicator will be returned in
STATUS.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
- BUFFER:
output, array of anything
Array
containing output data.
Optional
arguments:
- LINE:
input, integer
Indicates
the starting line for the read. For BSQ images, by default the starting line is
incremented from its position in the last read until each band is exhausted
(after NL reads), at which time it resets to the first line for the new band.
For BIL images, the line number increments after NB reads, and for BIP images
the line number increments after NS x NB reads.
- SAMP:
input, integer
Indicates
the starting sample (starting pixel in the SAMP dimension) for the read. For
BSQ and BIL images, the default is 1. For BIP images, the starting sample is
incremented from the last read by default.
- BAND:
input, integer
Indicates
the starting band for the read. For BIP images, the default is 1. For BIL
images, the starting band is incremented from the last read by default. For BSQ
images, the starting band increments when each band is exhausted, that is,
every NL lines.
- NSAMPS:
input, integer
Indicates
the number of samples to be accessed in a single operation. Defaults to the
number of pixels in an image line if the file organization is BSQ or BIL. Not
yet available for BIP images.
- NBANDS:
input, integer
As
in NLINES but for the band dimension. Currently only available for a file
organization of BIP.
- NLINES:
input, integer
Indicates
the number of lines to be accessed in a single operation. Defaults to 1.
- U_NL:
input, integer
Indicates
that the Executive is to create an output file capable of holding NL lines. If
the file associated with the unit number already exists but is too small, it
will be enlarged.