pg_listen

PG_LISTEN()	       PostgreSQL 7.4.19 Documentation		  PG_LISTEN()



NAME
       pg_listen  -  set  or  change a callback for asynchronous notification
       messages


SYNOPSIS
       pg_listen conn notifyName [callbackCommand]


DESCRIPTION
       pg_listen creates, changes, or cancels a request to listen  for	asyn-
       chronous	 notification  messages	 from  the  PostgreSQL server. With a
       callbackCommand parameter, the request is established, or the  command
       string  of  an already existing request is replaced. With no callback-
       Command parameter, a prior request is canceled.

       After a pg_listen request is established, the specified command string
       is  executed  whenever  a  notification message bearing the given name
       arrives from the server. This occurs when any PostgreSQL client appli-
       cation  issues  a  NOTIFY  command  referencing that name. The command
       string is executed from the Tcl idle loop. That	is  the	 normal	 idle
       state of an application written with Tk. In non-Tk Tcl shells, you can
       execute update or vwait to cause the idle loop to be entered.

       You should not invoke the SQL statements LISTEN or  UNLISTEN  directly
       when using pg_listen. pgtcl takes care of issuing those statements for
       you. But if you want to send a notification message  yourself,  invoke
       the SQL NOTIFY statement using pg_exec.

ARGUMENTS
       conn   The  handle  of the connection on which to listen for notifica-
	      tions.

       notifyName
	      The name of the notification condition to start or stop listen-
	      ing to.

       callbackCommand
	      If  present,  provides  the  command  string  to execute when a
	      matching notification arrives.

RETURN VALUE
       None



				  2008-01-03			  PG_LISTEN()