GetRecordsValues()
Summary
Reads the values of one or more fields for a group of records in a view.
Syntax
values_array = GetRecordsValues(string view_set, string start_rh, array field_names, array sort_order, int num_records, string order, array options)
| Argument | Contents |
|---|---|
| view_set | The view and selection set from which values are read |
| start_rh | The record handle of the first record from which values are read, or null for the current record |
| field_names | An array of names of fields to read, or null to read all fields |
| sort_order | An array indicating the desired sort order, or null for natural order. |
| num_records | The number of records to read |
| order | "Row" to return information one record at a time, or "Column" (the default) to return information one field at a time, as described below |
| options | No options are currently supported |
The sort_order information is an array of field name-order pairs, as indicated below:
| Element | Type | Contents |
|---|---|---|
| 1 | String | The name of the field |
| 2 | String | "Ascending" or "Descending" |
Returns
A two-dimensional array of record values. If order is "Row" then each array element is an array of values of the specified fields for a particular record. If order is "Column" then each array element is an array of values of a particular field for all of the records.
The values in the returned array are ordered identically to the input field_names array. If the input field_names array is null, GetRecordsValues() reads all fields and returns the array in the natural order of fields in the view. See GetFields() for more information.
Notes
If the input start_rh is null, GetRecordsValues() starts reading with the current record.
Unlike GetRecordValues(), the value array does not include field names.
Example
//Open BDOCUMENTS\CALIPER\\< product name>\TUTORIAL\NElayers.wrkz
tutorial_folder = RunMacro("G30 Tutorial Folder")
wrkz = OpenWorkspace(tutorial_folder + "NElayers.wrkz")rh = LocateRecord("County|", "[County Name]", {"SUFFOLK MA"}, )
vals = GetRecordsValues("County|", rh, {"[County Name]", "Population",
"[Per Capita Income]"}, {{"[County Name]", "Ascending"}}, 25, "Row", null)
ShowArray(vals)Error Codes
| Error Type | Meaning |
|---|---|
| Error | The start_rh is null and the view has no current record; the start_rh is non-null but invalid; orGetRecordsValues() encountered file reading errors |
| NotFound | The specified view, or one or more of the specified fields, does not exist |
See Also
| Function | Summary |
|---|---|
| GetDataVector() | Creates a vector from a field in a view|set |
| GetDataVectors() | Creates vectors from fields in a view|set |
| GetFields() | Gets a list of the fields in a view |
| GetRecord() | Gets the record handle of the current record of a view |
| GetRecordValues() | Reads the values of one or more fields for a record in a view |
| LocateRecord() | Locates a record based on the value of a field |
| SetDataVector() | Fills values into a field in a view|set from a vector |
| SetDataVectors() | Fills values into fields in a view|set from vectors |
| SetRecord() | Sets the current record of a view |
| SetRecordsValues() | Writes a value or sequence of numbers into a range of cells in a view on a table |
| SetRecordValues() | Updates the data for a record in a view |