|
|
|
Adds a record to a NetMaster database (NDB).
&NDBADD dbname { [ DATA ] add-text | START | END | CANCEL |
FORMAT=fmtname [ FSCOPE={ PROCESS | GLOBAL } ] }
where add-text is:
fieldname = fieldvalue [ fieldname = fieldvalue ... ]
The &NDBADD statement allows an NCL procedure to add a new record to an NDB. The new record contains the fields listed on the &NDBADD statement, with the listed values. Following completion of the statement, the system variable &NDBRC will indicate success or failure, and, if successful, the system variable &NDBRID will have the record ID of the new record.
Operands:
The name of the NDB that you wish to add a record to is a required operand. The NDB named must have been previously opened by an &NDBOPEN statement.
Indicates that free-form text follows. This operand is optional, but it is recommended, as it prevents any ambiguous meaning of a field name or field value of DATA, START, END, or CANCEL.
Indicates the start of a multi-statement &NDBADD. The statement must end after the START keyword.
Indicates the end of a multi-statement &NDBADD. This statement will call the database, passing the concatenated &NDBADD DATA information.
Indicates an active &NDBADD START/END set is to be canceled. If there is no active &NDBADD START/END for this database, the statement is ignored.
FORMAT=fmtname specifies that the output format fmtname, defined on the &NDBFMT statement, is to be used.
The nominated format must exist in the nominated scope. PROCESS is the default and means a format defined by the current NCL process. GLOBAL indicates a format is to be found in the global format pool for the NDB.
If this operand is specified, the START, DATA, CANCEL, and END operands are not allowed.
Free-form text naming the fields to be given values in the new record, and the values to be placed in those fields.
There may be as many name = value pairs as desired, and they may be split across multiple statements as described in the front of the chapter, using START/DATA.../END.
If fieldvalue is a null variable (for example, &NULL =/ &NDBADD ... X = &NULL), the null variable will be passed to the database as a null indicator, indicating the relevant field is not present. This is not the same as present, with a null value (for example, 0 for a numeric field).
The following code sets FIELD1 to a value, FIELD2 to present, with a null value, and FIELD3 not present:
&FIELD1 = value -* set to a value
&FIELD2 = &SETBLNK 1 -* set to a blank
&FIELD3 = -* set null
&NDBADD MYNDB DATA FIELD1 = &FIELD1 FIELD2 =+
&FIELD2 FIELD3 = &FIELD3
Note: The omission of a field name and its accompanying value also sets that field as 'not present' in the new record.
Examples: &NDBADD
The following example will add a record to the NDB called MYNDB, setting the field SURNAME to the value BLOGGS, and the field FIRSTNAME to the value FRED.
&NDBADD MYNDB DATA SURNAME='BLOGGS' FIRSTNAME='FRED'
The next example adds a new record to the NDB called MYNDB, and builds the list of fields across multiple statements. It illustrates how the free-form text is split at any point where a blank is valid.
&NDBADD MYNDB START &NDBADD MYNDB DATA SURNAME = JONES &NDBADD MYNDB DATA DOB = &NDBADD MYNDB DATA 600101 FIRSTNAME = 'JOHN' &NDBADD MYNDB END
Notes:
Errors encountered whilst processing the &NDBADD statement may cause the procedure to terminate, or may just be reflected in the &NDBRC system variable, depending on the setting of &NDBCTL ERROR option.
If the record is added successfully (&NDBRC is 0 after the single-statement &NDBADD, or after the &NDBADD END for a multiple-statement add), the system variable &NDBRID will contain the assigned record ID of the new record.
At least one fieldname = fieldvalue must be specified to successfully add a record (although the value may be the null indicator).
| Copyright © 2009 CA. All rights reserved. |
|