NAME

hub_table_SQL - obtain table data as SQL, optionally open safe subscription(s)

SYNOPSIS

package require Humelib
hub_table_SQL tablelist {want_reply 1} {want_send 0} {sendto_box {}} {subname {}} {submaxcount 100}

DESCRIPTION

Use hub_table_SQL to obtain the table create statement and current data of a table (or tables) as a list of SQL statements. The command can optionally open a subscription to future changes. The data is read and the subscription is established without possible intervening change of the table data.

When a subscription is opened, the functionality is similar to opening a data subscription using the CREATE and SYNC options, but the efficiency can be greater since the create statement and current data is obtained as one large message instead of a flurry of small SQL messages. Also, the command integrates use of the hub_safe_sub_set command to provide safety checking for runaway subscriptions.

There is an option to obtain the SQL statements as a returned result, or to have it sent as the first message to a specified mailbox.

Command arguments:

tablelist
One of more SQL table names.
want_reply
If 1, a list of SQL statements is the return value of the procedure. Defaults to 1. If 0, the return value of the procedure is:
  1. if subscriptions are opened, the reply from opening the last subscription
  2. else if want_send is true, the message, "data sent to $sendto_box"
  3. else the message, "no observable output!"
want_send
If 1, data is sent to the sendto_box as one big message in a format that is compatible with the usual processing of DMH messages as SQL commands. Defaults to 0.
subname
Optionally, a unique name for the subscription(s), if a subscription is to be opened. The default value of an empty string means that subscriptions are not opened.
sendto_box
Optionally, a mailbox name for the current data and/or the subscription messages if a subscription is to be opened. This should be a mailbox that handles received messages as SQL commands. An example mailbox setup would be,
"mbx whenmsg MYBOX_SQL mbx_SQL"
Running the hub application script is also a means of setting up a mailbox to process received messages as SQL commands.
submaxcount
If both subname and sendto_box values are non-blank a subscription is opened. The hub_safe_sub logic is used to close the subscription if greater than an expected number of messages are seen in the mailbox during a polling check. The optional argument, submaxcount, can set the limit.

The command is part of the Humelib package and it exists in the global namespace.

EXAMPLE

# at the server process
package require Humelib

  # at the client process
  if { ![hub_table_exists dc_user] } {
      set tablelist {dc_user dc_user_group dc_user_privilege}
      set cmd [list eval hub_table_SQL $tablelist 1 0 $dc_ui(MB_SQL) $dc_ui(MB_SQL)]
      # this gives us the existing data as an efficient big reply
      # and opens subscriptions for future changes
      # and also registers us for safe subscription checking
      set reply [dc_ui_hub_xact $cmd $dc_ui(dmh)]
      foreach stmt $reply { SQL $stmt }
      mbx whenmsg $dc_ui(MB_SQL) mbx_SQL
      }

AUTHOR

Hume Integration Software, www.hume.com

SEE ALSO

DMH  hub_safe_sub_set  SQL open  SQL select

KEYWORDS

datahub, DMH, open, select, subscription