Clara-Doc - Method Reference
CTARR_Set
Description
Use this method to set the value at a specified index within the array. 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 garbage will be copied over to the array item and this may cause undesirable results.
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 that will hold the value to be copied in the array. |
@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 set successfully. |
| CS_FAILURE | 1 | The item was not set. One possible reason is that the provided index is out of range. |
Examples
HDatEdit(*YMD)
*--------------------------------------------------------------
* Common Definitions
*--------------------------------------------------------------
/Include QINCSRC,CTBASE_H
DEntryProc Pr ExtProc('EXLST07')
DEntryProc PI
*-------------------------------------------------------------------------------
* Main
*-------------------------------------------------------------------------------
DArray S *
DCount S 10I 0
Dn S 10I 0
DSize S 10I 0
DBytes S 10I 0
DBuffer S 32A
DExtension S 4A
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 create a brand new array of size 4
// with item size that of a 4 byte string ...
// We will not initialize the array items.
CTARR_Alloc(Array: 4: 4: *Null);
// Let's set the array items with the F2
// Field of our record.
// Only the first 4 bytes will be copied.
Record.F2 = 'This is a string';
CTARR_Set(Array: %Addr(Record.F2): 1);
CTARR_Set(Array: %Addr(Record.F2): 2);
CTARR_Set(Array: %Addr(Record.F2): 3);
CTARR_Set(Array: %Addr(Record.F2): 4);
// The array items will only hold the
// first 4 bytes of the Record.F2 field
// because the array object only copies
// to the item's size.
// Notice also that it's ok to retrieve
// in a buffer larger than the items size;
// if the buffer was smaller, the
// program could crash however.
CTARR_Get(Array: %Addr(Buffer): 1);
Buffer = *Blanks;
CTARR_Get(Array: %Addr(Buffer): 2);
Buffer = *Blanks;
CTARR_Get(Array: %Addr(Buffer): 3);
Buffer = *Blanks;
CTARR_Get(Array: %Addr(Buffer): 4);
// Since the retrieval is performed
// up to the array items size, we can
// take advantage of this fact.
// We will set our array items
// to file extensions ....
// Notice that even though our
// file extensions are 3 bytes long,
// we copy them in a 4 byte buffer
// because the array will copy 4 bytes
// which is it's item size. We don't
// want to provide a 3 byte buffer and have
// the array copy garbage at the end.
Extension = 'DOC';
CTARR_Set(Array: %Addr(Extension): 1);
Extension = 'XLS';
CTARR_Set(Array: %Addr(Extension): 2);
Extension = 'TXT';
CTARR_Set(Array: %Addr(Extension): 3);
Extension = 'CPP';
CTARR_Set(Array: %Addr(Extension): 4);
// We will now make file names
// From the extensions. Again
// You have to be sure that the provided
// buffer will hold all the data. In the following
// Example, we use pointer offsets. This means
// the offset could cause a buffer overflow, so
// beware of this situation.
Buffer = 'MYFILE.';
CTARR_Get(Array: %Addr(Buffer)+7: 1);
CTARR_Get(Array: %Addr(Buffer)+7: 2);
CTARR_Get(Array: %Addr(Buffer)+7: 3);
CTARR_Get(Array: %Addr(Buffer)+7: 4);
// With each retrieval, the buffer will
// contain these successive values:
//
// MYFILE.DOC
// MYFILE.XLS
// MYFILE.TXT
// MYFILE.CPP
CTARR_Destructor(Array);
*InLr = *On;
Return;
/End-Free