| GEOS SDK TechDocs | | ECCheckProcessHandle() ... | ElementArrayDelete() ...

---

ECVMCheckVMBlockHandle()

void	ECVMCheckVMBlockHandle(
        VMFileHandle file,
        VMBlockHandle block);

This routine checks the validity of the given VM file and block handles. If assertions fail, a fatal error will occur.

Include: ec.h

ECVMCheckVMFile()

void	ECVMCheckVMFile(
        VMFileHandle file);

This routine checks the validity of the given VM file handle. If assertions fail, a fatal error will occur.

Include: ec.h

ElementArrayAddElement ()

word	ElementArrayAddElement(
        optr	arr,		/* Handle of element array */
        void *	element,		/* Element to add (if necessary) */
        dword	callBackData,		/* This is passed to the Callback routine */
        Boolean _pascal (*callback) (void *elementToAdd, 
			void *elementFromArray, 			dword valueForCallback));

This routine is used to add elements to an array. It is passed the address of a potential element. It compares the element with each member of an element array. If there are no matches, it adds the element to the array and sets the reference count to one. If there is a match, it increments the reference count of the matching element in the array and returns; it does not add the new element. When you pass the address of an element, make sure you pass the address of the data portion of the element (not the reference-count header).

You can pass a callback routine to ElementArrayAddElement() . ElementArrayAddElement() will call the callback routine to compare elements and see if they match. The callback routine should be declared _pascal. ElementArrayAddElement() passes the callback routine the address of the element you passed it, as well as the address of the data-portion of the element in the array (the part after the RefElementHeader structure). If the two elements match (by whatever criteria you use), return true ; otherwise, return false . If you pass a null function pointer, the default comparison routine will be called, which checks to see if every data byte matches.

Include: chunkarr.h

Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling ElementArrayAddReference() .

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddReference().

ElementArrayAddElementHandles()

word	ElementArrayAddElementHandles(
        MemHandle		mh,				/* Global handle of LMem heap */
        ChunkHandle		chunk				/* Chunk handle of element array */
        void *		element,				/* Element to add */
        dword		callBackData,		/* Passed to the Callback routine */
        Boolean _pascal (*callback) (void *elementToAdd, 
			void *elementFromArray, 			dword valueForCallback));

This routine is exactly like ElementArrayAddElement() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling ElementArrayAddReference() .

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddReference().

ElementArrayAddReference()

void	ElementArrayAddReference(
        optr	arr,				/* optr to element array */
        word	token);				/* Index number of element */

This routine increments the reference count of a member of an element array.

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddElement().

ElementArrayAddReferenceHandles()

void	ElementArrayAddReferenceHandles(
        MemHandle		mh,				/* Handle of LMem heap's block */
        ChunkHandle		ch,				/* Handle of element array */
        word		token);				/* Index number of element */

This routine is exactly like ElementArrayAddReference() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayCreate()

ChunkHandle ElementArrayCreate(
        MemHandle		mh,				/* Handle of LMem heap's block */
        word		elementSize,				/* Size of each element, or zero
							 * for variable-sized */

        word		headerSize);				/* Header size (zero for default) */

This routine creates an element array in the indicated LMem heap. It creates an ElementArrayHeader structure at the head of the chunk. If you want to leave extra space before the start of the array, you can pass a larger header size; if you want to use the standard header, pass a header size of zero.

You can specify the size of each element. Remember that the first three bytes of every element in an element array are the element's RefElementHeader ; structure, which contains the reference count; leave room for this when you choose a size. For arrays with variable-sized elements, pass a size of zero.

Include: chunkarr.h

Tips and Tricks: You may want to declare a structure for array elements; the first component should be a RefElementHeader . You can pass the size of this structure to ElementArrayCreate() .

If you want extra space after the ElementArrayHeader , you may want to create your own header structure, the first element of which is an ElementArrayHeader . You can pass the size of this header to ElementArrayCreate() , and access the data in your header via the structure.

Be Sure To: Lock the block on the global heap before calling this routine (unless it is fixed). If you pass a header size, make sure it is larger than sizeof(ElementArrayHeader) .

ElementArrayCreateAt()

ChunkHandle 	ElementArrayCreateAt(
        optr	arr,				/* optr of chunk for array */
        word	elementSize,				/* Size of each element, or zero
						 * for variable-sized */

        word	headerSize);				/* Header size (zero for default) */

This routine is just like ElementArrayCreate() above, except that the element array is created in a pre-existing chunk. The contents of that chunk will be overwritten.

Include: chunkarr.h

Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.

ElementArrayCreateAtHandles()

ChunkHandle 	ElementArrayCreateAtHandles(
        MemHandle		mh,				/* Handle of LMem heap */
        ChunkHandle		ch				/* Create array in this chunk */
        word		elementSize,				/* Size of each element, or zero
						 * for variable-sized */

        word		headerSize);				/* Header size (zero for default) */

This routine is exactly like ElementArrayCreateAt() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.