View source for CM INSERTRECORDARRAY

This message inserts one or more [[RECORDCORE]] structures into a container control.
;Note:; If the CCS_MINIRECORDCORE style bit is specified when a container control is created, then [[MINIRECORDCORE]] should be used instead of [[RECORDCORE]], and PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data structures and messages.
==Syntax==
<PRE>
param1
PVOID pRecordArray;    /* Pointer to an array of pointers to RECORDCORE structures that are to be inserted into the container. */

param2
PRECORDINSERT pRecordInsert; /* Pointer to the RECORDINSERT structure. */
</PRE>

==Parameters==
;pRecordArray ([[PVOID]]) - Input
: Pointer to an array of pointers to [[RECORDCORE]] structures that are to be inserted into the container.
;pRecordInsert ([[PRECORDINSERT]]) - Input
: Pointer to the [[RECORDINSERT]] structure.

==Returns==
;cRecords ([[ULONG]]) - returns
: Number of [[RECORDCORE]] structures in the root level of the container.
::0: No [[RECORDCORE]] structures were inserted. The [[WinGetLastError]] function may return the following errors:
:::PMERR_INVALID_PARAMETERS
:::PMERR_INSUFFICIENT_MEMORY
:::PMERR_RECORD_CURRENTLY_INSERTED
::Other: The number of [[RECORDCORE]] structures in the container.

==Remarks==
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.

The '''cRecords''' parameter always specifies an array of pointers to [[RECORDCORE]] structures to be inserted into the container. The number of pointers contained in the array must equal the value specified in the '''cRecordsInsert''' field of the [[RECORDINSERT]] structure.

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.

If the CCS_VERIFYPOINTERS style bit is set and the '''pRecordArray''' 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.

==Default Processing==
The default window procedure does not expect to receive this message and, therefore, takes no action on it other than to return FALSE.

[[Category:Messages]]