EntireX Broker provides the following internal services: Command Service, Information Service and Administration Service, which can be used to administer and monitor brokers and RPC servers. Because these services are implemented internally, nothing has to be started or configured. You can use these services immediately after starting EntireX Broker. This document covers the following topics:

• etbinfo

• etbcmd

---

etbinfo

Queries 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.

Although basic formatting of the output is available, it is usually formatted by script languages or other means external to the Broker.

• Running the Command-line Utility

• Command-line Parameters

• Command-line Parameters from File

• Profile

• Format String

• Using SSL/TLS

• Using an Encrypted Password

Running the Command-line Utility

In a UNIX 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.

Command-line Parameters

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	Possible values: Object Provides Info on BROKER Broker. CLIENT Client. CMDLOG-FILTER Command log filter. CONVERSATION Conversation. NET Entire Net-Work transport. PARTICIPANT Participant. POOL-USAGE Broker pool usage. PSF Unit-of-work status. PSFADA Adabas persistent store. PSFCTREE c-tree persistent store. PSFDIV DIV persistent store. RESOURCE-USAGE Broker resource usage. SECURITY EntireX Security. SERVER Server. SERVICE Service. SSL SSL transport. STATISTICS Broker statistics. TCP TCP transport. UOW-STATISTICS Units of work per service. USER Participant (short). WORKER Worker. WORKER-USAGE Worker usage.
-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: FULL All information. SHORT User-specific information.
-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	file	O	Here you can specify a file that defines the layout of the output. There are default files you can modify or you can use your own. The default files are: BROKER CLIENT CLOGFLT CONV NET POOL PSF PSFADA PSFCTREE  PSFDIV SERVICE  SSL STATIS STATIS TCP USER WORKER  WKRUSAGE See Profile.
-q	puserid	O	Physical user ID. This selection criterion is valid only for objects CLIENT, SERVER, CONVERSATION, Note: Must be a hex value.
-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 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.

Command-line Parameters from File

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

Profile

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 that includes only those columns.

The following default sample profiles include all the columns defined for each display type:

BROKER CLIENT CLOGFLT CONV

NET POOL PSF PSFADA

PSFCTREE PSFDIV RESOURCE SECURITY

SERVER SERVICE SSL STATIS

TCP USER WKRUSAGE WORKER

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.

Location of Profiles

On UNIX, the profiles are contained in directory /<Install_Dir>/EntireX/etc and are named broker.pro, client.pro etc.

Example 1

Profile for object SERVICE: SERVICE.

etbinfo -b ETB001 -d SERVICE -p service.pro -l FULL

The following list is displayed:

SAG                              ETBCIS     INFO  
 1 0 16 86400 0 31647 0 00 00 00 00 0 0  
SAG                              ETBCIS     USER-INFO
 2 0 16 86400 0 31647 0 00 00 00 00 0 0                  
SAG                              ETBCIS     CMD      
 6 0 16 86400 0 31647 0 00 00 00 00 0 0

Example 2

Your own profile: MYPROF

etbinfo -b ETB001 -d SERVICE -p my_service.pro

The following list is displayed:

ACLA    ASERVER
BCLA    BSERVER
CCLA    CSERVER

Sample Profiles for etbinfo

You can find the sample profiles for etbinfo in your /<Install_Dir>/EntireX/config directory.

Format String

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 quotation marks. 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

Using SSL/TLS

To set up SSL

1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

2. 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.

3. Specify SSL parameters with the option -s|S (lowercase for etbcmd; uppercase for etbinfo). See SSL/TLS Parameters for SSL Clients.

4. Make sure the broker is prepared for SSL connections as well. See Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE.

Using an Encrypted Password

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.

To encrypt a password

1. Enter the command:

   etbnattr --echo_password_only -w clear_text_password 

   The encrypted password is written to stdout.

2. 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

etbcmd

Allows the user to take actions - for example purge a unit of work, stop a server, shut down a Broker - against EntireX Broker.

• Running the Command-line Utility

• Command-line Parameters

• Command-line Parameters from File

• List of Commands and Objects

• Examples

• Using SSL/TLS

• Using an Encrypted Password

Running the Command-line Utility

In a UNIX 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.

Command-line Parameters

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	ALLOW-NEWUOWMSGS APPMON-ON APPMON-OFF CLEAR-CMDLOG-FILTER CONNECT-PSTORE DISABLE-ACCOUNTING DISABLE-CMDLOG-FILTER DISABLE-CMDLOG DISABLE-DYN-WORKER DISCONNECT-PSTORE ENABLE-ACCOUNTING ENABLE-CMDLOG-FILTER ENABLE-CMDLOG ENABLE-DYN-WORKER FORBID-NEWUOWMSGS PING PRODUCE-STATISTICS PURGE RESET-USER RESUME SET-CMDLOG-FILTER SET-COLLECTOR SET-UOW-STATUS SHUTDOWN START STATUS STOP SUSPEND SWITCH-CMDLOG TRACE-FLUSH TRACE-OFF TRACE-ON TRAP-ERROR	R	Command to be performed. See List of Commands and Objects below.
object type	-d	BROKER CONVERSATION PARTICIPANT PSF SECURITY SERVER SERVICE TRANSPORT	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. See Implicit Logon and Explicit Logon. A participant could act as client or server.
	-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	ACCEPTED CANCELLED IMMED QUIESCE LEVELn, where n=1-8	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.

Transport ID Values

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

Command-line Parameters from File

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

List of Commands and Objects

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

Examples

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	Shutdown service CLASS=ACLASS,SERVER=ASERVER,SERVICE=ASERVICE. See also SHUTDOWN SERVICE 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.

Using SSL/TLS

To set up SSL

1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

2. 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.

3. Specify SSL parameters with the option -s|S (lowercase for etbcmd; uppercase for etbinfo). See SSL/TLS Parameters for SSL Clients.

4. Make sure the broker is prepared for SSL connections as well. See Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE.

Using an Encrypted Password

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.

To encrypt a password

1. Enter the command:

   etbnattr --echo_password_only -w clear_text_password 

   The encrypted password is written to stdout.

2. 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