Lines with ### are used for navigation by the program's help system. ###0### DbEwarn v1.5. Program for checking data flow in Database, sending e-mail warnings & writing the results into Database as statistics. Usage: dbewarn [OPTIONS] If dbewarn starts without any option, it tries to get all the options from dbewarn.ini. Boolean options (such as -um & -usestat) in command line can be simply present (without a value), in which case their value is cosidered to be "1" (true/on/yes). In options defining filename/directory, either "\" or "/" can be used as a divider of directories. OPTIONS (position doesn't matter, except for -? & -lang): -? - Help, must be the first option in the comm. line, shows help about the next option, for example: -? -tstart. If there is no option after -?, then the general help is shown (this text). To get help in Russian, the -lang option must be put before -?. For example, to get help about -lang itself in Russian, options in the comm. line should go like this: -lang=ru -? -lang If Russian chars are shown incorrectly, a default encoding can be changed (see help on the -lang option); -lang - Language of the interface, help & e-mails. To get help in Russian, -lang must be the first in the comm. line, otherwise its position doesn't matter; -odbc - Name of ODBC source (wsg by default); -user - User name (wsg by default); -password - User password (wsg by default); -sta - Mandatory. Station(s) to check, see its own help for details; -tstart - Start time of checking period (current moment in UTC by default); -tend - End time of checking period; -tbegin - Start time of checking period (in UNIX format: [-]111.11); -tqty - Duration in seconds from the start time (can be negative); -m0 - Sets time to 00:00:00 for -tstart/-tbegin, -tend & -tstbegin; -use_tend - Use TEND field instead of TBEGIN+TQTY in checking conditions; -to - List of e-mails divided by ";" or "," (w/o spaces). This is a list of the warnings' recipients; -from - E-mail of the sender of warnings (test@gsras.ru by default); -sub - Subject of the warning messages (default: DbEwarn ALERT); -ms - the sending SMTP mail server (default: mailhost.gsras.ru); -um - Send one e-mail warning for all stations (default: separated e-mails for all stations); -restore - Send notices, when data flow is restored; -log - Log filename (default: dbewarn.log); -maxlogsize - Max log-file size (default: 3 Mb); -dir - Directory for log files (has a higher priority than -log); -ini - Ini-file with options (default: dbewarn.ini); -tn - n = 1..8, i.e. t1,t2...t8, periods of data absence & warnings. -tfuture - Send wanrings with this period, if data with dates in the future (after - tend) is found. Default: at every program's run; -usestat - Use the statistics table STATIS; -tstbegin - The earliest time in the table STATIS. All the statistics before that time is deleted at the program's start; -maxdel - Max number of records, that can be deleted from the table STATIS (default: 300000); -admto - List of e-mails divided by ";" or "," for sending warnings, when more than -maxdel record needs to be deleted from STATIS. If that option is not specified, then the option -to used instead; -stdr - Draw statistics (default: no); -stlib - A path to the dynamic library, which draws statistics (default: dbewarndl.* in the curr. dir, extension depends on OS); -stini - Ini-file with options for drawing statistics (DbEwarn's ini by default); -v - Log's verbose level. ###0### The table STATIS for storing statistics ------------------------------------------------------------------------------- If -usestat=1, the table is created, if it doesn't exist in the DB yet, at the program's start. Attempts to create it with different date/time types are made in this order: 1. datetime; 2. smalldatetime - for MS SQL; 3. date - for Oracle (and any other DBMS?). The creation query (types are put in place of asterisks): CREATE TABLE statis (id integer not null,sta varchar(6),chan varchar(8), lcode varchar(8), maxtime ***,maxitime float,checktime ***,flags integer, primary key (id)) =============================================================================== Options of the command line and ini-file. ------------------------------------------------------------------------------- ###?### OPTION -? FORMAT: -? [-_other_option_] EXAMPLE: -? -sta Get the help about "_other_option_". -? must be the first option in the comm. line, the next (second) option is the one, you want to read a help about. The second option must be put without value (i.e. just -? -sta, and not -? -sta=...). The -? option can go second, olny when a Russina help is desired. In that case the -lang option (specifying a language and, if needed, an ecoding of the console) goes first. Encoding can be specified, if Russian symbols are shown incorrectly, i.e., if the console's encoding is different from the one used by the program. For details see help on the -lang option. The -lang option ca also be specified in the ini-file, then it can be ommited in the command line. This particular help topic is shown, when "dbewarn -? -?" is executed. If _other_option_ is not specified, then the general help is shown. ###?### ------------------------------------------------------------------------------- ###lang### OPTION -lang FORMAT: -lang=language[:encoding] EXAMPLES: -lang=ru:UTF-16 -lang=ru:1251 -lang=ru:cp866 The language of the interface, help & e-mails. To get help in Russian, -lang must be put first in th command line, otherwise its position doesn't matter. Default: en. The language can be "en" (English) or "ru" (Russian). The Russian language's encoding can be one of the following (in fact, all that Qt supports): 1. IBM 866 2. KOI8-R 3. KOI8-U 4. Windows-1250 to 1258 5. UTF-8 6. UTF-16 7. UTF-16BE 8. UTF-16LE 9. UTF-32 10. UTF-32BE 11. UTF-32LE 12. Apple Roman 13. Big5 14. Big5-HKSCS 15. CP949 16. EUC-JP 17. EUC-KR 18. IBM 850 19. IBM 874 20. ISO 2022-JP 21. JIS X 0201 22. JIS X 0208 23. MuleLao-1 24. ISO 8859-1 to 10 25. ROMAN8 26. Shift-JIS 27. TIS-620 28. ISO 8859-13 to 16 29. TSCII 30. WINSAMI2 31. GB18030-0 32. Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml For items 1, 4, 15, 18, 19 a number or "cp"+number can be specified. "cp" (in English leters) means "code page". If the encoding is ommited, then the default encoding is used: for Windows: IBM 866 (DOS' Russian encoding); for other OS's (MacOS, Unix's): UTF-8. This "encoding" doesn't affect the encoding of the log-file & e-mails - for those Windows-1251 is always used. The -lang option can also be specified in the ini-file, then it can be ommited in the command line. ###lang### ------------------------------------------------------------------------------- ###odbc### OPTION -odbc FORMAT: -odbc=source_name EXAMPLE: -odbc="wsg oracle1" ODBC-source name (default: "wsg"). ###odbc### ------------------------------------------------------------------------------- ###user### OPTION -user FORMAT: -user=user_name EXAMPLE: -user="wsg oracle1" User name for logging in the database (default: "wsg"). ###user### ------------------------------------------------------------------------------- ###password### OPTION -password FORMAT: -password=user_pass EXAMPLE: -password="wsg oracle1" User password for logging in the database (default: "wsg"). ###password### ------------------------------------------------------------------------------- ###sta### OPTION -sta FORMAT (without spaces): -sta={ @path | * channels | STA1[*] channels1 [: LC1] [; STA2[*] channels2 [: LC2]]... } where path (goes after the @ symbol) is a path to the other ini-file (not dbewarn.ini) in wsg_wrtdl format, which contains the stations list; channels ::= [: CH1[*] [, CH2[*]]...] LCx - location code (LCODE field), optional ('??' by default), if LCx=?? or is ommited, then the condition "LCODE='??' OR LCODE IS NULL" is used, if LCx=NULL, then the condition "LCODE IS NULL" is used, any other value results in the "LCODE='LCx'" condition; STAx - station code (not international, but from the SITE.STA field, i.e., the internal WSG code); CHx - channel name for the corresponding STAx. * (asterisk) in STAx & CHx represents any combination of these chars: % _ ? * and changes "=" to "LIKE" in the checking conditions (for example: STA='AAA' / STA LIKE 'AA%') * or % - any text; ? or _ - any char. EXAMPLES: -sta=@..\wsg_wrtdl\wsg_wrtdl.ini - read stations and channels list from another ini-file -sta=* - all stations -sta=*:BHZ - all stations' BHZ channel -sta=*:BH*,SHN - all stations' SHN channel & all channels like BH... -sta=OBN - all channels for the station OBN -sta=OBN:BHN,BHE - station OBN: BHN & BHZ channels -sta=A*:BH*,SHE;OBN:BHZ - all stations like A...: all channels like BH... & SHE channel; station OBN: BHZ channel STA is a mandatory option (no default value)! It can only be ommited, if the list of stations & channels is specified in the ini-file containg options (in which case, in the system section of the ini-file there must be the field groups=N, and also N sections describibg stations in the wsg_wrtdl.ini format, must be present). ###sta### ------------------------------------------------------------------------------- ###tstart### OPTIONS -tstart, -tend, -tbegin, -tqty & -tstbegin -tstart - start time of the period, in whicj the data presence is checked. Has a higher priority than -tbegin. -tbegin - the same as above, but in the UNIX format (a number of seconds from 01.01.1970). May be < 0, in which case it means a number of seconds BACK from the current system time. -tend - end time of the period. Has a higher priority than -tqty. -tqty - time in seconds from -tstart/-tbegin. May be used instead of -tend, in which case tend = tbegin/tstart + tqty. -tstbegin - the earliest time, from which the statistics is present in DB. All the statistics before that time is deleted at the program's starts. This option is ignored, if -usestat is not specified (that is, set to 1). See also help for -maxdel. FORMAT of -tqty: -tqty=[-]seconds EXAMPLE: -tqty=-86400 FORMAT of -tstart, -tend & -tstbegin (use double quotes, if there are spaces): -tstart="{[-] | [+]}{Date Time | Time Date}" Date format: [[-]YEAR.[-]MONTH.[-]DAY] | [-]MONTH.[-]DAY] | [-]DAY] Time format: [[-]HOUR:[-]MIN:[-]SEC] | [-]MIN:[-]SEC] | [-]SEC] Let SD is current system date & TM is a date of -tstart, -tend & -tstbegin. EXAMPLES: -tstart="--1.2.-100 11:-156" - one year after SD.year, but two months earlier, plus 100 days, minus 11 minutes & plus 156 seconds. -tstart=2000.11.23 - February, the 23th, year 2000, midnight (with -m0 set) or the current system time (without -m0). Date & Time parts may be put in any order, thus the first encountered divider ("." or ":") defines the type ("." - it's a Date, ":" - it's a Time). If a number w/o a divider is encountered first, it's considered to be a DAY OF DATE (then the next part, if present, is Time, for ex.: "23 12:45:10"). If "-" or "+" is encountered at the very 1st position, then: 1) All the folowing numbers are relative to the corresponding parts of the current system date. 2) TM.year = SD.year (- / +) YEAR (and so on for other parts of the date/time). That means, ANY numbers can be used for YEAR/MONTH/..., including those < 0. 3) You can put "-" before any of YEAR/MONTH/... values, which also influents the sign of operaion in (2). 4) Any omitted part of Date/Time is set to a base value (YEAR - 1970, others - 0 or 1). 5) -m0 option sets SD time to 00:00:00. 6) If, for example, MONTH=-1, & SD.month=3 (March) & SD.day=31, then the result will be: TM.month=2 (February) & TM.day=28 (or 29 for a leap year, but not 31!). If there is NO "-" or "+" at the 1st position, then: 1) Date & Time are interpreted normally (TM.year = YEAR & so on). 2) You can NOT put "-" before YEAR/MONTH/...! 3) Any omitted part of Date/Time is replaced with the corresponding SD part. 4) -m0 option sets SD time to 00:00:00, and in (3) all the ommited parts are set to base values. If neither of -tstart / -tbegin is specified, then the start time is set to current moment (SD). In this case, option -m0 (if specified) sets the start time to the midnight of the current day. If -tstart is specified, then -tbegin is ignored. If -tend is specified, then -tqty is ignored. If -tbegin < 0, then "start time" = SD + tbegin (i.e., if -tbegin < 0, it changes to subtraction). If "start time" > "end time", they are exchanged. If neither of -tend / -tqty is specified, then the checking period is 1 day before the current sys. time. ###tstart### ------------------------------------------------------------------------------- ###m0### OPTION -m0 FORMAT: -m0 Sets the Time part of -tstart/-tbegin, -tend è -tstbegin to 00:00:00 (default: leave the Time part alone). ###m0### ------------------------------------------------------------------------------- ###use_tend### OPTION -use_tend FORMAT: -use_tend This option makes the program use TEND field instead of TBEGIN+TQTY in checking conditions (default: use TBEGIN+TQTY). ###use_tend### ------------------------------------------------------------------------------- ###to### OPTION -to FORMAT: -to=emails where emails ::= email1[;email2...] EXAMPLE: -to=aaa@gsras.ru;bbb@mail.ru E-mail addresses, divided by ";" or ",", to which the warnings about the absence of data and its restoration are sent. If this option is ommited, then no e-mails will be sent, leaving only screen & log file output. ###to### ------------------------------------------------------------------------------- ###from### OPTION -from FORMAT: -from=sender_email EXAMPLE: -from=aaa@gsras.ru E-mail address of the sender of warnings (default: test@gsras.ru). ###from### ------------------------------------------------------------------------------- ###sub### OPTION -sub FORMAT: -sub=subject EXAMPLE: -sub="No data!" The general part of the subject of all warning e-mails (default: "DbEwarn ALERT"). If -um is not specified or a system warning needs to be sent (see the -admto option), then a type of a warning will be added to this subject, when sending an e-mail. ###sub### ------------------------------------------------------------------------------- ###ms### OPTION -ms FORMAT: -ms=smtp_server EXAMPLE: -ms=smtp.sm.com SMTP mail server for sending warnings (default: mailhost.gsras.ru). ###ms### ------------------------------------------------------------------------------- ###um### OPTION -um FORMAT: -um Makes program send united warnings for all stations (i.e., all warnings for all stations are sent in one e-mail with the subject -sub). (default: send a separated e-mail for every station). If this options is NOT specified, then the e-mail subject will be: (_), for example: DbEwarn ALERT (ANN_no data). can be one of these: "no data" - data absence message; "restored" - data restoral (after absence) message; "future" - data error, i.e. data with dates in the future is found (after -tend, with the date 01.01.2047, for example); "Frestored" - data restoral (after "future") message. "restored" and "Frestored" messages are only sent, if -restore is specified. ###um### ------------------------------------------------------------------------------- ###restore### OPTION -restore FORMAT: -restore Makes the program send messages about the restoral of the data flow after a period of absence or an error. (default: don't send messages about the data flow's restoral). ###restore### ------------------------------------------------------------------------------- ###log### OPTION -log FORMAT: -log=log_file EXAMPLE: -log="c:\tmp 2\log1.txt" Log filename (default: dbewarn.log in the program's directory). It's better to use an extension (log, txt), that can be immediately openned by a text editor. If the -dir option is specified, then -log is ignored. ###log### ------------------------------------------------------------------------------- ###maxlogsize### OPTION -maxlogsize FORMAT: -maxlogsize=max_size EXAMPLES: -maxlogsize=20m -maxlogsize=7d Max size of a log file (default: 3 Mb). 1. If the -dir option is NOT specified: 1.1. If -maxlogsize is specified with simply a number, or a number with letters K/k/M/m after it: When a log file begins to exceed this size, its upper lines are deleted until the log file's size is less than -maxlogsize. The max size is specified in bytes (a number w/o any letters), kilobytes (an English "k" or "K" is added to the number) or megabytes (an English "m"/"M" is added), but it can't be < 16 Kb. "k" - a multiplication by 1024, m - a multiplication by 1024*1024=1048576. 1.2. If -maxlogsize is specified with a letter D/d: The upper lines with dates <= current system date minus a number of days from -maxlogsize (7d - seven days), are deleted. It can't be less than one day. 2. If the -dir option is specified: 2.1. If -maxlogsize is specified with simply a number, or a number with letters K/k/M/m after it: A combined size of 1-day files is calculated, starting from the current system date and moving back to the past. When a combined size starts to exceed -maxlogsize, a deletion of 1-day log files starts (excluding the log file, which was the first to make a combined size exceed -maxlogsize). 2.2. If -maxlogsize is specified with a letter D/d: All log files with dates <= current system date minus a number of days from -maxlogsize, are deleted. ###maxlogsize### ------------------------------------------------------------------------------- ###dir### OPTION -dir FORMAT: -dir=directory EXAMPLE: -dir="c:\log 2" A directory, in which log files (a separate file for every day) will be written. That is, logs of every complete run of the program of one day are written to the same log file. Logs of complete runs of the next day will be writen to a new file, etc. Log filenames are constucted using this pattern: yyyy_mm_dd.log If the -dir option is specified, the -log option is ignored (-dir has a higher priority). ###dir### ------------------------------------------------------------------------------- ###ini### OPTION -ini FORMAT: -ini=ini_file EXAMPLE: -ini="c:\tmp 2\111.ini" Ini filename (default: "dbewarn.ini" in the program's directory). Ini-file can contain fields with the names, identical to the names of options of the command line, in the sections described below. Boolean options (such as -m0) must have a value 1/true or 0/false (unlike in the command line, where they may be just present w/o a value, which is equivalent to the value of 1). Command line's options have a higher priority, than options with the same names in ini-file. Ini-file's sections and options inside of them: [LOG] - LOG (the same name as the section's), MAXLOGSIZE, DIR; [MAIL] - TO, FROM, SUB, MS, UM, RESTORE, ADMTO; [DATABASE] - ODBC, USER, PASSWORD, USE_TEND, USESTAT; [SYSTEM] - GROUPS, M0, STA, TSTART, TEND, TBEGIN, TQTY, TFUTURE, TSTBEGIN, MAXDEL, V, LANG, STDR, STLIB, STINI. The GROUPS option is only used in ini-file. It defines a number of [GROUPx] sections, that must be used to perform a data check. "x" in [GROUPx] is a number from 1 to GROUPS. Each section must contain a description of: 1. station code (STATION field, an internal WSG code,not an international one); 2. station's channels (CHAN field, with a list of channels divided with ","); 3. location code (LCODE field). If the STA option is not specified, an attempt to build it from such "groups" is made, provided that they are present in the ini-file. But it should be noted, that the STA option has a higher priority, than "groups". Every [GROUPx] section MUST contain the STATION field and MAY contain the CHAN and LCODE fields. If CHAN is not specified, it's assumed to be "all channels"; if LCODE is not specified, a condition "LCODE='??' OR LCODE IS NULL" is used. Also, section with the time marks and the latest data states are written to the ini-file. They are used by the program to send e-mails with defined intervals (-t1,-t2...). ###ini### ------------------------------------------------------------------------------- ###t1### OPTION -t1, -t2, -t3, -t4, -t5, -t6, -t7, -t8 FORMAT: -tn=p1[-p2] EXAMPLE: -t1=1h-15n These are set in the command line or in the SYSTEM section in the ini-file. The meaning of these options is to increase the interval between e-mail warnings, when data is absent for a long time. The longer the absence period, the longer the interval between warnings. Different units may be used to specify a period: 1. seconds (s or nothing); 2. minutes (n); 3. hours (h); 4. days (d); 5. weeks (w); 6. months (m); 7. years (y); Letters in brackets are the notations of a period's time units. Units "year" & "month" don't depend on a leap year or certain month, they are constants, i.e., 1y = 365 days (365d), 1m - 30 days (30d). Other units: 1w = 7d, 1d = 24h, 1h = 60n, 1n = 60s. In other words, -t1=604800s is an equivalent of -t1=1w (60*60*24*7 = 604800). If seconds are used to specify a period, "s" letter may be ommited. The pairs "data absence period"-"sending period of warnings" are defined in p1 & p2 parameters. If p2 is ommited, it is assumed to be p1/4, e.g., -t1=1h is an equivalent of -t1=1h-15n. Logics of the check: if no -tn options are set at all, then warnings are sent on every program's run (when corresponding data is absent, that is). If there is no data during p1 from t1, then warnings are sent with p2 interval from t1. If the data absence period exceeds p1 from t1, then -t2 is checked. If there is no data during p1 from t2, then warnings are sent with p2 interval from t2 and so on. Example: T1=1h-15n T2=3h-30n T3=1d-1h T4=1w-1d That means, during the first hour of data absence warnings will be sent about every 15 minutes (considering the scheduler timings & other system inaccuracies). When more than an hour will have passed, program will start to check the second period; during 3 hours of the data absence, warnings will be sent every 30 minutes. 3 hours have passed - warnings will be sent once an hour. 1 day has passed - warnings will be sent once a day. 1 week has passed - warnings will still be sent once a day, that is with the interval p2 of the last period T4. Periods must be set in the order of an increasing duration of p1, otherwise the cheching logics will be disrupted. The 1st period (p1 from t1) should be >= tqty. To make warnings be sent in p2 intervals, the time marks are stored in the ini-file. For every channel of every station to be checked, the time of the last program's run is stored (if data is present), or the time of the last last warning's sending (if data is absent). Sections' names are stations' codes to be ckecked, and fields' names in each section are channels' codes to be ckecked. The state of date (absent/present/error - 0/1/2) is also stored if fields with names of channels plus "_TYPE". This is the last state of data flow, that the program determined on its last run, and that very number is inserted into the STATIS table, if statistics is enabled. Ini-file example: [ANN] BHE=1226930607 BHN=1226930607 BHZ=1226930548 BHE_TYPE=0 BHN_TYPE=0 BHZ_TYPE=0 ###t1### ------------------------------------------------------------------------------- ###tfuture### OPTION -tfuture FORMAT: -tfuture=p0 EXAMPLE: -tfuture=3h If data after the end of the checking period (e.g., there is data on 01.01.2047) is found, then a warning will be sent with an interval, specified in this option (default: 3 hours). Also, this message is sent (regardless of -tfuture), when "data in the future" appearss for the first time. Same units (n, h, d, etc.) can be used as for the -t1, -t2... options. ###tfuture### ------------------------------------------------------------------------------- ###usestat### OPTION -usestat FORMAT: -usestat This option defines, whether the program will or will not be working with the statistics table STATIS (create it if need be, and fill it with data). Default: no. ###usestat### ------------------------------------------------------------------------------- ###maxdel### OPTION -maxdel FORMAT: -maxdel=N EXAMPLE: -maxdel=500000 This option defines the max number of records (300000 by default), that the program is allowed to delete from STATIS. If more than -maxdel records need to be deleted, then a corresponding message is sent to the addresses from -admto (if specified) or -to (if -admto is not specified), and the deletion is canceled. In this case data needs to be deleted manually, making sure the DB is still functioning properly. The fact is that some DBMS's write all deleted records into the transaction log, which, in case of vast delete operations, may lead to a complete inability to make ANY changes to the data in the DB. This situation was tested on MS SQL. If -usestat is not specified, then -maxdel is ignored. ###maxdel### ------------------------------------------------------------------------------- ###admto### OPTION -admto FORMAT: -admto=emails where emails ::= email1[;email2...] EXAMPLE: -admto=aaa@gsras.ru;bbb@mail.ru E-mail addresses, divided with ";" or ",", which receive system warnings, such as those about inability to auto-clean the statistics table (when too many records need to be deleted, which can lead to an overflow of the DBMS' transaction log). See also the help on -maxdel. If the -admto option is ommited, then e-mails will be sent to the recipients from the -to option. If neither of them is specified, then e-mails won't be sent at all, leaving only screen & log file output. ###admto### ------------------------------------------------------------------------------- ###stdr### OPTION -stdr FORMAT: -stdr This option defines, whether the program will create statistic html-pages and pictures. They are not created by default. ###stdr### ------------------------------------------------------------------------------- ###stlib### OPTION -stlib FORMAT: -stlib=dyn_lib_file EXAMPLE: -stlib="c:\tmp 2\dbe.dll" The dynamic library, that is resposible for creating all of the statistic html-pages and pictures. This option makes sense, when the same library is used by a number of programs (for example, by both DbEwarnView and DbEwarn). ###stlib### ------------------------------------------------------------------------------- ###stini### OPTION -stini FORMAT: -stini=ini_file EXAMPLE: -stini="c:\tmp 2\111.ini" Default: DbEwarn's ini. This ini-file should contain all the option for creating html-pages of statistics. ###stini### ------------------------------------------------------------------------------- ###v### OPTION -v FORMAT: -v=N EXAMPLE: -v=2 Verbose level of the log file. "N" can be one of these: 0 - normal output (by default, only necessary info); 1 - "insert into statis" requests are also logged; 2 - ALL the requests to the DB are logged. ###v###