Clara-Doc - Method Reference
CTARR_Get
Description
Use this method to retrieve a copy of the value at a specified index within the array. You must provide a buffer that will receive the value. Since the array item size is fixed and known beforehand, you do not need to provide the size of the supplied buffer. The buffer you provide MUST however be of the proper size (or larger). If the buffer you provide has a smaller size than the array item size, then a buffer overflow will occur and this may cause undesirable results.
If the index is out of range, nothing is copied in the buffer and the method returns a failure code.
If the index is out of range, nothing is copied in the buffer and the method returns a failure code.
Prototype
DCTARR_Get...
D PR 10I 0
D
D@This * Value
D@pBuffer * Value
D@Index 10I 0 Value
Parameters
@This
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of an array instance. This pointer MUST be obtained through a call to CTARR_Constructor. |
@pBuffer
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of a buffer where the array item will be copied. |
@Index
| Type | 10I 0 |
| Passing Mode | Value |
| Description | The index position of the item within the array. If you specify an index larger than the actual number of items in the array, the method will fail. The first list item is at index 1 |
Return Values
| Symbolic Constant | Value | Description |
| CS_SUCCESS | 0 | The item was copied successfully. |
| CS_FAILURE | 1 | The item was not copied. One possible reason is that the provided index is out of range. |
Examples
HDatEdit(*YMD)
*--------------------------------------------------------------
* Common Definitions
*--------------------------------------------------------------
/Include QINCSRC,CTBASE
DEntryProc Pr ExtProc('EXLST06')
DEntryProc PI
*-------------------------------------------------------------------------------
* Main
*-------------------------------------------------------------------------------
DArray S *
DCount S 10I 0
Dn S 10I 0
DSize S 10I 0
DBytes S 10I 0
DRecord DS Qualified
DF1 10I 0
DF2 32A
/Free
Array = CTARR_Constructor();
// Let's allocate an array of size 3
// And initialize each item with an empty record
Clear Record;
CTARR_Alloc(Array: 3: %Size(Record): %Addr(Record));
// Set the second array item
Record.F1 = 777;
Record.F2 = 'This is a string';
CTARR_Set(Array: %Addr(Record): 2);
// Look at each item (check that second item is set)
For n=1 To CTARR_Count(Array) By 1;
CTARR_Get(Array: %Addr(Record): n);
EndFor;
// Let's extend the array with 2 more items
// Initialize additional items with empty record
Clear Record;
CTARR_Realloc(Array: 5: %Addr(Record));
// Look at each item (check that second item is still set).
For n=1 To CTARR_Count(Array) By 1;
CTARR_Get(Array: %Addr(Record): n);
EndFor;
// Let's reduce the array size to 2 items
// This time, there is no need to specify
// an initial item value since we will
// only have what already exists
CTARR_Realloc(Array: 2: *Null);
// Look at each item (check that second item is still set).
For n=1 To CTARR_Count(Array) By 1;
CTARR_Get(Array: %Addr(Record): n);
EndFor;
CTARR_Destructor(Array);
*InLr = *On;
Return;
/End-Free