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

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:

• If the current delimiter is not a space (see the SET DELIMITER command), then two delimiters side-by-side indicate that a field is $Null. For example, if a slash (/) were the delimiter, then abc/def// would generate three assignments: abc, def, and $Null.
• If the current line in the application document does not contain enough values for the fields in the records, the remaining fields are left unchanged.
• An input line of zero length is taken as an end-of-file indicator and stops the CHANGE command, unless a SET EOFVALUE command has been issued.
• An asterisk (*) used with CHANGE indicates that an existing value is to be left untouched. To specify an asterisk as a literal character, place a backslash () preceding it.

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.

3. 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:
   • If the current delimiter is not a space (see SET DELIMITER), then two delimiters side-by-side explicitly indicate an unassigned value ($Null). For example, if a slash (/) is the delimiter, then abc/def// generates three values: abc, def and $Null.
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.

See Also

ADD

UPDATE