# SQLOP\_FETCH\_ROW

__

**xcall SQL, SQLOP\_FETCH\_ROW, cmdhdr, field1, … fieldN**

**xcall SQL, SQLOP\_FETCH\_ROW, cmdhdr, field(1)**

**xcall SQL, SQLOP\_FETCH\_ROW, cmdhdr, rowstring**

**xcall SQL, SQLOP\_FETCH\_ROW, cmdhdr, \$map()**

**xcall SQL, SQLOP\_FETCH\_ROW, cmdhdr, ds**

This operation retrieves the actual field data for the current row of the current result set. 

**Parameters**

_cmdhdr_ (ST\_SQL\_CMDHDR), \[in/out\]

The fields of interest to this opcode in the _cmdhdr_ structure (defined in [SQL.DEF](https://bitbucket.org/microsabio/exlib/src/master/909060/sql.def)) are listed below.

| **Field** | **Dir** | **Notes** |
|------|------|------|
| handle | in | handle to connection (returned from SQLOP\_INIT\_CONN) |
| dbmsconid | in | [DBMS Connector ID](dbmsconnectorid.md) |
| opflags | in | see FETCHR\_xxx |
| cmdarg1 | in | max # elements in field() array (second syntax form above) or delimiter to use if FETCHR\_DELIMETER (third syntax form) |
| cmdarg2 | in | row number within result set to fetch (1=first row); 0 for next row (or first if last operation was the query). |
| rc | out | return code (0 = ok, see SQLERR\_xxx) |
| rcext | out | extended error code |
| info1 | out | \# of fields returned.  |
| info2 | in/<br>out | row # just read (0 indicates no more rows available). Note that when cmdarg2 is set to 0 to read the next row, the routine assumes that info2 is left untouched by the application (and thus can simply be incremented to return the next row). See [Multiple Result Sets](multipleresultsets.md) for other caveats. |
| sqlstate | out | ANSI standard SQL state code |
| reshdl | in | result set handle. Can be ignored if only working with one result set at a time. Otherwise you must set it to match the value used for the SQLOP\_QUERY call which created the result set. |
| psthdl | in | set to the prepared statement handle for the statement which generated the result set (i.e. from SQLOP\_PST\_PREPARE), or 0 the result set was generated from a directly executed statement. |




| **Opflag** | **Value** | **Notes** |
|------|------|------|
| FETCHR\_FIELDS | \&h0000 | (first syntax form) Data retrieved into individual fields, which can be of differing sizes and types. |
| FETCHR\_ARRAY | \&h0001 | _field(1)_ argument (second syntax line above) is an array of max _cmdarg1_ elements. |
| FETCHR\_ROWSTR | \&h0002 | (for third syntax form) _rowstring_ is a single string argument to receive entire row. (Perfect for XTREE)  |
| FETCHR\_ROWMAP | \&h0010 | (for fourth syntax form) The specified ordmap \$map() will be populated such that \$map(column-name) -> column-value. |
| FETCHR\_ORGNAME | \&h0020 | (for fourth syntax form) Combine with FETCHR\_ROWMAP and optionally FETCHR\_TBLNAME to use the column org'name (original name) instead of the name and/or org'table instead of table. |
| FETCHR\_TBLNAME | \&h0040 | (for fourth syntax form) Combine with FETCHR\_ROWMAP and optionally FETCHR\_ORGNAME  to prepend the table (or org'table) name to the column name (or org'name) as the key. For example, given a table named "planes" and a column "model", a returned pair might be \$map("planes:model") -> "B52". |
| [FETCHR\_DYNFLDNUM](fetchrowintoadynstruct.md) | \&h0080 | (for fifth syntax form)  Fetch row into DYNSTRUCT by field number. |
| [FETCHR\_DYNFLDNUMX](fetchrowintoadynstruct.md) | \&h0400 | Similar to FETCHR\_DYNFLDNUM but somewhat smarter about handling multi-level DYNSTRUCTs. |
| [FETCHR\_DYNFLDNAME](fetchrowintoadynstruct.md) | \&h0800 | (for fifth syntax form) Fetch row into DYNSTRUCT by field name. |




| FETCH\_NULLS | \&h0100 | With FETCHR\_ROWMAP (fourth syntax form), causes NULL fields to be returned as "NULL" rather than "". For the first three syntax forms, causes NULL fields to be returned as .NULL (which displays as "<null>"). Otherwise, NULL fields are returned as "". Note that the symbol prefix here is FETCH\_ rather than FETCHR\_ due to the fact that it may be applied to other SQLOP\_xxx opcodes besides SQLOP\_FETCH\_ROW. |




_field1, … fieldN _\[any type, out\]

(first syntax form) Each of the _field_ parameters returns the data for the associated column of the applicable row of the result set (according to the sequence of columns determined by the query). An effort will be made to perform “appropriate” data type conversions, but the simplest method is just to use strings for all data except for blobs containing binary data that cannot be represented appropriately using printable characters. For all other field types (integers, dates, floats, etc.), the field will be formatted as a string according to the field type and flags. (For example, dates will always appear as “ccyy-mm-dd”.) Another advantage of using string variables to receive the data is that it allows you to use a generic array of string variables of an appropriate maximum size, rather than having to match up specific variable types to specific queries.

_field(1) _\[first element in an array of strings, out\]

(second syntax form) This form of the field list may be used to specify an array of strings, with each element to receive one field from the current row of the result set. This may be more convenient than specifying individual xcall arguments for each field but does limit you to string format. Dynamic strings—i.e. s,0—are supported though, eliminating concerns about having to allow for the maximum field size. The element specified will be considered as the first element in an array, and the _cmdarg2_ member of the _cmdhdr_ structure must specify the maximum number of items—starting with the specified item—in the array.

_rowstring _\[string, out\]

(third syntax form) The entire row is returned as a single string, with field sizes either determined by the column information (SQLOP\_FETCH\_COLUMNS) or delimited by the character whose ASCII value is in the _cmdarg2_ field (FETCHR\_DELIMITER) or using standard CSV formatting (FETCHR\_CSV).

_\$map() \[ordmap(varstr;varx) by reference\]_

(fourth syntax form; FETCHR\_ROWMAP) Each field in the query result is returned as an entry in the ordered map, with the key being the field _name_ (or _org'name_, possibly prefixed with the table name; see FETCHR\_ORGNAME, FETCHR\_TBLNAME), and the value being the field value. The value representation, except for BLOB types, will be the same as for the FETCHR\_ROWSTR or FETCHR\_ARRAY modes, i.e. a string suitable for display purposes. For BLOB types, the representation will be the same as the storage format, in which case you'll need to copy the value from the \$map() to a variable of suitable type/size for practical use. For string values, ordmap(varstr;varx) is the same as ordmap(varstr;varstr) so no conversion is needed. Note that if the query result contains unnamed fields, such as expressions, a pseudo column name of the form "expr-#" will be assigned as the key to avoid having multiple result fields with the same key. Also note that the map is not automatically cleared before each SQLOP\_FETCH\_ROW operation. Typically this is not an issue since each row in the result set will have the same number of fields, but in most cases, the application may need to explicitly issue a .CLEAR \$map() statement prior to fetching the first row so as to eliminate any map entries left over from a prior query.

_ds \[DYNSTRUCT, out\]_

(fifth syntax form)  A DYNSTRUCT initialized and bound to a structure definition to receive the returned row. See [SQLOP\_FETCH\_ROW into a DYNSTRUCT](fetchrowintoadynstruct.md) for additional details.

**Notes**

If the QRYF\_NOSTORE flags was used for the query, you must keep issuing SQLOP\_FETCH\_ROW requests (preferably without delay) until info2 comes back as 0. 

**See Also**

•	[SQLOP\_FETCH\_GRID](sqlop_fetch_grid.md)

**History**

2025 April, A-Shell 7.0.1771:  Add support for the variation [SQLOP\_FETCH\_ROW into a DYNSTRUCT](fetchrowintoadynstruct.md).

2023 April, ashodbc connector 1.6.120 \& ashmysql connector 1.6.146:  FETCH\_NULLS added.

2018 February, A-Shell 6.5.1630, ashmysql connector version 1.4.142:  Implement the \$map() option (fourth syntax form). Requires A-Shell 6.5.1630.0+.