$transmitkey

$transmitkey Object

Syntax: $transmitkey

Return Value: Character string

Description:

The $transmitkey object captures the name of the last EXIT or TRANSMIT key pressed during form input operations. This object is essential for managing form navigation and submission, especially when custom key bindings are involved.

Key Concepts:

1. EXIT and TRANSMIT Keys:
   • These keys are defined using the FORM SET or WINDOW SET ACCELERATOR commands.
   • EXIT Key: Typically used to exit or cancel the form input process.
   • TRANSMIT Key: Used to submit the form data.
2. Form Input Termination:
   • Normally, a TRANSMIT key cannot terminate FORM INPUT if any “required” fields are empty.
   • Exception: If the TRANSMIT key is pressed while the cursor is in a modified transmit field or an “always transmit” field, the field will transmit, causing FORM INPUT to terminate.
   • If required fields are still empty after this action, $transmitkey will be set to an empty string ("").
3. Resetting $transmitkey:
   • The $transmitkey object can be reset at any time to clear its value. This is useful for ensuring that the object accurately reflects the most recent key press.

Practical Usage:

Defining Keys:

To define EXIT and TRANSMIT keys, you use the FORM SET or WINDOW SET ACCELERATOR commands. For example:

FORM SET ACCELERATOR EXIT F2
FORM SET ACCELERATOR TRANSMIT F1

In this example, the F2 key is set as the EXIT key, and the F1 key is set as the TRANSMIT key.

Handling Key Presses:

You can check the value of $transmitkey to determine which key was pressed and take appropriate actions. For example:

IF $transmitkey = "F1" THEN
    // Handle the F1 key press (TRANSMIT)
    CALL ProcessFormSubmission()
ELSE IF $transmitkey = "F2" THEN
    // Handle the F2 key press (EXIT)
    CALL CancelFormInput()
ENDIF

In this example, different actions are taken based on whether the F1 or F2 key was pressed.

Special Considerations:

• Modified Transmit Fields: These are fields that can trigger form submission even if other required fields are empty. This is useful for scenarios where partial data submission is allowed.
• Always Transmit Fields: These fields always trigger form submission when the TRANSMIT key is pressed, regardless of the state of other fields.

Example Scenario:

Imagine a form with several required fields. If the user presses the TRANSMIT key (F1) while in a modified transmit field, the form will attempt to submit. If any required fields are still empty, $transmitkey will be set to an empty string, indicating that the submission was not successful.

FORM SET ACCELERATOR TRANSMIT F1
FORM SET ACCELERATOR EXIT F2

// User presses F1 while in a modified transmit field
IF $transmitkey = "F1" THEN
    IF AllRequiredFieldsFilled() THEN
        CALL SubmitForm()
    ELSE
        $transmitkey = ""  // Reset because required fields are empty
    ENDIF
ENDIF

This ensures that the form submission logic is robust and handles incomplete data appropriately.