begriffs open source - ai-pg/blob - full-docs/src/sgml/html/ecpg-sql-get-descriptor.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>GET DESCRIPTOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE" /><link rel="next" href="ecpg-sql-open.html" title="OPEN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">GET DESCRIPTOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="34.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">34.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-open.html" title="OPEN">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-GET-DESCRIPTOR"><div class="titlepage"></div><div class="refnamediv"><h2>GET DESCRIPTOR</h2><p>GET DESCRIPTOR — get information from an SQL descriptor area</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 GET DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em> <em class="replaceable"><code>:cvariable</code></em> = <em class="replaceable"><code>descriptor_header_item</code></em> [, ... ]
   4 GET DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em> VALUE <em class="replaceable"><code>column_number</code></em> <em class="replaceable"><code>:cvariable</code></em> = <em class="replaceable"><code>descriptor_item</code></em> [, ... ]
   5 </pre></div><div class="refsect1" id="id-1.7.5.20.11.3"><h2>Description</h2><p>
   6      <code class="command">GET DESCRIPTOR</code> retrieves information about a
   7      query result set from an SQL descriptor area and stores it into
   8      host variables.  A descriptor area is typically populated
   9      using <code class="command">FETCH</code> or <code class="command">SELECT</code>
  10      before using this command to transfer the information into host
  11      language variables.
  12     </p><p>
  13      This command has two forms: The first form retrieves
  14      descriptor <span class="quote">“<span class="quote">header</span>”</span> items, which apply to the result
  15      set in its entirety.  One example is the row count.  The second
  16      form, which requires the column number as additional parameter,
  17      retrieves information about a particular column.  Examples are
  18      the column name and the actual column value.
  19     </p></div><div class="refsect1" id="id-1.7.5.20.11.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt id="ECPG-SQL-GET-DESCRIPTOR-DESCRIPTOR-NAME"><span class="term"><em class="replaceable"><code>descriptor_name</code></em></span> <a href="#ECPG-SQL-GET-DESCRIPTOR-DESCRIPTOR-NAME" class="id_link">#</a></dt><dd><p>
  20         A descriptor name.
  21        </p></dd><dt id="ECPG-SQL-GET-DESCRIPTOR-DESCRIPTOR-HEADER-ITEM"><span class="term"><em class="replaceable"><code>descriptor_header_item</code></em></span> <a href="#ECPG-SQL-GET-DESCRIPTOR-DESCRIPTOR-HEADER-ITEM" class="id_link">#</a></dt><dd><p>
  22         A token identifying which header information item to retrieve.
  23         Only <code class="literal">COUNT</code>, to get the number of columns in the
  24         result set, is currently supported.
  25        </p></dd><dt id="ECPG-SQL-GET-DESCRIPTOR-COLUMN-NUMBER"><span class="term"><em class="replaceable"><code>column_number</code></em></span> <a href="#ECPG-SQL-GET-DESCRIPTOR-COLUMN-NUMBER" class="id_link">#</a></dt><dd><p>
  26         The number of the column about which information is to be
  27         retrieved.  The count starts at 1.
  28        </p></dd><dt id="ECPG-SQL-GET-DESCRIPTOR-DESCRIPTOR-ITEM"><span class="term"><em class="replaceable"><code>descriptor_item</code></em></span> <a href="#ECPG-SQL-GET-DESCRIPTOR-DESCRIPTOR-ITEM" class="id_link">#</a></dt><dd><p>
  29         A token identifying which item of information about a column
  30         to retrieve.  See <a class="xref" href="ecpg-descriptors.html#ECPG-NAMED-DESCRIPTORS" title="34.7.1. Named SQL Descriptor Areas">Section 34.7.1</a> for
  31         a list of supported items.
  32        </p></dd><dt id="ECPG-SQL-GET-DESCRIPTOR-CVARIABLE"><span class="term"><em class="replaceable"><code>cvariable</code></em></span> <a href="#ECPG-SQL-GET-DESCRIPTOR-CVARIABLE" class="id_link">#</a></dt><dd><p>
  33         A host variable that will receive the data retrieved from the
  34         descriptor area.
  35        </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.11.5"><h2>Examples</h2><p>
  36      An example to retrieve the number of columns in a result set:
  37 </p><pre class="programlisting">
  38 EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
  39 </pre><p>
  40     </p><p>
  41      An example to retrieve a data length in the first column:
  42 </p><pre class="programlisting">
  43 EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
  44 </pre><p>
  45     </p><p>
  46      An example to retrieve the data body of the second column as a
  47      string:
  48 </p><pre class="programlisting">
  49 EXEC SQL GET DESCRIPTOR d VALUE 2 :d_data = DATA;
  50 </pre><p>
  51     </p><p>
  52      Here is an example for a whole procedure of
  53      executing <code class="literal">SELECT current_database();</code> and showing the number of
  54      columns, the column data length, and the column data:
  55 </p><pre class="programlisting">
  56 int
  57 main(void)
  58 {
  59 EXEC SQL BEGIN DECLARE SECTION;
  60     int  d_count;
  61     char d_data[1024];
  62     int  d_returned_octet_length;
  63 EXEC SQL END DECLARE SECTION;
  64
  65     EXEC SQL CONNECT TO testdb AS con1 USER testuser;
  66     EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
  67     EXEC SQL ALLOCATE DESCRIPTOR d;
  68
  69     /* Declare, open a cursor, and assign a descriptor to the cursor  */
  70     EXEC SQL DECLARE cur CURSOR FOR SELECT current_database();
  71     EXEC SQL OPEN cur;
  72     EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;
  73
  74     /* Get a number of total columns */
  75     EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
  76     printf("d_count                 = %d\n", d_count);
  77
  78     /* Get length of a returned column */
  79     EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
  80     printf("d_returned_octet_length = %d\n", d_returned_octet_length);
  81
  82     /* Fetch the returned column as a string */
  83     EXEC SQL GET DESCRIPTOR d VALUE 1 :d_data = DATA;
  84     printf("d_data                  = %s\n", d_data);
  85
  86     /* Closing */
  87     EXEC SQL CLOSE cur;
  88     EXEC SQL COMMIT;
  89
  90     EXEC SQL DEALLOCATE DESCRIPTOR d;
  91     EXEC SQL DISCONNECT ALL;
  92
  93     return 0;
  94 }
  95 </pre><p>
  96      When the example is executed, the result will look like this:
  97 </p><pre class="screen">
  98 d_count                 = 1
  99 d_returned_octet_length = 6
 100 d_data                  = testdb
 101 </pre><p>
 102     </p></div><div class="refsect1" id="id-1.7.5.20.11.6"><h2>Compatibility</h2><p>
 103      <code class="command">GET DESCRIPTOR</code> is specified in the SQL standard.
 104     </p></div><div class="refsect1" id="id-1.7.5.20.11.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">ALLOCATE DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">SET DESCRIPTOR</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="34.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-open.html" title="OPEN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">EXECUTE IMMEDIATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> OPEN</td></tr></table></div></body></html>