DATES.DOC 1 Revised: 10-16-96 This program keeps track of birthdays, anniversaries, upcoming events, etc giving you advance warning so you can send out cards, leave town, etc. Features of this program: * Initially defaults to showing all events happening within 14 days. * You can set up multiple date files, each with their own day threshold; for example, one file for birthdays, another for business meetings, etc. * You can establish a different threshold on an event-by-event basis if desired. * This program can be included in your AUTOEXEC.BAT file to provide notices every time you turn on your PC. * You can specify dates like the "last Thursday" or the "first Monday" of a given month. * Month-long dates can be entered (e.g. "10/XX/XX Customer Service Month"). * Recurring dates that happen each month on the same date (e.g. "XX/14/XX Mortgage due") can be used. * Weekly reminders for events that happen the same weekday every week can be used. * Dates can be in the United States format (/DATE=mm/dd/yy) or in most other formats (e.g. /DATE=dd-mm-yy). * The output date format does not have to correspond to the input date format. * Months can be entered as sequential months (1 for January, 2 for February, etc) or else entered as the months themselves (JAN, FEB, etc). * Dates don't have to be padded (9/6/94, 09/06/94, and SEP/06/1994 are all accepted). * Dates in the future can be processed or ignored at your preference. * The program will show you the weekday, age, and/or days until the event if desired. * Comment lines can be displayed if desired (e.g. "Events relating to work:"). * The program can automatically pause when done or after a set number of lines if desired. * Entries can be sorted before display based on their "date difference" (the number of days before the event occurs) or in their original order. * Decimal codes (like CR/LF) can be embedded in the display file if desired, allowing you to change colors with in the display line or split the line into several lines for display. The dates input file: The dates file is a simple ASCII text file, created and maintained with any text editor. Each record should begin with a date (typically in mm/dd/yy format) followed by a description of the event. For example: 05/05/93 Lucy Baines Blank lines or any line which begins with a colon (":") or semi-colon (";") are ignored by the program. Lines which begin with an asterisk ("*") are printed verbatim (minus the asterisk); add spacing after the asterisk if you want the lines to be indented upon display. Note: Comments will be ignored if /SORT is specified. DATES.DOC 2 Revised: 10-16-96 The format for the date: Note that the format for the dates shown in the input file is not necessarily the same as the format shown on display. See the /ODATE=format parameter for output formats. For the date portion of the record, you have some flexibility. By default, the program expects dates to be in a mm/dd/yy format. So August 5, 1993 is "08/05/93". Even with the "mm/dd/yy" format, however, four-digit years can be entered if desired (e.g. "06/05/2005"). You can change the sequence of the numbers by using the "/DATE=format" option. For example, you can specify "/DATE=dd-mm-yy" if you want. The format must consist of the characters "DD", "MM, "YY", and one delimiter character. The "DD", "MM", and "YY" characters can be in either uppercase or lowercase letters. The date delimiter has to be one of the following characters: - (dash) / (slash) . (period) Examples of /DATE=format specifications might be any of the following: /DATE=mm/dd/yy (which is the default) /DATE=dd.mm.yy /DATE=mm-dd-yy The routine parses the date field based on the delimiters and accept fields with or without padding, years with or without the century, and alphabetic months instead of just numeric ones. For example, using /DATE=dd.mm.yy, all of the following September 5, 1994 events are the same: 05.09.94 Big event 5.9.94 Same event 5.sep.1994 Still the same thing 05.september.1994 And yet again the same event Relative weekdays: If you want, you can specify a day of the month based on a relative weekday within the month. For example, in the United States, Thanksgiving falls on the last Thursday in November and Father's Day is the third Sunday in June. If it's a relative weekday from the beginning of the month, DATES allows you to enter these in the "day" field by using "nww" where "n" indicates the sequence of the weekday (if you leave it off, it's presumed to be the first) and "ww" is the first two letters of the day. If it's a relative weekday from the end of the month, use "Lnww" ("n" defaults to 1). The weekdays themselves are entered as "SU", "MO", "TU", "WE", "TH", "FR", and "SA". So, for these two examples, they can be entered in your file as: 11/LTH/XX Thanksgiving 06/3SU/XX Father's Day DATES.DOC 3 Revised: 10-16-96 Weekly reminders: The program can be used to display weekly reminders, which happen the same day every week. This is entered like this: xx/FR/xx It's Friday! In this case, the program will show you the first instance of the event no matter what your /Ddays parameter is. If you want the event to be shown multiple times based on your /Ddays parameter, enter 5 relative weekday requests instead: xx/1FR/xx It's Friday (showing in advance) xx/2FR/xx It's Friday (showing in advance) xx/3FR/xx It's Friday (showing in advance) xx/4FR/xx It's Friday (showing in advance) xx/5FR/xx It's Friday (showing in advance) Dummy month, day, year parameters: The month, day, and year portions can be "xx" if desired. (Obviously, they can't be all provided as such.) If a day is "xx", you will be given the notice for the entire month and for 15 days before the start of the month. For dates which vary from year to year and which can't be done using something like "LTH" or "2MO" (primarily Easter) you can either use the "xx" option for the day or revise the file every year. If a month is "XX", the date is presumed to recur each month. For example, "XX/10/XX Mortgage due" or "XX/3TH/XX Monthly Alanon meeting". Which dates will show up (the /Ddays parameter): There's a default age threshold which determines what entries in your dates file(s) will show up. (Using multiple dates files--each with their own date threshhold--is documented below.) By default, any event coming due in the next 14 days will show up when the program is run. Dates with explicitly coded years which are in the future will, by default, not show up. If you'd like to add the next five years of specific dates for the family reunion in Hoboken, you can do so and only the next one will potentially show up. This can be overridden using the "/-FUTURE" parameter. Additionally, you can specify age thresholds on an event-by-event basis by beginning the relevant descriptions with "/Ddays" (e.g. "11/01/95 /D60 BIG meeting!"). Specific age thresholds like this are not overridden by the "/Ddays" parameter specified from the command line. There are other parameters which can be imbedded in the input file; see the "Other event-by-event parameters" section below. DATES.DOC 4 Revised: 10-16-96 How the dates are actually displayed: As far as the actual display of the information is concerned, each event is typically presented as just "date event", where any relative day references like "4TH" get resolved before the date is shown. For example, presume it's May 25 in 1994, /D14 is in effect, and your input file has the following three lines: 05/28/30 Mr.Fury 05/LMO/xx Memorial Day 05/31/57 Bruce Guthrie The initial display settings are /DATE /-DAY /-AGE /-CTDOWN. This presents the information as: 05/28/30 Mr.Fury 05/30/xx Memorial Day 05/31/57 Bruce Guthrie See the syntax descriptions for what each of these settings mean. Changing the settings to /-DATE /DAY /AGE /CTDOWN presents it as: [Sat] (64th) 3 days until Mr.Fury [Mon] 5 days until Memorial Day [Tue] (37th) 6 days until Bruce Guthrie In addition, DATES.EXE allows the dates that are displayed to be in a totally different format than those in the input file. By default, the output date format is identical to the input date format but it does not have to be. It can be overridden using the /ODATE=format parameter. The characters that can be used in the output format include the following special characters (from the VB/DOS on-line help): Symbol Description ÍÍÍÍÍÍ ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ d Display the day as a number without leading zeros (1-31) dd Display the day as a number with leading zeros (01-31) ddd Display the day as an abbreviation (Sun-Sat) dddd Display the day as a full name (Sunday-Saturday) ddddd Display a serial date number as a complete date (including day, month, and year) m Display the month as a number without leading zeros (1-12); if used immediately following h or hh, the minute rather than the month is displayed mm Display the month as a number with leading zeros (01-12); if used immediately following h or hh, the minute rather than the month is displayed mmm Display the month as an abbreviation (Jan-Dec) mmmm Display the month as a full name (January-December) yy Display the year as a two-digit number (00-99) yyyy Display the year as a four-digit number (1900-2040) DATES.DOC 5 Revised: 10-16-96 You can imbed other characters in the format string as well. If you need a space character, use an underscore character instead. For example, if today is September 12, 1996, the following /ODATE=format specifications yield the following results: mm/dd/yy 09/12/96 mmm_dd,_yyyy Sep 12, 1996 You can add the weekday to the output either using the /DAY parameter or by specifying the /ODATE=format to be something like: mm/dd/yy [ddd] The program does not actually verify your /ODATE=format specification and you may get a run-time error if you specify it incorrectly. Sorting: Records in the input file don't have to be in any particular order. Unless sorting is specified, the dates will be presented in the order they appear in the file so putting them in chronological order makes the most sense. Multiple input files: You can specify multiple date input files. They are processed in the order they are entered. By default, each will have the initial date restriction (typically 14 days). You can override the date restriction for a specific file by including the date restriction after the file name. For example: DATES DATE1.TXT DATE2.TXT /D10 DATE3.TXT Given a default 14-day restriction, the date restrictions will be 14 days for DATE1.TXT and DATE3.TXT, 10 days for DATE2.TXT. If you want to override the date restriction for all files, include that date restriction before the file name. For example: DATES /D5 DATE1.TXT DATE2.TXT /D10 DATE3.TXT In this case, the date restriction will be 5 days for DATE1.TXT and DATE3.TXT and 10 days for DATE2.TXT. DATES.DOC 6 Revised: 10-16-96 Other event-by-event parameters: In addition to being able to specify "/Ddays" on an event-by-event basis, certain command-line parameters can be embedded within the dates input file. See the discussion about "Syntax" later for a description of these parameters. These parameters must begin in the first column of the line and only one parameter can be specified on a line. These parameters override one or more defaults for the current input file only and can be set and reset throughout the file. The parameters affect the defaults for all dates which appear after them in the file until either another parameter overrides them or the file ends. The acceptable parameters are: /Ddays (can also be specified for an individual event) /DATE=format /DATE and /-DATE /DAY and /-DAY (same as /WEEKDAY and /-WEEKDAY) /AGE and /-AGE /CTDOWN and /-CTDOWN /COLOR=nnn nnn nnn nnn For example: 01/01/XX A stellar new years event /-AGE /-DAY 01/20/92 Expect the unexpected! 01/22/94 Another one (still covered by same parameters) /AGE 01/23/94 Skipping age on this one /-AGE 01/25/94 And reinstating it here A sample United States-oriented DATES.TXT file is provided and consists of the following lines: 01/01/xx New Year's Day 01/3MO/xx Martin Luther King's birthday 02/14/xx \000\012\000 Valentine's Day  03/17/xx St. Patrick's Day 03/30/xx -ish Easter 04/1SU/xx Daylight Savings Time begins (add an hour) 05/2SU/xx Mother's Day 05/LMO/xx Memorial Day 05/31/57 Bruce Guthrie (bguthrie@nmaa.org) \000\012\000û 06/3SU/xx Father's Day 07/04/xx July 4th (\000\012\000U.S \000\015\000Independence \000\009\000Day) 09/1MO/xx Labor Day 10/LSU/xx Daylight Savings Time ends (subtract an hour) 10/31/xx Halloween 11/1TU/xx Election Day 11/11/xx Veteran's Day 11/4TH/xx Thanksgiving 12/25/xx Christmas (See "Embedding decimal codes in the date files" discussion below for explanation of "\nnn" codes.) DATES.DOC 7 Revised: 10-16-96 Embedding decimal codes in the date files: You can embed decimal codes in the data file using "\nnn" (where "nnn" is the decimal value) or "&Hhh" (where "hh" is a hexadecimal code). This is mainly used in cases where you might want to split the entry into multiple lines by putting in a "\013". You're responsible for your own spacing if you use this feature. See the BRUCEHEX.DOC file. You can also use this feature to embed color commands within the text so the text colors change when a particular item is displayed. This requires some effort but it can be done by embedding \000\0ff\00b in the text. For example: 07/06/95 This is a \000\006\003multiline\000\007\004\013test The example above displays the item in two lines. The first part of the line will be in the default color (defaults to white on black), the word "multiline" will be brown on cyan, and the word "test" will be in white on red. The \nnn codes must be entered correctly or you'll get unpredictable results. Note that this requires three "\nnn" parameters each time; the first is "\000" saying that the color's about to be reset, the second is "\0ff" and specifies the foreground color, and the third is "\00b" and specifies the background color. Foreground colors: Low intensity High intensity 0 = black 8 = dark grey 1 = blue 9 = light blue 2 = green 10 = light green 3 = cyan 11 = light cyan 4 = red 12 = light red 5 = magenta 13 = light magenta 6 = brown 14 = light yellow 7 = white 15 = bright white Adding 16 to any color will make the text blink. Background colors can consist of 0 to 7 above. Bright white on blue, for example, would be \000\015\001. If you wanted to, you could embed something like this in your file: 07/04/xx July 4th \013\000\012\007ÝÝ\000\001\007°°\013\000\012\007ÝÝÝÝ The "Ý" symbol is decimal 221 and can be entered as Alt-221 (using the numeric keyboard or replaced with "\221"). Similarly, "°" is decimal 176. The above example would draw a (crappy) little flag on your screen. Remember again that you are responsible for your own line indentation for the second and subsequent lines. Want to flag lines that are more significant than others? Add something like \000\012\000û at the end of the items that are important. This adds a bright red on black check mark (decimal 251) to important lines. DATES.DOC 8 Revised: 10-16-96 Specifying command-line parameters: Parameters for this program can be set in the following ways. The last setting encountered always wins: - Read from an *.INI file (see BRUCEINI.DOC file), - Through the use of an environmental variable (SET DATES=whatever), or - From the command line (see "Syntax" below) Syntax: DATES [ date_file ... ] [ /Ddays ] [ /SKIP ] [ /DATE=format ] [ /ODATE=format ] [ /-DATE ] [ /DAY ] [ /-AGE ] [ /FUTURE ] [ /CTDOWN ] [ /SORT | /-SORT ] [ /GLOBAL | /-GLOBAL ] [ /COLOR=nnn nnn nnn | /MONO ] [ /Q | /-Q ] [ /CLS | /-CLS ] [ /P | /Pn | /-P ] [ /W | /W0 | /-W ] [ /R ] [ /Iinitfile | /-I ] [ /? ] [ /?&H ] [ > filename ] where: "date_file" is the name of the input text file. It can contain drive and path information if desired. This defaults to DATES.TXT. If no filename is specified, the program will check for it along your DOS path beginning with your default subdirectory. Multiple date files and date restrictions are allowed. See the notes above about this. In order to allow you to specify the date_file (or files) in an *.INI file, the date_file name can be preceded by "/C". For example, "/CC:\BAT\DATEMINE.TXT". "/Ddays" (or "days") are the number of days in advance you want the warning. Initially defaults to /D14. Generic days ("11/xx/xx") are not affected by this setting; you automatically get the notice 15 days before the beginning of the month and through the entire month itself. Events coded with specific "/Ddays" entries are also not affected by the command-line "/Ddays" setting. "/SKIP" says to print a message (unless /Q is specified) but otherwise ignore it if one or more of the date input files is not found. "/-SKIP" says to abort if any of the input files are not found. "/DATE=format" specifies the format that the date is to have. The date must consist of pairs of "mm" (month), "dd" (day), and "yy" (year) characters in any order. A single consistent delimiter character--either "/", ".", or "-"--should be used around the pairs of characters. Examples, /DATE=mm/dd/yy and /DATE=dd.mm.yy. Note that the format does not restrict you to have two-character date items; it is mainly used to identify the delimiter between items as well as the order in which the month, day, and year items appear. Four-digit years, spelled out months, etc are all acceptable. "/ODATE=format" specifies the format that the output date is to have. See the section on "How the dates are actually displayed" above for more details about options in the format. DATES.DOC 9 Revised: 10-16-96 "/DATE" indicates that the date is to be presented if the entry is show. This is initially the default. "/-DATE" skips showing the date of the event when it's displayed. "/DAY" (or "/WEEKDAY") shows the day of the week for each event if possible. "/-DAY" (or "/-WEEKDAY") skips showing the day of the week. This is initially the default. "/AGE" shows the age of the event when it's displayed. This is only done for entries that have a specific year. This is initially the default. "/-AGE" skips showing the age of the event. "/FUTURE" says to include dates which occur in future years outside of your date range. For example, if it's currently June 5, 1996, "/FUTURE" will allow an event scheduled for June 5, 1997 to show up; otherwise, it won't. Initially defaults to "/-FUTURE". "/-FUTURE" says that dates which occur in future years will not show up. This allows you to pre-load your file with major upcoming dates into the far future (family reunions for the rest of eternity, for example). This is initially the default. "/CTDOWN" adds a "x days until" message in front of any displayed event. "/-CTDOWN" skips adding the "x days until" message. This is initially the default. "/SORT" sorts the entries by their date difference (the number of days between now and the date of the event). If you're using more than one dates file with the "/-GLOBAL" (default) parameter, all appropriate entries from a given dates file will be sorted and displayed before any entries from the next dates file are displayed. The "/GLOBAL" parameter will combine them all before sorting them. Using "/SORT" precludes you from showing any display comments (lines beginning with "*") in your file. Currently, the program limits you to displaying 100 items per input file if /SORT is specified; let me know if this limit is too low for you. "/-SORT" says to display the entries as they're found in the files. This is initially the default. "/GLOBAL" invokes "/SORT" and merges multiple date input files if found, sorting them as a unit instead of individually. "/-GLOBAL" treats each date input file as a unique entity for sorting purposes. This is initially the default. DATES.DOC 10 Revised: 10-16-96 "/COLOR=nnn nnn nnn" specifies the color settings to use for (in order) regular text, dates happening today, and the ages of dates happening today. Any input lines which begin with an asterisk are printed using the third color set. Each setting must consist of three digits, the first two being the foreground color and the last being the background color. The foreground color should be padded on the left with a 0 if it is only one digit in length. Defaults to "COLOR=070 150 090" (white on black, bright white on black, and bright blue on black). Foreground colors: Low intensity High intensity 0 = black 8 = dark grey 1 = blue 9 = light blue 2 = green 10 = light green 3 = cyan 11 = light cyan 4 = red 12 = light red 5 = magenta 13 = light magenta 6 = brown 14 = light yellow 7 = white 15 = bright white Adding 16 to any color will make the text blink. Background colors can consist of 0 to 7 above. Bright white on blue, for example, would be "151". "/MONO" (or "/-COLOR") suppresses all screen color settings. Initially defaults to "/COLOR". "/COLOR" (or "/-MONO") allows screen color settings and is initially the default. "/Q" stops the printing every message except for the actual date lines. This option is automatically invoked if redirection is used. "/-Q" turns back on the printing of almost every message. This is the initially default unless redirection is used. "/CLS" clears the display before showing the results. "/-CLS" does not clear the display first. This is the default. "/P" says to pause the output every 23 lines. (NOTE: The /P, /Pn, and /-P options affect pausing while listing events; the /W, /W0, /-W options affect pausing after the program finishes.) "/Pn" says to pause the output every n-number of lines. "/-P" says to not pause the output at all. This is initially the default. DATES.DOC 11 Revised: 10-16-96 "/W" says to pause with a "Press any key to continue" message after the program finishes if any hits were found. Note that this parameter is ignored if redirection out is being used. "/W0" says to pause afterward whether any hits were found or not. Note that this parameter is ignored if redirection out is being used. This is initially the default if the program is run under Windows. "/-W" says to not pause afterward at all. This is initially the default if the program is run under DOS. "/R" sets a DOS return code equal to the number of dates found. The standard way to use something like this is with a test on the DOS ERRORLEVEL in an AUTOEXEC.BAT file or something. For example: DATES /R IF ERRORLEVEL 1 GOTO HITS GOTO END :HITS PAUSE :END ECHO DONE Note that the results of particular example could have been done easier using DATES' /W parameter. "/Iinitfile" says to read an initialization file with the file name "initfile". The file specification *must* contain a period. Initfiles are described in the BRUCEINI.DOC file. Initially defaults to "/IDATES.INI". "/-I" (or "/INULL") says to skip loading the initialization file. "/?" or "/HELP" or "HELP" shows you the syntax for the command. "/?&H" gives you a hexadecimal and decimal conversion table. "> filename" redirects the output to a DOS file. This is standard DOS redirection. Automatically invokes /Q option and turns off the last of the status messages. DATES.DOC 12 Revised: 10-16-96 Return codes: DATES returns the following ERRORLEVEL codes: 255 = syntax problems, or /? requested If /R is specified, the ERRORLEVEL code will be the number of hits found. Author: This program was written by Bruce Guthrie of Wayne Software. It is free for use and redistribution provided relevant documentation is kept with the program, no changes are made to the program or documentation, and it is not bundled with commercial programs or charged for separately. People who need to bundle it in for-sale packages must pay a $50 registration fee to "Wayne Software" at the following address. Additional information about this and other Wayne Software programs can be found in the file BRUCEymm.DOC which should be included in the original ZIP file. ("ymm" is replaced by the last digit of the year and the two digit month of the release. BRUCE512.DOC came out in December 1995. This same naming convention is used in naming the ZIP file that this program was included in.) Comments and suggestions can also be sent to: Bruce Guthrie Wayne Software 113 Sheffield St. Silver Spring, MD 20910 fax: (301) 588-8986 e-mail: bguthrie@nmaa.org http://hjs.geol.uib.no/guthrie/ See BRUCEymm.DOC file for revision history. Please provide an Internet e-mail address on all correspondence.