8.2 Utility
API
8.2.1 abend/zabend—Terminate
processing abnormally
call abend()
zabend()
abend
issues a message indicating that
abend
was called, and then calls
x/zvend
with a status of zero to indicate a program failure. Any open VICAR files are
closed and write buffers flushed before termination.
8.2.2 x/zmove—Move
bytes from one buffer to another
call xmove(from, to, len)
zmove(from, to, len);
Move
bytes from one buffer to another. Overlapping moves are handled correctly,
unlike the C routine
memcpy().
Arguments:
- FROM:
pixel-array, input
FROM
is the buffer to move the bytes from (the source). It may
not
be a FORTRAN CHARACTER*n variable.
- TO:
pixel-array, input
TO
is the buffer to move the bytes to (the destination). It may
not
be a FORTRAN CHARACTER*n variable.
- LEN:
integer, input
The
number of bytes to move. There is no restriction on how many bytes can be
moved, except available memory. LEN is measured in
bytes,
not
pixels.
8.2.3 x/zvbands—Return
band usage information
call xvbands(sb, nb, nbi)
zvbands(sb, nb, nbi);
x/zvbands
is analogous to
x/zvsize
in its usage. It returns information from the command line given in either the
BANDS or the SB, NB parameters, or, if the parameters were not specified, from
the input file size.
Arguments:
- SB:
output, integer
The
starting band for processing. If the BANDS parameter (BANDS = (SB, NB))was
given, the first element of BANDS is used. If BANDS was not given, and the SB
parameter was given, SB is used. Otherwise, the default is 1.
- NB:
output, integer
The
number of bands for processing. If the BANDS parameter was given, the second
element of BANDS is used. If BANDS was not given, and the NB parameter was
given, NB is used. Otherwise, the default value is the number of bands in the
primary input.
- NBI:
output, integer
The
number of bands in the primary input file.
8.2.4 x/zvcmdout—Sends
a command string to TAE to be executed
call xvcmdout(command, status)
status = zvcmdout(command);
Sends
a command string to TAE to be executed, and returns output values in the
interactive parblock, accessible by the
x/zviparm
family of routines. The command must be a TAE intrinsic command, or a procedure
PDF that uses only intrinsic commands, i.e. no processes, no DCL or shell. This
is mainly intended for running VIDS procedures from within a program, but it
may have other applications as well.
This
routine is quite similar to
x/zvcommand.
The only difference is that
x/zvcmdout
makes any output variables accessible. This is most useful with the VIDS JGET
command, which returns values to the caller in TAE variables. These variables
are placed in the interactive parblock.
Arguments:
- COMMAND:
string, input
The
command string to execute. It may be a TAE intrinsic command or a procedure PDF
which uses intrinsic commands only ( this includes almost all VIDS PDF's). All
potential outputs from the executed command will be in the form of NAME
parameters. The values you wish returned should be declared as local variables
in the PDF for the program (the one you're writing, not the one being called).
These local variables should then be passed in the COMMAND string as values for
the NAME parameters in the executed command. The variables can then be accessed
from the interactive parblock via the
x/zviparm
family
of routines.
- 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 command didn't
execute or the outputs didn't get returned correctly, and the returned values
should not be used.
8.2.5 x/zvcommand—Execute
a VICAR command string
call xvcommand(command,status)
status =zvcommand(command,status)
x/zvcommand
passes a command string on to the VICAR supervisor (TAE) for execution.
The
command may be a VICAR intrinsic command or a procedure PDF that uses only
VICAR intrinsic commands (or other procedure PDF's). Process PDF's and DCL
commands are not allowed. Examples of commands that are allowed are VIDS
commands and tape mounting commands (but NOT tape initialization since it uses
DCL commands).
Arguments:
- COMMAND:
input, string
The
command string is passed in exactly as the user would type it on the command
line. It may be either a FORTRAN or a C string.
- STATUS:
output, integer
Error
status code. A value of one indicates success. The error code may be
XVCOMMAND_ERROR ( meaning an internal error with interprocess communications)
or it will be a success/failure indicator (either it's equal to SUCCESS or it's
not). The actual error code from the command may be returned for some types of
commands, but all you can count on is a success/fail indication.
If
an error occurs, the action specified by
x/zveaction
is performed. Even if 'S' is not specified in the
x/zveaction
call (which tells VICAR not to print system messages), the executed program
will still print error messages from the executed command. The only message
that 'S' controls is the message from VICAR saying that
x/zvcommand
failed.
8.2.6 x/zvfilename—Returns
a filename suitable for use with a system open() call
call xvfilename(in_name, out_name, status)
status = zvfilename(in_name,out_name, out_len);
Given
a filename as input by the user, this function returns a filename suitable for
use with a system
open()
call or other non-VICAR file operation. For UNIX, this means that environment
variables and
~username
are expanded. For VMS, this means the old-style temporary filename suffix. Z
xx
is added. For both systems, the “
+
“ form of temporary file is expanded.
This
function does not need to be called if the RTL is used for I/O (it is called
internally by
x/zvopen).
But, any program that gets a filename from the user for use in non-RTL I/O
should make use of this function.
Because
this function is only intended for use with non-VICAR I/O, only diskfile names
are supported. Names specifying tape files or memory files will be treated as
if they were disk files, which could provide surprising results. “
*”
as a wildcard character is legal in this function, and is passed through
unchanged (so the output has a “
*”
in it).
For
UNIX, the expansions are as follows:
- $var:Expand
environment variable “
var”.
- ${var}:Expand
environment variable “
var”.
- ~user:
Expand to home directory of user”
user”.
- ~:
Expand to home directory of current user (
$HOME).
- $$:
Insert a single
$
(no environment variable).
- +:
Expand to translation of
”$VTMP/”
for temporary files.
For
VMS, the expansions are as follows:
- +:
Expand to “
vtmp:”
(if subdirectory present) or “
vtmp:[000000]”(if
no subdirectory) for temporary files.
- no
+
and no suffix
:
Append “. Z
xx”
(where
xx
comes from
v2$pidcode)
for old-style temporary names.
Under
VMS, both expansions may occur on the same name.
The
temporary filename locations (
$VTMP
and
vtmp)
are set up in vicset2.
Arguments:
- IN_NAME:
string, input
IN_NAME
is the input filename that you want converted.
- OUT_NAME:
string, output
The
resultant converted string is returned in OUT_NAME.
- OUT_LEN:
integer, input
This
argument specifies the length of the output string buffer OUT_NAME (to avoid
overflow). A length of 0 means the buffer is unlimited, and it is the caller's
responsibility to make sure there is no overflow. OUT_LEN is only present in
the C interface.
- 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 filename did not
translate properly, and the returned value should not be used.
8.2.7 x/zvfilpos—Return
the current tape position
POSITION = x/zvfilpos(UNIT)
x/zvfilpos
looks up the current file position of the given unit if it is a tape, and
returns it in POSITION. If the file is not on tape, -1 is returned.
This
routine assumes that file UNIT has already been opened with
x/zvopen.
Arguments:
- UNIT:
input, integer
The
unit number of the tape from
x/zvunit.
UNIT must have already been opened with a call to
x/zvopen.
8.2.8 x/zvmessage—Log
a user message
call xvmessage(message, key)
zvmessage(message, key)
x/zvmessage
is the primary subroutine to be used to print messages on the user terminal or
in log files. It will work whether or not the program is under the VICAR
supervisor, and allows the specification of a “key” for help on the
message.
Arguments:
- MESSAGE:
input, string
The
message to be logged. May be either a C or FORTRAN string.
- KEY:
input, string
KEY
is an optional argument used to give a
message
key
.
A message key is used to look up help information for an error message. It
consists of a string of the form “
facility-key”,
where
facility
is the same for all error messages described in one package, and
key
is a unique identifier for that error messages.
For
example, a program named COPY could have a series of error messages, all of
which would begin with the facility name “COPY”, using keys such as
“COPY-NO INPUT” or “COPY-END OFFILE”. The error
messages would then be stored in a file called COPYFAC. MSG in the standard TAE
error message file format. The user could then use HELP-MESSAGE or the
“?” command to get help on any error messages received. Details on
the use of message files can be found in the
TAE
Application Programmer's Reference Manual
.
A
null value (empty string) or a single blank given for KEY is equivalent to not
specifying the argument.
8.2.9 x/zvselpi—Selects
the file to use as the primary input
call xvselpi(instance)
zvselpi(instance);
Selects
the file to use as the primary input. The primary input is normally the first
file given in the INP parameter. It is used for several purposes. If file
attributes like size, type, etc. aren’t specified when opening a file,
defaults are taken from the primary input. When creating a new output file,
history and property labels for it are copied from the primary input, in order
to maintain the processing history and file attributes.
In
the rare cases where the first INP file is not appropriate for the primary
input, calling
x/zvselpi
allows you to change the file that is used as the primary input, or to disable
the primary input altogether. The file selected must still be one of the files
in the INP parameter. For example, you might be taking
n
input files and creating
n
output files after doing the same processing to each. You would want to set the
primary input for each output file to the corresponding input file, in order to
preserve the history labels. Or, you may want to create a file with no history
labels whatsoever (except for the current task).
This
routine should be called before the
x/zvopen
of the output file you want associated with the input. The only routines that
use the primary input directly are
x/zvopen,
x/zvsize,
and
x/zvbands.
The primary input in effect at the time each of these routines is called
determines which input file is used. You may change
x/zvselpi
after the
x/zvopen
statement, even if you do more processing to the file. It will still use the
primary input in effect at the time the file was opened.
It
is slightly more efficient to call
x/zvselpi
before you open the primary input file for other reasons, because it avoids an
extra file open. However, this should not have a big impact.
There
is no status return from this routine.
Arguments:
- INSTANCE:
integer, input
Determines
which instance of the INP parameter to use as the primary input. Numbering
starts at one, so you may restore the default behavior by calling
x/zvselpi
with an INSTANCE of 1. An INSTANCE of 4 would mean the fourth item in the INP
parameter, etc.
If
INSTANCE is zero, then the primary input is disabled. Provide all necessary
file size and type parameters to
x/zvopen,
since there are no defaults. The history labels also will not be copied, so the
current task will be the first (and only) task in the new file's label. This is
the primary reason for disabling the primary input.
8.2.10 x/zvselpiu—Selects
the file to use as primary input
call xvselpiu(unit)
zvselpiu(unit);
Selects
the file to use as the primary input. The primary input is normally the first
file given in the INP parameter. It is used for several purposes. If file
attributes like size, type, etc. aren’t specified when opening a file,
defaults are taken from the primary input. When creating a new output file,
history and property labels for it are copied from the primary input, in order
to maintain the processing history and file attributes.
In
the rare cases where the first INP file is not appropriate for the primary
input, calling
x/zvselpiu
allows you to change the file that is used as the primary input. This unit then
becomes the primary input. This allows any file, not just one associated with
the INP parameter, to be the primary input. The file associated with the unit
may be open or closed,but you should not free the unit (CLOS_ACT, FREE) as long
as it is the primary input. A primary input unit of 0 is valid. To disable the
primary input completely, call
x/zvselpi(0);
do not use
x/zvselpiu()
for this case.
This
routine should be called before the
x/zvopen
of the output file you want associated with the input. The only routines that
use the primary input directly are
x/zvopen,
x/zvsize,
and
x/zvbands.
The primary input in effect at the time each of these routines is called
determines which input file is used. You may change
x/zvselpiu
after the
x/zvopen
statement, even if you do more processing to the file. It will still use the
primary input in effect at the time the file was opened.
It
is slightly more efficient to call
x/zvselpiu
before you open the primary input file for other reasons, because it avoids an
extra file open. However, this should not have a big impact.
There
is no status return from this routine.
Arguments:
- UNIT:
input, integer
Unit
number of file from
x/zvunit.
8.2.11 x/zvsize—Return
image size values
call xvsize(sl, ss, nl, ns, nli, nsi)
zvsize(sl, ss, nl, ns, nli, nsi);
x/zvsize
searches the user parameters and the first input file for image size values.
The values are returned as described below under “arguments”. If
there is an input file, it must be opened before calling
x/zvsize.
For
3 dimensional files
x/zvsize
must be supplimented with
x/zvbands,
which returns infomation about bands..
Arguments:
- SL:
output, integer
SL
is the starting line which should be used when reading the input. If the SIZE
parameter was given, SL is taken from the first element in the size field. If
SIZE was not given, but the SL parameter was, SL is taken from the SL
parameter. Otherwise, SL defaults to a value of one.
- SS:
output, integer
SS
is the starting sample which should be used when reading the input. If the SIZE
parameter was given, SS is taken from the second element in the size field. If
SIZE was not given, but the SS parameter was, SS is taken from the SS
parameter. Otherwise, SS defaults to a value of one.
- NL:
output, integer
NL
is the number of lines which should be read from the input and written to the
output. If the SIZE parameter was given, NL is taken from the third element in
the size field. If SIZE was not given, but the NL parameter was, NL is taken
from the NL parameter. Otherwise, NL defaults to the size of the primary input.
a value of zero for NL is treated as if no value was given.
- NS:
output, integer
NS
is the number of samples per line which should be read from the input and
written to the output. If the SIZE parameter was given, NS is taken from the
fourth element in the size field. If SIZE was not given, but the NS parameter
was, NS is taken from the NS parameter. Otherwise, NS defaults to the size of
the primary input. A value of zero for NS is treated as if no value was given.
- NLI:
output, integer
NLI
is the number of lines in the primary input. It is obtained from the NL
optional to
x/zvget.
- NSI:
output, integer
NSI
is the number of samples per line in the primary input. It is obtained from the
NS optional to
x/zvget.