You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Year 2000 Issues

Applies to: WG3.x

Editor's note: this chapter is new in the WG3 layer. It is from section 6 ("Year 2000 issues") of the Developer's Addendum for Worldgroup 3.12 (wg312dev; the earlier 3.10 edition, devad3, is the same text apart from "3.10" for "3.12", BC5 for BC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. The client-side paragraphs (date entry, date output, date input) are tagged WG1-3.x (Client); see also chapter 20. Related: chapters 8, 9 and 11.

The Major BBS Baseline Changes Required For Year 2000 Compliance

The year 2000 issue has at its heart one problem: the use of two digits to represent a year value that requires more than two digits for a complete representation. For example, it is common practice when writing a date to represent 1998 as 98. This practice was also adopted by many computer programs and can cause bugs when the century portion of the year can not be inferred with 100% accuracy or when dates are sorted using a two-digit representation of the year.

What is known as "year 2000 compliance" is defined differently by different organizations. However, all definitions come down to one issue: will the software continue to work correctly after the year 2000? In the Major BBS, most dates are stored using DOS binary format which is valid until 2108, or VB binary format which is valid until 9999. However, three major areas were identified that were not year 2000 compliant and may affect developers: the birth date field of the user account structure, the date format used by the Audit Trail, and certain date entry functions used by client applications.

User Account Birth Date

The user account birth date (usually referenced through usaptr->birthd) was stored as a string using the U.S. standard month/day/year format, with two digits used to represent the year. This may not have been a

serious problem -- after all, the likelihood of having users on a system who were born both in 1900 and in 2000 at the same time is rather small. Even so, it is not impossible, and age discrimination is usually considered undesirable. However, the problem was greater than that because previous versions of Worldgroup will always consider the century to be 1900 when calculating age.

To fix this problem, the format of the birth date field was changed to a string containing year, month, and day packed together in that order. For example, March 24, 1978 is now represented by the string "19780324". Since this format requires the same amount of storage space as the old format, no data file conversion is required. The software will automatically re-format the birth date when the account is loaded

(assuming 1900 as the century if the date is in the old format). In addition, all data entry fields used for the birth date have been lengthened to accommodate a four-digit year.

Audit Trail

In previous versions of Worldgroup, Audit Trail information was stored in a Btrieve data file. The time stamp on each entry was stored as a string with a two-digit year. In addition, the time stamp was used as the key for the data file. Thus, when the year 2000 arrived, the Audit Trail would start adding entries to the beginning of the list rather than at the end (after all, "00" is less than "99").

This problem was fixed by creating an entirely new file format. Since Audit Trail information is usually only appended, and random access to the data is usually not a high priority, the Audit Trail is now stored in a binary/text file instead of a Btrieve data file. The exact nature of the new storage format is discussed below and in the Audit Trail API documentation.

Client Application Date Entry

Applies to: WG1-3.x (Client)

Client application date entry (VB masked edit boxes, Format$(), DateValue()).

Galacticomm's client applications have historically used a masked edit box for date entry. The standard format used for the masked edit box was two digits for the month, two digits for the day, and two digits for the year. The two-digit limitation on years is clearly not in keeping with year 2000 compliance. Since this limitation had to be removed, and since there are standard functions in VB that will recognize any valid date string, all masked edit boxes being used for date entry were replaced with standard text boxes. Users can now enter any valid date and it will be recognized by the clients.

API Changes And Additions

Birth Date Manipulation Functions

Applies to: WG3.x

Header check: fixBirthdate() and calcage() are declared in MAJORBBS.H, strBirthdate() returns const CHAR * (MAJORBBS.H:975) and okbday() takes CHAR *stg (a buffer that it rewrites to the new format); DATSIZ is 9 (DNTAPI.H:137).

Fortunately, all Galacticomm modules use the same function to validate birthdates:

INT                                /*   returns TRUE if valid              */
okbday(                            /* is this a valid birthday?            */
CHAR *stg);                        /*   date str buffer (must be DATSIZ)   */

This function can be found in SIGNUP.C. It has been modified to do the following:

1. Accept dates in the format MM/DD/YY, MM/DD/YYYY, MMDDYY, or MMDDYYYY. If two digits are used for the year, 1900 is assumed for the century.

2. Modify the input to contain the new YYYYMMDD format.

The current age of a user can be calculated using the following function:

INT
calcage(                           /* compute age (in years) as of today   */
const CHAR *birthd);               /*   birth date (YYYYMMDD or MM/DD/YY)  */

This function also existed in earlier versions of Worldgroup, but it has been modified to accept either the new or the old date format (YYYYMMDD or MM/DD/YY). Again, 1900 is assumed for the century if the date is in the old format.

Two new functions have also been added specifically for dealing with user birth dates:

GBOOL                              /*   returns TRUE if modified           */
fixBirthdate(                      /* fix date from MM/DD/YY to YYYYMMDD   */
CHAR *strDate);                    /*   birth date string (must be DATSIZ) */
const CHAR *                       /*   returns pointer to static buffer   */
strBirthdate(                      /* format birthdate into "MM/DD/YYYY"   */
const CHAR *strDate);              /*   birth date string                  */

The first function is specifically for converting old format dates to the new format. It examines the input and converts it to the new date format if it is in the old format. It does not accept four-digit years in the old format and it always assumes 1900 as the century. This function is called each time the user account is loaded to ensure that the birth date is in the correct format.

The second function is used to convert the birth date string (in either the old or new format) to a version that can be used for displays. The output is the date in U.S. standard format, MM/DD/YYYY.

Date and Time API

To facilitate year 2000 compliance, a number of new functions have been added to the existing date and time API and some existing functions have been modified. These changes fall into three basic categories: changes to support the use of four-digit years, new functions to support a "sort" date format, and new functions to support dates treated as discrete components. Complete details on these functions can be found in the Date and Time API documentation. An overview of the important changes follows.

Four-Digit Years:

Four-digit years obviously require more storage space than two-digit years. There is a global define that specifies the amount of space required to store a date string in MM/DD/YY format:

#define DATSIZ 9                   /* size of a date in MM/DD/YY format    */

This define was originally in USRACC.H. It has been moved to DNTAPI.H. To accommodate dates with four-digit years, a new define was created:

#define LDATSIZ 11                 /* size of a date in MM/DD/YYYY format  */

The primary function for decoding a string into a DOS binary date is dcdate(). This function was already reasonably well-behaved. It accepted only two-digit years, but it would assume years less-than 80 were in the 2000s and years greater-than or equal-to 80 were in the 1900s. This functionality has been retained, but it has also been modified to accept four-digit years.

The primary functions for creating a date string from a DOS or VB binary date are ncdate(), ncedat(), and v2sdat(). These functions all create date strings in with two-digit years. New, "long", versions of these functions have been added that create date strings with four-digit years: ncdatel(), ncedatl(), and v2sdatl().

Sort Format Date Strings:

In order to provide a convenient, compact format that contains complete date information and can be used to easily sort dates and times, new date and time string formats have been defined: the sort formats.

The sort date format is the format now used for birth dates in the user account structure. It consists of a four-digit year, immediately followed by a two-digit month, immediately followed by a two-digit day. For example, January 2, 1980 is represented by "19800102".

The sort time format is similar to the existing time string format, but contains no punctuation. It consists of a two-digit hour (in 24-hour format), immediately followed by a two-digit minute, immediately followed by a two-digit second. For example, three seconds before midnight (11:59:57 PM) is represented by "235957".

A suite of functions for encoding and decoding sort date and time strings in various ways has been added. These functions are described in detail in the Date and Time API documentation. They can be identified easily because the function names all begin with a lower-case s.

Discrete Components Binary Format:

The most flexible binary date format is using a separate integer variable to hold each of the year, month, and day components of a date. This is referred to in the documentation as the "discrete components" format. A suite of functions has been added to manipulate discrete component dates. Most of these functions mirror functions that existed for manipulating DOS packed dates. See the Date and Time API documentation for details.

Audit Trail API

The Audit Trail data file format was changed for Worldgroup 3.12 for two main reasons: to provide year 2000 compliance, and to provide easier access to the Audit Trail data.

Historically, the Audit Trail has been stored in a Btrieve data file. This provided a standard access mechanism, since most data in the Major BBS is stored in Btrieve files, and under the DOS versions of the Major BBS, this provided a certain amount of data security, since the Btrieve engine has built-in mechanisms to ensure file integrity. The primary down-side of storing any information in a Btrieve file is that the data is difficult for non-the Major BBS products to access the data. In most cases, custom programming is required to read the data from the Btrieve file and convert it to a more generic format that can be read by general-purpose data manipulation utilities.

For Worldgroup 3.1, Audit Trail data is stored in a binary/text file. The file is opened and accessed in binary mode by the Major BBS itself, but the contents of the file are formatted so that it can be treated by outside programs as a fixed-length ASCII data file. See the Audit Trail API documentation for details.

Because of this change, from a Btrieve file to a special type of file, some changes to add-on modules may be required. If you only add items to the Audit Trail using shocst(), no changes will be required. This function still operates exactly as it did before. In addition, all hooks called by shocst() (ntfysopr and rsyfad_hook) operate exactly as before.

Add-ons that read from the Audit Trail will require changes, however. The Audit Trail API provides generic access to Audit Trail files. When reading from the Major BBS Audit Trail, always use the global handle which is opened by the baseline. This handle is declared in MAJORBBS.H and imported through WGSERVER.LIB:

HAUDFILE WGSEXP hAuditTrail;       /* Audit Trail file handle             */

Offline utilities that operate only while the Worldgroup Server is not running can open the file themselves. There is a define in MAJORBBS.H that can be used to get the name of the file:

#define AUDITFILE "wgsaudit.adt"   /* Audit Trail file name                */

See the Audit Trail API documentation for details on opening and closing Audit Trail files.

Audit Trail files are treated by the API as binary files containing records. The records are numbered from zero to the one less than the total number of records. You can get the number of records by calling the following function:

ULONG
audfNumRecs(                       /* get number of records in file        */
HAUDFILE haud);                    /*   Audit Trail file to use            */

The format of records in the new Audit Trail is very similar to that in the old one. The main differences are the format of the time stamp and that the maximum length of the detailed information has been increased. The new format has also been formalized using the following structure:

struct audEntry {                  /* Audit Trail record format            */
     CHAR stamp[AUDSTAMPSIZ];      /*   time stamp ("YYYYMMDD HHMMSS")     */
     CHAR brief[AUDBRIEFSIZ];      /*   brief description                  */
     CHAR channel[AUDCHANSIZ];     /*   channel/console/event/cleanup      */
     CHAR detail[AUDDETSIZ];       /*   detailed description               */
};

The main function to read a single record by number is:

INT                                /*   returns result code                */
audfReadEntry(                     /* read an entry by record number       */
HAUDFILE haud,                     /*   Audit Trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audEntry *buf,              /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

If you have a large amount of existing code that deals with the old Audit Trail record format and you don't want to change it all to work with the new format, you can use the following function instead:

INT                                /*   returns result code                */
audfReadOldStyle(                  /* read an old-style entry              */
HAUDFILE haud,                     /*   Audit Trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audOldStyle *buf,           /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

The audOldStyle structure is simply a formalization of the old record format. You can pass a character buffer and simply typecast it when using this function.

There are also functions to find records by date. See the Audit Trail API documentation for details on these functions.

Compliance Guidelines

Handling Birth Date

Online modules that accept birth dates as input should use okbday() to validate the input. The user input should be passed to this function and the modified date string should then be copied into the user account structure.

Modules that read the birth date may need to be able to handle both formats. Modules written only for the Major BBS version 3.12 and later should call fixBirthdate() before using the birth date field, especially if the account record is read directly from the data file. Then the birth date can be decoded using sDateDecode(). Modules that must remain compatible with the Major BBS version 3.0 can use the GCOMM library function alldgs() to determine whether a birth date is in the new format or the old format. For example:

     INT year,month,day;
     if (alldgs(usaptr->birthd)) {
          /* it's the new format */
          sscanf(usaptr->birthd,"%4d%2d%2d",&year,&month,&day);
     }
     else {
          /* it's the old format */
          sscanf(usaptr->birthd,"%d/%d/%d",&month,&day,&year);
     }

Using the New Audit Trail

Complete details on using the new Audit Trail are given in the above section on API Changes and Additions and in the Audit Trail API documentation. The key points to keep in mind are:

- Discontinue use of audbb and the WGSAUDT2.DAT file.

Applies to: WG3.x

Header check: audbb appears in no WG3.2 header; it is the WG3.0 name of the old Btrieve audit file pointer (WGSAUDT2.DAT) and is mentioned here as history. New code uses AUDITFILE (MAJORBBS.H:430) and the audf*() API (chapter 26).

- Online modules should read from the Audit Trail using hAuditTrail.

- Offline utilities should get the Audit Trail file name from the AUDITFILE define in MAJORBBS.H.

Date Output

On the server, dates that are output for display only and for which the century can be implied with a high degree of accuracy do not strictly need to be changed to use four-digit years. However, you should be aware that some organizations require a complete year in all date displays in order to consider a product "year 2000 compliant".

Dates that are output for data entry purposes should in general be changed to use four-digit years. If you are using prndat() for date output, you can change the year to four digits simply by adding 12 to the mode argument. If you are using ncdate() or ncedat(), change these calls to use ncdatel() or ncedatl(), respectively.

Applies to: WG1-3.x (Client)

Client-side date output.

All client-side date output should now be done using the standard VB library function Format$(). In particular, you should change all calls to the Galacticomm function mebdate() to use Format$() instead. In addition to the existing standard date format strings defined in GCSPCLI.BAS (DATEFMT, MDATEFMT, LDATEFMT, and SERVDFMT), two new format strings have been added. The first one, LSRVDFMT, is equivalent to the existing SERVDFMT format. It generates a date string in the format MM/DD/YYYY which can be decoded using dcdate(). The difference between the two is that SERVDFMT generated a string with a two-digit year while LSRVDFMT generates a string with a four-digit year. The second new format string, SORTDFMT, is used to generate a sort format date string (YYYYMMDD).

Date Input

On the server, change the size of date string buffers to LDATSIZ instead of DATSIZ. For FSD templates, increase the length of date entry fields from eight to ten. You can still use dcdate() for decoding date strings to DOS packed format or you can use the new dateDecode() function to decode to discrete components.

Applies to: WG1-3.x (Client)

Client-side date input.

On the client, use a regular text box instead of a masked edit box for date entry fields. When decoding the date string to VB binary format, use the standard VB library function DateValue().

  • No labels