Chapter 4: The Demonstration Programs There are nineteen demonstration programs provided in source and executable form, and an additional demonstration program provided only as an executable file. Below is given, for each program, a brief description of what it does, its usage display and a list of the Dolphin functions used in the program. The usage display is the reminder of the syntax which is displayed when the program name is entered at the DOS prompt without any command line parameters. Some programs do not have usage displays. Certain details of the use of many of the Dolphin functions in these demonstration programs are explained in the corresponding parts of Chapter 3. Some date programs omit the "19" when display- ing dates in this century. The display format is selectable (see the DATEFORM program). (a) CALCONV Description: This program exercises the basic date conversion functions, namely, those which convert between a calendrical date and a Julian day number. (Julian day numbers are explained in Chapter 3, Section 1.) The program is three programs in one. The first converts a date to a Julian day number (and also shows the day of the week for that date). The second converts a Julian day number back to a date (with day-of-week). The third takes two dates, converts them to Julian day numbers and displays the difference plus one, i.e. the number of days between those dates and including them. Note that dates in this century must be entered as: month day 19year. If you enter 12 31 92 then the program will assume you mean not a date in the 20th Century but rather a date in the 1st Century. Usage display: This program provides three calendrical conversions: 1. For date to day-of-week and Julian day number use CALCONV month day year. 2. For Julian day number to date and day-of-week use CALCONV jdn. 3. For days between dates use CALCONV m1 d1 y1 m2 d2 y2. The number of parameters (3, 1 or 6) determines the conversion per- formed. All dates are in the Gregorian calendar (or in the proleptic Gregorian calendar if prior to October 15, 1592 (Gregorian)). Dolphin functions used: date_to_jdn() date_to_str() day_name() day_of_week() days_in_date_range() jdn_to_date() set_date_format_default() sltoa_commas() (b) DATEFORM Description: This program takes a date and demonstrates the many ways in which a date can be formatted. The combinations of different values in the Date_format structure, which is used to control the date display, allow for hundreds of different date display formats. Usage display: Use DATEFORM month day year Dolphin functions used: date_to_str() date_valid() output_redirected() pad_on_right() set_date_format_default() string() (c) NWEEKDAY Description: This program demonstrates the use of some date functions. It is used to calculate the date of a particular day of the week in a given month of a given year. Usage display: Use: NWEEKDAY n day_name month year This gives the date of the nth Friday or whatever for the specified month and year in the Gregorian calendar. The day name can be abbreviated, e.g. NWEEKDAY 3 Fri 12 2012. Dolphin functions used: capitalize() date_to_str() date_valid() day_name() day_of_week() ordinal_suffix() set_date_format_default() (d) TIMEFORM Description: This program takes a time and demonstrates the ways in which a time can be formatted. The combinations of different values in the Time_format structure, which is used to control the time display, allow for at least 27 different time display formats. Usage display: Use TIMEFORM hour minute second hsecond Dolphin functions used: pad_on_left() set_time_format_default() time_to_str() time_valid() (e) DSKPARAM Description: This program displays normally inaccessible information about the disk in each of the available drives. The data displayed is: drive number, device driver unit number, bytes per sector, sectors per cluster, shift factor, number of reserved boot sectors, number of FATs, number of root directory entries, offset to first data sector, number of clusters, sectors per FAT, offset to first root directory sector, device driver address and the media descriptor byte. Further details are given in Chapter 3, Section 4. Usage display: none Dolphin functions used: bios_disk_present() get_drive_parameter_block() output_redirected() (f) CURRDIR Description: This program displays the current subdirectories on all drives, and then randomly changes the current directory to a subdirectory on some drive. Usage display: none Dolphin functions used: bios_disk_present() get_directory() high_drive() last_drive_used() num_floppy_drives() set_directory() strrchr_n() time_elapsed_this_year() (g) SPLIT_P Description: This program demonstrates the directory functions to normalize a subdirectory path which is input by a user, and to split that path into its components and to recombine them. When run it awaits the entry of a path. This can include .., as in: ..\..\ABC\DEF\..\GHI The path is checked for validity and for existence. Usage display: none Dolphin functions used: gets_n() make_path() normalize_path() split_path() trim() (h) DIR_ATTR This program displays the files in a given subdirectory which satisfy a given file specification together with their file attributes. As explained in 3.6(a), the attribute specification is a string of the form [str1][!str2] which consists of one or more of R, H, S, V, D and A, which are interpreted as: R = read only, H = hidden, S = system, V = volume label, D = directory and A = archive. The string str1!str2 means: having one or more of the attributes in str1 and none of the attributes in str2; e.g. D!H means all directories which are not hidden and !HSVD means all files except those which are hidden, system, volume labels or directories. If the attribute specification is the empty string or is the null pointer NULL then all non-hidden files (other than directories and any volume name) are assumed; this is equivalent to attribute specification !HVD. Description: Usage display: Use: DIR_ATTR file_spec [attribute_spec] file attributes: RHSVDA, ! = not, e.g. DIR_ATTR K*.* AS!R Dolphin functions used: num_matching_files() output_redirected() read_directory() (i) SETFDATE Description: This is a small utility for setting the date and time stamp on a file. It accepts pathnames and wildcards, so it is possible, e.g. to use: SETFDATE \XYZ\*.TXT 31-12-1992 12:00. This is similar to the TOUCH utility provided by some vendors. Important: Do not change the dates of the executable files on the demonstration disk if you want VALIDATE.EXE to report that they have the correct date. Usage display: Use: SETFDATE file_spec [month-day-year] [hour:minute] Dolphin functions used: date_to_str() date_valid() get_system_date() get_system_time() normalize_path() set_date_format_default() set_file_date_time() set_time_format_default() time_to_str() time_valid() (j) COMPARE Description: This is a utility to compare files. It differs from the COMP utility provided with DOS in that it accepts wildcards. Thus one may enter: COMPARE \ABC\*.* \UVW\XYZ\*.* to compare all files in \ABC with files of the same name in \UVW\XYZ. Usage display: Use: COMPARE file_1 file_2 wildcards OK (e.g. COMPARE *.TXT *.DEC) Dolphin functions used: get_input_output_files() make_path() split_path() (k) NUMLINES Description: This counts the number of lines in a textfile, distinguishing between blank and non-blank lines. Usage display: Use: NUMLINES filename Dolphin functions used: num_lines_in_file() (l) PR_SPOOL Description: This program demonstrates the use of the interface provided in this library to the print spooler PRINT.COM (or PRINT.EXE). When run it checks whether the print spooler is installed, and if not asks whether to install it. A file for printing may be specified at the command line (e.g. PR_SPOOL FILE.TXT) but wildcards in the file specification are not allowed (this is left as an exercise for the reader). The program maintains the following menu: ... files in print queue: ... S Submit a file C Cancel a file (wildcards OK) A Cancel all files H Hold the queue E End the hold R Redisplay queue Q Quit --> The source code in PR_SPOOL.C shows how the user's selection is translated into calls to the print spooler. Usage display: none Dolphin functions used: char_at() gets_n() print_com_end_hold() print_com_cancel_all() print_com_cancel_file() print_com_hold() print_com_install() print_com_status() print_com_submit_file() trim() (m) ALL_DRVS Description: This provides information on all physical floppy drives and hard drives present, showing numbers of tracks, etc. Usage display: none Dolphin functions used: drive_type() num_floppy_drives() num_hard_drives() (n) FINAL Description: This copies a string from its place in the the near heap (in the default data segment) to a place in the far heap (outside of the default data segment) and displays the final character of each occurrence of the string. Usage display: none Dolphin functions used: final_char() final_null() strcpy_f() (o) TIMER Description: This program times keypresses. The time is measured either in clock ticks or in seconds. The system clock ticks at the rate of 18.20651245 ticks per second. Usage display: none Dolphin functions used: time_elapsed() (p) DISKTYPE Description: This program determines the type of disk in a specified drive. It distinguishes among different floppy disk types. Anything which is not a floppy disk is reported as a fixed disk. This may be either a hard disk or a RAM disk. Usage display: Use: DISKTYPE drive_letter Dolphin functions used: get_disk_free() disk_type() (q) MAKE&DEL Description: This program makes names for 26 new files (i.e. names which are not already names of files in the current subdirectory) and creates them. It then deletes all files created. Usage display: none Dolphin functions used: make_new_file_name() delete_files() (r) SAVEVALS Description: This program displays the current values of a string variable x and an integer variable y then allows them to be changed. The new values are saved in SAVEVALS.EXE and displayed the next time the program is run. Usage display: none Dolphin functions used: gets_n() trim() save_values_in_exe() (s) FILETYPE Description: This program displays the file types of the file(s) specified on the command line; wildcards are permitted. Usage display: Use: FILETYPE file_spec Dolphin functions used: file_type() get_input_output_files() make_path() split_path() (t) MCDEMO Description: This is a self-running demonstration of Dolphin Software's Mayan Calendrics program. It uses the date functions from this library as the basis for a comprehensive calendrical conversion program. The program converts dates in the Maya calendar to and from Western dates. Maya dates may be either dates in the sacred and civil calendars (the so-called tzolkin/haab dates, e.g. 13 Imix 19 Kayab) or long count dates (e.g. 9.9.16.0.0). Western dates may be expressed in either the Gregorian calendar or the Julian calendar. A date expressed in any calendrical system is automatically con- verted to dates in all the others (and to the Julian day number). Arithmetic operations with long count dates are supported. When a tzolkin/haab date is entered the software displays which year-bearer systems it is consistent with, and allows identifica- tion of all Western dates within a given range of years which correspond to that tzolkin/haab date. The source code for this program is not included on the demonstra- tion disk.