Working with TextBoxes 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 TextBox control.

Textboxes can save a COBOL developer a significant amount of coding time. Most COBOL developers are used to reading some data from a screen, processing the data and when an error is found in a field the screen is sent back to the user with some annotation to correct the field in error. This process may occur numerous times until all the data on the screen has been checked for formatting and accepted. With textboxes and masked textboxes the developer is able to define input length, formats and type so that a user would have a very hard time entering in a piece of data that was unacceptable to the underlying application.

The TextBox example will show several different styles of textboxes and explain how each can be used.

WinForm

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

We've created examples of the most popular uses of text boxes.

Field	Purpose
Basic	Basic entry of up to a specific number of characters
Password	Allows for the entry of password characters that are 'masked' or hidden when entered
Multi-Line	Used for entering a large amount of data. The information entered can span several lines as necessary
Numeric	How to get numeric data into a form without a lot of extra coding
SSN	Using a mask to obtain data in a specific format

The Numeric and SSN examples are actually 'Masked' textboxes. Masked textboxes enable the developer to provide a pre-defined format for entering information. More on Masked Textboxes in a bit.

We utilize a button to initiate processing of the information entered on the screen. Our example will show how to accept the information entered in .NET data format and move it into the standard 'PIC' format COBOL developers are used to seeing. Once it's in the COBOL data layouts you can then easily integrate with existing business logic to process the information.

Properties

Textboxes, like all controls, have properties associated with them. Although there are many properties that can be manipulated there really are only a few that have any real implication when working with Textboxes.

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
CharacterCasing	Automatically converts the characters entered to upper or lower case
MaxLength	The number of characters allowed in the textbox
PasswordChar	Character to substitute when an entry is made in the textbox
Text	The actual text that is displayed to the user
Visible	Can you see the control. Accepts a Boolean value of 'true' or 'false'

For information on the remaining properties for a Textbox 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 TextBoxes I like to use the abbreviation 'tbx' in the first three positions and then follow that with something specific to what the Textbox is for. For Masked Textboxes I use the abbreviation 'mtb' in the first three positions. 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.



Character Casing Property

When you entered some information for the multi-line textbox you may have noticed that no matter what you entered the characters were converted to upper case. This was due to the CharacterCasing property being set to 'Upper'. In some instances a program may only accept upper or lower case information. Rather than accept the information from the screen, create a parser to interpret the information for case, and adjust accordingly a simple setting in the control enables the proper case.



MaxLength Property

MaxLength is the maximum number of characters a textbox will accept. For the Basic textbox we've set the maximum number of characters to accept to '50'.



Password Character Property

One property that is very useful is the Password Character property. When a user enters data into a field with this property set the characters are automatically changed to the character in the property. For our example we've used the ampersand "@" character.



Experiment with this property and see what character works well for your environment.

Text Property

Text is the information entered into the textbox by the user. In most instances the text property will be set to null or spaces in the property dialog.

You may have an occasion where you will want to set an initial value and this is where you can do that. In our example we are actually reading the information the user entered into the different text boxes. We do this programmatically with the following code:



The 'text' property for each control was accessed and the contents were moved to a temporary working-storage field using the 'set' verb. The temporary holding fields were defined in the method using standard COBOL PIC clauses:



By using standard COBOL data definitions I can now call a standard COBOL program to process the data just entered.

Visible Property

The Visible property is used to either show or hide a control on a form. You can use hidden fields to store information that the user entered on a screen, as a counter or just about anything you don't want the user to see. In our example we use the Visible property to both show and hide different controls on the screen.

There are actually two buttons on the Form with only one being visible. We use the 'Visible' property with a value of 'True' to show a control or a value of 'False' to hide a control. The Process button has it's Visible property set to true via the Property Panel:

For the Reset Button the Visible property is set to 'False' in the Property Panel:

The Visible property can be manipulated through code to either show or hide an existing control.

When the Process button is clicked we want to hide it and then show the Reset button. The code to perform this little trick is:




The first line of code shows the hidden Reset button. (btnReset::Visible to true).

The next line of code hides the Process button. (btnProcess::Visible to false).

Masked Text Boxes

Our example uses two masked text boxes, one for numeric data and one for the entry of a typical United States Social Security Number.

Masked text boxes, as the name implies, enable the user to define a mask so that any data entered into the field will be checked to determine if it meets the criteria specified. For the numeric textbox we have set the Mask property to allow only numeric characters. This is accomplished by the following in the properties area:

We've entered 12 zeros, thus implying this textbox can only accept numeric data and only up to 12 numbers. Try entering a non-numeric character. Can you? There's more you can do with masks. Notice the selection button to the right of the zeros? When you click the button the following dialogue box appears:

The Input Mask screen allows the developer to use a preconfigured Mask or to define a custom mask (which is what we did with the 12 numeric characters). If you'll notice, the Social Security Number is a pre-defined mask and we simply used it with the other masked text box.

When working with masked textboxes though, no matter how you define the mask the data being accepted is still considered text (that is 'System.String' in .NET data types). So even though we defined the input to be numeric when we read it into our temporary fields programmatically it is text data and has to be converted to numeric. In our example we defined two fields, numericTemp and numericEntered and defined them as:

In order to read our data from the screen we first read the data from the screen field into the temporary character based field (numericTemp) and then move it into the numeric field (numericEntered). The following code accomplishes this:

Masked Textboxes can save a COBOL developer a significant amount of coding and testing. The edits a developer would normally have to define, create and test are already defined within the .NET environment. The coding time required to create a new form to place in front of an existing legacy application should be significantly reduced, not to mention the amount of code created. Masked Textboxes are a control anyone creating user interfaces should experiment with and become familiar with. This is a significant time saver.

Reset Button

The Reset button is used to return the application to the state it was in when we the application first started. Study the code and the technique. There is nothing different in the method than what has already been discussed above, without all the comments in-line in the code. In our example we called another method to reset the Visible property of all the controls rather than have them in the same method.

One technique I would like to point out is how the text fields are reset. Notice the construct "String::Empty"? We're taking advantage of the .NET Framework and the capabilities it provides. The String class has a read-only field and the value of this field is the zero-length string, "".

In application code, this field is most commonly used in assignments to initialize a string variable to an empty string. You can also test whether the value of a string is either null or String.Empty by using the IsNullOrEmpty method.

Wrap-Up

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 TextBox 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!