INP specifies the name of the input file. The input must have a valid VICAR label. Note: If no output file name is given, the input file's label will be modified directly.
OUT is the name of the output file to which the data and the modified label are to be written. If OUT is omitted from the command line, the label items are added to the input file directly.
The label items which are to be added. The items are given as a
list in a single string parameter, in the form
key(element)=value-list
where "key" is a valid (0 - 8 character) label keyword, "element"
is an optional starting element number (an integer), and "value-list"
is the list of values to be associated with that keyword.
The operation differs slightly depending on whether or not the
starting element number is given.
If the element is not given, i.e. the item is of the form
"key=value-list", then the entire label item is affected. The
indicated keyword is added to the label, with one or more values
specified by "value-list". If the keyword already exists, an
error message is produced.
If the element is given, then only parts of the label item are
affected. If the keyword currently exists in the file, then the
indicated values are inserted into it, starting at element number
"element". For instance, if the label item "LIST" had three values
(1,2,3), and the following was in the label-add ITEM string:
"LIST(2)=(10,11)", then values 10 and 11 would be inserted into
LIST starting at position 2. The new value of LIST would be
(1,10,11,2,3).
If the element is given, but the keyword does not currently exist
in the file, the element number is ignored and a new label item
is created containing the values in "value-list".
A value of -1 for the element number indicates the end of the label
item, i.e. all elements will be appended to the end of the item.
If the same keyword appears twice in "value-list", each is treated
independently, i.e. the first one is used, then the second one. If
the first one causes the number of elements or the relative position
of an element to change, the second one uses the NEW positions, values,
and number of elements.
"Value-list" is a list of values, enclosed in parentheses, and
separated by commas. If there is only one value, the parentheses
are not necessary.
All of the values in "value-list" should be of the same type:
integer, real, doub(le), or string. The type should also match the type
of the existing label, if "element" is given. The LABEL program will
try to convert to the appropriate type, but if it can't it will give
an error. It can convert integers to real, doub(le) or string, and
reals to doub(le) or string. Any other conversion is an error.
The four types are differentiated by the way in which they are
specified. Strings should be contained in single quotes. The quotes
are not strictly necessary if there are no commas, spaces, or parentheses
in the string, but they should normally be included anyway. Standard
FORTRAN notation for integers, reals and doub(le)s is understood. Doub(le)s
are real values with more than 6 significant digits.
Examples of valid "value-list" specifications:
Specification Meaning
------------- -------
787 single integer
(21) single integer
(6,-9,42) list of three integers
+3e2 single real
-2.000001 single doub(le)
(3.14159, 2) list of two reals. The integer 2 is
converted to a real: (3.14159, 2.0)
'a string item' single string
('another string item') single string
('string 1','string 2') list of two strings
('string 1', 123, 4.5, wow) list of four strings. The values get converted
to strings: ('string 1', '123', '4.5', 'wow')
Using this input format, the entire list of items is input
as a single string, such as
"slope=-45.8, planet='Jupiter' avgdn = 128 coord=(86.3, 44.8)"
This string stores the real value "slope", the string value
"planet", the integer value "avgdn", and the two element real
value "coord".
The name of the task heading or history subset under which the label item is to be stored. The presence of TASK implies that the history label will be modified, so TYPE is unnecessary. If you wish to add to a property label, use PROPERTY instead. If neither TASK nor PROPERTY are given, and TYPE is omitted, all labels will be placed in the history label under the heading of the current task (LABEL if an output file is given, the last task otherwise). An error occurs if both TASK and PROPERTY are given, or if TASK is given with TYPE=PROPERTY.
Since the same program may be run on an image several times, it is possible to have multiple history task headings with the same name. INSTANCE=n is used to refer to the n-th occurence of the named history task. If INSTANCE is not specified, 1 is assumed. If TASK is not specified, or if the property label is being modified, then INSTANCE is ignored.
The name of the property subset under which the label item is to be stored. The presence of PROPERTY implies that the property label will be modified, so TYPE is unnecessary. If you wish to add to a history label, use TASK instead. PROPERTY is mandatory for property labels, so even if you say TYPE=PROPERTY you must still specify a property name. An error occurs if both PROPERTY and TASK are given, or if PROPERTY is given with TYPE=HISTORY.
Specifies whether the items will be added to the HISTORY or PROPERTY label. TYPE is not normally needed, since the presence of the TASK parameter implies history labels, while the presence of the PROPERTY parameter implies property labels. TYPE may be used for error-checking, however, as TASK, PROPERTY, and TYPE must all agree on the type of labels being added. ! .SUBCMD CREATE LABEL-CREATE takes a file with no label and, using the information given by the user, generates a system label for it. VICAR in some cases can attempt to determining the image size for you on a VMS machine if you don't specify it, but to avoid potential problems it is recommended that you give the input size with NL, NS, and NB when it is known. The image size cannot be automatically determined on a Unix machine. In addition, if the pixel format is not specified, byte format is assumed. If the file organization is not specified, BSQ (band sequential) is assumed. Unless you specify otherwise via the HOST label, the input file is assumed to be in the data format of the machine you are running on. If this is not the case (i.e. the file was created on a VAX and you are running on a Sun), then you need to specify HOST.
The name of a single input file which does not have a valid VICAR label. The input is assumed unconditionally to have no label, and the new label is simply prepended to the output.
The name of a single output file to receive the new label and the data from the input.
The number of lines in the input image. Note that this number is not a window but the actual number of image lines (not including any binary headers), and is unconditionally assumed to be correct.
The number of samples in the input image. Note that this number is not a window but the actual number of samples (not including any binary headers), and is unconditionally assumed to be correct.
The number of bands in the input image. Note that this number is not a window but the actual number of bands (not including any binary headers), and is unconditionally assumed to be correct. Default is a one band image.
The number of bytes of binary prefix which precede each image record in the output file. This number is added to NS (for BSQ or BIL files) or NB (for BIP files) to get the total size of an image record (i.e. the values for NS and NB should not include NBB). The BINARY keyword must be specified in order for NBB to take effect. The default for NBB is 0.
The number of lines of binary header that precede the image data. This number is added to the number of image records to get the total number of record in the image (i.e. the values for NL, NS, and NB should not include NLB). The BINARY keyword must be specified in order for NLB to take effect. The default for NLB is 0.
The format of the pixels in the file. Defaults to BYTE. The valid values are: BYTE Single byte unsigned binary integer HALF Half-precision (usually two bytes) signed integer FULL Full-precision (usually four bytes) signed integer REAL Single-precision floating point number DOUB Double-precision floating point number COMP Complex pairs of REAL numbers in the order (real,imaginary)
ORG provides a means of specifying the file organization. Organizations may be : BSQ (band sequential), BIP (band interleaved by pixel), or BIL (band inerleaved by line). Default is BSQ.
If BINARY is specified as a keyword, the new file is created with a binary label specified by NLB and NBB. The data in the binary labels comes from the input file, i.e. if NLB is 2 then the first two lines of the input file will make up the binary header. See also NLB and NBB.
WINDOW provides a means of extracting a subset of the input for writing to the output. Its format is the same as that of the VICAR size field, WINDOW = (sl,ss,nl,ns) where sl is the starting line to read, ss is the starting sample, nl is the number of lines to read, ns is the number of samples to be extracted from each line. Note that the window is independent of the parameters NL and NS. NL and NS specify the physical size of the input, and window provides a subset of the input for output. To create a 3-dimensional window, the BANDS parameter must also be used. If BINARY is set, then WINDOW and BANDS are ignored.
BANDS provides a means of extracting a subset of the input for writing to the output. Its format is as follows: BANDS = (sb,nb) where sb is the starting band to read, nb is the number of bands to be extracted. Note that the BANDS parameter is independent of the NB parameter. NB specifies the physical size of the input, and BANDS provides a subset of the input for output. See also WINDOW. If BINARY is set, then WINDOW and BANDS are ignored.
COMMENT is an optional string label item for the user to insert into the label. It is stored under the keyword COMMENT in the current task. It may be up to 132 characters in length.
HOST provides a means to specify the type of machine the data came from. If the image was created on a machine type other than the one you are running on, then the image data will likely be in a different data format, e.g. VAX floating point instead of IEEE floating point. Setting the proper value for HOST allows other VICAR programs to access the image data properly. The default for HOST is "NATIVE", meaning the data format for the machine that LABEL-CREATE is running on. The valid values may expand as VICAR is ported to other machines, but as of this writing they are: NATIVE The machine LABEL-CREATE is currently running on (default). LOCAL Same as NATIVE. ALLIANT Alliant FX series computer. CRAY Cray (port is incomplete). DECSTATN DECstation (any DEC MIPS-based RISC machine) running Ultrix. HP-700 HP 9000 Series 700 workstation. MAC-AUX Macintosh running A/UX. MAC-MPW Macintosh running native mode with Mac Programmers Workbench. SGI Silicon Graphics workstation. SUN-3 Sun 3, any model. SUN-4 Sun 4 or SPARCstation, or clone such as Solbourne. TEK Tektronix workstation. VAX-VMS VAX running VMS.
INTFMT specifies the format used to represent integers in the image. It should rarely be used, as it defaults to the integer format for the machine specified in HOST. The valid values may expand as VICAR is ported to other machines, but as of this writing they are: NATIVE The format for the machine LABEL-CREATE is currently running on. LOCAL Same as NATIVE. HIGH High byte first, "big endian", used with most hosts. LOW Low byte first, "little endian", used with VAX-VMS and DECSTATN.
REALFMT specifies the format used to represent floating-point data in the
image. It should rarely be used, as it defaults to the floating-point
format for the machine specified in HOST.
The valid values may expand as VICAR is ported to other machines, but as
of this writing they are:
NATIVE The format for the machine LABEL-CREATE is currently running on.
LOCAL Same as NATIVE.
IEEE IEEE 754 format, with high-order bytes firt, used with most hosts.
RIEEE Reverse IEEE format, like IEEE but with bytes reversed. Used
on DECSTATN.
VAX VAX format, single precision is VAX F, double is VAX D, used on
VAX-VMS.
BHOST provides a means to specify the type of machine the data in the binary label came from. If the binary label was created on a machine type other than the one you are running on, then the binary label data will likely be in a different data format, e.g. VAX floating point instead of IEEE floating point. Setting the proper value for BHOST allows other VICAR programs to access the image data properly. BHOST defaults to the value given for HOST (which in turn defaults to the native format), so BHOST should rarely be needed. BHOST is ignored if BINARY is not set. The valid values may expand as VICAR is ported to other machines, but as of this writing they are: NATIVE The machine LABEL-CREATE is currently running on (default). LOCAL Same as NATIVE. ALLIANT Alliant FX series computer. CRAY Cray (port is incomplete). DECSTATN DECstation (any DEC MIPS-based RISC machine) running Ultrix. HP-700 HP 9000 Series 700 workstation. MAC-AUX Macintosh running A/UX. MAC-MPW Macintosh running native mode with Mac Programmers Workbench. SGI Silicon Graphics workstation. SUN-3 Sun 3, any model. SUN-4 Sun 4 or SPARCstation, or clone such as Solbourne. TEK Tektronix workstation. VAX-VMS VAX running VMS.
BINTFMT specifies the format used to represent integers in the image. It should rarely be used, as it defaults to the integer format for the machine specified in BHOST. BINTFMT is ignored if BINARY is not set. The valid values may expand as VICAR is ported to other machines, but as of this writing they are: NATIVE The format for the machine LABEL-CREATE is currently running on. LOCAL Same as NATIVE. HIGH High byte first, "big endian", used with most hosts. LOW Low byte first, "little endian", used with VAX-VMS and DECSTATN.
BREALFMT specifies the format used to represent floating-point data in the
image. It should rarely be used, as it defaults to the floating-point
format for the machine specified in BHOST. BREALFMT is ignored if BINARY
is not set.
The valid values may expand as VICAR is ported to other machines, but as
of this writing they are:
NATIVE The format for the machine LABEL-CREATE is currently running on.
LOCAL Same as NATIVE.
IEEE IEEE 754 format, with high-order bytes firt, used with most hosts.
RIEEE Reverse IEEE format, like IEEE but with bytes reversed. Used
on DECSTATN.
VAX VAX format, single precision is VAX F, double is VAX D, used on
VAX-VMS.
BLTYPE is a string specifying the type of the binary label, if present. It is optional, but is highly recommended to document what kind of binary label is present. No checking is performed on the value for BLTYPE, but it should correspond to one of the registered binary label type names. Consult the cognizant programmer for the program that created the image if you do not know the binary label type name. ! .SUBCMD DELETE LABEL-DELETE can be used to delete all or part of the history or property label information in a given VICAR image file. The extent of deletion is controlled by the different parameters. For help on the operation of each parameter, type HELP parameter-name from tutor mode. If only an input file is given, the input file label is modified, and no output is produced. If an output file is given, then the input file is not modified and the output file is copied from the input. Examples: LABEL-DELETE A B The entire history label is deleted from A, and the result is written to B. Only the system and property labels remain. LABEL-DELETE A 'PROPERTY The entire property label is deleted from A. The system and history labels remain. LABEL-DELETE A KEYS=COMMENT Every occurrence of the item COMMENT is deleted from the history label of A, leaving the rest of the label intact. No output file is produced. Examples (cont.) LABEL-DELETE A KEYS=/ALL 'HISTORY Every keyword is deleted from each history task, leaving the history subsets themselves intact. LABEL-DELETE A B TASKS=(GEOMA,LABEL) Deletes every occurence of the history subsets created by the tasks GEOMA and LABEL (including the current task). LABEL-DELETE A B PROPERTY=MAP Deletes the entire MAP property, including the property header. Examples (cont.) LABEL-DELETE A B KEYS=(NAH,COMMENT) TASKS=(LABEL,GEOMA) INSTNCES=(1,2) Here let's assume that GEOMA was run on A once, and it wrote the item NAH. LABEL was run on the image twice previously (making the current task instance 3), writing the keyword COMMENT only once. The item NAH will then be deleted from the first (only) instance of GEOMA, and COMMENT will be deleted from the one instance of LABEL in which it is found. LABEL-DELETE A B KEYS=MANYVAL ELEMENT=3 NELEMENT=2 Elements 3 and 4 will be deleted from all occurrences of the item MANYVAL in the history label. If any occurrence of MANYVAL has 2 or less elements, nothing will be changed for that occurrence. If any occurrence of MANYVAL has 3 elements, only the third will be deleted. Examples (cont.) LABEL-DELETE A B KEYS=YOW TASK=FUNSTUF INSTANCE=2 ELEMENT=5 NELEMENT=1 Element 5 will be deleted from the item YOW found in the second instance of the task FUNSTUF. LABEL-DELETE A B KEYS=COORD PROPERTY=MINE ELEMENT=2 NELEMENT=2 Elements 2 and 3 will be deleted from the item COORD found in the property subset MINE. LABEL-DELETE A B KEYS=/ALL ELEMENT=2 NELEMENT=-1 Elements 2 through the end of the item will be deleted for every item in the history label. The result will be that all history label items in the file become single-valued. !
Name of a single input file. It must have a valid VICAR label. If no output file is given, the input file label is modified.
Name of an optional output file. If an output file name is given, the modified label and the image data are copied to the output file, and the input file remains unchanged. If no output file name is given, the input file label is modified directly.
Indicates the names, or keywords, of specific items to be deleted. If nothing is given under TASKS or PROPERTY, then every occurrence of the given keywords will be deleted from the appropriate (history or property) label section. A list of specific subsets can be given with the TASKS and INSTNCES parameters or PROPERTY parameter to narrow the scope of the deletion. ELEMENT and NELEMENT may also be used to limit what is deleted. In addition, the value /ALL may be given for this parameter, specifying that every key is to be deleted provided it does not form part of a subset header. The effect is to empty the subset without deleting the subset itself.
TASKS can be used to limit the deletion process to certain history subsets or task labels within the history label. If items were given under the parameter KEYS, then the task names given limit the deletion of those items to the named tasks. Otherwise, the subsets named by TASKS are deleted. The parameter INSTNCES can be used to limit which tasks are looked in for items (if KEYS is given) or which tasks are deleted (if KEYS not given). The presence of TASKS implies that the history label will be modified, so TYPE is unnecessary. If you wish to delete a property label, use PROPERTY instead. If neither TASKS nor PROPERTY are given, and TYPE is omitted, then the HISTORY label is assumed. An error occurs if both TASKS and PROPERTY are given, or if TASKS is given with TYPE=PROPERTY.
The parameter INSTNCES can be used to limit the history tasks in which items are deleted (if KEYS is given), or the tasks which are deleted (if KEYS is not given). If specific task names were given in TASKS, then each value given for INSTNCES will be applied to every subset task name. If nothing was specified in TASKS (and TYPE=HISTORY), then every task with the named instances will be deleted. For example, TASKS=(STRETCH,LGEOM) INSTNCES=(1,4) would refer to the first and fourth instances of both the STRETCH task and the LGEOM task. If one or more of the tasks does not exist, an informational message is issued, but no fatal error occurs. If the property label is being modified instead of the history label, then INSTNCES is ignored.
PROPERTY can be used to limit the deletion process to certain property subsets within the property label. If items were given under the parameter KEYS, then the property names given limit the deletion of those items to the named property. Otherwise, the subsets named by PROPERTY are deleted. The presence of PROPERTY implies that the property label will be modified, so TYPE is unnecessary. If you wish to delete a history label, use TASKS instead, or specify TYPE=HISTORY. If neither TASKS nor PROPERTY are given, and TYPE is omitted, then the HISTORY label is assumed. An error occurs if both TASKS and PROPERTY are given, or if PROPERTY is given with TYPE=HISTORY.
Specifies the starting element to delete in each item for multi-valued label items. This parameter limits the action of the other parameters. Without ELEMENT, each selected item is deleted in its entirety. With ELEMENT, only part of each selected item is normally deleted. If the element specified does not exist in a particular item, then no action is taken on that item, and no warning is issued. If ELEMENT is given as 1 (the default value), then the entire item may be deleted, depending on the value of NELEMENT. This parameter is normally used in conjunction with NELEMENT.
Specifies the number of elements to delete in each item for multi-valued label items. This parameter limits the action of the other parameters. NELEMENT defaults to -1. If NELEMENT is given as -1 (or defaulted), then all the remaining elements in the item are deleted. If ELEMENT is greater than 1, it deletes all elements from ELEMENT to the end of the item. If ELEMENT is 1, the entire item is deleted. If there are not enough elements in a particular item to satisfy the request, then the number of elements deleted is reduced to fit. No warning is issued. For example, if an item has 5 elements, and you request ELEMENT 4, NELEMENT 3, that would mean you want to delete elements 4, 5, and 6. Since there are only 5 elements, only 4 and 5 are deleted. This parameter is normally used in conjunction with ELEMENT.
Specifies whether the items will be deleted from the HISTORY or PROPERTY label. If TYPE is not specified, the type is assumed from the presence of the TASKS or PROPERTY parameters. If neither TASKS, PROPERTY, or TYPE is specified, then HISTORY labels are assumed. If both the TASKS and PROPERTY labels are specified, or if they disagree with a given TYPE, then an error occurs. ! .SUBCMD LIST LABEL-LIST is used to list out the contents of the label in various formats (specified by EXTENT). Up to 10 input files may be given. No processing is done on any of the files. Multi-valued items are listed enclosed in parentheses and separated by commas.
The names of from one to ten input files. The input files must have valid labels.
EXTENT specifies how and how much of the label is
to be listed. The valid values are:
ALL SYSTEM, PROPERTY, and HISTORY together.
SYSTEM Lists out the important system label information
in a readable format.
PROPERTY Lists out a header for each property subset,
followed by all keyword-value pairs in that subset.
TASKS Lists out a header for each history subset task,
containing the task name, name of the user who ran the
task, and the date and time of the task.
HISTORY Lists out a header for each history subset task,
followed by all keyword-value pairs in that subset.
DUMP Lists out every keyword-value pair in the label.
No attempt is made to format beyond the most basic level.
PACK specifies whether or not to pack more than one label item onto one line in the output. Valid values are PACK and NOPACK. NOPACK is the default. If NOPACK is in effect, every label item is listed on a line by itself. If there is more than one element in an item, as many elements as will fit are listed on the same line. If PACK is in effect, then label items are packed together as much as possible on the output line, separated by spaces. If there is not room for the label key and at least one of the values, a new line is started. Only label items from one property or history subset are packed together. PACK and NOPACK apply when EXTENT is PROPERTY, HISTORY, or DUMP. It also applies when EXTENT is ALL, but only to the property and history portions. ! .SUBCMD REMOVE LABEL-REMOVE can be used to remove the the binary header, binary prefix or both the binary header and prefix from the input, and write the results with the data in an output file. If the output is a tape, the NOBLOCK keyword may be specified to prevent the tape from being blocked (useful for sending to foreign installations).
VICAR labeled input file whose label is to be removed. The input file data will be copied to the output, and the input file will remain unchanged.
The required output file. The output file will consist only of image data and will have no label. Take care to record the image size of the output file, since VICAR may not be able to determine the proper size if needed on a future date.
SIZE can be used to copy only a portion of the input to the output file. It is in standard VICAR size field format SIZE=(sl,ss,nl,ns) , where sl is the starting line to read, ss is the starting sample, nl is the number of lines to read, ns is the number of samples to be extracted from each line. Note that SIZE works only in the line and sample directions--to provide a complete subsection specification, you must also use the BANDS parameter. SIZE is ignored if BINARY is set.
BANDS can be used to copy only a portion of the input to the output file. It has the following format: BANDS= (sb,nb) where sb is the starting band to read, nb is the number of bands to read. The output file size will be nl x ns x nb, where nl and ns are specified with the SIZE parameter. BANDS is ignored if BINARY is in effect.
If NOBLOCK is specified, then if the output is tape the tape will not be blocked, that is, there will be one record per block on the tape. If NOBLOCK is not specified, then the output tape will be in blocks of in the neighborhood of 20,000 bytes. If the output is disk, this parameter has no effect.
If BINARY is specified as a keyword, the binary label of the file is not
removed with the VICAR label. This option tells the program to determine
the size of the binary header and prefix and generates an output file
containing the binary header and prefix. NOBINARY causes LABEL-REMOVE
to remove the binary label along with the VICAR label. NOBINHEAD causes
LABEL-REMOVE to remove the binary header. NOBINPREF causes LABEL-REMOVE
to remove the binary prefix. The default is NOBINARY.
If BINARY is specified, then the SIZE and BANDS parameters are disabled,
so the entire file will be copied.
!
.SUBCMD REPLACE
LABEL-REPLACE is used in the same fashion as LABEL-ADD, except
1) The item must already exist, and
2) The item may be in the system label as well as the history and
property labels.
If TASK is specified, TYPE=HISTORY is assumed and an error occurs if
TYPE is different. Likewise, if PROPERTY is specified, TYPE=PROPERTY
is assumed.
To replace an item in the system label, the keyword SYSTEM must be
given, and TASK and PROPERTY may not be specified. Great care should
be given to replacing any system items, however, as it may affect how
the data is read by the executive. In particular, NS, RECSIZE, BUFSIZE,
and LBLSIZE should never be changed. The results would be unpredictable.
INP specifies the name of the input file. The input must have a valid VICAR label. Note: If no output file name is given, the input file's label will be modified directly.
OUT is the name of the output file to which the data and the modified label are to be written. If OUT is omitted from the command line, the label items are replaced in the input file directly.
The label items which are to be replaced. The items are given as a
list in a single string parameter, in the form
key(element)=value-list
where "key" is a valid (0 - 8 character) label keyword, "element"
is an optional starting element number (an integer), and "value-list"
is the list of values to be associated with that keyword.
The operation differs slightly depending on whether or not the
starting element number is given.
If the element is not given, i.e. the item is of the form "key=value-list",
then the entire label item is replaced. The indicated keyword is
first deleted from the label in its entirety, then the new item is
added with values specified in "value-list". The keyword must
previously exist in the label, or an error message will be issued.
If the element is given, then only parts of the label item are
affected. If the keyword currently exists in the file, then the
indicated values replace existing elements in it, starting at element
number "element". For instance, if the label item "LIST" had four
values (1,2,3,4), and the following was in the label-replace ITEM
string: "LIST(2)=(10,11)", then values 10 and 11 would be put into
LIST starting at position 2, replacing the old values at those
positions. The new value of LIST would be (1,10,11,4).
If the element is given, but the keyword does not currently exist
in the file, the element number is ignored and a new label item
is created containing the values in "value-list". This is slightly
different from the action when "element" is not given, as the item
does not have to previously exist.
A value of -1 for the element number indicates the end of the label
item, i.e. all elements will be appended to the end of the item.
If the same keyword appears twice in "value-list", each is treated
independently, i.e. the first one is used, then the second one. If
the first one causes the number of elements or the relative position
of an element to change, the second one uses the NEW positions, values,
and number of elements.
"Value-list" is a list of values, enclosed in parentheses, and
separated by commas. If there is only one value, the parentheses
are not necessary.
All of the values in "value-list" should be of the same type:
integer, real, doub(le) or string. The type should also match the type
of the existing label, if "element" is given. The LABEL program will
try to convert to the appropriate type, but if it can't it will give
an error. It can convert integers to real, doub(le) or string, and
reals to doub(le) or string. Any other conversion is an error.
The four types are differentiated by the way in which they are
specified. Strings should be contained in single quotes. The quotes
are not strictly necessary if there are no commas, spaces, or parentheses
in the string, but they should normally be included anyway. Standard
FORTRAN notation for integers and reals is understood. Doub(le)s
are real values with more than 6 significant digits.
Examples of valid "value-list" specifications:
Specification Meaning
------------- -------
787 single integer
(21) single integer
(6,-9,42) list of three integers
+3e2 single real
-2.000001 single doub(le)
(3.14159, 2) list of two reals. The integer 2 is
converted to a real: (3.14159, 2.0)
'a string item' single string
('another string item') single string
('string 1','string 2') list of two strings
('string 1', 123, 4.5, wow) list of four strings. The values get converted
to strings: ('string 1', '123', '4.5', 'wow')
Using this input format, the entire list of items is input
as a single string, such as
"slope=-45.8, planet='Jupiter' avgdn = 128 coord=(86.3, 44.8)"
This string replaces the real value "slope", the string value
"planet", the integer value "avgdn", and the two element real
value "coord".
The name of the task heading or history subset under which the label item is to be stored. The presence of TASK implies that the history label will be modified, so TYPE is unnecessary. If you wish to replace a property label, use PROPERTY instead. If neither TASK nor PROPERTY are given, and TYPE is omitted, all labels will be placed in the history label under the heading of the current task (LABEL if an output file is given, the last task otherwise). An error occurs if both TASK and PROPERTY are given, or if TASK is given with TYPE=PROPERTY or TYPE=SYSTEM.
Since the same program may be run on an image several times, it is possible to have multiple history task headings with the same name. INSTANCE=n is used to refer to the n-th occurence of the named history task. If INSTANCE is not specified, 1 is assumed. If TASK is not specified, or if the property or system labels are being modified, then INSTANCE is ignored.
The name of the property subset under which the label item is to be stored. The presence of PROPERTY implies that the property label will be modified, so TYPE is unnecessary. If you wish to replace a history label, use TASK instead. PROPERTY is mandatory for property labels, so even if you say TYPE=PROPERTY you must still specify a property name. An error occurs if both PROPERTY and TASK are given, or if PROPERTY is given with TYPE=HISTORY or TYPE=SYSTEM.
TASK specifies whether the items will be replaced in the SYSTEM, HISTORY, or PROPERTY label. TYPE is not normally needed for history and property labels, since the presence of the TASK parameter implies history labels, while the presence of the PROPERTY parameter implies property labels. TYPE may be used for error-checking, however, as TASK, PROPERTY, and TYPE must all agree on the type of labels being added. To replace an item in the system label, the keyword SYSTEM must be given. Great care should be given to replacing any system items, however, as it may affect how the data is read be the executive. In particular, NS, RECSIZE, BUFSIZE, and LBLSIZE should never be changed. The results would be unpredictable. If TYPE=SYSTEM is given, then TASK and PROPERTY may not be used. ! .SUBCMD SWITCH LABEL-SWITCH creates an output file containing the following: the history and property labels of the first input file the system label of the second input the data of the second input file INVOCATION: LABEL-SWITCH (A,B) C where A, B, and C are VICAR labeled files.
The two input files whose labels are to be switched. See help on LABEL-SWITCH for all the details.
A single output file containing the data of the second input and the history and property labels of the first input.