Using the Broker ID in Applications

The broker ID describes the connection from a client or server to a broker instance. It indicates the protocol or transport method to be used and where the broker is located. We distinguish two styles of broker IDs: the URL-style broker ID and the transport-method-style broker ID.

The URL-style broker ID is the recommended style. Simple forms of this style are identical with the transport method style. For both styles, the syntax, values, defaults, examples, and restrictions are listed. This document describes the two styles of broker ID:

URL-style Broker ID

Syntax

The URL syntax is described in RFC1738 and related RFCs.

<protocol><host><port><parameter>
Element Description Permitted Values Default Notes
<protocol> The transport protocol. tcpip://, ssl://, http://, https://, or none; tcpip:// Not case-sensitive.
<host> The host where the broker operates. A valid host name. This may be a numerical IP address or a domain name. localhost For the syntax of the domain name, see RFC1034 (Domain Names - Concepts and Facilities).
<port> The port where the broker listens. a valid port number in the form ": n", where n is an integer.

Non-Java-based components:
The port is resolved by the domain name service (DNS) for all components. If the DNS cannot resolve the port, 1971 is used for TCP/IP and 1958 is used for SSL.

Java-based components:
The default depends on the protocol:

tcpip:// 1971
ssl:// 1958
http:// 80
https:// 443
 
<parameter> Parameters in the form 
?<parm1>&<parm2>&...
 The keys and the permitted values depend on the protocol. none See Examples of Parameters for Java-based Components.

Notes

Use the URL-style Broker ID for Java-based EntireX components such as

Examples

  • localhost

  • localhost:1971

  • tcpip://myhost.com:1971

  • tcpip://127.0.0.1:1971

  • ssl://localhost:22101?trust_store=C:\SoftwareAG\EntireX/etc/ExxCACert.jks&key_store=C:\SoftwareAG\EntireX/etc/ExxJavaAppCert.jks&key_passwd=ExxJavaAppCert

  • http://www.yourhost.com/servlets/tunnel

  • https://www.yourhost.com/servlets/tunnel

Examples of Parameters for Java-based Components

  • Socket Pooling
  • Compression

    • compresslevel=[0|1|2|3|4|5|6|7|8|9|DEFAULT_COMPRESSION|NO_COMPRESSION|BEST_SPEED|DEFLATED|BEST_COMPRESSION|N|Y]. Set the level of compression; N is mapped to NO_COMPRESSION; Y is mapped to 6; see Using Compression under Writing Advanced Applications - EntireX Java ACI

  • HTTP, HTTPS

    • checkheaders=[yes|no]. If yes: check HTTP headers

    • log=[yes|no]. If yes: enable tracing; see Using HTTP(S) Tunneling (EntireX Java ACI | Java Wrapper)

  • SSL

    • verify_client=[yes|no]. If yes: SSL client has to send certificate

    • verify_server=[yes|no]. If yes: verify that the host name of the SSL server is the common name of the certificate. The SSL server can be EntireX Broker Broker SSL Agent or Direct RPC in Integration Server (IS inbound). See:

Transport-method-style Broker ID

Transport methods TCP, SSL and NET are available. The transport method may be omitted, whereby certain rules apply. See Default Rules. The transport methods TCP and NET may be also combined. See Examples below.

Transport Method TCP

<host><port>:TCP

Element Description Permitted Values Default Notes
<host> The host where the broker operates. Valid host name consisting of a domain name or a numerical IP address. localhost  
<port> The port where the broker listens. Valid port number. 1971 The port is resolved by the domain name service (DNS). If the DNS cannot resolve the port, the default 1971 is used.

Transport Method SSL

<host><port>:SSL

Element Description Permitted Values Default Notes
<host> The host where the broker operates. Valid host name consisting of a domain name or a numerical IP address. localhost See Using SSL/TLS with EntireX Components.
<port> The port where the broker listens. Valid port number. 1958 The port is resolved by the domain name service (DNS). If the DNS cannot resolve the port, the default 1958 is used.

Transport Method NET (Entire Net-Work) under z/OS, BS2000 and z/VSE

<name><node>:[<svc>]:NET

Element Description Permitted Values Default Notes
<name> Sequence of letters Any sequence of letters is allowed. none  
<node> Sequence of digits A node number for Entire Net-Work or a database ID. The node number is required. none  
<svc> SVC number
z/OS, z/VSE SVCnnn, where nnn is a valid SVC number. SVC must be uppercase. When omitted, the default SVC number is used.
BS2000 Not applicable.
none The broker stub module you use determines whether the SVC number can be specified as part of the broker ID. See SVC Number for Broker Communication.

Examples

  • Myhost.com:65534:SSL

  • ETB024::TCP tells the broker to use TCP/IP. ETB024 will be used to look up the host TCP address. Because the port number is not specified, the broker ID ETB024 will be used by default to look up the port number.

  • ETB024:3800:TCP tells the broker to use TCP/IP. ETB024 will be used to look up the host TCP address. Because the port number is specified, no lookup for the port number takes place; 3800 is used directly for the port number.

  • ETB024::NET tells the broker to use Entire Net-Work. Under z/OS: this format is used if the SVC number must not be changed.

  • ETB024:SVC252:NET tells the broker to use Entire Net-Work, SVC number 252, as the preferred transport. This form applies to z/OS (due to the SVC number).

Default Rules

  • If broker ID does not specify a transport method, environment variable ETB_TRANSPORT is used.

  • If environment variable ETB_TRANSPORT is also not specified, TCP is used.

  • If the port number is not specified, 1971 is used for TCP and 1958 is used for SSL.

Technical Limitations