Modified data tag and modified property

Each field on a text form has a modified data tag, which is a status value that indicates whether the user changed the form field when the form was last presented. In relation to CICS®, one benefit of the modified data tag is that network traffic is reduced because the transfer of data from user to program includes only modified fields.

As described later, a modified data tag is distinct from the modified property for the field, which is set in the program and which presets the value of the modified data tag.

Interacting with the user

In most cases, the modified data tag is preset to NO when the program presents the form to the user; then, if the user changes the data in the form field, the modified data tag is set to YES, and your program can use the following logic:
  • Use a data table or function to validate the modified data (as occurs automatically when the modified data tag for the field is YES)
  • Detect that the user modified the field by including the name of the field in an if statement that has the following structure:
      if (field is modified)
        ;
      end
    For details, see Logical expressions for Text UI forms.

The user sets the modified data tag by typing or deleting a character in the field. The modified data tag stays set, even if the user, before submitting the form, returns the field content to the value that was presented.

Validation involves two phases. Phase I involves properties such as InputRequired, as well as validations related to data tables. Phase II runs validator functions. When a form is re-displayed due to an error in phase I, the modified data tag is still set to YES in every field that was modified after the program ran converse or show. However, when a form is re-displayed due to an error in phase II, the modified data tag is no longer on in any fields at all unless a validator function reset the tag.

Setting the modified property

You might want your program to do a task regardless of whether the user modified a particular field; for example:
  • You might want to force the validation of a password field even if the user did not enter data into that field
  • You can specify a validation function for a critical field (even for a protected field) so that the program always does a particular cross-field validation, which means that your program logic validates a group of fields and considers how one field's value affects the validity of another.
To handle the previous cases, you can set the modified property for a particular field either in your program logic or in the form declaration:
  • In the logic that precedes the form presentation, include a set field modified statement. The result is that when the form is presented, the modified data tag for the field is preset to YES.
  • In the form declaration, set the modified property of the field to YES. In this case, the following rules apply:
    • When the form is presented for the first time, the modified data tag for the field is preset to YES.
    • If any of the following situations occurs before the form is presented, the modified data tag is preset to YES when the form is presented:
      • The code runs a set field initial statement, which reassigns the original content and property values for the field; or
      • The code runs a set field initialAttributes statement, which reassigns the original property values (but not content) for each field on the form; or
      • The code runs a set form initial statement, which reassigns the original content and property values for each field on the form; or
      • The code runs a set form initialAttributes statement, which reassigns the original property values (but not content) for each field on the form
The set statements affect the value of the modified property, not the current setting of the modified data tag. A test of the following type is based on the modified data tag value that was in effect when the form data was last returned to your program:
  if (field is modified)
    ;
  end
If you try to test the modified data tag for a field before your logic presents the form for the first time, an error occurs at run time.
If you need to detect whether the user (rather than the program) modified a field, make sure that the value of the modified data tag for the field is preset to NO:
  • If the modified property of the field is set to NO in the form declaration, do not use a set field modified statement. In the absence of that statement, the modified property is automatically set to NO prior to each form presentation.
  • If the modified property of the field is set to YES in the form declaration, use a set field normal statement in the logic that precedes form presentation. That statement sets the modified property to NO and (as a secondary result) presents the field as unprotected, with normal intensity.

Testing whether the form is modified

The form as a whole is considered to be modified if the modified data tag is set to YES for any of the variable form fields. If you test the modified status of a form that was not yet presented to the user, the test result is FALSE.

Examples

Assume the following settings in the form form01:
  • The modified property for the field field01 is set to NO.
  • The modified property for the field field02 is set to YES.

The following logic shows the result of various tests:

  // tests false because a converse statement 
  // was not run for the form
  if (form01 is modified)
    ;
  end

  // causes a runtime error because a converse 
  // statement was not run for the form
  if (field01 is modified)
    ;
  end

  // assume that the user modifies both fields
  converse form01;

  // tests true
  if (field01 is modified)
    ;
  end

  // tests true
  if (field02 is modified)
    ;
  end

  // sets the modified property to no 
  // at the next converse statement for the form 
  set field01 initialAttributes;
  
  // sets the modified property to yes 
  // at the next converse statement for the form 
  set field02 initialAttributes;

  // tests true 
  // (the previous set statement takes effect only
  // at the next converse statement for the form
  if (field01 is modified)
    ;
  end

  // assume that the user does not modify either field
  converse form01;

  // tests false because the program set the modified 
  // data tag to no, and the user entered no data 
  if (field01 is modified)
    ;
  end

  // tests true because the program set the modified 
  // data tag to yes
  if (field02 is modified)
    ;
  end
  
  // assume that the user does not modify either field
  converse form01;

  // tests false
  if (field01 is modified)
    ;
  end

  // tests false because the presentation was not
  // the first, and the program did not reset the
  // field properties to their initial values
  if (field02 is modified)
    ;
  end


Feedback