EntireX Broker provides the following internal services:
These services are implemented internally; nothing has to be started or configured. You can use these services immediately after starting EntireX Broker.
With this command-line utility you can query the Broker for different types of information, generating an
output text string with basic formatting. This text output can be further
processed by script languages. etbinfo uses data descriptions called profiles
to control the type of data that is returned for a request. etbinfo is useful
for monitoring and administering EntireX Broker efficiently, for example how
many users can run concurrently and whether the number of specified message
containers is large enough. You can format your output
using a profile (recommended)
using a format string (this may be useful for ad hoc queries)
by other means external to the broker
This section covers the following topics:
In a Linux environment, run the command-line utility with
etbinfo. If the environment variable
LOGNAME is not set, you must use the -x option
(see below) to provide a user ID if the Broker is running with
EntireX Security. etbinfo is located in directory /<Install_Dir>/EntireX/bin.
The table below explains the command-line parameters. The format string and profile parameters are described in detail following the table. All entries in the Option column are case-sensitive.
| Option | Command-line Parameter | Req/ Opt |
Explanation | ||||
|---|---|---|---|---|---|---|---|
-b |
brokerid |
R | Broker identifier, for example
localhost:1971:TCP.
|
||||
-c |
class |
O | Class as selection criterion. | ||||
-C |
O | Create output with comma-separated values, suitable for input into a spreadsheet or other analysis tool. Any format string specified by means of format string or profile command-line parameters is ignored. | |||||
-d |
object |
R | Defines the information retrieved from broker. If an optional profile is provided, object and profile must match. See Table of Options and Profiles. | ||||
-e |
recv class |
O | Receiver's class name. This selection criterion is valid only for object PSF.
|
||||
-f |
Format String | O | Format string how you expect the output. See Profile. | ||||
-g |
recv service |
O | Receiver's service name. This selection criterion
is valid only for object PSF.
|
||||
-h |
help |
O | Prints help information. | ||||
-i |
convid |
O | Conversation ID as selection criterion. Only
valid for object CONVERSATION.
|
||||
-I |
conv type |
O | Conversation's type. | ||||
-j |
recv server |
O | Receiver's server name. This selection criterion
is valid only for object PSF.
|
||||
-k |
recv token |
O | Receiver's token. This selection criterion is
valid only for object PSF.
|
||||
-l |
level |
O | The amount of information displayed:
|
||||
-m |
recv userid |
O | Receiver's user ID. This selection criterion is
valid only for object PSF.
|
||||
-n |
server name |
O | Server name. This selection criterion is valid
only for the objects SERVER,
SERVICE or
CONVERSATION.
|
||||
-p |
profile |
O | Here you can specify a profile that defines the layout of the output. If provided, it must match the object. See Table of Options and Profiles. | ||||
-q |
puserid |
O | Physical user ID. This selection criterion is valid only for objects
CLIENT,
SERVER,
CONVERSATION.
Note: |
||||
-r |
sec |
O | Refresh information after seconds. | ||||
-s |
service |
O | Service. This selection criterion is valid only
for objects SERVER,
SERVICE or
CONVERSATION.
|
||||
-S |
"sslparms" |
O | When using SSL transport for Broker communication. See Using SSL/TLS. | ||||
-t |
token |
O | This selection criterion is valid only for
objects CLIENT,
SERVER,
SERVICE or
CONVERSATION.
|
||||
-u |
userid |
O | User ID. This selection criterion is only valid
for the display types CLIENT,
SERVER,
SERVICE or
CONVERSATION.
|
||||
-v |
UOW status |
O | Unit of work status. This selection criterion is
valid only for object PSF.
|
||||
-w |
UOW ID |
O | Unit of work ID. This selection criterion is
valid only for object PSF.
|
||||
-x |
userid |
O | User ID. For security purposes. | ||||
-y |
password |
O | Password. For security purposes. | ||||
-z |
token |
O | Used with userid to uniquely identify a caller to Broker Command and Information Services.
|
||||
--longmsg |
O | If an error occurs, delivers the long text of an error message, corresponding to Error Messages and Codes. Output is generated as with the exxmsg utility. See EXXMSG - Command-line Tool for Displaying Error Messages in the Error Messages and Codes documentation.
|
|||||
--external |
O | Reduces the output of SERVICE objects to external services. Broker-internal services are not displayed.
|
|||||
--internal |
O | Reduces the output of SERVICE objects to Broker-internal services. The external user-specific services are not displayed.
|
|||||
--pingrpc |
O | Executes an RPC ping to a specified RPC service. The parameters -c <class_name>, -n <server_name> and -s <service> are also required. If the service is running, return code 0 and a corresponding text are returned. If the service is not
running, a return code other than 0 is given.
|
|||||
--encrypted_password_from_stdin |
O | Encrypted password. See Using an Encrypted Password. | |||||
Profiles are provided for a more structured and improved understandable output. If you do not use the profile option or a format string, your output will be an unformatted list with all columns of that display type. To display specific columns, specify a profile (you can create your own) that includes only those columns.
Note:
The deprecated profiles are still delivered for compatibility reasons.
Option -d (object)
|
Option -p (profile)
|
Option -p (deprecated profile)
|
Information Object (see Information Reply Structures) |
|---|---|---|---|
BROKER |
broker2 |
broker |
BROKER-OBJECT |
CLIENT |
client2 |
client |
CLIENT-SERVER-PARTICIPANT-OBJECT |
CMDLOG-FILTER |
clogflt2 |
clogflt |
CMDLOG_FILTER-OBJECT |
CONVERSATION |
conv2 |
conv |
CONVERSATION-OBJECT |
NET |
net2 |
net |
NET-OBJECT |
POOL |
pool2 |
pool |
POOL-USAGE-OBJECT |
PSF |
psf2 |
psf |
PSF-OBJECT |
PSFADA |
psfada2 |
psfada |
PSFADA-OBJECT |
PSFCTREE |
psfctre2 |
psfctree |
PSFCTREE-OBJECT |
PSFDIV |
psfdiv2 |
psfdiv |
PSFDIV-OBJECT |
RESOURCE |
resourc2 |
resource |
RESOURCE-USAGE-OBJECT |
SECURITY |
securit2 |
security |
SECURITY-OBJECT |
SERVER |
server2 |
server |
CLIENT-SERVER-PARTICIPANT-OBJECT |
SERVICE |
service2 |
service |
SERVICE-OBJECT |
SSL |
ssl2 |
ssl |
SSL-OBJECT |
STATISTICS |
statist2 |
statis |
STATISTICS-OBJECT |
TCP |
tcp2 |
tcp |
TCP-OBJECT |
UOW-STATISTICS |
uowstat2 |
uowstat |
UOW-STATISTICS |
USER |
user2 |
user |
USER-OBJECT |
WORKER |
worker2 |
worker |
WORKER-OBJECT |
WORKER-USAGE |
wkrusag2 |
wkrusag |
WORKER-USAGE-OBJECT |
etbinfo supports an alternative method of passing command-line
parameters.
If the environment variable INF_ATTR is set, the content is interpreted
as a file name. If no command-line parameters are given, the command
etbinfo evaluates the content of the file.
Example:
-blocalhost:3930:TCP -dBROKER
If you do not use the profile option or a format string, your output will be an unformatted list with all columns of that display type. We recommend using the profiles described under Table of Options and Profiles.
On Linux, the profiles are contained in directory /<Install_Dir>/EntireX/etc and are named broker2.pro, client2.pro etc.
You can either delete the columns not required or copy the default profile and modify the order of the columns.
Ensure that the column names have a leading "%". Column names can be written in one line or on separate lines.
The output is always written side by side.
With profile parameters %DATE and %TIME you can provide a timestamp for the command-line query.
This example uses the default profile delivered with EntireX for object BROKER: broker2.pro:
etbinfo -b <brokerid> -d BROKER -p broker2.pro
The following list is displayed:
Broker Identification
Broker Information of BROKER-ID: ETB001
on Platform: PC Windows 10 Enterprise
SYSPLEX-NAME:
Process ID (PID): 11056
Thread ID (TID): 2B34
Running on Host: myHost
Version and License information
Product Version: EntireX 11.0.0.00
Highest supported API Version: x0D (Hex value)
Highest supported CIS Version: x0C (Hex value)
Active License (LICENSE-FILE): C:\SoftwareAG\Suite1015\EntireX\config\license.xml
SNMP Licensed: 01 (00: no, 01: yes)
Valid until (EXPIRATION): UNLIMITED
Configuration Details
Broker attribute file: C:\SoftwareAG\Suite1015\EntireX\config\etb\ETB001\ETB001.atr
Broker Log File: C:\SoftwareAG\Suite1015\EntireX\config\etb\ETB001\ETB001.log
Size of Broker Log File: 20616 BYTES
Security Type: 00
00: No Security
01: EntireX Security
02: Light
03: Other
This example uses profile my_service.pro you created yourself:
etbinfo -b ETB001 -d SERVICE -p my_service.pro
In this example, profile my_service.pro
contains: %4.4SERVERCLASS %SERVERNAME. The following list is displayed:
ACLA ASERVER BCLA BSERVER CCLA CSERVER
The format string, if specified, will override the use of a profile. The
format string is built like a printf() in C language.
The string must be enclosed in quotes. You can specify the columns by
using a "%" and the column name. The column name must contain
letters only. Numeric characters are not allowed. You can specify the length of
column output by using a format precision, as in the ANSI-C
printf() function. The column name must be followed by
a blank. For example:
etbinfo -b ETB001 -d BROKER -f "%12.12CPLATNAME %NUM-SERVER %NUM-CLIENT"
which produces the following output, for example:
MVS/SP 7.04 30 100
You can also use an arbitrary column separator, which can be any
character other than "%". You can use \n for a new
line in the output and \t for a tabulator in the format string or
profile. For example:
etbinfo -b ETB001 -d SERVER -f "UserID: %5.5USER-ID Token: %5.5TOKEN"
which produces:
UserID: HUGO Token: MYTOK UserID: EGON Token: UserID: HELMU Token: Helmu
If you want to structure your output a little more, you can operate with
the \n or \t character. For example:
etbinfo -b ETB001 -d SERVICE -f "Class:%5.5SERVER-CLASS \n\tName:%5.5SERVER-NAME \n\tService:%5.5SERVICE"
which produces:
Class:DATAB
Name:DB10
Service:Admin
Class:PRINT
Name:LPT1
Service:PRINT
...
You can also add a timestamp to the query:
etbinfo -b ETB001 -d BROKER -f "%DATE %TIME"
which produces:
2014-08-19 10:00:00.234
To set up SSL
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Specify the Broker ID, using one of the following styles:
URL Style, for example:
ssl://localhost:2010
Transport-method Style, for example:
ETB024:1609:SSL
If no port number is specified, port 1958 is used as default.
Specify SSL parameters with the option -s|S (lowercase for etbcmd; uppercase for etbinfo).
See SSL/TLS Parameters for SSL Clients.
Make sure the broker is prepared for SSL connections as well. See Running Broker with SSL/TLS Transport under z/OS | Linux | Windows.
You can encrypt a password and store this in a file. Specify this file instead of a cleartext password when you call a secure broker.
Notes:
etbnattr must be executed on the system where the encrypted password is used as input value.
To encrypt a password
Enter the command:
etbnattr --echo_password_only -w clear_text_passwordThe encrypted password is written to stdout.
Copy the password value to an empty file. (Ignore the prefix KEY-PASSWD-ENCRYPTED:.)
To specify the encrypted password from stdin
Enter the command:
etbinfo -x uid --encrypted_password_from_stdin < file
Where file is the file containing the encrypted password you created as described above. Example:
etbinfo -b localhost:1971 -d BROKER -x UID --encrypted_password_from_stdin < myPwd
With this command-line utility you can take actions - for example purge a unit of work, stop a server, shut down a Broker - against EntireX Broker.
In a Linux environment, run the command-line utility with etbcmd.
If the environment variable LOGNAME is not set, you must use the
-x option (see below) to provide a user ID if the
Broker is running with EntireX Security. etbcmd is located in the directory /<Install_Dir>/EntireX/bin.
The table below explains the command-line parameters. All entries in the Option column are case-sensitive.
| Command-line Parameter | Option | Parameter | Req/ Opt | Explanation | |
|---|---|---|---|---|---|
brokerid |
-b |
e.g. ETB001 |
R | Broker ID. | |
command |
-c |
|
R | Command to be performed. See List of Commands and Objects below. | |
object type |
-d |
|
R | The object type to be operated on. See List of Commands and Objects below.
Within EntireX Broker nomenclature, a participant is an application implicitly or explicitly logged on to the Broker as a
specific user.
|
|
-D |
collector brokerid |
O | For command SET-COLLECTOR only. If provided, sets the collector ID to the given collector broker ID.
|
||
-e |
errornumber |
O | Error number being trapped. | ||
-E |
O | Exclude attach servers from service shutdown. | |||
help |
-h |
O | Prints help information. | ||
class/server/service |
-n |
class/server/service |
O | Service triplet. | |
| option | -o |
|
O | Command option. | |
puserid |
-p |
puserid |
O | Physical User ID. For SERVER and PARTICIPANT objects only. This
must be a hex value.
|
|
sslparms |
-s |
SSL parameters | O | When using SSL transport for broker communication. See Using SSL/TLS. | |
seqno |
-S |
sequence number |
O | Sequence number of participant. | |
token |
-t |
token |
O | Token. For PARTICIPANT object only.
|
|
uowid |
-u |
uowid |
O | Unit of work ID. For PSF object only. | |
userid |
-U |
userid |
O | User ID. For PARTICIPANT object only.
|
|
secuserid |
-x |
userid |
O | User ID for security purposes. | |
transportid |
-X |
Transport ID | O | One of the following:COM|NET|SSL|Snn|TCP|Tnn. See table below.
|
|
secpassword |
-y |
password |
O | Password for security purposes. | |
--encrypted_password_from_stdin |
O | Encrypted password. See Using an Encrypted Password. | |||
--header |
O | Prints version header of this program. | |||
--host=HOST |
O | Host name of the participant. | |||
--longmsg |
O | Prints long error message. | |||
--pid=PID |
O | Process ID of the participant. | |||
--tid=TID |
O | Thread ID of the participant. | |||
This table explains the possible values for parameter transportid:
| Transport ID | Explanation |
|---|---|
COM |
all communicators |
NET |
NET transport communicator |
SSL |
all SSL communicators |
S00 |
SSL communicator 1 |
S01 |
SSL communicator 2 |
S02 |
SSL communicator 3 |
S03 |
SSL communicator 4 |
S04 |
SSL communicator 5 |
TCP |
all TCP/IP communicators |
T00 |
TCP/IP communicator 1 |
T01 |
TCP/IP communicator 2 |
T02 |
TCP/IP communicator 3 |
T03 |
TCP/IP communicator 4 |
T04 |
TCP/IP communicator 5 |
etbcmd supports an alternative method of passing command-line parameters.
If the environment variable CMD_ATTR is set, the content is interpreted
as a file name. If no command-line parameters are given, the command
etbcmd evaluates the content of the file.
Example:
-blocalhost:3930:TCP -cPRODUCE-STATISTICS -dBROKER
This table lists the available commands and the objects to which they can be applied.
| Command | Object | |||||||
|---|---|---|---|---|---|---|---|---|
BROKER |
CONVERSATION |
PARTICIPANT |
PSF |
SECURITY |
SERVER |
SERVICE |
TRANSPORT |
|
ALLOW-NEWUOWMSGS |
x | |||||||
APPMON-OFF |
x | |||||||
APPMON-ON |
x | |||||||
CLEAR-CMDLOG-FILTER |
x | |||||||
CONNECT-PSTORE |
x | |||||||
DISABLE-ACCOUNTING |
x | |||||||
DISABLE-CMDLOG-FILTER |
x | |||||||
DISABLE-CMDLOG |
x | |||||||
DISABLE-DYN-WORKER |
x | |||||||
DISCONNECT-PSTORE |
x | |||||||
ENABLE-ACCOUNTING |
x | |||||||
ENABLE-CMDLOG-FILTER |
x | |||||||
ENABLE-CMDLOG |
x | |||||||
ENABLE-DYN-WORKER |
x | |||||||
FORBID-NEWUOWMSGS |
x | |||||||
PING |
x | |||||||
PRODUCE-STATISTICS |
x | |||||||
PURGE |
x | |||||||
REFRESH-RULES |
x | |||||||
RESET-USER |
x | |||||||
RESUME |
x | |||||||
SET-CMDLOG-FILTER |
x | |||||||
SET-COLLECTOR |
x | |||||||
SET-UOW-STATUS |
x | |||||||
SHUTDOWN |
x | x | x | x | x | |||
START |
x | |||||||
STATUS |
x | |||||||
STOP |
x | |||||||
SUSPEND |
x | |||||||
SWITCH-CMDLOG |
x | |||||||
TRACE-FLUSH |
x | |||||||
TRACE-OFF |
x | x | x | |||||
TRACE-ON |
x | x | x | |||||
TRAP-ERROR |
x | |||||||
Note:
Object type TRANSPORT applies to operating system z/OS only.
| Example | Description |
|---|---|
etbcmd -b etb001 -h |
Displays ETBCMD help text. |
etbcmd -b etb001 -d BROKER -c
TRACE-OFF |
Turns Broker tracing off. |
etbcmd -b etb001 -d BROKER -c TRACE-ON -o
LEVEL2 |
Sets Broker trace level to 2. |
etbcmd -b etb001 -d BROKER -c
SHUTDOWN |
Performs Broker shutdown. |
etbcmd -b etb001 -d SERVICE -c SHUTDOWN -o IMMED -n
ACLASS/ASERVER/ASERVICE |
Shut down service CLASS=ACLASS,SERVER=ASERVER,SERVICE=ASERVICE.
See also SHUTDOWN SERVICE under Broker Command and Information Services in the EntireX Broker documentation for more information on
shutdown options.
|
Create list of servers and shutdown specific server in two
steps (first step uses etbinfo). See also SHUTDOWN SERVER.
|
|
etbinfo -b etb001 -d SERVER -l FULL -f"%USER-ID
%SEQNO" |
1. Determine a list of all servers with sequence numbers. |
etbcmd -b etb001 -d SERVER -c SHUTDOWN -o IMMED -S32 |
2. Shutdown server with sequence number 32. |
etbcmd -b etb001 -d BROKER -c PING |
Performs an EntireX ping against the Broker. |
etbcmd -b etb001 -d PSF -c DISCONNECT-PSTORE |
Disconnects the Broker PSTORE. |
etbcmd -b etb001 -d PSF -c CONNECT-PSTORE |
Connects the Broker PSTORE. |
etbcmd -b etb001 -d PSF -c PURGE -u 100000000U00001A |
Purges a unit of work. |
etbcmd -b etb001 -d PSF -c ALLOW-NEWUOWMSGS |
Allows new units of work to be stored. |
etbcmd -b etb001 -d PSF -c FORBID-NEWUOWMSGS |
Disallows new units of work to be stored. |
etbcmd -b etb001 -d PSF -c SET-UOW-STATUS -o ACCEPTED -n ACLASS/ASERVER/ASERVICE |
Sets the status of UOWs that reside in the postpone queue back to ACCEPTED for service ACLASS/ASERVER/ASERVICE. See also Postponing Units of Work under Using Persistence and Units of Work in the platform-independent Administration documentation.
|
etbcmd -b etb001 -d PSF -c SET-UOW-STATUS -o CANCELLED -u 0010000000000100 |
Cancel UOW with UOWID 0010000000000100 that resides in the postpone queue. See also Postponing Units of Work. |
etbcmd -b etb001 -d SECURITY -c REFRESH-RULES |
Broker re-reads the attribute file to refresh the active authorization rules. |
To set up SSL
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Specify the Broker ID, using one of the following styles:
URL Style, for example:
ssl://localhost:2010
Transport-method Style, for example:
ETB024:1609:SSL
If no port number is specified, port 1958 is used as default.
Specify SSL parameters with the option -s|S (lowercase for etbcmd; uppercase for etbinfo).
See SSL/TLS Parameters for SSL Clients.
Make sure the broker is prepared for SSL connections as well. See Running Broker with SSL/TLS Transport under z/OS | Linux | Windows.
You can encrypt a password and store this in a file. Specify this file instead of a cleartext password when you call a secure broker.
Notes:
etbnattr must be executed on the system where the encrypted password is used as input value.
To encrypt a password
Enter the command:
etbnattr --echo_password_only -w clear_text_passwordThe encrypted password is written to stdout.
Copy the password value to an empty file. (Ignore the prefix KEY-PASSWD-ENCRYPTED:.)
To specify the encrypted password from stdin
Enter the command:
etbcmd -xuid --encrypted_password_from_stdin < file
Where file is the file containing the encrypted password you created as described above. Example:
etbcmd -blocalhost:1971 -cPING -dBROKER -xUID --encrypted_password_from_stdin < myPwd