The pRecordInsert parameter is used to insert RECORDCORE structures into the container. The pRecordOrder and pRecordParent fields of the RECORDINSERT data structure are used to place each record into the container in order, relative to the other records. If the CMA_FIRST or CMA_END attributes are specified, records are inserted before the first child or after the last child of the record specified in the pRecordParent field. If the value of the pRecordParent field is NULL, the record or records are inserted before the first record or after the last record, respectively, at the root level. Otherwise, if the value of the pRecordOrder field is a pointer to a record, the record or records to be inserted are placed after this record.

A z-ordering of the records is maintained by the container control. The zOrder field of the RECORDINSERT data structure is used to specify the record's z-order in the container, relative to the other records. The CMA_TOP attribute is used to place the record at the end of the z-order list, while the CMA_BOTTOM attribute places the record at the beginning of the z-order list. Z-ordering is used for the icon view only.

If the value of the cRecordsInsert field of the RECORDINSERT data structure is greater than 1, a linked list of RECORDCORE structures is inserted in the order specified by the pRecordOrder, pRecordParent, and zOrder fields. Here, the pRecord parameter points to the first RECORDCORE structure of a linked list of structures.

If one RECORDCORE structure is to be inserted, the cRecordsInsert field has a value of 1 and the pRecord parameter points to the RECORDCORE structure to be inserted.

When containers display the icon view, the coordinates specified by the RECORDCORE structure's ptlIcon field are used to position inserted container records in the container's workspace. If the coordinates are not specified and the CCS_AUTOPOSITION style bit is not set, all of the inserted container records are positioned at (0,0) and a CM_ARRANGE message must be sent to position them elsewhere. If the CCS_AUTOPOSITION style bit is set, the container records are positioned without the CM_ARRANGE message being sent.

After the container records have been inserted:

• If the fInvalidateRecord field of the RECORDINSERT data structure is FALSE, the CM_INVALIDATERECORD message must be sent to update the display with the inserted records. If the current view is the icon view and either the CCS_AUTOPOSITION style bit is set or the fInvalidateRecord field is TRUE, the view is updated without the CM_INVALIDATERECORD message being sent.

• The preccNextRecord, flRecordAttr, and ptlIcon fields of the external RECORDCORE structure are not updated as changes occur within the container. However, if records are shared among multiple containers, the flRecordAttr and ptlIcon fields are modified internally. See the PM Programming Guide for more information about the modification of these fields.

If the CCS_VERIFYPOINTERS style bit is set and the pRecord parameter contains a pointer to a RECORDCORE structure that is currently inserted, the PMERR_RECORD_CURRENTLY_INSERTED error is set and no RECORDCORE structures are inserted.

If the RECORDCORE structures are sorted on insertion, the pRecordOrder and zOrder fields are ignored.