begriffs open source - ai-pg/blob - full-docs/txt/ecpg-sql-get-descriptor.txt

   1
   2 GET DESCRIPTOR
   3
   4    GET DESCRIPTOR — get information from an SQL descriptor area
   5
   6 Synopsis
   7
   8 GET DESCRIPTOR descriptor_name :cvariable = descriptor_header_item [, ... ]
   9 GET DESCRIPTOR descriptor_name VALUE column_number :cvariable = descriptor_item
  10 [, ... ]
  11
  12 Description
  13
  14    GET DESCRIPTOR retrieves information about a query result set from an
  15    SQL descriptor area and stores it into host variables. A descriptor
  16    area is typically populated using FETCH or SELECT before using this
  17    command to transfer the information into host language variables.
  18
  19    This command has two forms: The first form retrieves descriptor
  20    “header” items, which apply to the result set in its entirety. One
  21    example is the row count. The second form, which requires the column
  22    number as additional parameter, retrieves information about a
  23    particular column. Examples are the column name and the actual column
  24    value.
  25
  26 Parameters
  27
  28    descriptor_name #
  29           A descriptor name.
  30
  31    descriptor_header_item #
  32           A token identifying which header information item to retrieve.
  33           Only COUNT, to get the number of columns in the result set, is
  34           currently supported.
  35
  36    column_number #
  37           The number of the column about which information is to be
  38           retrieved. The count starts at 1.
  39
  40    descriptor_item #
  41           A token identifying which item of information about a column to
  42           retrieve. See Section 34.7.1 for a list of supported items.
  43
  44    cvariable #
  45           A host variable that will receive the data retrieved from the
  46           descriptor area.
  47
  48 Examples
  49
  50    An example to retrieve the number of columns in a result set:
  51 EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
  52
  53    An example to retrieve a data length in the first column:
  54 EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENG
  55 TH;
  56
  57    An example to retrieve the data body of the second column as a string:
  58 EXEC SQL GET DESCRIPTOR d VALUE 2 :d_data = DATA;
  59
  60    Here is an example for a whole procedure of executing SELECT
  61    current_database(); and showing the number of columns, the column data
  62    length, and the column data:
  63 int
  64 main(void)
  65 {
  66 EXEC SQL BEGIN DECLARE SECTION;
  67     int  d_count;
  68     char d_data[1024];
  69     int  d_returned_octet_length;
  70 EXEC SQL END DECLARE SECTION;
  71
  72     EXEC SQL CONNECT TO testdb AS con1 USER testuser;
  73     EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL CO
  74 MMIT;
  75     EXEC SQL ALLOCATE DESCRIPTOR d;
  76
  77     /* Declare, open a cursor, and assign a descriptor to the cursor  */
  78     EXEC SQL DECLARE cur CURSOR FOR SELECT current_database();
  79     EXEC SQL OPEN cur;
  80     EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;
  81
  82     /* Get a number of total columns */
  83     EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
  84     printf("d_count                 = %d\n", d_count);
  85
  86     /* Get length of a returned column */
  87     EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_
  88 LENGTH;
  89     printf("d_returned_octet_length = %d\n", d_returned_octet_length);
  90
  91     /* Fetch the returned column as a string */
  92     EXEC SQL GET DESCRIPTOR d VALUE 1 :d_data = DATA;
  93     printf("d_data                  = %s\n", d_data);
  94
  95     /* Closing */
  96     EXEC SQL CLOSE cur;
  97     EXEC SQL COMMIT;
  98
  99     EXEC SQL DEALLOCATE DESCRIPTOR d;
 100     EXEC SQL DISCONNECT ALL;
 101
 102     return 0;
 103 }
 104
 105    When the example is executed, the result will look like this:
 106 d_count                 = 1
 107 d_returned_octet_length = 6
 108 d_data                  = testdb
 109
 110 Compatibility
 111
 112    GET DESCRIPTOR is specified in the SQL standard.
 113
 114 See Also
 115
 116    ALLOCATE DESCRIPTOR, SET DESCRIPTOR