CopyMemoryToStringArray - Transfer data from memory to a string array

 Top  Previous  Next

Syntax

<aStrings> := CopyMemoryToStringArray( <nAddress>, [<nType>], [<nMaxElementCount>], [<nElementLen>], [@<nBytesRead>] )

Parameters

<nAddress>

 

Start address of string array in memory.

 

<nType>

 

Type of string data to be read from memory. See Cockpit string types for details.

 

<nMaxElementCount>

 

Maximum number of elements in the returned array. If this parameter is not specified, all elements in the array found in memory are read. This parameter contains the number of elements to be read if <nMaxElementLen> is given.

 

<nElementLen>

 

Length of an element (number of characters) in the returned array. If this parameter is specified, <nMaxElementCount> must be given. Note that the actual buffer size in bytes is twice this value for Unicode text strings.

 

<nBytesRead>

 

Number of bytes read during the operation. In fixed size mode the return value is <nElementLen> * <nMaxElementCount> * character width. In dynamic size mode this value contains the number of bytes read including all terminators.

Return value

An array containing the strings found in memory at the address <nAddress>.

Description

CopyMemoryToStringArray operates in two modes, depending on <nElementLen>. If <nElementLen> is given, the array to be read is assumed to have elements with fixed sizes in memory.

 

Operation in fixed size mode: If <nElementLen> is passed in as numeric value, the number of elements to be read from memory is determined by <nMaxElementCount> which is the exact element count in this mode. For each array element a buffer of <nElementLen> length characters is read from memory. Depending on the string type passed in <nType> the actual strings returned in the array can be shorter, if the termination character is found in the buffer.

 

Operation in dynamic size mode: If <nElementLen> is not passed in as numeric value, <nMaxElementCount> can limit the number of elements returned in the array. In dynamic size mode CopyMemoryToStringArray determines the element sizes by scanning for the termination character according to <nType>. The string array in memory is terminated by an extra terminator without preceding characters. If the terminator is found at <nAddress>, an empty array is returned. As a consequence of this array termination handling, an array read with CopyMemoryToStringArray cannot contain empty strings.

 

In both modes, character set conversion according to <nType> takes place during transfer:

 

The string array read can only extend in one dimension, which means it is a list.

Classification

Core

Category

Pointers and memory

Quick Info

Library: cckptcor.lib / cckptcor.dll

Header: StringTypes.ch

See also

CopyStringArrayToMemory, SetCX, Character set conversion

Example

 

#INCLUDE "CockpitCoreLibs.ch"

#INCLUDE "StringTypes.ch"

 

FUNCTION Main

 

LOCAL address

 

* Put a Unicode string array in memory. The number of terminating Chr(0)'s passed

* could be reduced to two, because LockString always adds them.

address := LockString(Ansi2Unicode("Here")+Chr(0)+Chr(0)+Ansi2Unicode("we");

                     +Chr(0)+Chr(0)+Ansi2Unicode("go")+Chr(0)+Chr(0)+Chr(0)+Chr(0))

 

* Read the string array, convert from Unicode to Ansi

? CopyMemoryToStringArray( address,STRINGTYPE_UNICODETEXT )

 

* Release the allocated memory

ReleaseLockString( address )

 

RETURN NIL