Working with the DateTimePicker in Micro Focus Visual COBOL for .NET

One of the most frequent tasks a COBOL developer has to perform is date manipulation. Programming has to be created for; accepting a potential date value from the screen, validating the data that was entered, calculate the number of days between two dates, figuring out the day of the week or even determine what todays date is. All these are tasks most COBOL programmers have had to perform at some time in their programming career.

The DateTimePicker control, along with the namespaces System.DateTime and System.TimeSpan can however save a COBOL developer a significant amount of time where date validation and manipulation is concerned. The DateTimePicker control restricts the input of data to valid dates, it can contain proper formatting and be set to ensure data ranges are valid before any data is accepted into the application. The System.DateTime namespace provides the developer with a set of properties and methods geared specifically towards date and time manipulation. The System.TimeSpan namespace allows us to determine the amount of time between two points as days, hours, or minutes. As we’ll see in the article existing date calculations that required numerous lengthy paragraphs to determine can now be handled with one or two lines of code.

The DateTimePicker example will show several different methods of determining date values and how they can be used with existing code.

WinForm

We’ve already created the WinForm we’ll be using. Remember, the intent is to learn how to work with the control and namespace, not create WinForms. Our WinForm was specifically designed to be simple and present only the basic information. It appears as:



For our example we have a starting date, which is a DateTimePicker control, and an ending date, which is another DataTimePicker control. The remaining fields are read-only textboxes that will be populated with data once the ‘Calculate’ button is selected. The intent is to show you, in the code, how to determine the values for each of these fields based on simply entering in some dates. To start, save the project to your hard drive, build the project and then execute it without debugging it.

When you select a start date, select a date that is in the future. Notice what happens after you have selected the start date; the end date is automatically updated to the same date. We’ll discuss how this happens in a bit but what this implies is I now have a date range that will always ensure my end-date will never be less than my start date. Let’s move on to the mechanics of the DateTimePicker control.

Properties

DateTimePicker, like all controls, has properties associated with them. Although there are many properties that can be manipulated we’ll discuss a few that may be used more often.

When working with properties the general format used to update a property is:

SET controlName::property TO {something}

Where: controlName is the name of the control,

Property is the name of the property to be manipulated.

{something} is specific to each property and can be text, Boolean, enums, etc.

We’re going to concentrate our discussion on the following properties:

Property	Description
Name	How the control is referenced programmatically
Format	Determines whether dates and times are displayed and in what format
CustomFormat	The custom format string used to display the date/time in the control
MaxDate	The maximum date that can be selected
MinDate	The minimum date that can be selected

For information on the remaining properties for a DateTimePicker control or to review the properties above please see the Visual COBOL documentation or Microsoft Developer Network (MSDN).

Name Property

The Name property is used to provide a unique name to the control so it can be accessed programmatically. For DateTimePicker I like to use the abbreviation ‘dtp’ in the first three positions and then follow that with something specific to what the DateTimePicker is for. I like to use camel-case (capital letter for the first letter of each word) for readability purposes. I would highly recommend establishing a naming convention to be used in your shop. The sample below shows the properties for the ‘Start Date’ object so I’ve used the name ‘dtpStartDate’.



Format Property

The DateTimePicker control allows the developer to define how the date and/or time will be displayed to the user. When selected the developer can choose either Short, Long, Custom or Time. When Short is selected only the date is shown. When Long is selected the date and time is shown. When Time is selected only the time of day is shown and when Custom is selected the information defined by the developer in the CustomFormat property is shown. For our example I’ve selected the ‘short’ format.



CustomFormat Property

Not all date and time formats are readily available to the developer to use in their presentation. The CustomFormat property enables a developer to select the characteristics best suited to their environment to request and display date and time information. In our example we formatted the date to contain the full name of the month(MMMM), the day(dd), year(yyyy) and the day of the week preceded by a dash(-dddd).



There are many combinations available to use for formatting your date and time. To review the options available please consult MSDN for the available options. The link I used was:

• DateTimePicker.CustomFormat Property

MinDate Property

The MinDate property sets the minimum date that can be selected in the control. The default value is 1/1/1753, which I have left in the controls. The value can however be set programmatically via an event.



The End Date DateTimePicker control has had the MinDate property updated when the date was updated in the Start Date DateTimePicker. The event that enabled this was ‘ValueChanged’ and is executed any time the value of the control changes. The code to affect updating the MinDate property of the EndDate control is:



The ‘set’ statement uses the Value from the Start Date to update the minimum date of the end date. By setting the end date to be same as the start date we ensure the process hasn’t ended before it began. This simple statement and use of events can save a tremendous amount of processing time, not to mention coding, by ensuring the data being forward to the application for processing is valid.

MaxDate Property

MaxDate is the maximum date that can be selected for the control. The default value is 12/31/9998 and has been left in our example.



Calculating the data

Now that we have the controls defined and we understand the properties being used we need to calculate the data required and then display it back to the screen. A big portion of our job though has already been completed. Since we are using a DateTimePicker we do not have to edit the data coming in for format or validity as the .NET Framework assures us only valid data is entered. The control ensures we have valid dates and thanks to the CustomFormat property that the data is even in the right format.

We’re going to start by defining some variables in our method that will be used as working or holding fields.



If you’ll notice we have standard COBOL definitions for our start and end dates (ws-start-date and ws-end-date, respectively) along with the .NET representation of those same dates (start-date and end-date). By using both definitions I can utilize the power of .NET while preparing the data to be passed back to my existing procedural based COBOL programs.

One key technique is the use of the ‘type’ keyword. The ‘type’ keyword enables access to standard .NET assemblies. Type instructs the compiler that I am defining the field to be a standard .NET data definition of the following category. By doing this I can then take advantage of all the properties and methods associated with that namespace.

The first step in processing the data is to retrieve the data! The following code returns the value of the start date field.



The first line of code retrieves the Value of the DateTimePicker control called StartDate and stores it into a field defined as a type DateTime (short for System.DateTime). If you’ll notice the parameter ‘Date’ at the end of the line. This instructs the runtime to return only the date portion of the date time picker, since that is all we are interested in at this time. By retrieving the data into a DateTime defined field we now have access to the structure of the data using the properties of the DateTime object. We can now directly access the data and store the right values for month, day and year into the standard COBOL data items. We do a similar step for the end date DateTimePicker:



Now that we have our start and end dates we can calculate the difference between the two dates. Because we stored them into DateTime data types we can utilize a variable defined as a TimeSpan type. A TimeSpan type represents an interval of time. It can be hours, minutes, seconds, milliseconds or days. By definition the time span data type understands the data being passed to it is of a DateTime data type and determining the time interval between the two dates is a simple subtraction statement coded as follows:



The TimeSpan type has several properties representing days, hours, minutes, seconds, ticks that we can now access and use in our programming. For our example we wanted to know the number of days between the two dates so we set a local storage variable (ws-nbr-of-days) to the Days property of the TimeSpan object we just calculated (ws-TimeSpan). So in two lines of code I have the difference in days between two dates in a local storage variable that I can now use in my calculations. In procedural COBOL how many lines of code would this require? The final line of code is to display the value back to the text box on the screen.

Working with Today

The previous examples used data that was entered onto the screen to determine values and results. The DateTime namespace also provides the ability to access data based on today. The following code retrieves the date for today and stores it into local storage variable defined as type DateTime.



Now that I have the date, I can format it:

 

There are numerous formats available. You can experiment with the different options to provide the format that works best for you. Trying using intelli-sense to see the different variations available.

You can also get the day of the week for Today:



Finally you can determine how many days are in the current month:



Wrap-Up

The DateTimePicker control along with the namespaces System.DateTime and System.TimeSpan offer a COBOL developer a huge toolbox to draw from. These routines can save you a significant amount of time and effort that would normally be spent to create and test code. These are ready to go and available to you, even if you’re working with procedural COBOL.

The ZIP file has all the necessary source code for you to follow along and see how to update the properties we’ve described in the article. Read through the code; learn from it and use it in your projects. Even though we used a WinForm to present the information, the same concepts apply to WPF or WebForms. Yes there may be differences but this should at least serve as a starting point to help you figure out how to manipulate similar properties in the other presentation environments. Also, if you have a property you’re not sure how to work with send it to us. Chances are if you’re having questions someone else is also and we’d like to help you figure it out.