&NDBUPD

Updates a record in a NetMaster database (NDB).

&NDBUPD dbname 
    { [ RID=rid ] [ DATA ] update-text |
        RID=rid START | END | CANCEL |
        RID=rid FORMAT=fmtname [ FSCOPE={ PROCESS | GLOBAL } ] }

update-text is:

fieldname = fieldvalue [ fieldname = fieldvalue ... ]

The &NDBUPD statement allows an NCL procedure to update an existing record in an NDB. The existing record will have the fields listed in the &NDBUPD statement set to the new values, and all other fields will be left as is. Following completion of the statement, the system variable &NDBRC will indicate success or failure if the update.

Operands:

dbname

The name of the NDB that you wish to update the record in is a mandatory operand. This NDB must have been previously opened by an &NDBOPEN statement.

RID=rid

A required parameter, if a single-statement update, or if the START statement of a multi-statement update. Rid is the Record ID of the record you want to update.

DATA

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.

START

Indicates the start of a multi-statement &NDBUPD. The statement must end after the START keyword. The RID=rid parameter must be specified on this statement.

END

Indicates the end of a multi-statement &NDBUPD. This statement will call the database, passing the concatenated &NDBUPD DATA information.

CANCEL

Indicates an active &NDBUPD START/END set is to be canceled. If there is no active &NDBUPD START/END for this database, the statement is ignored.

FORMAT=fmtname [ FSCOPE={ PROCESS | GLOBAL } ]

FORMAT=fmtname specifies that 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.

fieldname = fieldvalue ...

Free-form text naming the fields to be updated in the nominated record, and the new values for those fields. There is as many fieldname = fieldvalue pairs as desired, and they may be split across multiple statements, 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 to be set not present. This is not the same as present, with a null value (for example, 0 for a numeric field).

For example, the following 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 
&NDBUPD MYNDB RID=&RID DATA FIELD1 = &FIELD1 +
                            FIELD2 = &FIELD2 +
                            FIELD3 = &FIELD3

Omission of a field name and its accompanying value means that the field stays as it was in that record.

Examples: &NDBUPD

The following example sets the value of field FIRSTNAME in the record with the RID in &SAVERID to JOHN. All other fields in the record are left as they were.

&NDBUPD MYNDB RID=&SAVERID DATA FIRSTNAME='JOHN'

The next example updates the first record in the NDB called MYNDB with field SURNAME equal to JONES, altering the values of fields DOB and FIRSTNAME. It illustrates how the free-form text is split at any point where a blank is valid.

&NDBGET MYNDB FIELD=SURNAME VALUE=JONES 
&NDBUPD MYNDB RID=&NDBRID START 
&NDBUPD MYNDB DATA DOB = 
&NDBUPD MYNDB DATA FIRSTNAME = 'MARK' 
&NDBUPD MYNDB END

Notes:

Errors encountered while processing the &NDBUPD statement can 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 updated successfully (&NDBRC is 0 after the single-statement &NDBUPD, or after the &NDBUPD END for a multiple-statement update), the system variable &NDBRID will contain the record id of the updated record.

At least one fieldname = fieldvalue must be specified to successfully update a record (although the value may be the null indicator).

More information:

&NDBADD

&NDBDEL