CHANGE

Changes data in EntitySets, relationships, forms, or result sets.

Syntax #1

Changes specific fields in one or more records in an EntitySet, relationship, form, or set. The existing values in target fields are changed to specified values. The LET subcommand explicitly assigns values to the target fields. Only fields explicitly named in the LET subcommand are changed.

CHANGE [num] [setspec] [LET clause] [EVALUATE clause] [-> clause]

Syntax #2

Changes one or more records in an EntitySet, relationship, form, or set from data found in a set specification. Data for the target fields in the records is taken from a specified set. The LET subcommand can be used to direct the source data to particular target fields, and, if desired, to process the source data in some manner before assignment.

CHANGE [num] [setspec] [FROM source] [LET clause] [EVALUATE clause] [-> clause]

Syntax #3

Changes one or more records in an EntitySet, relationship, form, or set from data found in an application document. Date for the target fields in the records is taken from an unstructured application document or a set whose only component is an unstructured application document. You can use the FORMAT clause to direct the source data to particular target fields. The PROMPT clause performs the same function, but, in addition, sends the field names and their current values to the current output destination for display. You can use the LET subcommand to process the source data in some manner before assignment.

CHANGE [num] [setspec] FROM doc [LET clause]
 [FORMAT | PROMPT [«field »]] [EVALUATE clause] [-> clause]

Parameters

num

Can be
an integer constant (15, 200);
a variable, form field, or parameter that evaluates to an integer;
the word ALL.
If num is omitted, or less than 0, it defaults to 1.

setspec

The set specification (made up of application documents, EntitySets, relationships, forms, or result sets), designating the records to be changed. If omitted, the current set (if available) is used.
Application documents named in the set specification cannot be updated.

source

The set specification where the data to replace the existing values in setspec can be found. If omitted, the data is taken from the current set (if available).

doc

The name of an unstructured application document, or a result set whose only component is an unstructured application document, from which you are taking data to replace existing values in setspec.

FORMAT

Specifies the order in which data for the specified fields of setspec appears in doc. If omitted, the data is assumed to appear in full, field-sequential order (as setspec's fields were defined). Used to direct the source data to particular target fields.

PROMPT

Specifies the order in which data for the specified fields of setspec appears in doc (which is normally TERMINAL in this context), and displays the field name(s) on the terminal. If omitted, prompts for the data appear in full, field-sequential order (as the fields were defined for setspec). Used to direct the source data to particular target fields.

field

Specifies one or more fields that are to be prompted for or formatted. If omitted from the PROMPT or FORMAT clause, all fields in the object being changed are prompted for or formatted.

Comments

Any number of fields can be assigned a value through the LET clause. Any target field that has not explicitly been assigned a data value by LET is supplied with a data value from the field in source that has the same name (if any). If no field in source has the same name as a target field and if no value has been explicitly assigned, then the target field is left unchanged.

The FORMAT clause specifies the order in which data for each field appears. The PROMPT clause performs the same function, but, in addition, it displays the field names and the old values on the terminal. Target fields not assigned data values by LET, FORMAT, or PROMPT are left unchanged.

Special rules apply when data is taken from an unstructured application document to change the values in target fields:

Before all fields are assigned their new values, they are checked to ensure that a required field is not $Null. If a required field is $Null, an error is generated and the record is not changed. This check can be turned off with the SET CHECKNULLS command.

Messages marking the progress of a CHANGE command can be displayed on the terminal. See SET MEMBERCOUNT and SET MEMBERINTERVAL for details.

Refrain from using the CHANGE command to modify records to the Object Dictionary EntitySets for user interface objects (windows, menus, forms/displays, and form field/menu items).
The records contain many fields, often with important inter-field dependencies. Records modified using CHANGE are not validated in the usual way, and incorrect values in the record could cause the software to behave unexpectedly or even crash.
Use the Screen Painter to modify all user interface objects.

Rules for Value Assignments to Fields During CHANGE

The software assigns a value to each target field based on the first of the following situations that holds true for that field:

  1. The target field is explicitly assigned a new value in a LET subcommand.
  2. The structured source object contains an identically-named field whose value is implicitly assigned to the target field.

OR

The unstructured source object contains a value in the sequential position that matches the sequential position of the target field's name in the FORMAT or PROMPT clause.

OR

The unstructured source object contains a value in the same sequential position of the target field in the records. This occurs when no FORMAT or PROMPT clause is supplied, or when the clause does not specify field names.

  1. In all other cases, the value of the target field does not change.

Once new values have been determined for all target fields in the record, the software checks to ensure that a Required field is not $Null. If a Required field is $Null, the software raises an error, and the record is not changed. This check can be switched off with a SET CHECKNULLS OFF command.

Special rules apply when the data in an EntitySet or relationship is being changed using data from an unstructured application document (Syntax #3):

  1. The $Null property can be explicitly assigned to a field using the following technique:
  2. If a line in the document fails to provide a value for every field in the record being changed, each field not assigned a value remains unchanged.
  3. An asterisk (*) explicitly indicates a field that is to be left unchanged. For example, abc * def generates three values: abc, "no change", and def. To specify an asterisk as a literal character, place a backslash (\ - Escape) before it. For example, if you want a particular field to have the value 5*6, type 5\*6 into the source document. Alternatively, use SET SPECIALSCAN to control how the metacharacters backslash (\) and asterisk (*) are to be handled when they appear in an unstructured application document that is being used as a data source. When SET SPECIALSCAN is ON, the backslash and asterisk characters have their special meanings. When SET SPECIALSCAN is OFF, the backslash and asterisk characters are treated as ordinary data.
  4. A line of zero length in the source document (i.e., the line consists solely of a carriage return or a newline character) is taken as an end-of-file indicator by default. The CHANGE command stops unless a SET EOFVALUE command has been issued.

Example

change all Emps from terminal prompt LastName FirstName

LastName  FirstName
Smith   John
:

Prompts with the existing values for each record and waits for input.

LastName  FirstName
Smith   John
:* Jim
LastName  FirstName
Jones   Fred
:

Typing * Jim and pressing Return changes the first name from John to Jim. A prompt for the next record appears.

LastName  FirstName
Jones   Fred
:Johnston
LastName  FirstName
Samuels  Jim
:

Typing Johnston and pressing Return changes the last name from Jones to Johnston. A prompt for the next record appears.

Pressing Return without typing anything terminates the CHANGE command.

change WaterSamples from fWaterSamples

Updates an EntitySet based on the data in a form.

change Employees (unrelated) WorkOn Projects \
   sorted by LastName from NewProjects \
   where ProjAssigned = "N" \
   sorted by ProjDate descending \
   let Employees.ProjNum = NewProjects.ProjId

Assigns a new project to Employees that are not currently working on a project. The employee records that are unrelated to any project are sorted in LastName order. The sorted records are updated from the set of NewProjects that are not assigned (ProjAssigned="N").

change let LastName = "Smith"

Changes the last name in the current member of the current set.

change all Employees where DeptNum = D01 let DeptNum = D02

Changes department number D01 to D02 for the entire set.

form open dInvoice
change all fInvItem from LineItems
form display input

Fills the occurrences of a particular form with data from a particular set.

 

Related Topics