Adds data to EntitySets or relationships.

Syntax #1

Adds a single record to an EntitySet or relationship. Use the LET subcommand to explicitly assign values to the target fields in the record.

ADD objname [LET clause] [EVALUATE clause] [-> clause]

Syntax #2

Adds one or more records from a set specification to an EntitySet or relationship. Data for target fields in the records is take from the 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.

ADD [num] objname [FROM source] [LET clause] [EVALUATE clause] [-> clause]

Syntax #3

Adds one or more records from an unstructured application document to an EntitySet or relationship. Data 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. The LET subcommand can be used to process the source data in some manner before assignment. You can use the FORMAT clause to direct the source data to particular target fields. The PROMPT clause performs the same function but also sends the field names to the current output destination for display.

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

Parameters

Comments

If a field is not explicitly assigned a value during an ADD, the field is checked for a defined default value. If available, the default value is assigned; otherwise, $Null is assigned.

Before adding each record, the software ensure that every required field has been assigned a value. If any required field is $Null, an error results, and the corresponding record is not added. To switch this check off, use the SET CHECKNULLS OFF command.

Even before execution of the ADD, while the parser is processing the command, a check is performed to determine if required fields that have no defined default value are being assigned a value. If no value is being assigned, an error is immediately generated. This check is always performed.

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

Refrain from using the ADD command to add 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 added using ADD 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 define all user interface objects.

Rules for Value Assignments to Fields During ADD

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 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. The target field takes the default value defined for it in the Object Dictionary.
2. The target field is $Null (unassigned).

Once 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 added. This check can be switched off with a SET CHECKNULLS OFF command.

When an ADD command is parsed, the software checks if Required fields that have no defined default value are being assigned a value. If no value is being assigned,the software raises an error immediately, before any attempt to execute the ADD. This check is always performed.

Special rules apply when the data being added to an EntitySet or relationship comes from an unstructured application document (Syntax #3):

1. The $Null property can be explicitly assigned to a field using one of the following techniques:
   • 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.
   • An asterisk (*) also explicitly indicates an unassigned value ($Null). For example, abc * def generates three values: abc, $Null and def. To specific an asterisk as a literal character, place a backslash ( – Escape) preceding 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.
2. If a line in the document fails to provide a value for every field in the record being added, each field not assigned a value becomes $Null.
3. 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 ADD command stops unless a SET EOFVALUE command has been issued.

Example

add Employees let  LastName = “Smith” FirstName = “Jeff”

EmpNum = 99 DeptNum = “D04”

Adds a single record, explicitly specifying the data.

add Employees from NewEmps let EmpNum = Enum + 100

Adds records from a structured application document, assigning values from NewEmps to fields in Employees that carry identical names. Adds 100 to Enum field and assigns resulting value to EmpNum.

add Employees from NewEmps format DeptNum LastName FirstName

Adds records from an unstructured (but consistently formatted) application document, noting the order in which the data appears.

add Employees from terminal prompt

Adds records based on responses to a prompt containing the field names from Employees.

add Employees from terminal prompt FirstName LastName

Adds records based on responses to a prompt containing only specified field names. If other fields in Employees have been defined as “required”, this command produces an error.

See Also

$MemberCount

CHANGE

INSERT