home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / bcast100.zip / FIELDS.MAN < prev    next >
Text File  |  1991-11-18  |  12KB  |  228 lines
  1.  
  2.                      DOCUMENTATION FOR PROGRAM 'FIELDS'
  3.                      ---------------------------------
  4.  
  5.                         Version 1.00 - Copyright 1991
  6.                           Solar Terrestrial Dispatch
  7.  
  8.  
  9.      The program FIELDS is powerful utility program included on the BCAST
  10. distribution disk.  This program lets you customize the extraction of data
  11. from the BCAST database file so that the data can be stored in a textual form
  12. which can be read directly by other external data processors such as
  13. spreadsheets, statistical processors, or graphical analysis packages such as
  14. GLE, etc.
  15.  
  16.      FIELDS operates by extracting specific data values (or fields) from the
  17. database file and displaying them or placing them in another text ASCII file
  18. in a format of your choosing.
  19.  
  20.      In order for FIELDS to operate properly, it must know the name of the
  21. file containing the format it is to use to create the textual data file.
  22. This format file can be created using a simple text editor.  The contents of
  23. a simple example format file is given below.  It consists of a single line of
  24. text containing four acronyms beginning with a percent sign (%) and separated
  25. by blank spaces:
  26.  
  27. %a %d %e %f
  28.  
  29. FIELDS scans this sample format file and replaces each of the acronyms with a
  30. value from each record in the database file.  In this example, the acronyms
  31. are defined as:
  32.  
  33.           %a = Record Number
  34.           %d = 10.7 cm Solar Radio Flux
  35.           %e = Sunspot Number
  36.           %f = 90-Day Average Solar Flux
  37.  
  38. After FIELDS processes this sample format file, it reads each of the records
  39. in the database file created by BCAST and extracts the four values given
  40. above.  It then either displays these values on-screen or creates another
  41. text file and writes the values there.  Here is a sample output from FIELDS:
  42.  
  43.      1 204.2 254 198
  44.      2 208.6 267 198
  45.      3 212.8 272 199
  46.      4 215.1 270 200
  47.      5 214.7 260 200
  48.  
  49. This is the output which FIELDS would produce with the sample format file
  50. above, provided five records (or datasets) existed in your BCAST database
  51. file.  Notice that each line produced by FIELDS is in the same format as the
  52. format file given above.  The values are also all separated by a single blank
  53. space, as they are in the format file.
  54.  
  55.      FIELDS is not limited to handling simple single-line format files such
  56. as the example given above.  Indeed, things can become significantly more
  57. complex.  The following format file shows you just how complex the format
  58. specification can become.  It should be noted that this next example lists
  59. almost all of the acronyms which FIELDS can process.  A formalized definition
  60. of the available acronyms will be discussed shortly.
  61.  
  62. ----------------------------  File: EXAMPLE.FMT  ----------------------------
  63. RECORD NUMBER: %a, Date=%i/%j/%k, DOY=%l
  64. Flux=%d, SSN=%e, 90AVG=%f, BAI=%g, PAI=%h
  65. Boulder K-Indices: %m, Planetary K-Indices: %n
  66. BGXRAY=%o, Fluence(1Mev)=%p, Fluence(10MeV)=%q,
  67. 3-Hr Boulder Deviations=%s, Avg Deviation=%r
  68. SWF episodes=%t, SWF Duration=%u, Boulder Total Field Avg=%y
  69. Avg Xray Flux=%v, Neutron Avg=%w%%, PCA Avg=%x
  70. Xray Max=%za, Xray Min=%zb, Neu-Max=%zc%%, Neu-Min=%zd %%
  71. PCA-Max=%ze, PCA-Min=%zf, Total Field Max=%zg, Total Field Min=%zh
  72. GOES-7 AVg Par=%zi, Avg Earth=%zj, Avg Perp=%zk, Max=%zl, Min=%zm
  73. GOES-6 AVg Par=%zn, Avg Earth=%zo, Avg Perp=%zp, Max=%zq, Min=%zr
  74.  
  75. ----------------------------     End of File     ----------------------------
  76.  
  77. This file (excluding the first and last dashed lines) may be found with the
  78. BCAST distribution disk under the filename "EXAMPLE.FMT".  Note that there is
  79. a blank line at the end of the file (following the GOES-6 statistics line).
  80. Without this blank space, all of the data for each record in the database
  81. file would be squished together.  By placing a single blank line at the end
  82. of the file, each record output by FIELDS is separated by a blank line.
  83.  
  84. With the format file give above, FIELDS would produce an output as follows:
  85.  
  86. ---------------------------  Sample FIELDS Output  --------------------------
  87. RECORD NUMBER:     1, Date=09/04/91, DOY=247
  88. Flux=171.0, SSN=219, 90AVG=207, BAI= 12, PAI= 15
  89. Boulder K-Indices: 2 3 4 3 3 2 1 2, Planetary K-Indices: 3 3 4 3 3 2 2 2
  90. BGXRAY=0.00000100, Fluence(1Mev)=2.2E+05, Fluence(10MeV)=8.9E+03,
  91. 3-Hr Boulder Deviations= 18  21  45  30  26  14   8  19, Avg Deviation= 22
  92. SWF episodes= 3, SWF Duration= 26, Boulder Total Field Avg=55301
  93. Avg Xray Flux=0.00000170, Neutron Avg=  0.7%, PCA Avg= -0.1
  94. Xray Max=0.00001500, Xray Min=0.00000085, Neu-Max=   3%, Neu-Min=  -1 %
  95. PCA-Max=  0.0, PCA-Min= -0.4, Total Field Max=55317, Total Field Min=55272
  96. GOES-7 AVg Par=   70, Avg Earth=   62, Avg Perp=    2, Max=  106, Min=  -39
  97. GOES-6 AVg Par=   79, Avg Earth=   24, Avg Perp=   14, Max=  106, Min=   -6
  98.  
  99. RECORD NUMBER:     2, Date=09/05/91, DOY=248
  100. Flux=164.0, SSN=204, 90AVG=206, BAI= 25, PAI= 29
  101. Boulder K-Indices: 5 4 5 4 3 3 2 3, Planetary K-Indices: 5 4 5 4 4 3 3 3
  102. BGXRAY=0.00000086, Fluence(1Mev)=2.7E+05, Fluence(10MeV)=8.3E+03,
  103. 3-Hr Boulder Deviations= 93  51  73  60  23  30  12  21, Avg Deviation= 45
  104. SWF episodes= 5, SWF Duration= 79, Boulder Total Field Avg=55301
  105. Avg Xray Flux=0.00000250, Neutron Avg=  0.5%, PCA Avg= -0.1
  106. Xray Max=0.00004400, Xray Min=0.00000080, Neu-Max=   3%, Neu-Min=  -2 %
  107. PCA-Max=  0.7, PCA-Min= -0.2, Total Field Max=55331, Total Field Min=55263
  108. GOES-7 AVg Par=   67, Avg Earth=   63, Avg Perp=    2, Max=  113, Min=  -52
  109. GOES-6 AVg Par=   73, Avg Earth=   26, Avg Perp=   14, Max=  101, Min=  -10
  110. ---------------------------     End of Output      --------------------------
  111.  
  112. Notice how the blank line at the end of the format file produces a break
  113. between records as output by FIELDS.  Also notice that each acronym is
  114. replaced with a properly formatted output, right-justified to fit within the
  115. field and padded with blank spaces.
  116.  
  117.      Each of the available acronyms are discussed below.  Acronyms are
  118. identified by a preceding percent sign.  All acronyms used by FIELDS must be
  119. labelled in this manner.  If the leading percent sign is not included, FIELDS
  120. will treat the acronym as part of the text within the format file and will
  121. not process it.  The acronyms are case insensitive.  You may therefore use
  122. either lower or upper case acronyms.
  123.  
  124.  
  125.                           LIST OF AVAILABLE ACRONYMS
  126.                           --------------------------
  127.  
  128. %a = The record number of the dataset within the database file.
  129. %b = A general integer counter.  Each time FIELDS encounters this acronym, it
  130.      replaces it with the current value of the counter and then increments
  131.      the counter by one.  This may be useful for counting subsets of data
  132.      such as K-indices.
  133. %c = When FIELDS encounters this acronym, it resets the general integer
  134.      counter (%b) to one (1).
  135. %d = FIELDS replaces this acronym with the 10.7 cm solar radio flux value.
  136. %e = This is the acronym for the sunspot number.
  137. %f = Average 90-day solar flux value.
  138. %g = Boulder A-Index.
  139. %h = Planetary A-Index.
  140. %i = Month of the dataset (from 1 to 12).
  141. %j = Day of the dataset.
  142. %k = Year of the dataset.
  143. %l = The day of year of the dataset (from 1 to 365).
  144. %m = Boulder K-Indices.  FIELDS replaces this acronym with eight K-indices
  145.      separated by a single blank space.
  146. %n = Planetary K-Indices.  The output format is the same as with %m.
  147. %o = Background x-ray flux.  These values are given in watts / meter^2.
  148. %p = Daily proton fluence at greater than 1 MeV.
  149. %q = Daily proton fluence at greater than 10 MeV.
  150. %r = Average daily maximum deviation of the Boulder USGS magnetometer.
  151. %s = The eight daily maximum deviation values of the Boulder magnetometer.
  152.      These values are related to the Boulder K-Indices.
  153. %t = Estimated maximum number of daily Short Wave Fadeout (SWF) episodes.
  154. %u = Estimated maximum combined daily duration of the SWFs in minutes.
  155. %v = Average daily x-ray flux (given in watts / meter^2).
  156. %w = Average daily neutron monitor count.
  157. %x = Average daily Polar Cap Absorption (PCA) value.
  158. %y = Average Total Field value of the geomagnetic field at Boulder, Colorado.
  159. %z = FIELDS uses this acronym as an extension.  In order for FIELDS to
  160.      process other acronyms in addition to those given above, this acronym
  161.      must be followed by another letter.  The extended list of acronyms are:
  162. %za = Observed daily maximum x-ray flux (in watts / meter^2).
  163. %zb = Observed daily minimum x-ray flux (in watts / meter^2).
  164. %zc = Observed daily maximum neutron monitor count.
  165. %zd = Observed daily minimum neutron monitor count.
  166. %ze = Observed daily maximum PCA value.
  167. %zf = Observed daily minimum PCA value.
  168. %zg = The daily maximum total field value over Boulder.
  169. %zh = The daily minimum total field value over Boulder.
  170. %zi = Daily average value of the parallel magnetic component as observed by
  171.       the GOES-7 geosynchronous satellite.
  172. %zj = Daily average value of the earthward magnetic component at GOES-7.
  173. %zk = Daily average value of the perpendicular magnetic component at GOES-7.
  174. %zl = Observed daily maximum magnetic field value of either of the three
  175.       magnetic components at GOES-7.
  176. %zm = Observed daily minimum magnetic field value of either of the three
  177.       magnetic components at GOES-7.
  178. %zn = Daily average value of the parallel magnetic component as observed by
  179.       the GOES-6 geosynchronous satellite.
  180. %zo = Daily average value of the earthward magnetic component at GOES-6.
  181. %zp = Daily average value of the perpendicular magnetic component at GOES-6.
  182. %zq = Observed daily maximum magnetic field value of either of the three
  183.       magnetic components at GOES-6.
  184. %zr = Observed daily minimum magnetic field value of either of the three
  185.       magnetic components at GOES-6.
  186. %%  = This is a special acronym used by FIELDS.  Since the percent-sign (%)
  187.       is already used by FIELDS to denote a processable acronym, FIELDS uses
  188.       this %% acronym to output a single percent-sign.  So, for example, by
  189.       placing "%%%%" in the format file, FIELDS will output two percent
  190.       signs.
  191.  
  192.  
  193.      The power of FIELDS comes from the use of these acronyms.  Using FIELDS,
  194. you can develop custom versions of the BCAST database which can be more
  195. easily imported by other external software processing programs.  A good
  196. example is the professional scientific GLE program, which will read in data
  197. in textual format and produce publishable graphs or other images in a variety
  198. of formats (ex. dot-matrix, LaTeX, or Postscript).  GLE was not developed by
  199. the Solar Terrestrial Dispatch, but may be freely downloaded from the STD
  200. computer BBS in the Utilities file section.
  201.  
  202.      To run FIELDS, make sure an appropriate format file exists.  You must
  203. also be in the same directory as the BCAST database file "DATASETS.DAT" since
  204. FIELDS expects to find this file in the current directory.  The syntax for
  205. FIELDS is:
  206.  
  207.                        FIELDS format_file > output_file
  208.  
  209. If the redirection command "> output_file" is not included, FIELDS will
  210. display the output on-screen.  In order to produce an output file, the
  211. redirection command must be included on the command line.
  212.  
  213.      For example, to process the BCAST database file using the sample format
  214. file "EXAMPLE.FMT" (which is included with this software package), simply
  215. execute FIELDS with the following command at the DOS prompt:
  216.  
  217.                        FIELDS EXAMPLE.FMT > OUTPUT.TXT
  218.  
  219. Provided you are in the same directory as the database file "DATASETS.DAT"
  220. and data actually exists in the database file, FIELDS will produce an output
  221. file named "OUTPUT.TXT" similar in format to what was shown earlier in this
  222. manual.
  223.  
  224.      It should be noted that in order to generate a BCAST database file which
  225. FIELDS can process, you must register your version of BCAST with the Solar
  226. Terrestrial Dispatch (see the file "REGISTER.DOC" for more information).
  227.  
  228.