# _CP_readfields

_CP_readfields supports reading a set of named fields.

## Syntax

```
 _CP_readfields(int type, CPSTR ** buffer, CPSTR ** returnset, CPSTR ** statusset,
 int dictfd, int datafd, CPSTR * filename, CPSTR * itemidlist, int * lockedresult,
 CPSTR * fieldnames)
```

## Style of read types

| Type | Style of read |
| --- | --- |
| _CP_READ | Reads do not set item locks. |
| _CP_READU | Reads set item locks and the call blocks until it can do so. |
| _CP_READUL | Reads set item locks, but the call does not block. If the item is successfully locked by this call, then lockedresult = 1. If the item is not successfully locked by this call, then lockedresult = 0. |

## Parameters

| type | Indicates the style of read type: _CP_READ _CP_READU _CP_READUL See the Style of read types table for more information. |
| --- | --- |
| buffer | The address of a CPSTR* object that contains the results from the call. It is a segment mark delimited list of results. There is one entry for each item processed. Each item has one attribute for each attribute listed in fieldnames. |
| returnset | A segment mark delimited list of return values corresponding to each item read from the itemidlist. If the item was read successfully, the value will be 0. If there was an error reading an item, the value will be the result of _CP_errno() for the failed read. |
| statusset | A segment mark delimited list of status values corresponding to each item read from the itemidlist. If the item was read successfully, the value will be 0. If there was an error reading an item, the value will be -1. |
| dictfd | The handle, returned by _CP_open(), to the dictionary level of the file containing the ADIs referenced by fieldnames. |
| datafd | The handle, returned by _CP_open(), to the data level of the file containing the items referenced by itemidlist. |
| filename | The full path to the dictionary level of the file containing the ADIs. This is needed in addition to dictfd to handle A-Correlatives. |
| itemidlist | An attribute mark delimited list of the item-ids used to read items from datafd. |
| lockedresult | The lock status of the last item read. |
| fieldnames | An attribute mark delimited list of the named fields (aka ADIs) to read and process for each item in itemidlist.CAUTION: If a particular ADI cannot be read, then that field will be returned without being processed. |

## Description

For each item id in the attribute mark delimited *itemidlist* dynamic
 array:

- The item is read.

- The correlative and output conversion of each field (that is, ADI) listed in the attribute mark delimited fieldnames dynamic array is applied to the item.

- The results are placed in buffer.

For each item processed, there will be one attribute for each attribute listed in
 *fieldnames*. This function returns -1 if an error occurs and the error code
 is contained in _CP_errno.

 The *returnset* and *statusset* provide information about
 error conditions. Typical common errors include:

- Using a type of CP_READ for an item that does not exist.

- Using a type of CP_READUL for an item that is locked.

## Example(s)

**Example 1**

 This example demonstrates the use of the _CP_readfields function with the
 D3 mvdemo,orders, file in Python.

```

 import d3py
 def run():
 d3py.logon('localhost', 'dm', '', 'mvdemo')
 f = d3py.File('mvdemo,orders,')
 list = d3py.List(1, f)
 fields = d3py.DynArray(['orderid', 'orderdate', 'shipname',
 'shipaddress'])
 while True:
 id = list.next()
 if len(id.to_list()) == 0:
 print('End of File')
 break
 else:
 print(id)
 print(f.readnamedfields(id, fields))
```

 **Example 2**

 C Programming example:

```

 /*
 Reads items '12', '15', '57', and '55' from "mvdemo,orders," and
 applies the correlatives from 'orderid', 'orderdate', 'shipname', 'shipaddress' to each.
 */
 CPSTR * dict = _CP_mkstr("dict");
 CPSTR * filename = _CP_mkstr("mvdemo,orders,");
 CPSTR * itemidlist = _CP_mkstr("12" "\xfe" "15" "\xfe" "57" "\xfe" "55");
 CPSTR * fieldnames = _CP_mkstr("orderid" "\xfe" "orderdate" "\xfe" "shipname" "\xfe" "shipaddress");
 int lockedresult = 0;
 CPSTR * results = _CP_str_null;
 CPSTR * returnset = _CP_str_null;
 CPSTR * statusset = _CP_str_null;
 int datafd, dictfd;

 _CP_open(&datafd, _CP_str_null, filename);
 _CP_open(&dictfd, dict, filename);
 _CP_readfields(_CP_READ, &results, &returnset, &statusset, dictfd, datafd, filename, itemidlist,
 &lockedresult, fieldnames);
 _CP_print(results);

 _CP_str_free(statusset);
 _CP_str_free(returnset);
 _CP_str_free(results);
 _CP_str_free(fieldnames);
 _CP_str_free(itemidlist);
 _CP_str_free(filename);
 _CP_str_free(dict);
```

## See also

- [C functions overview](https://d3codex.com/cfunctions/c-functions-overview/)
- [_CP_open](https://d3codex.com/cfunctions/cp-open/)
- [_CP_writefields](https://d3codex.com/cfunctions/cp-writefields/)

---
Source: https://d3codex.com/cfunctions/cp-readfields/ - part of the D3Codex reference.