PROCEDURE Clause

General Format

{BEFORE   } PROCEDURE IS {proc-1 [{THROUGH} proc-2]}
{AFTER    }                       {THRU }
{EXCEPTION}              {NULL }
{EVENT    }

Syntax Rules

1. proc-1 and proc-2 must be names of paragraphs or sections defined in the Procedure Division of the program.
2. THROUGH and THRU are synonymous.
3. You may have one event procedure or up to three embedded procedures defined for each Screen Section entry–one BEFORE, one AFTER, and one EXCEPTION. You may not have more than one of each type in any one Screen Section entry.

General Rules

Embedded Procedures

1. An ACCEPT statement executes embedded procedures when the cursor reaches the field defined by the associated Screen Section entry. The type of an embedded procedure defines exactly when it will execute:
   • BEFORE procedures execute when control is transferred to the associated field, before the user can enter any data.
   • AFTER procedures execute when the user attempts to leave the field normally. This can be due to typing a termination key, filling an auto-terminate field, or typing a field-movement key such as the Tab key. Keys that serve as both movement and exception keys, such as the default definition of the Up arrow key, always cause the AFTER procedure to execute.

     As pertains to this rule, the movement actions are defined as:

     Default-Next, Down, Erase-All, Erase-Next, First, Last, Left, Next, Next-Line, Numeric-Next, Previous, Previous-Line, Right, and Up.

     In the default keyboard configuration, this affects the handling of the Up and Down arrows in the first and last fields of a Screen Section item.

     To avoid having keys that are both movement keys and exception keys, you can make the affected keys movement and termination keys. In the default keyboard configuration, you would change the Up and Down arrows to be:

          KEYBOARD   Edit=Up    Terminate=52  ku
          KEYBOARD   Edit=Down  Terminate=53  kd

   • EXCEPTION procedures execute when the user types an exception key (assuming that exception keys are allowed) or when some other exception condition exists.
2. The word NULL in the PROCEDURE phrase indicates that no procedure exists. It has the same effect as omitting the PROCEDURE phrase and is essentially commentary.
3. When the ACCEPT statement executes an embedded procedure, it treats proc-1 and proc-2 in the same manner that a PERFORM statement does. That is, it begins execution at proc-1 and continues to the end of proc-2 (or proc-1 if you omit proc-2). When the embedded procedure completes, control returns to the ACCEPT statement.
4. An embedded procedure may contain other ACCEPT statements, which, in turn, can contain embedded procedures. This is handled in the same fashion as nested PERFORMS. Embedded procedures may CALL subprograms. An embedded procedure remains active until one of the following occurs:
   • The embedded procedure finishes and returns control to its ACCEPT statement.
   • The program containing the embedded procedure does an implicit or explicit EXIT PROGRAM.
   • The run-unit containing the embedded procedure does an implicit or explicit STOP RUN.
5. Prior to executing an embedded procedure, the ACCEPT statement moves the contents of each input and update field to its corresponding data item. In addition, each control is INQUIREd for its current VALUE (unless the TC_CONTROL_SYNC_LEVEL configuration variable is set to a value that contradicts this behavior). This allows you to examine the current Screen Section data from inside an embedded procedure.
6. The ACCEPT statement updates any CURSOR variable that you have declared in Special-Names. It does this prior to executing any AFTER or EXCEPTION procedure. Note that BEFORE procedures do not update the variable. This is due to the fact that the cursor does not actually move to the field being entered until the BEFORE procedure returns control to the ACCEPT statement.
7. The ACCEPT statement updates any CRT STATUS variable that you have declared prior to executing an AFTER or EXCEPTION procedure. This allows you to determine what key the user typed to leave the field. You may also use the ACCEPT FROM ESCAPE KEY verb inside an embedded procedure for this purpose.
   • If the user leaves the field due to the action of an editing key (such as an arrow key or a "next field" key), the CRT STATUS will be set to zero (for a numeric CRT STATUS) or to 0", "0", x"00" (for a group item CRT STATUS). See Special-Names Paragraph for the format of a group item CRT STATUS.
   • Note that some keys are both editing keys and termination keys. For example, by default, the Tab key is set up to be a "next field" key until the last field of the Screen Section, when it becomes a termination key. These keys are treated as editing keys until their termination condition applies. Therefore, their CRT STATUS value will change depending on whether the key is being treated as an editing key or a termination key.
8. After completing an embedded procedure, the ACCEPT statement re-computes all variable information contained in the Screen Section entry being accepted. This allows you to change colors and other aspects of the Screen Section entry dynamically.
   • Note, however, that data is not automatically moved to update (USING) fields from their corresponding data items. If you want to change the contents of an update field from inside an embedded procedure (to provide a new default, for example), you must DISPLAY the changed field. The DISPLAY verb moves data to the Screen Section and shows it on the screen.
   • In an embedded procedure, you may "protect" screen fields by changing their COLOR value. As a result, the ACCEPT statement may terminate when the embedded procedure returns control because there are no remaining fields to enter. If this occurs, the CRT STATUS is left unchanged from the value it had when the embedded procedure returned.
9. An embedded procedure can alter the behavior of its controlling ACCEPT statement. See Special-Names Paragraph for details on the SCREEN CONTROL data item.
10. You may specify an embedded procedure for a group item in the Screen Section. The effect is to apply that procedure to each elementary item contained in the group. Subsidiary items may specify their own embedded procedures, which take precedence over the group's embedded procedures. See Using Screen Section Embedded Procedures for more information.

Event Procedures

1. The EVENT option of the PROCEDURE phrase establishes an event procedure for a control. Event procedures are different from Screen Section embedded procedures in that an event procedure becomes part of the control when it is created, while embedded procedures do not. An event procedure is executed directly by the control. Embedded procedures execute as part of the flow of control of the Screen Section. An event procedure can potentially execute any time after its owning control is created, even when the defining Screen Section item is not being ACCEPTed.
2. By default, a control does not have an event procedure, which is like specifying an event procedure of NULL.
3. When a control invokes an event procedure, the EVENT-STATUS data item reflects the invoking event. When the procedure terminates, the previous contents of the EVENT-STATUS item are restored (this is important when nested events exist). If the program does not contain an EVENT-STATUS data item, then the event is processed normally. See Special-Names Paragraph for more information about the EVENT-STATUS data item.
4. Event procedures are similar to embedded procedures (for example, the AFTER procedure). However, you should note the following differences:
   • Unlike embedded procedures, the values of data elements corresponding to a control's values are not updated when an event procedure is entered. You must use the INQUIRE verb to examine the current value of a control inside an event procedure.
   • Unlike embedded procedures, the event procedure executes while processing the control, instead of after the control terminates. Every event that occurs in the control is passed to the event procedure. When the event procedure terminates, the event is processed by the control and the control continues normal processing as dictated by the value of the EVENT-ACTION element of EVENT-STATUS. An advantage of event procedures is that they receive all events. You do not need to remember if the event should be processed in the AFTER or EXCEPTION procedure.
   • Event procedures can be executed any time the control receives events. The Screen Section embedded procedures receive control only during an ACCEPT of the corresponding Screen Section. This behavior can be important with tool bar controls, which normally are not ACCEPTed.
   • Events classified as messages (whose symbolic names start with MSG-) are sent only to event procedures. They cannot be detected by the Screen Section embedded procedures. See Events Reference in User Interface Programming for detailed information about messages.
   • You can change a control's event procedure via the MODIFY verb. The Screen Section's embedded procedures are fixed.
5. Event procedures are unique in that they can receive control when the owning COBOL program is otherwise inactive. The following rules cover the activation of an event procedure:
   1. If the current program contains the event procedure, then it is executed as if it were the subject of the PERFORM statement.
   2. If the program containing the event procedure is active, but is not the current program, control flows to the containing program at the point of the event procedure. This situation is not considered a recursive call, because the transfer of control is not via CALL. When the event procedure terminates, control returns to the original program.
   3. If the program containing the event procedure is not active, but is resident in memory, it is made active with the following conditions:
      • It has no USING items passed to it, so program parameters are not defined and should not be used.
      • While active, the program is not affected by CANCEL (just like all active programs).
      • When the event procedure terminates, the program is made inactive again.
      • On entry to the event procedure, all other states of the program (e.g., the values of variables) are unchanged from the time when the program was last active.
      • The program retains any changes made to its state (variables and file state) when the procedure exits.
   4. If the program containing the event procedure is not memory resident, then the event procedure is removed from the control.
   5. For recursive programs, the copy of the program at the depth that registered the procedure is the one that counts for determining which program contains the event procedure.
   6. While an event procedure is active (due to an event), an EXIT PROGRAM statement is ignored in the event procedure's controlling program.
6. When programming an event procedure, you should avoid using the ACCEPT statement to allow input from controls. Most graphical host systems are not designed to expect input events while in the process of handling another input event. This situation stresses the host system and can lead to situations where the results are unpredictable.

   If you want to place an ACCEPT statement inside an event procedure, one way to avoid this situation is to turn the event to a terminating event and then perform the ACCEPT in the corresponding exception procedure. Exceptions occur after event handling is complete, so this avoids the nested input events syndrome. To turn an event into a terminating event, see the description of EVENT-STATUS in Special-Names Paragraph. Another effective technique is to run the procedure that performs the ACCEPT in a separate thread. This allows the original event to complete and also avoids the situation. Typically you can do this by placing the desired event-handling code in a separate paragraph and then using PERFORM THREAD to run that paragraph from the control's event handler.