Handles

Normally, when you create a graphical object, the run-time system generates a unique value to identify that object, and stores that value in the program's specified handle. You make future references to that object by naming its handle. Most of the graphically oriented features of ACUCOBOL-GT make use of handles. A handle is a COBOL data item. Internally, a handle is simply a number. The COBOL program uses handles to identify various graphical items.

Note: In addition to all the graphical controls and user-interface-type objects (for example, window or font), a handle can be applied to a thread within a program.

If you have worked with ACUCOBOL-GT's text-based subwindows (textual, pop-up windows), you are already familiar with the use of handles. The POP-UP AREA phrase of the DISPLAY WINDOW verb names a PIC X(10) data item that holds the handle of the created window. When you want to remove the window, you use that data item in the CLOSE WINDOW verb. The data item tells the system which window to close.

There is a data type, called USAGE IS HANDLE, that you use when you want to declare a handle for a data item. The syntax for it is as follows:

USAGE IS HANDLE OF type

You can use this data type with or without specifying a type of handle, but there are certain benefits if you do specify it. The primary benefit, for handles of controls, is that the proper style and property names are known by the Compiler and can be used. Consider the difference in this example:

77  h-1  handle.
77  h-2  handle of entry-field.

then,

modify h-2, max-text = 15.     ( legal )
modify h-1, max-text = 15.     ( compile error )

Another significant benefit to typed handles is that the Compiler can check that they are being used in proper contexts.

The run-time system can tell when a handle is no longer valid. If you make reference to an invalid handle (for example, a handle to an object you have destroyed), the requested operation is simply ignored.

When you make use of graphical objects in the Screen Section, the run-time system automatically creates and manages the associated handles for you. In this case you do not explicitly use handles when referring to graphical objects.

See USAGE Clause for more information about handles and the USAGE IS clause.