esp_subscribe

Connects to an instance of the Event Stream Processor via the Command and Control and Gateway interfaces and subscribes to transaction streaming data. The received records are converted to XML (or optionally delimited format) and written to the standard output.

Syntax

esp_subscribe  -p host:port/workspace/project [OPTION...]

Required Arguments

-p host:port/workspace/project – Together, the host:port/workspace/project arguments specify the URI to connect to the ESP Server (cluster manager). For example, if you have started your ESP cluster server on port 19011 of your local machine, and you are running a project called prj1 in the default workspace, specify -p as: -p localhost:19011/default/prj1

Options

-A – Adds subscriptions to this conn_handle connection handle. esp_subscribe exits after processing the request.
-b – Connects to the server in reverse byte order of the machine architecture on which esp_subscribe is running.
-B – Drops the connection if it supplies data faster than esp_subscribe can absorb it.
-c user[:password] – Authenticates with a user ID and, optionally, a password. If the password is not provided, the user is prompted for the password. If the Event Stream Processor successfully authenticates with these credentials, the connection is maintained, otherwise, the Event Stream Processor immediately closes the connection.
-d separator – Puts the subscribe client into delimited output mode and uses the specified separator as the delimiting character.
-D conn_handle – Deletes subscriptions to this conn_handle connection handle. This esp_subscribe exits after processing the request.
-e – Encrypts traffic with the Event Stream Processor via openSSL sockets.
Note: Ensure that the Event Stream Processor is started in encrypted mode to use this option.
-f configfile – Specifies the CCX configuration file that describes the location data that will be read via standard input.
-F schemafile – Sets the XML schema file. The default schema file is $ESP_HOME/etc/Platform.xsd.
-g gateway_host – Uses the specified gateway host rather than the host returned from the get_gateway() call.
-h – Prints a list of possible options on the screen along with a brief explanation for each option.
-H – Subscribes to the Event Stream Processor heartbeat messages, (sID,Qd), ... (sID,qD).
-i streamId[,...] – Specifies one or more streams to subscribe to, using each stream's integer handle.
-k privateRsaKeyFile – Performs authentication by using the RSA private key file mechanism instead of password authentication. The privateRsaKeyFile must specify the pathname of the private RSA key file.
Note: Ensure that the ESP Server has been started with the -k option specifying the directory in which to store the RSA keys.
-l – Puts the subscribe client into lossy mode, where data is shed (lost) if the subscribe client cannot keep up with the streaming data produced by the Event Stream Processor.
-L N – Specifies a pulsed subscription, where records are collected, and delivered every N seconds.
-m conn_name – Sets a symbolic tag name for the connection. This allows esp_subscribe to look up the connection easily in the _ESP_Clients metadata stream. The tag is stored in the conn_tag field. To kill the connections by tag name, use the esp_client to input the kill every command.
-M number – Specifies the number of multiple connections to establish (all for the same streams).
-P precision – Sets the number of decimal places in output for FLOAT. Default value is 6 decimal places.
-Q SQL statement – Specifies an SQL select statement to apply to outbound records.
The outbound records are marked with insert, update, and delete, even when the SQL statement might not include the key columns of the stream. To give insert/update/delete meaning in these cases, you can specify a special column ESP_SEQNO. For example, the statement select *, ESP_SEQNO from Vwap order by Price automatically fills in values for the ESP_SEQNO column. With order by, the ESP_SEQNO reflects the ordering of the rows in the output set.
-R – Subscribes with shine through (if possible) so that when an update contains no new data for previously received fields, information for those fields is retained.
-s stream_1 [,...,stream_N] – Specifies one or more streams using the logical name of each stream, to subscribe to snapshot the table, (exit after the SYNC records are received).
-S – Takes a snapshot of the table: receive the initial state of the stream and exit immediately afterward.
-t – Puts the subscribe client into transaction-only mode, so it receives transactional updates to streams upon connection to the Event Stream Processor, rather than the initial state of the streams.
-T – Prints out transaction block begin <block>, and transaction block end </block> markers.
-v – Reports special events (start synchronization, end synchronization, or stream exit).
-W baseDrainTimeout – Sets the time limit, in milliseconds, that this client has to read all base data from the subscribe stream before being dropped. When this parameter is not specified, the default value is 8,000 milliseconds or 8 seconds.
-X – Exits the process after all the subscriptions exit, even if the Event Stream Processor does not drop the connection.
-z queueSize – Sets the subscriber queue size to queueSize, of the output gateway connection. This queue front ends the connected socket, buffering data to be delivered to the client. The minimum value for the queueSize is 1000 records. The default value is 8192 records.
-V – Prints the esp_subscribe utility version.

Examples

to subscribe to two streams named PreprocessorTransactions and DebitMovements, of default/prj1 project running on a cluster manager on localhost:11180, printing all stream data in XML format on standard output:

esp_subscribe -c user:pass -s PreprocessorTransactions,DebitMovements -p localhost:11180/default/prj1

To subscribe to two streams named PreprocessorTransactions and DebitMovements, printing all stream data in pipe-separated format on standard output:

esp_subscribe -c user:pass -d "|" -s PreprocessorTransactions,DebitMovements -p localhost:11180/default/prj1

To subscribe to one stream named PreprocessorTransactions that has data generated by a server running on a machine named HOST (which has differing byte order than the machine that subscribe is running on) and print all stream data in pipe-separated format on standard output:

esp_subscribe -c user:pass -d "|" -s PreprocessorTransactions -p localhost:11180/default/prj1

To subscribe to one stream named baseInput and apply a SQL statement:

esp_subscribe -c user:pass -Q   "select intData_1, 10*intData_1+dblData_1 from baseInput where intData_1 > 20" -p localhost:11180/default/prj1

To subscribe to an error stream, named ErrorStream:

esp_subscribe -p localhost:11180/default/prj1 -Q "select e.*, recordDataToString(e.sourceStreamName, e.errorRecord ) errorRecord from ErrorStream e"