0. Introduction
FORTRAN 77 software is provided to assist users in unpacking and using some of the available binary data products. As discussed in each product description, it is assumed that the user has the low-level and generally machine-dependent capabilities of 1) transferring a binary block into memory and 2) then extracting into INTEGER variables the bit strings whose lengths are specified. The two capabilities are discussed briefly in secs. 1-3, together with the efficiency and machine-portability considerations that have constrained the design of product formats. A more general discussion including the advantage in execution time and storage relative to traditional techniques can be found in [3].
Source code listings for the available software appear under the filenames given in Table H0-1. Files are listed on pp. H6-H46 (except that the information in LLN2F1 appears on the 2° box map in supp. G). In addition, the files can be furnished by NCAR's Data Support Section in machine-readable form.
----------------------------------------------------------------
Filename Level Purpose
----------------------------------------------------------------
BOXLIB .01J tools for working with 2°, 4°*, and 10°
boxes,or Marsden Squares
QI9 .01G read and print MSU.2
QI12 .01D read and print CMR.4
QI21 .01D read and print MSUG.1 group 1
QI22 .01D read and print MSUG.1 group 2
QI24 .01C read and print DSU.2
QL14 .01C read and print MST.3
QL16 .01C read and print TRP.1
QL21 .01C read and print CMR.5
QL28 .01C read and print MSTG.1 group 3
QL29 .01C read and print MSTG.1 group 4
QL30 .01C read and print MSTG.1 group 5
QL31 .01C read and print MSTG.1 group 6
QL32 .01C read and print MSTG.1 group 7
RDINV .01B read and print INV. 3
READER .01B read landlocked file LLN2F1
LLN2F1 n/a landlocked file
----------------------------------------------------------------
* 4° boxes are similar to 2° boxes. BOX4-1 and -4052 are dedicated
to the exact North and South poles, respectively; the remaining
boxes 2 through 4051 each enclose four 2° boxes (number 2 has
BOX2-2, -3, -182, -183; number 3 has BOX2-4, -5, -184, -185; etc.).
_______________________
Software may require some modification to work properly on a given machine, because of differences in FORTRAN and computer characteristics, or if the machine dependent capabilities discussed in secs. 1-3 are not available or differ in their implementation. Table H0-2 summarizes known, potential incompatibilities for each filename.
---------------------------------------------------------------------
Filename
--------------------------------------
Incompatibility BOXLIB QI9-QL32 RDINV READER LLN2F1 Reference
---------------------------------------------------------------------
FORTRAN 66 X Xa X n/a --
7-char variables Xb n/a --
DATE X X X n/a this section
TIME X X X n/a this section
BPW (bits/word) X Xc n/a this section
BUFFER IN X X n/a sec. 1
UNIT X X n/a sec. 1
LENGTH X n/a sec. 1
RPTIN Xd n/a sec. 1
GBYTES X X n/a sec. 2
DEC computer X X n/ae sec. 3
---------------------------------------------------------------------
a Limited to use of the PARAMETER statement, those parameters in the
DIMENSION and DATA statement, and the apostrophe to delimit literals
in PRINT and FORMAT statements.
b Only one, INDEXCK.
c Called WRDSIZ.
d Referenced but never called in the default implementation (since
RPTOFF = 1, BUFFER IN is called instead). On systems that are
rigorous in satisfying program externals, this reference should be
made into a comment.
e Unless input as binary data.
___________________
The more minor of these incompatibilities are discussed in the following; see the referenced section for information about others.
1. Binary Input
The method of handling binary input depends on two levels of organization that are commonly used in storing data on magnetic tape and disk. First, a logical record is the amount of data a user desires access to in one input operation. Examples are an individual monthly summary (for MSTG 384 bits long), or an individual report (for CMR.5 192 bits long). Second, a block (or physical record) is the amount of data a user may be required to access in one input operation because of hardware or system software limitations, and which is characterized by system-recognizable boundaries of various sorts between blocks. Usually, shorter logical records are blocked together into larger physical records for efficiency of storage and input/output (i/o). Although a block may be the real unit of input, in many cases system software can make this distinction transparent to the user.
The software provided here makes use of a non-ANSI but relatively common feature called BUFFER IN to input a binary block, sometimes concurrently with the calling program. The form of BUFFER IN used is
BUFFER IN(LUN, M) (K(1), K(N))
where LUN is the unit designator, K is an array that will receive the block, N is at least the number of words required to hold a block and no more (on some machines less) than the DIMENSION of K*, and M is a machine-dependent parameter for input mode. The function UNIT must be checked before K is used, to be sure BUFFER IN is done
JEOF=UNIT(LUN)
and JEOF can be
The UNIT check must be delayed as long as possible to allow BUFFER IN to work concurrently with the intervening statements. This was not possible in these programs because only one buffer was used; in order to improve clock performance a "ping-pong" approach that switches between two buffers could be used. Once UNIT has been checked, the LENGTH(LUN) function can be used. It will return the number of words transferred into K.
Block sizes have been chosen that are evenly divisible by 64-bit and 60-bit words, and thus also by any smaller word size that divides evenly into 64 or 60 (e.g., 16, 32). This is convenient for BUFFER IN, as well as for alternative techniques. One alternative is to read a block in "An" format where n is the number of characters per word. For example, on a 32-bit IBM machine with 8-bit characters,
INTEGER K(1800)
100 READ(1,200) K
200 FORMAT(1800A4)
will read one 57,600-bit block (MSTG).
Logical record sizes have also been chosen that are evenly divisible by 64-bit words. This increases the likelihood, on a given machine, that it will be possible to read one logical record at a time. On a 60-bit CDC machine with 6-bit characters,
INTEGER K(4)
100 READ(1,200) K
200 FORMAT(3A10,A2)
will read one 192-bit logical record (CMR.5), provided a "record manager" available with the operating system is advised by
FILE(TAPE1,RT = F,FL = 32,RB = 150)
to supply a 32-character logical record blocked 150 for every READ.
Binary input can be further simplified on machines where the
RPTIN utility is available, and where the data are in RPTIN format.
This utility was developed at NCAR for unblocking variable-length
logical records, such as LMR, but will work equally well on fixed-length
records. A complete description of RPTIN including some of its
additional features can be found in [3].
In case it is available, RPTIN is offered as an option in this software, which
requires that the RPTOFF parameter be changed from its default setting of 1
(indicating that RPTIN is off) to 0 (indicating that RPTIN is on). Otherwise,
RPTIN will be an "unsatisfied external" that will never be called.
___________________
* Programs QI9-QL32 have this dimension set to the integer parameter
DIM BUF = (1006 * 64 - 1)/BPW + 1 for compatibility with RPTIN. Since
RPTIN is not called in the default implementation, DIM BUF can be
reduced, if necessary, to the length required to hold one full block
(plus 6 initial control words).
___________________
2. Bit-String Manipulations
After a binary block or record is transferred into memory, it will be necessary to extract into INTEGER variables the desired bit strings whose lengths are specified. Subroutines GBYTES and GBYTE are available on some machines for this purpose (together with reverse capabilities SBYTES and SBYTE as described in [3]). GBYTES is used to move N strings of constant-length-B bits from packed array P to unpacked array U, after initially skipping Q bits, and skipping S bits between each string. The call is
CALL GBYTES(P,U,Q,B,S,N)
where
If only one string is required,
CALL GBYTE(P,U,Q,B)
should be used. In improved implementations the restriction that Q be less than word size is dropped, easing code portability.
Where GBYTES and GBYTE are not available or where efficiency is the primary consideration, other techniques can be used. The Boolean operations AND, OR, SHIFT, and MASK are available on some machines; if not, it is possible to simulate them using integer arithmetic. In many cases string lengths have been chosen that are multiples of 8 bits, in which case it may be possible to treat them as characters on some machines.
3. Note for Users on DEC Equipment
All COADS packed-binary formats were designed and documented using the convention of numbering bits from high-order to low-order within words, and words are thought of as going from lowest address to highest address. This is convenient since it results in simple left to right representation of the data in a string of bits. Most large computers use this convention (IBM, Control Data, Cray, etc.) and most packed-binary formats have been designed using this convention. When 9-track tapes are read or written on such systems, the first 8-bit byte is accessed from or stored in the high-order 8 bits of the first word in the memory i/o buffer. Succeeding bytes are stored in the next lower 8 bits until the first word is filled, and storing continues in the high-order bits of the second word of the buffer.
Since DEC uses a low-order to high-order convention on bits and words, the interpretation of formats using the COADS convention can be somewhat confusing. When 8-bit bytes are read from a 9-track tape on DEC equipment, the first byte on the tape goes into the low-order 8 bits of the first word in the input memory i/o buffer. The result of this is that the 8-bit bytes within each DEC word are in reverse order of what is intended in the format. For example, if the format specifies that the first 12 bits of a data record represent a data value, after a tape is read on a DEC system these 12 bits are contained in the low-order byte followed by the high-order 4 bits of the next higher order byte.
This problem has been solved in different ways by various DEC installations. NCAR has a special version of GBYTES written for local DEC equipment. This routine allows users to think of the data as a string of bits in the COADS sense and access various sized strings of bits in the proper order. A listing of the routine may be requested from NCAR's Data Support Section.
Source Code Listings (originally pp. H6-H46)
Note: In the original published edition of COADS Release 1, listings of QI9 through QL32 referenced QI9 for listings of subroutines GETRPT and RCDIN.