It is designed primarily for users who need to know about HDF files at the level of individual data elements. It is not designed to provide a comprehensive high-level view of the contents of an HDF file -- other tools and utilities should be used for that purpose. To use hdfed one should be familiar with the components of an HDF file covered in the HDF Specifications manual.
15.16.2 Command-line Syntax
The syntax of hdfed ishdfed [-nobackup][-batch] filename
If a file named filename exists, it is opened and a backup is made of the file. Files may also be opened from within the editor.
-batch flag is useful when a group of commonly-used commands are included in a UNIX shell script. The following is an example of such a script, using the C-shell, that lists information about the groups in a specified HDF file.
#!/bin/csh -f
set file=$1
shift
hdfed -batch $file -nobackup << EOF
info -all group $*
close
quit
EOF
echo ""To receive usage information, as well as a quick list of the hdfed commands, type the command
hdfed -helpWhile in hdfed, the standard command prompt is displayed.
hdfed>Many hdfed commands have qualifiers, or flags. For example, the command info may be followed by the
-all, -long, -group, or -label flags.All of the commands and flags can be abbreviated to the extent that their abbreviations are unique. For example,
-he is ambiguous as it could stand for either the -hexadecimal or the -help flags, but -hel is not ambiguous.
any-hdfed-command -helpNote that usage information cannot be obtained by typing only the command, with no flags. There are other hdfed commands, such as
delete, that do not require an argument, so watch out for this kind of error.There is a subset of hdfed commands where predicates, items, and comparators are used. Items are used to denote an HDF object type and can be any of the following identifiers;
tag, ref, image_size, or label. A comparator is an expression used to compare an item with a user-defined value, and can be any of the following:
|
=
|
equal
|
|
!=
|
not equal
|
|
<
|
less than
|
|
<=
|
less than or equal
|
|
>
|
greater than
|
|
>=
|
greater than or equal
|
User-defined values can be either a number (with or without a decimal point) or a string of characters delimited by double-quotes. Predicates consist of items, comparators and user-defined values and are of the syntax:
item comparator-value
Or they may consist of the identifier group, as in the next group command. Some examples of predicates are:next group
next (same as "next group" as "group" is the default identifier)
next tag = 720
next ref = 2
next image_size < 1000
next label = "abc"
The following is a more inclusive description of the hdfed commands.Syntax: help
Flags: None
Description: Prints a help screen describing the basic purpose and functionality of the hdfed utility.
Usage Example:
hdfed> help
hdfed allows sophisticated HDF users the ability to manipulate the
elements in an HDF file. These manipulations include selecting groups
...
The open commandSyntax: open [-nobackup] filename
Flags:
-nobackup The specified file name is not backed up.Description: Opens the specified HDF file.
Usage Example:
hdfed> open -help
open <file> [-nobackup]
-nobackup Don't make a backup for this file.
hdfed>
hdfed> open h1
hdfed>
The info commandSyntax: info [-all] [-long] [-group] [-label]
Flags:
-all Displays information for all of the objects in the current file.
-long Displays the long form of the information.
-group Organizes the information into groups.
-label Shows any labels.Description: Displays information for a data object. The listing for special elements will contain a special tag value (in Item 13 below it's 18347, which corresponds to
DFTAG_VS) and the text "Unknown Tag".Usage Example:
hdfed> info -all -label -long
(1) Version Descriptor : (Tag 30)
Ref: 1, Offset: 202, Length :92 (bytes)
(2) Scientific Data : (Tag 702)
Ref: 2, Offset: 294, Length : 200 (bytes)
(3) Number type : (Tag 106)
Ref: 2, Offset: 494, Length : 4 (bytes)
(4) SciData description : (Tag 701)
Ref: 2, Offset: 498, Length : 2 (bytes)
(5) SciData max/min : (Tag 707)
Ref: 2, Offset: 520, Length : 4 (bytes)
*(6) Numeric Data Group : (Tag 720)
Ref: 2, Offset: 524, Length : 12 (bytes)
Label: Experiment #1
(7) Data Id Label : (Tag 104)
Ref: 3, Offset: 536, Length : 17 (bytes)
(8) Scientific Data : (Tag 702)
Ref: 4, Offset: 553, Length : 400 (bytes)
(9) Number type : (Tag 106)
Ref: 4, Offset: 953, Length : 4 (bytes)
(10) SciData description : (Tag 701)
Ref: 4, Offset:957, Length : 22 (bytes)
(11) Numeric Data Group : (Tag 720)
Ref: 4, Offset: 979, Length : 8 (bytes)
Label: Experiment #2
(12) Data Id Label : (Tag 104)
Ref: 5, Offset: 987, Length : 17 (bytes)
(13) Unknown Tag : (Tag 18347)
Ref: 8, Offset: 0, Length : 40(bytes
hdfed>
hdfed> info -group -all
**Group 1:
Numeric Data Group : (Tag 720) Ref 2
Scientific Data : (Tag 702) Ref 2
SciData description : (Tag 701) Ref 2
SciData max/min : (Tag 707) Ref 2
**Group 2:
Numeric Data Group : (Tag 720) Ref 4
Scientific Data : (Tag 702) Ref 4
SciData description : (Tag 701) Ref 4
**These do not belong to any group:
Version Descriptor : (Tag 30) Ref 1
Number Type : (Tag 106) Ref 2
Data Id Label : (Tag 104) Ref 3
Number Type : (Tag 106) Ref 4
Data Id Label : (Tag 104) Ref 5
hdfed>
The prev commandSyntax: prev predicate-list
Flags: None.
Description: Moves to the next object that satisfies the predicate list.
Usage Example:
hdfed> info -all
(1) Version Descriptor : (Tag 30) Ref 1
(2) Scientific Data : (Tag 702) Ref 2
(3) Number type : (Tag 106) Ref 2
(4) SciData description : (Tag 701) Ref 2
(5) SciData max/min : (Tag 707) Ref 2
*(6) Numeric Data Group : (Tag 720) Ref 2
(7) Data Id Label : (Tag 104) Ref 3
(8) Scientific Data : (Tag 702) Ref 4
(9) Number type : (Tag 106) Ref 4
(10) SciData description : (Tag 701) Ref 4
(11) Numeric Data Group : (Tag 720) Ref 4
(12) Data Id Label : (Tag 104) Ref 5
hdfed>
hdfed> ! The '*' in the first column marks the current
hdfed> ! position.
hdfed> ! The 'next' and 'prev' commands work with predicates.
hdfed> ! If I want to move to the max/min element,
hdfed> ! I can use the 'tag=' predicate.
hdfed>
hdfed> prev tag=707
hdfed> info
(5) SciData max/min (SciData) : (Tag 707) Ref:2
hdfed>
The next commandSyntax: next predicate-list
Flags: None.
Description: Moves to the next object that satisfies the predicate.
Usage Example:
hdfed> ! Move in the file using next and prev
hdfed> ! The move direction depends on the relative positions.
hdfed> ! so it is often necessary to do an 'info -all' first.
hdfed> info -all
(1) Version Descriptor : (Tag 30) Ref 1
(2) Scientific Data : (Tag 702) Ref 2
(3) Number type : (Tag 106) Ref 2
(4) SciData description : (Tag 701) Ref 2
*(5) SciData max/min : (Tag 707) Ref 2
(6) Numeric Data Group : (Tag 720) Ref 2
(7) Data Id Label : (Tag 104) Ref 3
(8) Scientific Data : (Tag 702) Ref 4
(9) Number type : (Tag 106) Ref 4
(10) SciData description : (Tag 701) Ref 4
(11) Numeric Data Group : (Tag 720) Ref 4
(12) Data Id Label : (Tag 104) Ref 5
hdfed>
hdfed> ! This predicate persists for the next and prev
hdfed> ! commands. That means if I now type another 'next'
hdfed> ! command, it will look for a tag that equals 707.
hdfed>
hdfed> next
Reached end of file. Not moved.
hdfed> info
(5) SciData max.min (SciData) : (Tag 707) Ref: 2
hdfed>
hdfed> next group
hdfed> next group
hdfed> info
(11) Numeric Data Group : (Tag 720) Ref 4
hdfed>
The dump commandSyntax: dump [-offset offset] [-length length] [-decimal|-short|-byte|-octal|-hexadecimal|-float|-double|-ascii]
Flags:
-offset Starting offset
-length Length of the object to dump.
-decimal Decimal format (32-bit integers)
-short Decimal format (16-bit integers)
-byte Decimal format (8-bit integers)
-octal Octal format (the default)
-hexadecimal Hexadecimal format
-float Single-precision floating-point format (32-bit floats)
-double Double-precision floating-point format (16-bit floats)
-ascii ASCII formatDescription: Displays the contents of the current object in the specified format.
Usage Example:
hdfed> ! to see the binary representation of this element
hdfed>
hdfed> dump
0: 257400004 257200004
hdfed>
hdfed> dump -short
hdfed>
0: 702 4 701 4
hdfed>
The delete commandSyntax: delete
Flags: None.
Description: Deletes the current object or group.
Usage Example:
hdfed> ! deleting groups
hdfed>
hdfed> ! If an element is required by other group it is alone.
hdfed> ! However, this is not perfect as the method by which group
hdfed> ! membership is determined can be pretty ad hoc.
hdfed>
hdfed> delete
hdfed> ! This deletes the Scientific Data Group
hdfed> info -all
(1) Version Descriptor : (Tag 30) Ref 1
(2) Scientific Data : (Tag 702) Ref 2
(3) Number type : (Tag 106) Ref 2
(4) SciData description : (Tag 701) Ref 2
(5) SciData max/min : (Tag 707) Ref 2
(6) Numeric Data Group : (Tag 720) Ref 2
(7) Data Id Label : (Tag 104) Ref 3
(8) Number type : (Tag 106) Ref 4
(9) Data Id Label : (Tag 104) Ref 5
hdfed>
hdfed> ! Notice that the Numeric Data Group with reference
hdfed> ! number 4 is missing, and now there are only 9
hdfed> ! objects in the file.
hdfed>
The annotate commandSyntax: annotate [-label] [-descriptor] [-editor editor]
Flags:
-label Edit a label (the default)
-descriptor Edit a descriptor.
-editor Use an editor. (Default is the editor referred to by the EDITOR environment variable.Description: Edits an annotation.
Usage Example:
hdfed>
hdfed> ! Annotations are labels and descriptors
hdfed>
hdfed> prev -group
hdfed> info -label
(6) Numeric Data Group : (Tag 720) Ref 2
Label: Experiment #1
hdfed> annotate -editor /usr/ucb/ex
"/tmp/he5091.1" 1 line, 14 characters
:p
Experiment #1
:s/$/ <more stuff>/
Experiment #1 <more stuff>
:wq
"/tmp/he5091.1" 1 line 27 characters
hdfed> info -label
(6) Numeric Data Group : (Tag 720) Ref 2
Label: Experiment #1 <more stuff>
hdfed>
The write commandSyntax: write [-attachto tag-reference-number] filename
Flags:
-attachto Which element the annotation will be attached to. (only for writing annotations)Description: Writes an element or group into another HDF file.
Usage Example:
hdfed>
hdfed> ! Write object or group to another HDF file.
hdfed>
hdfed> write test
hdfed>
hdfed> ! Let's take a look at the file 'test'
hdfed> close; open test; info -all
(1) Version Descriptor (Tag 30) Ref 1
(2) Scientific Data (Tag 702) Ref 2
(3) Number type (Tag 106) Ref 2
(4) SciData description (Tag 701) Ref 2
(5) SciData max/min (Tag 707) Ref 2
*(6) Numeric Data Group (Tag 720) Ref 2
hdfed>
hdfed> close;
hdfed>
The display commandSyntax: display [-position x-position y-position] [-expansion expansion] [-large]
Flags:
-position Image position on console screen
-expansion Image expansion factor
-large Make image as large as possibleDescription: Displays image on screen.
Usage Example:
hdfed> ! We will open a file with some RIS8 images.
hdfed>
hdfed> open denm,HDF
hdfed> display
hdfed>
hdfed> ! The 'display' command displays the current RIS8
hdfed> ! group image via ICR. I.e. if you are using NCSA Telnet
hdfed> ! on a Mac II, this would display the images from denm.HDF
hdfed> ! on your screen.
hdfed> ! NOTE: not guaranteed to work otherwise.
hdfed>
The putr8 commandSyntax: putr8 [-image image_filename palette _ilename -verbose]
Flags:
-image Image file name template (Default is "img#.@.%")
-palette Palette file name template (Default is "pal#")
-verbose To give output of steps taken.Description: Writes a RIS8 group into raw image and palette files.
Usage Example:
hdfed> ! putr8 puts an RIS8 group into raw files
hdfed>
hdfed> putr8 -image my_image.#.@.% -palette testPalettes# -verbose
Writing to file: my_image8.10.10
Writing to file: my_palette
hdfed>
The close commandSyntax: close [-keep]
Flags:
-keep The backup file is not deleted.Description: Closes the HDF file opened by the last open command.
Usage Example:
hdfed> close
hdfed>
The select commandSyntax: select predicate_list command_list
Flags: None.
Description: Step through all the elements in the HDF file that satisfies the predicates, and execute the command list.
Usage Example:
hdfed> ! To step through a file and, for example, putr8 on all
hdfed> ! RIS8 groups we can use the select command.
hdfed>
hdfed> select tag=306
>> putr8 -image testImages# -palette testPalettes# -verbose
>> end
Writing to file: testImages8
Writing to file: testPalettes8
Writing to file: test Images14
Writing to file: testPalettes14
Writing to file: testImages21
Writing to file: testPalettes21
hdfed>
hdfed> ! The 'select' and 'if' commands take the same
hdfed> ! predicates as 'next' and 'pref'. There are also
hdfed> ! the predicates 'succeed" and "fail" that test the
hdfed> ! return status of the 'last' command.
hdfed>
The put commandSyntax: put [-file filename] [-verbose]
Flags:
-file Output file name (Default is "elt#.@") -verbose Output diagnostic information.Description: Writes the raw binary image of the current object to a file.
Usage Example:
hdfed> ! The 'put' command writes an element into a binary file.
hdfed> ! This is a dumb routine and does not know about the
hdfed> ! formats of an element.
hdfed>
hdfed> put -file binary#
hdfed> put -file myBinary -verbose
Writing to file: myBinary
hdfed>
The revert comma ndSyntax: revert
Flags: None.
Description: Discards all changes made in the current hdfed session.
Usage Example:
hdfed> revert
hdfed>
The getr8 commandSyntax: getr8 image-file-name [x-dimension y-dimension] [-palette palette-file-name] [-raster|-rle|-imcomp]
Flags:
-palette Palette will be read from a binary file.
-raster No compression will be performed during the write. (the default)
-rle Run-length compression will be performed during the write.
-imcomp IMCOMP compression will be performed during the write.Description: Reads a RIS8 group from binary files.
The if conditional Syntax: if predicate-list command-list end
Flags: None.
Description: Executes commands in a loop if predicates are satisfied for each element processed.
The select loop commandSyntax: select predicate-list command-list end
Flags: None.
Description: Executes the list of commands for each element that satisfies the predicates.
The wait commandSyntax: wait message
Flags: None.
Description: Prints a message, then waits for a carriage return to be typed.