EntireX Broker is delivered with a Natural tutorial. This tutorial is written in the programming language Natural but is useful even if you are using another programming language. Natural is required for installation of the tutorial. This document covers the following topics:
See also Examples for EntireX Broker Tutorial.
The Natural tutorial shows you how to actively use EntireX Broker by
allowing you to specify values for the fields in the ACI, which allows you to issue all types of requests and test use of EntireX Broker. See ACI Test Tool: Single Broker Request.
allowing you to measure throughput and response time of EntireX Broker. See Stress Mode.
offering several example client and appropriate server programs for programming language Natural; see Examples for EntireX Broker Tutorial. All programs can be displayed, edited and executed. Help texts are available for each program to explain the purpose of the program, indicate typical usage, and illustrate the logical program flow.
Under UNIX and Windows, use the Natural SYSOBJH utility to install the EntireX Broker
Tutorial (the Natural-based tutorial application SYSETB that is provided with EntireX).
See Object Handler in the Natural Tools and Utilities documentation for more information.
To activate the online tutorial, log on to library SYSETB in your
Natural environment and issue the MENU command. This displays the online
tutorial menu, which consists of a list of the client and server example
programs:
18:54:34 *** ENTIREX BROKER TUTORIAL *** 07-11-15
Client Server
-------- -------- NON CONVERSATIONAL EXAMPLES ------------------------
__ EXCL01CP EXCL01SP Single Requests without Reply
__ EXCL03CP EXCL03SP Single Requests with Reply
-------- -------- Conversational Examples ----------------------------
__ EXCN01CP EXCN01SP Long running Service - Non-blocked Client
__ EXCN02CP EXCN02SP Transfer messages from Server to Client
__ EXCN04CP EXCN04SP Transfer messages from Client to Server
__ EXCN05CP EXCN05SP Server with multiple parallel Conversations
-------- -------- Special Features -----------------------------------
__ EXDM01CP EXDM01SP Send messages with HOLD - delayed delivery
__ EXDM02CP EXDM02SP Remove Service while Conversations exist
__ EXDM03CP EXDM03SP Server for multiple Services
-------- -------- Customized Client/Server computing -----------------
__ EXRQ01-P EXRQ01-P Single Broker Requests
__ NATEX1CP NATEX1SP Model to write Client/Server programs API Version 1
__ NATEX2CP NATEX2SP Model to write Client/Server programs API Version>1
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
HELP GLOB EXIT UP DOWN
The example programs are grouped according to the following types:
Meaning of the information in the columns:
| Column | Source |
|---|---|
| Client | Name of the client program |
| Server | Name of the server program followed by a description of the example. |
Function keys available from the main menu:
| PF Key | Function | Description |
|---|---|---|
| PF9 | HELP | A general help is displayed. |
| PF2 | GLOB | Prompts for global defaults to be used for the current session. |
| PF3 | EXIT | Leave the online tutorial. |
| PF7 | UP | Scroll up. |
| PF8 | DOWN | Scroll down. |
The following pop-up window is displayed when you press PF2 from the tutorial main menu:
18:54:38 *** ENTIREX BROKER TUTORIAL *** 07-11-15
Clie +------------------------------------------------------------------+
----- ! Please modify defaults or press ENTER to continue ... !
__ EXCL0 ! !
__ EXCL0 ! Broker ID ...... ETBxxx !
---- ! Server Class ... ETB !
__ EXCN0 ! Server Name .... Tutorial !
__ EXCN0 ! Broker Stub .... BROKER !
__ EXCN0 ! User ID ........ USR1 !
__ EXCN0 ! Token .......... !
__ EXCN0 ! !
----- ! Node ........... Node: MVS/ESA Name put into send data !
__ EXDM0 ! Msg Length ..... 64 Length of send/receive data !
__ EXDM0 ! !
__ EXDM0 ! Wait Time ...... 45S Time blocked SEND/RECEIVE !
__ EXDM0 ! UOW Status Life. Life time 'addifier' !
__ EXDM0 ! API Version 8 1, 2, 3, 4, 5, 6, 7, 8, 9 !
__ EXDM0 ! !
----- ! Locale String... !
__ EXRQ0 ! !
__ NATEX ! Force Logon .... 'Y', 'N' !
__ NATEX ! Compress Level.. '0' thru '9', 'Y', 'N' !
__ NATEX ! Kernel Security. 'Y', 'N', 'U' !
+------------------------------------------------------------------+
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
HELP GLOB EXIT UP DOWN
The following global default settings can be modified and will be valid for the current session:
| Global Default Setting | Meaning |
|---|---|
| Broker ID | ID of the Broker in use. |
| Server Class | Server class in use for every example. |
| Server Name | Server name in use for every example. |
| User ID | User ID in use when running an example. |
| Token | Token in use when running an example. |
| Node | Node name put into send data. |
| Msg Length | Message length used for the SEND-LENGTH and
RECEIVE-LENGTH.
|
| Wait Time | Timeout value used for blocked SEND
and RECEIVE calls.
|
| UOW Status Life | UOW Status lifetime. See Writing Applications: Units of Work. |
| API Version | API version of broker control block. See API-TYPE and API-VERSION.
|
| Locale String | Locale string. To be used to override or provide codepages. See Using Internationalization. |
| Force Logon | Override Broker AUTOLOGON. See Authentication.
|
| Compress Level | Compression level. See Data Compression. |
| Kernel Security | Kernel security. See Writing Applications using EntireX Security. |
From the tutorial menu you can execute, list and edit example programs. You can also display several help texts on each program.
You can perform a function by entering the appropriate line command in the input field preceding the client program name. To display a list of available line commands, enter an asterisk in the input field preceding the client program name.
The table below lists the available line commands:
| Command | Meaning |
|---|---|
XC |
Execute client program. |
XS |
Execute server program. |
SH |
Shut down server. |
H |
Help for the example as a whole. |
HC |
Help for client program. |
HS |
Help for server program. |
LC |
List (display) client program. |
LS |
List (display) server program. |
EC |
Edit client program. |
ES |
Edit server program. |
The examples are also documented in Examples for EntireX Broker Tutorial.
The tutorial help facility provides help texts for each client and
server example program. To display the online help text, issue the appropriate
line command, H, HC or
HS, for the selected example on the online tutorial
menu.
The following screen shows the online help for the server of the example
"Single Requests without Reply" (line command
HS):
19:08:25 *** ENTIREX BROKER Tutorial *** 03-05-15
Server: Single Requests without Reply
Descr. : This server establishes a service which is able to collect
simple messages from clients that require no reply.
A REGISTER is necessary to inform the Broker of the availability
of the service. The DEREGISTER, issued as the last action, informs
the Broker of the unavailability of the service served by this
server.
The server wants to wait for a client message and therefore uses
a blocked RECEIVE, that is, a RECEIVE with W=nS is issued to the
Broker.
Coding : LOGON ------> logon to Broker
REGISTER ------> offer service
repeat
RECEIVE,W=nS,CID=NEW ------> wait for message
until ...
DEREGISTER ------> deregister service
LOGOFF ------> logoff from Broker
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
HELP EXIT Expml Cln Srv
The following functions are available from the help screen. You can execute a function by pressing the appropriate PF key:
| PF Key | Function | Description |
|---|---|---|
| PF1 | HELP |
Display general help. |
| PF3 | EXIT |
Leave the help screen. |
| PF9 | EXMPL |
Display general help screen specific to example. |
| PF10 | CLN |
Display client help screen specific to example. |
| PF11 | SRV |
Display server help screen specific to example. |
Note:
You can use PF10 and PF11 to toggle between the
client and server help screens.
Use of the example "client/server programs" is the same for each example. You need to start two sessions in order to "play" with EntireX Broker, one by executing the server program and the other by executing the client program.
As the first session, start the server by entering
XS in the input field preceding the program name,
for example in the line for Single Requests without Reply. This displays the
following startup parameter pop-up window:
9:11:38 *** ENTIREX BROKER TUTORIAL *** 07-11-15
VERSION 8.0
Client Server
-------- -------- NON CONVERSATIONAL EXAMPLES ------------------------
xs EXCL01CP +-------------------------------------------------------+
__ EXCL03CP ! Please enter values or press ENTER to continue ... !
-------- ! ! ----
__ EXCN01CP ! Mode ......... 1 1=Step 2=Stress 3=Silent !
__ EXCN02CP ! !
__ EXCN04CP ! Server Class . ETB !
__ EXCN05CP ! Server Name .. Tutorial !
-------- ! Service ...... NcNoReply ! ----
__ EXDM01CP ! !
__ EXDM02CP ! User ID ...... ILGWBU !
__ EXDM03CP ! Token ........ !
-------- ! ! ----
__ EXRQ01-P ! Msg Length ... 64 !
__ NATEX1CP ! ! n 1
__ NATEX2CP +-------------------------------------------------------+ n>1
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
HELP GLOB EXIT UP DOWN
The fields in this window are listed in logical groups. The first group controls the execution of the example and contains the mode parameter; for clients, end criteria to stop the execution is also displayed. Valid mode parameters are Step Mode, Stress Mode, Silent Mode. The other fields show some global defaults which you can overwrite for this particular client/server run. Note, however, that the Broker ID and Wait Time values can only be modified in the Global Defaults window (see above).
When using an example for the first time, you are recommended to select Step mode.
In this mode, the example is executed step by step. This means that every broker call is displayed on your screen and must be explicitly issued by pressing PF5. Upon return, the response from the broker is displayed in the Errtxt field together with the next meaningful broker call, ready for execution. You can always view previous Broker calls using the trace facility (PF4), which provides "before and after" images of every call issued to the broker.
If you select Step Mode and press ENTER, a screen similar to the following is displayed for every example:
Press PF5 to issue Request ...
19:13:53 *** ENTIREX BROKER TUTORIAL *** 03-05-15
Server: Single Requests without Reply
Errtxt .....
Send Data .. ________________________________________________________________
Rcve Data ..
Type/Vers .. 1 / 5
Broker ID .. ETBxxx Send Len ..... 64
Function ..* LOGON___________ Rcve Len ..... 64
Option ....* ________________ Errtx Len .... 40
Wait ......* ________ Rtrn Len ..... 0
Class ...... ETB_____________ User ID ...... ILGWBU__________________________
Name ....... Tutorial________ Token ........ ________________________________
Service .... NcNoReply_______ Password ..... ________________________________
Conv ID ...* ________________ New Password . ________________________________
User Data .. ________________ Sec Token .... ________________________________
Conv Stat .. Environment .. ________________________________
Client UID ...
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Strss Exit Trace Exec SBuff RBuff
The following functions are available from this screen. You can execute a function by pressing the appropriate PF key:
| PF Key | Function | Description |
|---|---|---|
| PF1 | HELP |
Display the help screen on the example program. See Using the Tutorial Help. |
| PF2 | STRSS |
Change execution mode to Stress.
|
| PF3 | EXIT |
Leave sample program. |
| PF4 | TRACE |
Invoke the The Tutorial Trace Facility. |
| PF5 | EXEC |
Issue broker call. |
| PF10 | SBUFF |
See Display/Modify Send Buffer. |
| PF11 | RBUFF |
See Display/Reset Receive Buffer. |
In this mode, the example is executed without further user interaction. Every Broker call issued is also displayed on the screen to allow you to see the activity of the client or server. Execution terminates in different ways:
For clients:
Further end criteria (such as number of messages and number of
conversations) are supplied in the startup parameter window of the client
example. When the specified values are reached, processing stops.
For servers:
Servers run until they are shut down by a special shut down message
sent to the server (SH command from the tutorial
main menu).
When execution in Stress mode is stopped, the following summary of client/server activity is displayed:
Waiting for Request ...
20:54:37 *** ENTIREX BROKER TUTORIAL *** 03-05-15
Server: Single Requests without Reply
+------------------------------------------------------------------------------+
! !
! 00200216 API: Invalid BROKER-ID !
! OP System .. MVS Load Count Max !
! TP System .. CICS ------------ -------- -------- !
! Speed/Mode . 191.850 / 2 Messages ... !
! Msg Length . 64 Conv ....... !
! ETB Calls .. 1 Parallel CID !
! !
! Time/Call Count Ave Min Max Time elapsed Absolute Relative !
! ------------ ------ ------- ------- ------- ------------ -------- -------- !
! Send non-blk Total ...... 0.0 100 % !
! Send blocked Executing .. 0.0 83.5 % !
! Rcve non-blk Waiting !
! Rcve blocked Transport . 0.0 16.4 % !
! EOC ........ Partner ... 0.0 % !
! Undo ....... !
! Register ... !
! Deregister . !
+------------------------------------------------------------------------------+
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Strss Exit Trace Exec Buff RBuff
Meaning of the fields:
| Field | Meaning |
|---|---|
OP |
System Underlying operating system. |
TP |
System Underlying transaction monitor. |
Speed |
Indication of the performance of the environment, relative to the corresponding value of other environments. |
Mode |
Execution mode of the example. |
Msg |
Length of messages sent/received. |
ETB |
Number of calls issued to the broker. |
| Load | |
Messages/Count |
Number of messages sent/received. |
Messages/Max |
Number of messages used as criteria to stop execution. |
Conv/Count |
Number of conversations conducted. |
Conv/Max |
Number of conversations used as criteria to stop execution. |
Parallel CID/Count |
Highest number of parallel conversations reached. |
Parallel CID/Max |
Maximum number of parallel conversations allowed. |
| Time/Call | |
Send non-blk/Count |
Number of non-blocked SEND calls issued.
|
Send non-blk/Ave |
Average elapsed time for a non-blocked SEND call.
|
Send non-blk/Min |
Shortest elapsed time for a non-blocked SEND call.
|
Send non-blk/Max |
Longest elapsed time for a non-blocked SEND call.
|
Send blocked |
Same as above for blocked SEND calls.
|
Rcve non-blk |
Same as above for non-blocked RECEIVE calls.
|
Rcve blocked |
Same as above for blocked RECEIVE calls.
|
EOC |
Same as above for EOC calls.
|
Undo |
Same as above for UNDO calls.
|
Register |
Same as above for REGISTER calls.
|
Deregister |
Same as above for DEREGISTER calls.
|
| Time elapsed | |
Total/Absolute |
Elapsed time in seconds between start and end for the run. |
Total/Relative |
Percentage of time between start and end for the run. |
Executing/Absolute |
Elapsed time in seconds when example is executing. |
Executing/Relative |
Percentage of time when example is executing. |
Waiting |
Time needed for transport plus execution time required by the partner. |
Transport/Absolute |
Elapsed time in seconds used for transport services. Transport means EntireX Broker and all other media involved such as SVCs, link routines, Entire Net-work, TCP/IC. |
Transport/Relative |
Percentage of time used for transport services. |
Partner/Absolute |
Elapsed time in seconds needed by the partner to execute the
call. This is relevant only to blocked SEND calls, as this is the only call
involving a partner.
|
Partner/Relative |
Percentage of time needed by the partner to execute the call.
This is relevant only to blocked SEND calls, as this is the only call involving
a partner.
|
Note:
Total/Relative=(Executing/Relative)+(Transport/Relative)+Partner/Relative=100%
The waiting period of the different call types consists of the following times:
For blocked RECEIVEs, the elapsed time is calculated from the
following:
The time when the RECEIVE call was routed from the server to the
broker.
A time of no activity during which there was no client request to be processed. This value may be high.
The time when an incoming client request was routed from the broker to the server.
For blocked SENDs, the elapsed time is calculated from the
following:
The time when the SEND call was routed from the client to the
broker.
A time of no activity during which there was no server ready to process the request. This value may be high.
The time when the client request was routed from the broker to the server.
The time when the request was processed by the server.
The time when the response was routed from the server to the broker.
The time when the answer was routed from the broker back to the client.
For all other calls to the broker, the elapsed time is calculated from the following:
The time when the call was routed from the participant to the broker.
The time when the call was processed by the broker.
The time when the call was routed from the broker back to the participant.
In this mode, the same applies as for Stress mode, except that no map I/Os are performed between broker calls. It is therefore not possible to view activities while the client and server example is running.
The trace facility is activated by pressing the appropriate PF key after starting an example program. With the trace option on, "before and after" images of the last ten requests issued to the broker are made visible. When the trace option is selected, the most recent request is always displayed:
Use PF7 / PF8 to scroll to older / more recent requests. Scroll right with PF11 to display a second screen page for every request.
21:00:07 *** ENTIREX BROKER TUTORIAL *** 03-05-15
------------ Image after call --------------- Image before call - 0 First
Type/Vers .. 1 / 5 1 / 5
Errtext .... 00000000 Successful response
------------ -------------------------------- --------------------------------
Broker ID .. ETB233 ETB233
Class ...... ETB ETB
Name ....... Tutorial Tutorial
Service .... NcNoReply NcNoReply
Fct ........ LOGON LOGON
Option .....
Wait .......
Conv ID ....
Conv Status.
User Data ..
Client UID .
------------ -------------------------------- --------------------------------
Send Data .. 0000000000326891781
Rcve Data ..
------------ -------------------------------- --------------------------------
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Exit Up Down Left Right
The following functions are available from this screen You can execute a function by pressing the appropriate PF key:
| PF Key | Function | Description |
|---|---|---|
| PF1 | HELP |
Display a help screen on the example program. |
| PF3 | EXIT |
Leave trace. |
| PF7 | UP |
Scroll to older requests. |
| PF8 | DOWN |
Scroll to more recent requests. |
| PF10 | LEFT |
Scroll to first screen page. |
| PF11 | RIGHT |
Scroll to second screen page. |
Selecting this option by pressing PF10 after starting the example from the tutorial menu displays the send buffer contents in hexadecimal and character format:
21:01:28 *** ENTIREX BROKER TUTORIAL *** 03-05-15
Display/Modify Send Buffer
00016 0000000000081804 F0F0F0F0F0F0F0F0F0F0F0F8F1F8F0F4 Send Len .. 64
00032 070_____________ F0F7F040404040404040404040404040
00048 ________________ 40404040404040404040404040404040
00064 ________________ 40404040404040404040404040404040
00080 ________________ 40404040404040404040404040404040
00096 ________________ 40404040404040404040404040404040
00112 ________________ 40404040404040404040404040404040
00128 ________________ 40404040404040404040404040404040
00144 ________________ 40404040404040404040404040404040
00160 ________________ 40404040404040404040404040404040
00176 ________________ 40404040404040404040404040404040
00192 ________________ 40404040404040404040404040404040
00208 ________________ 40404040404040404040404040404040
00224 ________________ 40404040404040404040404040404040
00240 ________________ 40404040404040404040404040404040
00256 ________________ 40404040404040404040404040404040
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Exit Top Up Down Bot Posit Reset
Use PF6 to PF9 to scroll up or down as needed. Positioning to a specific offset is possible by pressing PF10. You can overwrite the send buffer contents in the character-oriented column. The send buffer is cleared with PF12.
Meaning of the information in the columns from left to right:
| Column | Meaning |
|---|---|
| 1 | Send buffer offset decimal. |
| 2 | Send buffer contents displayed in character format. |
| 3 | Send buffer contents displayed in hexadecimal format. |
The following functions are available from this screen. You can execute a function by pressing the appropriate PF key:
| PF Key | Function | Description |
|---|---|---|
| PF1 | HELP |
Display a help screen on the example program. |
| PF3 | EXIT |
Leave send buffer display. |
| PF6 | TOP |
Position to first page. |
| PF7 | UP |
Scroll one up page. |
| PF8 | DOWN |
Scroll down one page. |
| PF9 | BOT |
Position to last page. |
| PF10 | POSIT |
Position to a specified offset in the send buffer. |
| PF12 | RESET |
Set the send buffer to low values. |
Selecting this option by pressing PF11 after starting the example from the tutorial menu displays the receive buffer contents in hexadecimal and character format in the same way as for the send buffer. See See Display/Modify Send Buffer.
This screen is an ACI test tool. An interface is provided which allows you to fill the broker ACI yourself and therefore issue all types of ACI requests in any sequence. You can use it
for test purposes of EntireX Broker;
for studying EntireX Broker functions and functionality;
as counterpart of any client or server written in any programming language.
If you execute this program, (line command XC
or XS), the user interface presents the broker ACI directly, which you can fill:
Press PF5 to issue Request ...
19:46:24 *** ENTIREX BROKER TUTORIAL *** 03-05-15
: Single Broker Requests
Errtxt .....
Send Data .. ________________________________________________________________
Rcve Data ..
Type/Vers .. 1 / 5
Broker ID .. ETBxxx Send Len ..... 0
Function ..* ________________ Rcve Len ..... 0
Option ....* ________________ Errtx Len .... 40
Wait ......* ________ Rtrn Len ..... 0
Class ...... ETB_____________ User ID ...... ILGWBU__________________________
Name ....... Tutorial________ Token ........ ________________________________
Service .... Request_________ Password ..... ________________________________
Conv ID ...* ________________ New Password . ________________________________
User Data .. ________________ Sec Token .... ________________________________
Conv Stat .. Environment .. ________________________________
Client UID ...
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Exit Trace Exec Reg Dreg Send Rcve SBuff RBuff Reset
Press PF6 to PF9 to assign default values to the broker ACI for the selected function. A field help is available for fields marked with an asterisk (mark the field with the cursor and press PF1).
To issue a request to the broker, press PF5.
The following functions are available from this screen. You can execute a function by pressing the appropriate PF key:
| PF Key | Function | Description |
|---|---|---|
| PF1 | HELP |
Display a help screen on this example program. If you press PF1 with the cursor on a field marked with an asterisk (*), a help window for the field is displayed. |
| PF3 | EXIT |
Leave the program. |
| PF4 | TRACE |
Invoke tracing of requests. See The Tutorial Trace Facility. |
| PF5 | EXEC |
Route a request to the broker. |
| PF6 | REG |
Assign defaults for REGISTER function to the ACI.
|
| PF7 | DREG |
Assign defaults for DEREGISTER function to the
ACI.
|
| PF8 | SEND |
Assign defaults for SEND function to the ACI.
|
| PF9 | RCVE |
Assign defaults for RECEIVE function to the ACI.
|
| PF10 | SBUFF |
See Display/Modify Send Buffer |
| PF11 | RBUFF |
See Display/Reset Receive Buffer: |
| PF12 | RESET |
Set the ACI to low values. |