SHOWing and EDITing data-file contents in NEWSTAR
Contributed by Wim Brouw, December 1993
Revised/adapted by Johan Hamaker, June 1994
The programs NSCAN, NFLAG, NMAP and NGCALC have a SHOW option, with an EDIT sub-option. This EDIT sub-option can be used to examine and change any field in the SCN, WMP and NGF files. The EDIT option can show and/or edit the contents of NEWSTAR files. All values ('fields'), with the exception of values determining the structure of the file, may be edited individually (or in groups) by hand. This is laborious, but at least it is possible! The different files contain a variety of blocks (e.g. STH - sector header; MPH - map header). In addition to manipulating these fields, NEWSTAR programs know how to present their names and values in an intelligible form to the user, and conversely how to interpret the user's editing instructions. After starting EDIT, the message: **** Editing STH **** (or MPH or ....)
will appear, indicating the actual block available for editing at this instant.
SHOW gives a formatted display of the contents of the entire "current" block (i.e. the block currently accessed through a navigating command such as CONTINUE or NEXT. To display individual fields in the block one uses the EDIT option. Once in edit mode, one may both display and modify fileds. The display commands for an individual field consist of the field name, optionally followed by a colon and qualifying information. The various types of qualifier will be discussed below. A display command becomes an EDIT command when followed by a comma plus one or more new values.
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RA 0.06725881318561733
Note that pointer values can not be shown this way.
Appending a format specifier to the colon overrides the default format in which a value is displayed. Some of the possible formats are:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RA 01:36:51
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RA 01:36:51.1615
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RA 3fb137d4
The full list of available formats, including fieldsize indicators, exists only in the form of a table in the program source file wnctxt_x.for.
Elements of array fields can be selected by appending the start index and the number of elements to the field name, as follows: - <name>[(<offset>)][,/<number>] will show the value of <name>. If an offset is given for a multi-valued <name>, the display will start at this value; if /<number> is given, only that many values will be shown. Examples are given below. Remember that indices start at 0!.
Examples:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Known names:
LINK, XJ, , ; 0, 2, 1, 4
LEN, SI, , ; 8, 1, 1, 2
VER, SI, , ; 10, 1, 1, 2
FIELD, AL, , ; 28, 1, 0, 12
.
.
RA, DAF12.7, , ; 40, 1, 0, 8
DEC, DAF12.7, , ; 48, 1, 0, 8
RTP, E12.4, , ; 124, 14, 0, 4
NIFR, SJ, , ; 180, 1, 1, 4
IFRP, XJ, , P:IFRT; 184, 1, 1, 4
NFD, SJ, , ; 188, 1, 1, 4
FDP, XJ, , P:FDW; 192, 1, 1, 4
NOH, SJ, , ; 196, 1, 1, 4
.
.
The entries in this table are:
Most values in a data file can be edited. The field descriptors outlined above for SHOW are also valid for EDIT. Edit commands are charaterised by the presence of a comma following the field descriptor:
<name>[<(offset)>][</number>], <value> [,<value>...]
will change the value(s) at the given field. Examples:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RTP 12.0000 143.9919 287.9837 431.9756 575.9674
719.9592 863.9511 1007.9429 1151.9348 1295.9266
1367.9257 1439.9176 2663.8491 2735.8452
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Note that names are not case-sensitive!
RTP 1.0000 2.0000
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RTP 0.0000 143.9919 1.0000 2.0000 575.9674
719.9592 863.9511 1007.9429 1151.9348 1295.9266
1367.9257 1439.9176 2663.8491 2735.8452
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
RTP 287.9837 431.9756 575.9674 719.9592 863.9511
1007.9429 1151.9348 1295.9266 1367.9257 1439.9176
2663.8491 2735.8452
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Edit of field LINK not allowed LINK 0007ec60 00000098
The last example demonstrates that certain fields cannot be changed because the integrity of the file depends on them. This restriction may be overridden by appending '==' to the field descriptor:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
LINK 00000001
The value given is interpreted with the default format descriptor displayed by the name command). A different format can be used by giving a format specifier.
For integers, the radix specifiers %X (hexadecimal), %D(decimal) and %O (octal) can also be used. Values given as
hh:[[mm][:[ss][.ttt]] or
dd.[mm].[ss][.ttt]]
will be translated to degrees and saved in the appropriate F, R or D format;
The header blocks directly accessible through SHOW/EDIT contain pointers to other blocks. When their value is listed, :P is appended, meaning that the value is the address of a block on disk in the corresponding format format.
Certain fields in a block are arrays not of single values but of sub-blocks of some type; an example are the interferometer entries in the OHW block. When such a field is listed, :S is appended, meaning that this is an array of subblocks.
All secondary-block and substructure types known to the system (i.e. not only those associated with the current block) are displayed by the :: command:
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Known P: types: STH, FDW, OHW, SCW, SHW, FDX, GFH, IFRT, MDH, MDD, SGH, MDL,
SCH
IFRC, B, I, J, E, D, X, Y, S:SET, S:SRC, S:BCOR, S:MOZP, S:IFR, IFH
: indicates a sub-structure. The use of the data types B, I etc. is explained elsewhere.
Specifying the name of a pointer will steer the editing process to the block pointed at:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing STH ***
So nothing happened: There is no MDD block attached to this STH block.
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Edit data: IFRP, XJ, , P:IFRT; 184, 1, 1, 4
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing IFRT ***
This time we succeeded!
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Known names:
IFR, XI, , ; 0, 88, 0, 2
The IFR block is just an array of hex integers
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
IFR 0a09 0b0a 0d0c 0b09 0100
0201 0302 0403 0504 0605
.
.
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing STH ***
A null reply returns us to the parent block
An array of substructures can be shown in its entirety by: <name>* Example:
*** Editing SHW ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
INFNR 16667 WTEL 0 OTEL 13
RBAS 2736 NIH 2040
INFNR 16665 WTEL 0 OTEL 12
RBAS 2664 NIH 2047
.
.
*** Editing SHW ***
Note that the current block is still SHW.
A single sub-structure can be shown and edited by:
<name>[(<index>)]
Example:
*** Editing SHW ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing S:IFR ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
INFNR 16667 WTEL 0 OTEL 13 RBAS 2736 NIH 9120
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing SHW ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing S:IFR ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
INFNR 17689 WTEL 2 OTEL 12 RBAS 2376 NIH 9465
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing SHW ***
The options described here are available for system programmers. They assume a proper understanding of the architecture of Newstar data files and of the mechanisms (.dsc and .def files) through which it is defined. No attempt will be made here to help the reader on these points... The syntax of the advanced options is less intuitively clear than what has been described above and its expressive power is limited. In using it, the user will have to feel his way around, but he can safely do so as long as he doesnot rashly attempt to change any values.
Link pointers in linked lists are similar to other pointers, except that the type of the target block is not known a priori. It must therefore be specified: <name>[(<index>)]::<target block type> For example:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing GFH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
ID .SCN LEN 512 VER 1 CDAT 21-Sep-1993 CTIM 17:23 RDAT 13-Jun-1994 RTIM 16:16 RCNT 50 NAME A271A DATTP 7 LINK 00006550 00500e08 ALHD 00006550 00500e08 NLINK 4 ALLEN 4 LINKG 00000200 008069c8 :P LHD 00000200 008069c8 :P NLINKG 2 LLEN 2 IDMDL 0 ID1 0 ID2 0 USER 0
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Return to STH
*** Editing STH ***
Some pointers point to "naked" arrays of data structures. An example is MDD in the STH which points to the array of complex model visibilities:
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
We try to display the array in complex format ...
MDD 006179c8 00000000 :P
but the system does not understand us!
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing MDD ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
MDD -540.55+72.69I 0.00+0.00I
0.00+0.00I 0.00+0.00I
-540.50+72.76I 0.00+0.00I
0.00+0.00I 0.00+0.00I
.
.
This works, but it is not clear how we could select specific elements for display.
There are also data arrays whose address is defined implicitly by the fact that they contiguously follow a header block. An example is the scan-visibilities block headed by the SCN header. To access such data in the absence of a pointer, one must use a byte offset. For this we need the length of the header, which we can easily find. The technique is demonstrated below is a somewhat different context, viz. that of finding an SCH which is not directly pointed at.
*** Editing STH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
SCNL 1552
This is the length of an SCH plus the data.
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
*** Editing SCH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
HA -90.1250124 deg MAX 1294.000 W.U. SCAL 0.000000
REDNS 0.000 0.000 0.000 0.000 W.U.
.
.
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
Move to the next SCH. We can use multiples of SCNL to get to any of the SCHs.
*** Editing SCH ***
EDIT
(Edit: name [(offset)][/length][:format] , val [, ...])
= "":
HA -89.8743278 deg MAX 1349.000 W.U. SCAL 0.000000
REDNS 0.000 0.000 0.000 0.000 W.U.
ALGNS 0.000 0.000 0.000 0.000 W.U.
.
.
Absolute file addresses (i.e. byte offsets in the file) can be used instead of field names.
Relative addresses are byte offset relative to the start of the current block. They are specified in the form
.<offset>
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.