Working with the DateTimePicker in Micro Focus Visual COBOL

Micro Focus released VisualCOBOL R4 earlier this year and it has turned out to be an awesome addition to Visual Studio 2010. The development teams have done a great job in delivering a very usable product. To help you learn about VisualCOBOL and COBOL.NET in a managed environment we'd like to provide some example solutions. Now there are great samples that come with VisualCOBOL but they don't define or detail one specific control, they show a finished application and the user has to read through the code to figure out how the code was created.

Our examples will focus on a single control. We'll show you how to manipulate the properties of that control programmatically. We may have to include one additional control but the focus on each project will be on a single control with a supporting role for the additional control. This article is about the DateTimePicker control.

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, determined the number of days between two dates, figuring out the day of the week or even what is todays date are all 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 in time as days, hour, or minutes. As we'll see in the article existing date calculations that previously 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 I 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 controls, like all controls, have 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.

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.

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: http://msdn.microsoft.com/en-us/library/system.windows.forms.datetimepicker.customformat.aspx

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 accepted by the application 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. Because of the DateTimePicker we do not have to edit the data coming in for format or validity. 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 me to access 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). 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. This enables us to 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. 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 and 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 into 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.

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 time that would normally take a significant amount to create and test. These are already 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 and expand our examples!

Happy Coding!