Clara-Doc - Method Reference

 / packages  / CTBASE  / Version 01.00.00  / CTMAPX

CTMAPX_IterNext
Description
Retrieves the next available map item in keyed order within an iteration loop. The map value is copied in a caller-supplied buffer. Do not use a CTBUFF instance. Use the address of a local variable or the address of a buffer allocated with a call to %Alloc.

Prototype 

			     DCTMAPX_IterNext...
     D                 PR            10I 0
     D@This                            *   Value
     D@Key                             *   Value
     D@KeySize                       10I 0
     D@Value                           *   Value
     D@ValueSize                     10I 0
Parameters
@This
TypePointer (*)
Passing ModeValue
DescriptionThe address of a CTMAPX instance. This pointer MUST be obtained through a call to CMAPX_Constructor.
@Key
TypePointer (*)
Passing ModeValue
DescriptionThe address of a the caller-supplied buffer that contains the key value associated with the map item.
@KeySize
Type10I 0
Passing ModeReference
DescriptionThis is an IN/OUT parameter. On input, this holds the maximum number of bytes to copy in the buffer that will hold the key value (including the NULL terminator). On return, this parameter will hold the actual item's key size (including the NULL terminator). This happens to be the nmber of bytes copied into the @Key parameter.
@Value
TypePointer (*)
Passing ModeValue
DescriptionThe address of a caller-supplied buffer. Don't use a CTBUFF instance. This buffer can be a local variable or a buffer allocated with a call to %Alloc.
@ValueSize
Type10I 0
Passing ModeValue
DescriptionThe size in bytes of the @Value parameter. On return, this paramter will hold the actual size of the retrieved item. If the supplied buffer is too small, then only @ValueSize bytes have been copied so as to not overflow the supplied buffer. If the supplied buffer is larger than the map item, then, on return, this parameter holds the number of bytes that were actually copied into the supplied buffer (which happens to be the item's real size).
Return Values

Symbolic ConstantValueDescription
CS_SUCCESS0The next map item has been returned successfully.
CS_FAILURE1We are at the end of the list. Another possibility is that the key size is smaller than the actual item key size. The @KeySize parameter will hold the actual key size on return.