Changes between Version 4 and Version 5 of nmxptool


Ignore:
Timestamp:
04/08/12 16:50:04 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • nmxptool

    v4 v5  
    101101 
    102102 
     103=== Alphabetic Command Listing & Description === 
     104In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description. 
     105 
     106The following list is organized by: 
     107 
     108command [argument here] 
     109 
     110'''Channel [streamkey]'''[[BR]] 
     111Processed by: !ReadConfig[[BR]] 
     112Function: nmxptool parameters 
     113 
     114Specifies one stream of data to be requested from the !NmxpHost. The streamkey is not in SCNL format. It is composed of a network, station and channel code separated by period. network is optional and it is used only for output. Station code can be "*" that stands for all stations. Within channel code can appear character "?" that stands for any characters. Location value is always set to "--". DO NOT USE WITH ChannelFile! 
     115{{{ 
     116Default:  none 
     117Example:  Channel  ES.BOB.HH? 
     118          Channel  MN.TIR.HH? 
     119          Channel  SALO.HH? 
     120          Channel  *.HHZ 
     121 
     122N.B. Network code will be assigned from the first pattern that includes station and channel. 
     123     Unless HH channels of BOB and TIR, all other stations will have default network code from DefaultNetworkCode. 
     124}}} 
     125 
     126'''!ChannelFile [channel_state_file]'''[[BR]] 
     127Processed by: !ReadConfig[[BR]] 
     128Function: nmxptool parameters 
     129 
     130Specifies one or more streams of data to be requested from the !NmxpHost. The streamkey is the same for the Channel. Allow data continuity when short disconnections to !NaqsServer occur requesting data buffered by !NaqsServer (read Advanced Description for setting !DataBufferLength) and, optionally, retrieving data from !DataServer within seconds defined by !MaxDataToRetrieve. This file is created by the user, nmxptool will update date and time of last sample received for each channel into the file "channel_state_file.nmxpstate". DO NOT USE WITH Channel! 
     131{{{ 
     132Default:  none 
     133Example:  ChannelFile  /home/ew/list_channels_naqs1.txt 
     134 
     135Example of file created by the user: 
     136ES.BOB.HH? 
     137MN.TIR.HH? 
     138SALO.HH? 
     139*.HH? 
     140 
     141N.B. Network code will be assigned from the first pattern that includes station and channel. 
     142     Unless HH channels of BOB and TIR, all other stations will have default network code from DefaultNetworkCode. 
     143 
     144Example of file updated by nmxptool: 
     1451228603650 ES.BOB.HHE 2008.063,07:48:15.5799 2008.063,07:50:12.9000 
     1461228603649 ES.BOB.HHN 2008.063,07:48:16.0000 2008.063,07:50:13.6400 
     1471228603648 ES.BOB.HHZ 2008.063,07:48:16.0000 2008.063,07:50:12.4900 
     1481225851138 MN.TIR.HHE 2008.063,07:48:07.2200 2008.063,07:50:07.7999 
     1491225851137 MN.TIR.HHN 2008.063,07:48:16.0000 2008.063,07:50:07.9000 
     1501225851136 MN.TIR.HHZ 2008.063,07:48:05.7999 2008.063,07:50:08.2000 
     1511253900546 IV.SALO.HHE 2008.063,07:48:00.3199 2008.063,07:50:15.4800 
     1521253900545 IV.SALO.HHN 2008.063,07:48:16.0000 2008.063,07:50:15.7500 
     1531253900544 IV.SALO.HHZ 2008.063,07:48:16.0000 2008.063,07:50:16.3299 
     1541244987650 IV.AMUR.HHE 2008.063,07:48:09.0599 2008.063,07:50:13.3599 
     1551244987649 IV.AMUR.HHN 2008.063,07:48:10.9600 2008.063,07:50:11.8000 
     1561244987648 IV.AMUR.HHZ 2008.063,07:48:02.4600 2008.063,07:50:12.2799 
     1571237188866 IV.ARCI.HHE 2008.063,07:48:10.0099 2008.063,07:50:13.0100 
     1581237188865 IV.ARCI.HHN 2008.063,07:48:10.3399 2008.063,07:50:12.6200 
     1591237188864 IV.ARCI.HHZ 2008.063,07:48:16.0000 2008.063,07:50:11.6700 
     160... 
     161}}} 
     162 
     163'''!DefaultNetworkCode [network_code]'''[[BR]] 
     164Processed by: !ReadConfig[[BR]] 
     165Function: nmxptool parameters 
     166 
     167Specifies default network code for channels where is omitted. 
     168{{{ 
     169Default:  none 
     170Example:  DefaultNetworkCode  IV 
     171}}} 
     172 
     173'''!ForceTraceBuf1 [switch]'''[[BR]] 
     174Processed by: !ReadConfig[[BR]] 
     175Function: Earthworm setup 
     176 
     177Sets the on-off switch to force the creation of TRACEBUF messages on systems that support TRACEBUF2 messages. By default, the module will create TRACEBUF2 messages on systems that support them otherwise it will create the older TRACEBUF messages. This switch has no effect on systems that do no support TRACEBUF2 messages. This switch could be useful in environments where a transition is occuring between TRACEBUF and TRACEBUF2 messages, otherwise most people will never use this. 
     178{{{ 
     179Default:  0 (disabled) 
     180Example:  ForceTraceBuf1 1 
     181}}} 
     182 
     183'''!HeartBeatInterval [interval]'''[[BR]] 
     184Processed by: !ReadConfig[[BR]] 
     185Function: Earthworm setup 
     186            
     187Defines the interval in seconds at which the module will issue TYPE_HEARTBEAT messages. 
     188{{{ 
     189Default:  none 
     190Example:  HeartBeatInterval 30 
     191}}} 
     192 
     193'''!LogFile [switch]'''[[BR]] 
     194Processed by: !ReadConfig[[BR]] 
     195Function: Earthworm setup 
     196 
     197Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, nmxptool will write a daily log file(s) called nmxptool.log_yymmdd where xx is nmxptool's module id (set with !MyModuleId command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).  If switch is 2 the log file is written but output to stdout and stderr is suppressed. 
     198{{{ 
     199Default:  none 
     200Example:  LogFile   1 
     201}}} 
     202 
     203'''!MaxDataToRetrieve [seconds]'''[[BR]] 
     204Processed by: !ReadConfig[[BR]] 
     205Function: nmxptool parameters 
     206 
     207Max amount of data of the past to retrieve from the !DataServer when program restarts. 0 to disable connection to !DataServer. If this parameter is zero and !ChannelFile is used, only data buffered by !NaqsServer will be retrieved. Rather than using !MaxDataToRetrieve, it is preferable, inside the section !Datastream of the file Naqs.ini, setting !DataBufferLength to a high value (read Advanced Description). !MaxDataToRetrieve allows to retrieve much more data of the past when the program restarts but it considerably slows down the execution. It is extremely harmful when you have many channels, in this case you might consider to subdivide the channels into different nmxptool instances. Range is [0..86400]. 
     208{{{ 
     209Default:  0 
     210Example:  MaxDataToRetrieve  3600 
     211}}} 
     212 
     213'''!MaxTolerableLatency [seconds]'''[[BR]] 
     214Processed by: !ReadConfig[[BR]] 
     215Function: nmxptool parameters 
     216 
     217Specifies the max tolerable latency for raw stream connection. For enabling !NaqsServer to send out retransmission requests for missed packets set !RetxRequest (read Advanced Description). If !RetxRequest is not enabled then !MaxTolerableLatency is ineffective. Range is [60..600]. NOT use with parameter ShortTermCompletion. 
     218{{{ 
     219Default:  600 
     220Example:  MaxTolerableLatency  200 
     221}}} 
     222 
     223'''!MyModuleId [mod_id]'''[[BR]] 
     224Processed by: !ReadConfig[[BR]] 
     225Function: Earthworm setup 
     226 
     227Sets the module id for labeling all outgoing trigger, heartbeat, and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates to a unique single-byte number. 
     228{{{ 
     229Default:  none 
     230Example:  MyModuleId MOD_NMXPTOOL 
     231}}} 
     232 
     233'''mschan [mSECs/nC]'''[[BR]] 
     234Processed by: !ReadConfig[[BR]] 
     235Function: nmxptool parameters 
     236 
     237mSECs are milliseconds to wait before the next request, nC is the number of channels to request at a time. Delaying and requesting few channels at a time make data buffering on !NaqsServer side more efficient. Determined empiric values are default 280/9. 0/0 for disabling. Condition: !TotalNumberOfChannels * (mSECs/nC) < 15 sec. 
     238{{{ 
     239Default:  280/9 
     240Example:  mschan      350/12 
     241}}} 
     242 
     243'''!NmxpHost [address]'''[[BR]] 
     244Processed by: !ReadConfig[[BR]] 
     245Function: nmxptool parameters 
     246 
     247Specify the address of the Nanometrics server. This can be either on IP address (four period-separated numbers) or the domain name of the server. 
     248{{{ 
     249Default:  none 
     250Example:  NmxpHost      naqs1a.int.ingv.it 
     251}}} 
     252 
     253'''NmxpPortDAP [port]'''[[BR]] 
     254Processed by: !ReadConfig[[BR]] 
     255Function: nmxptool parameters 
     256 
     257Specifies the IP port number for the !DataServer (!NmxpHost). This is commonly 28002. 
     258{{{ 
     259Default:  28002 
     260Example:  NmxpPortDAP  28002 
     261}}} 
     262 
     263'''!NmxpPortPDS [port]'''[[BR]] 
     264Processed by: !ReadConfig[[BR]] 
     265Function: nmxptool parameters 
     266 
     267Specifies the IP port number for the !NaqsServer (!NmxpHost). This is commonly 28000. 
     268{{{ 
     269Default:  28000 
     270Example:  NmxpPortPDS  28000 
     271}}} 
     272 
     273'''PassDAP [password]'''[[BR]] 
     274Processed by: !ReadConfig[[BR]] 
     275Function: nmxptool parameters 
     276 
     277Specifies the password for the !DataServer (!NmxpHost). Leave commented if password in !DataServer.ini is set to "none". 
     278{{{ 
     279Default:  none 
     280Example:  PassDAP  mypass 
     281}}} 
     282 
     283'''!RingName [ring]'''[[BR]] 
     284Processed by: !ReadConfig[[BR]] 
     285Function: Earthworm setup 
     286 
     287Indicates which shared memory region to use for waveform output.  ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. 
     288{{{ 
     289Default:  none 
     290Example:  RingName WAVE_RING 
     291}}} 
     292 
     293'''!ShortTermCompletion [seconds]'''[[BR]] 
     294Processed by: !ReadConfig[[BR]] 
     295Function: nmxptool parameters 
     296 
     297Specifies the Short-Term-Completion for Buffered stream connection. Ranges:[[BR]] 
     2980                decompressed packets are received in chronological order without waiting for missing packets.[[BR]] 
     299[1..300]         decompressed packets are received in chronological order but waiting for missing packets at most SECs seconds.[[BR]] 
     300NOT use with parameter !MaxTolerableLatency. 
     301{{{ 
     302No default 
     303Example:  ShortTermCompletion  120 
     304}}} 
     305 
     306'''!TimeoutRecv [seconds]'''[[BR]] 
     307Processed by: !ReadConfig[[BR]] 
     308Function: nmxptool parameters 
     309 
     310Specifies time-out for flushing buffered packets for each channel. Useful for Data On Demand (i.e. channel HN? or HL?). It sets mschan to 0/0. Range is [10..300]. 
     311{{{ 
     312Default:  0  (No Time-out) 
     313Example:  TimeoutRecv  15 
     314}}} 
     315 
     316'''UserDAP [username]'''[[BR]] 
     317Processed by: !ReadConfig[[BR]] 
     318Function: nmxptool parameters 
     319 
     320Specifies the username for the !DataServer (!NmxpHost). Leave commented if username in !DataServer.ini is set to "none". 
     321{{{ 
     322Default:  none 
     323Example:  UserDAP  mtheo 
     324}}} 
     325 
     326'''Verbosity [level]'''[[BR]] 
     327Processed by: !ReadConfig[[BR]] 
     328Function: Earthworm setup 
     329 
     330Specifies the level of logging verbosity. Verbosity is a bitmap:[[BR]] 
     3311 Channel State, 2 Channel, 4 Raw Stream, 8 CRC32, 16 Connection flow, 32 Packet Management, 64 Extra, 128 Date, 256 Gap, 512 DOD, 1023 All messages. 
     332{{{ 
     333Default:  0 
     334Example:  Verbosity 80          # 16 Connection flow + 64 Extra 
     335}}} 
     336 
     337 
     338=== Advanced Description === 
     339'''Data continuity when short disconnections to !NaqsServer occur''' 
     340 
     341Inside the section Datastream of the file Naqs.ini set !DataBufferLength to a high value. 
     342{{{ 
     343    [ Datastream ]  
     344    Port = 28000              // TCP port for control/data connections to Naqs  
     345    Password = none           // access password (not used in version 1.3)  
     346    MaxConnections = 10       // maximum number of simultaneous connections  
     347    SocketType = Direct       // connection type (Direct or Callback)  
     348    DataBufferLength = 100    // Buffer length for data channels (# packets) 
     349}}} 
     350 
     351'''Packet retransmission''' 
     352 
     353Inside the section !NetworkInterface of the file Naqs.ini enable !RetxRequest. If !RetxRequest is not enabled then !MaxTolerableLatency is ineffective. 
     354{{{ 
     355    [ NetworkInterface ]  
     356    Port = 32000           // UDP port for incoming NMX data (usually 32000)  
     357    SendDelay = 250        // milliseconds to delay after each send  
     358    RetxRequest = Enabled 
     359    MulticastGroup = 224.1.1.1  
     360}}} 
     361 
     362 
     363=== Sample Configuration File === 
     364{{{ 
     365# 
     366#                     Configuration File for nmxptool 
     367# 
     368MyModuleId           MOD_NMXPTOOL 
     369RingName             WAVE_RING           # Transport ring to write data to. 
     370 
     371HeartBeatInterval    10                  # Heartbeat interval, in seconds. 
     372LogFile              1                   # 1 -> Keep log, 0 -> no log file 
     373                                         # 2 -> write to module log but not stderr/stdout 
     374 
     375#ForceTraceBuf1      0                   # On systems that support TRACEBUF2 
     376                                         # messages this flag will force the module 
     377                                         # to create TRACEBUF messages instead. 
     378                                         # Most people will never need this. 
     379 
     380Verbosity            16                  # Set level of verbosity. Verbosity is a bitmap: 
     381                                         # 1 Channel State, 2 Channel, 4 Raw Stream, 
     382                                         # 8 CRC32, 16 Connection flow, 
     383                                         # 32 Packet Management, 64 Extra, 128 Date, 
     384                                         # 256 Gap, 512 DOD, 1023 All messages. 
     385                                         # It is equivalent to the option -v. 
     386 
     387NmxpHost             naqs1a.int.ingv.it  # NaqsServer/DataServer hostname or IP address. 
     388                                         # It is equivalent to the option -H. 
     389 
     390NmxpPortPDS          28000               # Port number of NaqsServer (Default 28000) 
     391                                         # It is equivalent to the option -P. 
     392 
     393NmxpPortDAP          28002               # Port number of DataServer(Default 28002) 
     394                                         # It is equivalent to the option -D. 
     395#UserDAP              mtheo              # DataServer user name. Commented if 'none'. 
     396                                         # It is equivalent to the option -u. 
     397#PassDAP              mypass             # DataServer password. Commented if 'none'. 
     398                                         # It is equivalent to the option -p. 
     399 
     400#ShortTermCompletion  60                  # ShortTermCompletion, NOT use 'MaxTolerableLatency'. 
     401                                         #  0 decompressed packets are received in chronological 
     402                                         #    order without waiting for missing packets. 
     403                                         # [1..300] decompressed packets are received in 
     404                                         #    chronological order but waiting for missing packets 
     405                                         #    at most SECs seconds. 
     406 
     407MaxTolerableLatency  60                  # Raw Stream, NOT use 'ShortTermCompletion'. 
     408                                         # Max tolerable latency for each channel. 
     409                                         # (Default 600 sec.) [60..600]. 
     410                                         # Enable NaqsServer to send out retransmission requests 
     411                                         # for missed packets. Inside the section NetworkInterface 
     412                                         # of the file Naqs.ini set RetxRequest to Enabled. 
     413                                         # If RetxRequest is not enabled then MaxTolerableLatency is ineffective. 
     414                                         # In general, DO NOT use with parameter TimeoutRecv. 
     415                                         # It is equivalent to the option -M. 
     416 
     417#TimeoutRecv          30                 # Time-out in seconds for flushing queued data of each channel. 
     418                                         # It sets mschan to 0/0 ((Default 0. No time-out) [10..300]. 
     419                                         # Useful for retrieving Data On Demand with minimum delay. 
     420                                         # 'tsec' in nmxptool.desc should be greater than 'TimeoutRecv'. 
     421                                         # It is equivalent to the option -T. 
     422 
     423DefaultNetworkCode   IV                  # Default network code where in 'ChannelFile' or 'Channel' is not declared. 
     424                                         # It is equivalent to the option -N. 
     425 
     426                                         # N.B. nmxptool channel definition IS NOT equal to SCNL 
     427                                         # It is NSC, that is NET.STA.CHAN 
     428                                         # NET  is optional and used only for output. 
     429                                         # STA  can be '*', stands for all stations. 
     430                                         # CHAN can contain '?', stands for any character. 
     431                                         # Localtion value is always equal to "--". 
     432                                         # Related to the parameters 'ChannelFile' and 'Channel'. 
     433                                         # Network code will be assigned from the first 
     434                                         # pattern that includes station and channel. 
     435                                         # Example: N1.AAA.HH?,N2.*.HH?,MMM.BH? 
     436                                         # Second pattern includes the first. Unless AAA, all 
     437                                         # stations with HH channels will have network to N2. 
     438                                         # Station MMM will have default network defined by 'DefaultNetworkCode'. 
     439 
     440#MaxDataToRetrieve    3600               # Max amount of data of the past to retrieve from the 
     441                                         # DataServer when program restarts (default 0) [0..86400]. 
     442                                         # 0 to disable connection to DataServer. 
     443                                         # It is equivalent to the option -A. Related to 'ChannelFile'. 
     444                                         # If 'MaxDataToRetrieve' is zero and 'ChannelFile' is used, 
     445                                         # only data buffered by NaqsServer will be retrieved. 
     446                                         # Rather than using 'MaxDataToRetrieve', it is preferable, 
     447                                         # inside the section Datastream of the file Naqs.ini, 
     448                                         # setting DataBufferLength to a high value. 
     449                                         # 'MaxDataToRetrieve' allows to retrieve much more data of the past 
     450                                         # when the program restarts but it considerably slows down the execution. 
     451                                         # It is extremely harmful when you have many channels, 
     452                                         # in this case you might consider to subdivide the 
     453                                         # channels into different nmxptool instances. 
     454 
     455#mschan        280/9                     # mSECs/nC 
     456                                         # mSECs are milliseconds to wait before the next request, 
     457                                         # nC is the number of channels to request at a time. 
     458                                         # Delaying and requesting few channels at a time make 
     459                                         # data buffering on NaqsServer side more efficient. 
     460                                         # Determined empiric values are default 280/9. 
     461                                         # Condition: TotalNumberOfChannels * (mSECs/nC) < 15 sec.  
     462                                         # Related to -F and -b. 0/0 for disabling. 
     463 
     464ChannelFile   /home/ew/nmxptool.list.txt # List of channel patterns, as in 'Channel'. One for each line. 
     465                                         # This file will not be modified by nmxptool. 
     466                                         # Load/Save time of last sample of each channel in a file 
     467                                         # with the same name, same directory, appending suffix ".nmxpstate" 
     468                                         # It enables request of recent packets in order to allow data 
     469                                         # continuity when short disconnections occur or between program restarts. 
     470                                         # Related to 'MaxDataToRetrieve',  
     471                                         # It is equivalent to the option -F. Related to 'MaxDataToRetrieve'. 
     472 
     473    # DO NOT USE parameters 'Channel' and 'ChannelFile' together. 
     474    # 'ChannelFile' is preferable. At restart you can retrieve data of the past 
     475    # from the NaqsServer and optionally from the DataServer, see 'MaxDataToRetrieve'. 
     476 
     477# Example of nmxptool channel definition 
     478# Channel              ES.BOB.HH? 
     479# Channel              MN.TIR.HH? 
     480# Channel              MDI.HH? 
     481# Channel              DOI.HH? 
     482# Channel              SALO.HH? 
     483# Channel              MONC.HH? 
     484# Channel              *.BHZ               # Channel selection 
     485 
     486# Please, for other details about parameters, refer to the command line "nmxptool -h" 
     487}}} 
     488 
    103489 
    104490== Helpful Hints ==