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 covers the following topics:

URL-style Broker ID
Transport-method-style Broker ID

URL-style Broker ID

The URL syntax is described in RFC1738 and related RFCs.

<protocol><host><port><parameter>

Element

Description

Permitted Values

Default

Note

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 default 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

Parameters in the form

?<parm1>&<parm2>&...

The keys and the permitted values depend on the protocol.

none

See Examples of Parameters.

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

Java Programming Language

poolsize=n (n: number of connections)
pooltimeout=n (n: number of seconds until timeout)
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
For http, https: checkheaders=[yes|no] (check http headers if yes)
For http, https: log=[yes|no] (enable tracing if yes)
For ssl: verify_client=[yes|no] (SSL client has to send certificate if yes)
For ssl: verify_server=[yes|no] (verify that the host name of the broker is the common name of the certificate, if yes.)

Other Programming Languages

For ssl: verify_client=[yes|no] (SSL client has to send certificate if yes)
For ssl: verify_server=[yes|no] (verify that the host name of the broker is the common name of the certificate if yes)
EntireX RPC Server under Windows / UNIX and SSL

You may use either the keyword SSL_file in the configuration file to specify parameters for SSL or use SSL://<host><port>?ssl_file=MySSLfile.
CICS RPC Server and SSL

Use the keyword SSL_file to specify the memory block with the parameters for SSL.
EntireX RPC under C and SSL

You may use either SSL://<host><port>?ssl_file=MySSLfile or specify parameters for SSL in the ERX structure ERX_CLIENT_IDENTIFICATION.

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
<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.	The default port is resolved by the domain name service (DNS). If the DNS cannot resolve the port, 1971 is used.

Transport Method SSL

<host><port>:SSL

Element	Description	Permitted Values	Default
<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.	The default port is resolved by the domain name service (DNS). If the DNS cannot resolve the port, 1958 is used.

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

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

Element

Description

Permitted Values

Default

<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	SVC`nnn`, where `nnn` is a valid SVC number. SVC must be uppercase. When omitted, the default SVC number is used.
BS2000/OSD	Not applicable.

none

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

Java

The transport method is not supported for the programming language Java and EntireX components based on the programming language Java such as Broker Agent, Java Wrapper, Java RPC Server, etc.

Other Programming Languages

For all programming languages and for EntireX components under z/OS it depends on the broker stub module used if the SVC number can be specified as part of the broker ID. See SVC Number for Broker Communication.
For all programming languages except Java and for EntireX components not based on the programming language Java - such as EntireX RPC Server under z/OS, CICS, UNIX and Windows, DCOM Wrapper, C Wrapper etc. - broker ID has a maximum length of 32 characters (unless the LONG-BROKER-ID is used; see LONG-BROKER-ID-LENGTH under Broker ACI Fields).
For the URL style the supported protocols are:
- tcpip://
- ssl://