DESTROY Statement

Format 1

DESTROY  { screen-name-1 } ...
         { handle-1      }

Format 2

DESTROY ALL CONTROLS

Format 3

DESTROY { CONTROL

Remaining phrases are optional and can appear in any order.

AT screen-loc  [CELL  ]
               [CELLS ]
               [PIXEL ]
               [PIXELS]

AT LINE NUMBER line-num  [CELL  ]
                         [CELLS ]
                         [PIXEL ]
                         [PIXELS]

AT {COLUMN  } NUMBER col-num  [CELL  ]
   {COL     }                 [CELLS ]
   {POSITION}                 [PIXEL ]
   {POS     }                 [PIXELS]

AT CLINE NUMBER cline-num   [CELL ]
                            [CELLS]

AT CCOL NUMBER ccol-num   [CELL ]
                          [CELLS]
  } . . .

Syntax Rules

1. screen-name-1 is the name of a screen description entry found in the Screen Section.
2. handle-1 is a USAGE HANDLE or PIC X(10) data item.
3. screen-loc is an integer data item or literal that contains exactly 4 or 6 digits.
4. line-num, col-num, cline-num and ccol-num are numeric data items or literals. These may contain non-integer values.
5. Format 1 and Format 3 statements can be mixed into a single DESTROY statement.

General Rules

1. The DESTROY verb removes from memory the items it acts on. It also removes those items from the screen if that is appropriate. The exact meaning of the DESTROY verb depends on the type of item it is acting upon, as described below.
2. If the statement is a Format 1 DESTROY handle-1 statement, the handle is valid, and the DESTROY statement succeeds, handle-1 is set to the value NULL (binary zeros).
3. If handle-1 contains a valid handle to a control, then the control is removed from the screen (if it is visible) and any memory associated with the control is released.
4. If handle-1 contains the valid handle of a floating window or subwindow, the DESTROY statement acts the same as a CLOSE WINDOW statement acting on handle-1 (with no additional options), except that DESTROY sets the value of handle-1 to NULL. When you destroy (close) a floating window, every control contained in that window is also destroyed. Also, any other floating windows that are children of that window are destroyed.
5. If handle-1 is a handle of a font, that font is removed from memory. If handle-1 is a standard font (that is, one retrieved by ACCEPT from STANDARD OBJECT), destroying it has no effect. Destroying a font that is actively in use by a control or window is an error with unpredictable consequences. If you are destroying a set of controls and their associated fonts, you should destroy the controls first, and then destroy their fonts.
6. If handle-1 is a handle to a thread, DESTROY handle-1 has the same affect as a STOP THREAD handle-1 statement, except that the DESTROY statement also sets the value of handle-1 to NULL.
7. If handle-1 is the handle of a menu, then that menu is destroyed, and any memory associated with it is freed. It is an error (not caught) to destroy a menu that is currently associated with a window or a control. A menu that is displayed as the menu bar of a window is automatically destroyed when the corresponding window is destroyed. A menu displayed as the menu bar of a window should not be explicitly destroyed by your program (unless you remove it from the window first). Menus associated with windows or controls as pop-up menus are not automatically destroyed when the corresponding window or control is destroyed. This makes it easier to use the same pop-up menu in more than one control or window.
8. If handle-1 is a handle to a layout manager, the layout manager is removed from memory. A layout manager that is actively being used by a window should not be destroyed. You should first destroy the window or remove the layout manager from the window.
9. If handle-1 contains a value other than a valid handle to a window, control, thread, font, menu, or layout manager, the DESTROY verb has no effect.
10. If screen-name-1 is a Format 2 screen description entry (i.e., it describes a control), that control is removed from the screen, and any memory associated with it is released. screen-name-1 no longer refers to an existing control.
11. If screen-name-1 is an elementary Format 1 screen description entry (i.e., it describes a textual field), the DESTROY verb has no effect.
12. If screen-name-1 is a group item, each subsidiary elementary item is destroyed (i.e., the controls are destroyed and the textual fields are left alone).
13. A Format 2 DESTROY statement (DESTROY ALL CONTROLS) destroys every control contained in the current window. This includes controls created by Screen Section entries as well as controls created directly with a DISPLAY Control verb.
14. A Format 3 DESTROY statement destroys the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime system maintains a list of controls in each window. When attempting to destroy a control at a specific location, the runtime searches this list, using the first control it finds that exactly matches the location. The list is maintained in the order in which the controls are created. If the runtime does not find a control at the specified location, then nothing happens.
15. Use Format 1 DESTROY handle to destroy non-graphical .NET controls or assemblies. For graphical .NET controls, you can use either Format 1 DESTROY handle or Format 2 DESTROY ALL.