I686LINUX/util/I686LINUX/doc/postgresql/html/pgtcl-pgexecute.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >pg_execute</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="pgtcl Command Reference"
  16 HREF="libpgtcl-ref.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="pg_select"
  19 HREF="pgtcl-pgselect.html"><LINK
  20 REL="NEXT"
  21 TITLE="pg_listen"
  22 HREF="pgtcl-pglisten.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="pgtcl-pgselect.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="pgtcl-pgselect.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 ></TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="pgtcl-pglisten.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="pgtcl-pglisten.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><H1
  91 ><A
  92 NAME="PGTCL-PGEXECUTE"
  93 ></A
  94 >pg_execute</H1
  95 ><DIV
  96 CLASS="REFNAMEDIV"
  97 ><A
  98 NAME="AEN22689"
  99 ></A
 100 ><H2
 101 >Name</H2
 102 >pg_execute&nbsp;--&nbsp;send a query and optionally loop over the results<A
 103 NAME="IX-PGTCL-PGEXECUTE-2"
 104 ></A
 105 ></DIV
 106 ><DIV
 107 CLASS="REFSYNOPSISDIV"
 108 ><A
 109 NAME="AEN22694"
 110 ></A
 111 ><H2
 112 >Synopsis</H2
 113 ><PRE
 114 CLASS="SYNOPSIS"
 115 >pg_execute ?<SPAN
 116 CLASS="OPTIONAL"
 117 >-array <VAR
 118 CLASS="PARAMETER"
 119 >arrayVar</VAR
 120 ></SPAN
 121 >? ?<SPAN
 122 CLASS="OPTIONAL"
 123 >-oid <VAR
 124 CLASS="PARAMETER"
 125 >oidVar</VAR
 126 ></SPAN
 127 >? <VAR
 128 CLASS="PARAMETER"
 129 >conn</VAR
 130 > <VAR
 131 CLASS="PARAMETER"
 132 >commandString</VAR
 133 > ?<SPAN
 134 CLASS="OPTIONAL"
 135 ><VAR
 136 CLASS="PARAMETER"
 137 >procedure</VAR
 138 ></SPAN
 139 >?</PRE
 140 ></DIV
 141 ><DIV
 142 CLASS="REFSECT1"
 143 ><A
 144 NAME="AEN22704"
 145 ></A
 146 ><H2
 147 >Description</H2
 148 ><P
 149 >   <CODE
 150 CLASS="FUNCTION"
 151 >pg_execute</CODE
 152 > submits a command to the
 153    <SPAN
 154 CLASS="PRODUCTNAME"
 155 >PostgreSQL</SPAN
 156 > server.
 157   </P
 158 ><P
 159 >   If the command is not a <TT
 160 CLASS="COMMAND"
 161 >SELECT</TT
 162 > statement, the
 163    number of rows affected by the command is returned.  If the command
 164    is an <TT
 165 CLASS="COMMAND"
 166 >INSERT</TT
 167 > statement and a single row is
 168    inserted, the OID of the inserted row is stored in the variable
 169    <VAR
 170 CLASS="PARAMETER"
 171 >oidVar</VAR
 172 > if the optional <VAR
 173 CLASS="PARAMETER"
 174 >-oid</VAR
 175 >
 176    argument is supplied.
 177   </P
 178 ><P
 179 >   If the command is a <TT
 180 CLASS="COMMAND"
 181 >SELECT</TT
 182 > statement, then, for
 183    each row in the result, the row values are stored in the
 184    <VAR
 185 CLASS="PARAMETER"
 186 >arrayVar</VAR
 187 > variable, if supplied, using the
 188    column names as the array indices, else in variables named by the
 189    column names, and then the optional
 190    <VAR
 191 CLASS="PARAMETER"
 192 >procedure</VAR
 193 > is executed if supplied.
 194    (Omitting the <VAR
 195 CLASS="PARAMETER"
 196 >procedure</VAR
 197 > probably makes sense
 198    only if the query will return a single row.)  The number of rows
 199    selected is returned.
 200   </P
 201 ><P
 202 >   The <VAR
 203 CLASS="PARAMETER"
 204 >procedure</VAR
 205 > can use the Tcl commands
 206    <TT
 207 CLASS="LITERAL"
 208 >break</TT
 209 >, <TT
 210 CLASS="LITERAL"
 211 >continue</TT
 212 >, and
 213    <TT
 214 CLASS="LITERAL"
 215 >return</TT
 216 > with the expected behavior.  Note that if
 217    the <VAR
 218 CLASS="PARAMETER"
 219 >procedure</VAR
 220 > executes
 221    <TT
 222 CLASS="LITERAL"
 223 >return</TT
 224 >, then <CODE
 225 CLASS="FUNCTION"
 226 >pg_execute</CODE
 227 >
 228    does not return the number of affected rows.
 229   </P
 230 ><P
 231 >   <CODE
 232 CLASS="FUNCTION"
 233 >pg_execute</CODE
 234 > is a newer function which provides
 235    a superset of the features of <CODE
 236 CLASS="FUNCTION"
 237 >pg_select</CODE
 238 > and
 239    can replace <CODE
 240 CLASS="FUNCTION"
 241 >pg_exec</CODE
 242 > in many cases where access
 243    to the result handle is not needed.
 244   </P
 245 ><P
 246 >   For server-handled errors, <CODE
 247 CLASS="FUNCTION"
 248 >pg_execute</CODE
 249 > will
 250    throw a Tcl error and return a two-element list.  The first element
 251    is an error code, such as <TT
 252 CLASS="LITERAL"
 253 >PGRES_FATAL_ERROR</TT
 254 >, and
 255    the second element is the server error text.  For more serious
 256    errors, such as failure to communicate with the server,
 257    <CODE
 258 CLASS="FUNCTION"
 259 >pg_execute</CODE
 260 > will throw a Tcl error and return
 261    just the error message text.
 262   </P
 263 ></DIV
 264 ><DIV
 265 CLASS="REFSECT1"
 266 ><A
 267 NAME="AEN22735"
 268 ></A
 269 ><H2
 270 >Arguments</H2
 271 ><P
 272 ></P
 273 ><DIV
 274 CLASS="VARIABLELIST"
 275 ><DL
 276 ><DT
 277 ><VAR
 278 CLASS="OPTION"
 279 >-array <VAR
 280 CLASS="PARAMETER"
 281 >arrayVar</VAR
 282 ></VAR
 283 ></DT
 284 ><DD
 285 ><P
 286 >      Specifies the name of an array variable where result rows are
 287       stored, indexed by the column names.  This is ignored if
 288       <VAR
 289 CLASS="PARAMETER"
 290 >commandString</VAR
 291 > is not a <TT
 292 CLASS="COMMAND"
 293 >SELECT</TT
 294 >
 295       statement.
 296      </P
 297 ></DD
 298 ><DT
 299 ><VAR
 300 CLASS="OPTION"
 301 >-oid <VAR
 302 CLASS="PARAMETER"
 303 >oidVar</VAR
 304 ></VAR
 305 ></DT
 306 ><DD
 307 ><P
 308 >      Specifies the name of a variable into which the OID from an
 309       <TT
 310 CLASS="COMMAND"
 311 >INSERT</TT
 312 > statement will be stored.
 313      </P
 314 ></DD
 315 ><DT
 316 ><VAR
 317 CLASS="PARAMETER"
 318 >conn</VAR
 319 ></DT
 320 ><DD
 321 ><P
 322 >      The handle of the connection on which to execute the command.
 323      </P
 324 ></DD
 325 ><DT
 326 ><VAR
 327 CLASS="PARAMETER"
 328 >commandString</VAR
 329 ></DT
 330 ><DD
 331 ><P
 332 >      The SQL command to execute.
 333      </P
 334 ></DD
 335 ><DT
 336 ><VAR
 337 CLASS="PARAMETER"
 338 >procedure</VAR
 339 ></DT
 340 ><DD
 341 ><P
 342 >      Optional procedure to execute for each result row of a
 343       <TT
 344 CLASS="COMMAND"
 345 >SELECT</TT
 346 > statement.
 347      </P
 348 ></DD
 349 ></DL
 350 ></DIV
 351 ></DIV
 352 ><DIV
 353 CLASS="REFSECT1"
 354 ><A
 355 NAME="AEN22769"
 356 ></A
 357 ><H2
 358 >Return Value</H2
 359 ><P
 360 >   The number of rows affected or returned by the command.
 361   </P
 362 ></DIV
 363 ><DIV
 364 CLASS="REFSECT1"
 365 ><A
 366 NAME="AEN22772"
 367 ></A
 368 ><H2
 369 >Examples</H2
 370 ><P
 371 >   In the following examples, error checking with
 372    <TT
 373 CLASS="LITERAL"
 374 >catch</TT
 375 > has been omitted for clarity.
 376   </P
 377 ><P
 378 >   Insert a row and save the OID in <VAR
 379 CLASS="VARNAME"
 380 >result_oid</VAR
 381 >:
 382 </P><PRE
 383 CLASS="PROGRAMLISTING"
 384 >pg_execute -oid result_oid $pgconn "INSERT INTO mytable VALUES (1);"</PRE
 385 ><P>
 386   </P
 387 ><P
 388 >   Print the columns <TT
 389 CLASS="LITERAL"
 390 >item</TT
 391 > and <TT
 392 CLASS="LITERAL"
 393 >value</TT
 394 > from each
 395    row:
 396 </P><PRE
 397 CLASS="PROGRAMLISTING"
 398 >pg_execute -array d $pgconn "SELECT item, value FROM mytable;" {
 399     puts "Item=$d(item) Value=$d(value)"
 400 }</PRE
 401 ><P>
 402   </P
 403 ><P
 404 >   Find the maximum and minimum values and store them in
 405    <TT
 406 CLASS="LITERAL"
 407 >$s(max)</TT
 408 > and <TT
 409 CLASS="LITERAL"
 410 >$s(min)</TT
 411 >:
 412 </P><PRE
 413 CLASS="PROGRAMLISTING"
 414 >pg_execute -array s $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"</PRE
 415 ><P>
 416   </P
 417 ><P
 418 >   Find the maximum and minimum values and store them in
 419    <TT
 420 CLASS="LITERAL"
 421 >$max</TT
 422 > and <TT
 423 CLASS="LITERAL"
 424 >$min</TT
 425 >:
 426 </P><PRE
 427 CLASS="PROGRAMLISTING"
 428 >pg_execute $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"</PRE
 429 ><P>
 430   </P
 431 ></DIV
 432 ><DIV
 433 CLASS="NAVFOOTER"
 434 ><HR
 435 ALIGN="LEFT"
 436 WIDTH="100%"><TABLE
 437 SUMMARY="Footer navigation table"
 438 WIDTH="100%"
 439 BORDER="0"
 440 CELLPADDING="0"
 441 CELLSPACING="0"
 442 ><TR
 443 ><TD
 444 WIDTH="33%"
 445 ALIGN="left"
 446 VALIGN="top"
 447 ><A
 448 HREF="pgtcl-pgselect.html"
 449 ACCESSKEY="P"
 450 >Prev</A
 451 ></TD
 452 ><TD
 453 WIDTH="34%"
 454 ALIGN="center"
 455 VALIGN="top"
 456 ><A
 457 HREF="index.html"
 458 ACCESSKEY="H"
 459 >Home</A
 460 ></TD
 461 ><TD
 462 WIDTH="33%"
 463 ALIGN="right"
 464 VALIGN="top"
 465 ><A
 466 HREF="pgtcl-pglisten.html"
 467 ACCESSKEY="N"
 468 >Next</A
 469 ></TD
 470 ></TR
 471 ><TR
 472 ><TD
 473 WIDTH="33%"
 474 ALIGN="left"
 475 VALIGN="top"
 476 >pg_select</TD
 477 ><TD
 478 WIDTH="34%"
 479 ALIGN="center"
 480 VALIGN="top"
 481 ><A
 482 HREF="libpgtcl-ref.html"
 483 ACCESSKEY="U"
 484 >Up</A
 485 ></TD
 486 ><TD
 487 WIDTH="33%"
 488 ALIGN="right"
 489 VALIGN="top"
 490 >pg_listen</TD
 491 ></TR
 492 ></TABLE
 493 ></DIV
 494 ></BODY
 495 ></HTML
 496 >