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:
- The target field is explicitly assigned a value in a LET subcommand.
- 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.
- The target field takes the default value defined for it in the Object Dictionary.
- 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):
- 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.
- 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.
- 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.