ADD

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

objname

The name of an EntitySet or relationship with fields. A role name can be used.

num

The number of records to be added to object. Num can be
a constant
a variable, a form field, or a parameter that evaluates to an integer
the word ALL, which is the default value
If num is less than zero, num is set to ALL. Members are added to object until num members have been added or until source has been exhausted.

source

A set specification from which you are taking data to add to object. If source is not specified, the current set is used.

doc

The name of an unstructured application document, or a result set whose only component is an unstructured document, from which you are taking data to add to object.

field

The target field in object.

FORMAT

Specifies the order in which data for the specified field(s) of object appears in doc.

PROMPT

Specifies the order in which data from the specified fields(s) of object appear in doc (usually TERMINAL in this context), and displays the fieldname(s) on the terminals.

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:
  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.

 

Related Topics