Broker Command-line Utilities

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.


ETBINFO

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:

Running the Command-line Utility

In a z/OS environment, run the command-line utility ETBINFO as shown below.

Note:
The service data set name and member cannot be accessed directly, but only indirectly by its DD name in the JCL.

//ETBINFO EXEC PGM=ETBINFO,
// PARM=('ENVAR(''ETB_STUBLOG=0'')/ -p "//''EXX108.JOBS(BROKER)''" ',
//       '-bbrokerid -dBROKER -xuid -ypwd')
//STEPLIB  DD   DISP=SHR,DSN=< EXB-load-lib >
//         DD   DISP=SHR,DSN=< EXX-load-lib >
//         DD   DISP=SHR,DSN=< WAL-load-lib >
//TRACE1   DD   SYSOUT=*                               stublog
//SYSOUT   DD   SYSOUT=*                               stderr
//SYSPRINT DD   SYSOUT=*                               stdout
//

The SVC number specified in the ADARUN parameter must match the SVC number used for the target Broker ID.

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 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:
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 pds(member) O Here you can specify a PDS member that defines the layout of the output. See Table of Options and Profiles.
-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.
-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.

Table of Options and Profiles

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

Command-line Parameters from File

ETBINFO supports an alternative method of passing command-line parameters.

If the DDNAME INFFILE is allocated, using

//INFFILE  DD  DISP=SHR,DSN=pds(member)

and no command-line parameters are specified in the EXEC instruction, the content of the allocated member is evaluated. See sample member below (the apostrophes are included to show the record format (LRECL 80):

'-blocalhost:3930:TCP                                                            '
'-dBROKER                                                                        '

If ETBINFO is configured using INFFILE and a profile is specified, the syntax of the -p is as follows:

-p//'dsname(member)' if a PDS member is used
-p//'dsname' if a sequential data set is used

The syntax is based on IBM conventions for fopen.

Caution:
Make sure INFFILE does not contain line numbers in columns 73-80. If line numbers are present, arguments are not passed correctly. Only one option per line is supported.

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. We recommend using the profiles described under Table of Options and Profiles.

On z/OS, the profiles used to control the format of data displayed are members of the EXB source library and are named SERVER2, CLIENT2, etc. They can be saved as either sequential files or PDS members.

Hints for Creating your own Profile

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.

Example 1 - Default Profile

This example uses the default profile delivered with EntireX for object BROKER: BROKER2:

//ETBINFO EXEC PGM=ETBINFO,PARM=('/-b ETB001::NET -d SERVICE ',
//         '-p "//''EXX108.JOBS(SERVICE)''" -l FULL -xUID')

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 10.8.0.00 
       Highest supported API Version:     x0D (Hex value) 
       Highest supported CIS Version:     x0C (Hex value) 
       Active License (LICENSE-FILE):     C:\SoftwareAG\Suite1011\EntireX\config\license.xml 
       SNMP Licensed:                     01 (00: no, 01: yes)                                    
       Valid until (EXPIRATION):          UNLIMITED 
 
   Configuration Details 
       Broker attribute file:             C:\SoftwareAG\Suite1011\EntireX\config\etb\ETB001\ETB001.atr 
       Broker Log File:                   C:\SoftwareAG\Suite1011\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

Example 2 - Custom Profile

This example uses profile MYPROF you created yourself:

//ETBINFO EXEC PGM=ETBINFO,PARM=('/-b ETB001::NET -d SERVICE ',
//         '-p "//''EXX108.JOBS(MYPROF)''" -xUID')

In this example, profile MYPROF contains: %4.4SERVERCLASS %SERVERNAME. The following list is displayed:

ACLA    ASERVER
BCLA    BSERVER
CCLA    CSERVER

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

For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used where the establishment of the SSL connection is pushed down the stack into the TCP layer.

Configure the AT-TLS rules for the policy agent (PAGENT) graphics/no4.gif using an appropriate client graphics/no1.gif and the z/OS Management Facility (z/OSMF) graphics/no2.gif. Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by using the application graphics/no5.gif job name and local TCP port number. If the rules match, the TCP connection is turned into an SSL connection graphics/no6.gif. Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.

graphics/adminRpc_ssl_config-zos.png

graphics/no1.gif Client to interact with z/OS Management Facility (z/OSMF).
graphics/no2.gif AT-TLS rules are defined with z/OSMF policy management.
graphics/no3.gif Policy Repository with AT-TLS rules stored as z/OS files.
graphics/no4.gif Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
graphics/no5.gif Application using TCP connection.
graphics/no6.gif If AT-TLS rules match, the TCP connection is turned into an SSL connection.

Notes:

  1. The client graphics/no1.gif may vary per operating system, for example a Web browser for z/OS 2.1.
  2. z/OSMF graphics/no2.gif includes other administration and management tasks in addition to policy management.
  3. Policy Management graphics/no3.gif includes other rules, such as IP filtering, network address translation etc.

Start of instruction setTo set up SSL with AT-TLS

  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. Set up the tool for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:

    ETB024:1699:TCP
  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF). The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

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

ETBCMD

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.

Running the Command-line Utility

In a z/OS environment, run the ETBCMD command-line utility like this:

//ETBCMD  EXEC PGM=ETBCMD,
// PARM=('ENVAR(''ETB_STUBLOG=0'')/ -bbrokerid ',
//       '-dBROKER -c... -xuid -ypwd')
//STEPLIB  DD   DISP=SHR,DSN=< EXB-load-lib >
//         DD   DISP=SHR,DSN=< EXX-load-lib >
//         DD   DISP=SHR,DSN=< WAL-load-lib >
//TRACE1   DD   SYSOUT=*                               stublog
//SYSOUT   DD   SYSOUT=*                               stderr
//SYSPRINT DD   SYSOUT=*                               stdout
//

The SVC number specified in the ADARUN parameter must match the SVC number used for the target Broker ID.

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

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 DDNAME CMDFILE is allocated, using

//CMDFILE  DD  DISP=SHR,DSN=pds(member)

and no command-line parameters are specified in the EXEC instruction, the content of the allocated member is evaluated. See sample member below (the apostrophes are included to show the record format (LRECL 80):

'-blocalhost:3930:TCP                                                            '
'-dBROKER                                                                        '

Caution:
Make sure CMDFILE does not contain line numbers in columns 73-80. If line numbers are present, arguments are not passed correctly. Only one option per line is supported.

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

Using SSL/TLS

For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used where the establishment of the SSL connection is pushed down the stack into the TCP layer.

Configure the AT-TLS rules for the policy agent (PAGENT) graphics/no4.gif using an appropriate client graphics/no1.gif and the z/OS Management Facility (z/OSMF) graphics/no2.gif. Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by using the application graphics/no5.gif job name and local TCP port number. If the rules match, the TCP connection is turned into an SSL connection graphics/no6.gif. Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.

graphics/adminRpc_ssl_config-zos.png

graphics/no1.gif Client to interact with z/OS Management Facility (z/OSMF).
graphics/no2.gif AT-TLS rules are defined with z/OSMF policy management.
graphics/no3.gif Policy Repository with AT-TLS rules stored as z/OS files.
graphics/no4.gif Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
graphics/no5.gif Application using TCP connection.
graphics/no6.gif If AT-TLS rules match, the TCP connection is turned into an SSL connection.

Notes:

  1. The client graphics/no1.gif may vary per operating system, for example a Web browser for z/OS 2.1.
  2. z/OSMF graphics/no2.gif includes other administration and management tasks in addition to policy management.
  3. Policy Management graphics/no3.gif includes other rules, such as IP filtering, network address translation etc.

Start of instruction setTo set up SSL with AT-TLS

  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. Set up the tool for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:

    ETB024:1699:TCP
  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF). The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

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