Documentation for drupal_write_record doesn't state what happens to missing values on existing records

It would seem that skipping an item on update simply leaves the field with it's prior value.
In other words in an update "missing items" are unchanged.
Similarly if there is a serial value it should never change on update since the record itself is the same.

Should the documentation really reflect this?
It seems like standard behavior for a database update, but I guess if you are not familiar with the process it might help.

I could see something like:
"On update missing items and serial values remain unchanged."

I think this is a reasonable suggestion, and that the documentation for this function is a bit sketchy anyway, and could be expanded to make it clearer.

I read through the code in drupal_write_record() carefully, and I think this explains what it does.

We should probably fix this in D6 too, since the function behaves *somewhat* the same there. But I don't think it would be a straight port of the patch.

I refactored this function for D7.

@param $record needs to make a distinction between what happens to the record in the database and $record.

It isn't necessary to explain that primary keys aren't being updated to what they are already set to - even if they were, it wouldn't make any difference to the API of this function. It is an extremely micro optimisation.

How about:

... If inserting a new record, values not provided in $record will be populated with the default values from the schema (the database already knows these values), as well as a single serial (auto-increment) field (if present). If updating an existing record, only provided values are updated and $record is not modified.

OK... How's this? Mostly what jbrown wrote...

And definitely, the D6 function is a bit different in how it behaves, but the doc is similarly needing some love.

Works for me!

Extremely nitpicky reroll because one of the lines was over 80 characters. Otherwise looks good.

You have uploaded some other patch.

#6: 942006-6.patch queued for re-testing.

The patch in #6 is fine - the longest line is exactly 80 chars.

Committed to CVS HEAD. Thanks.