EntireX Broker Tutorial

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.


Introduction to the 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.

Calling the Tutorial Menu

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.

Global Defaults for the Tutorial

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.

Tutorial Commands

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.

Using the Tutorial Help

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.

Using the Example Programs

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.

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.

Stress Mode

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:

Blocked RECEIVE

For blocked RECEIVEs, the elapsed time is calculated from the following:

  1. The time when the RECEIVE call was routed from the server to the broker.

  2. A time of no activity during which there was no client request to be processed. This value may be high.

  3. The time when an incoming client request was routed from the broker to the server.

Blocked SEND

For blocked SENDs, the elapsed time is calculated from the following:

  1. The time when the SEND call was routed from the client to the broker.

  2. A time of no activity during which there was no server ready to process the request. This value may be high.

  3. The time when the client request was routed from the broker to the server.

  4. The time when the request was processed by the server.

  5. The time when the response was routed from the server to the broker.

  6. The time when the answer was routed from the broker back to the client.

All Other EntireX Broker Calls

For all other calls to the broker, the elapsed time is calculated from the following:

  1. The time when the call was routed from the participant to the broker.

  2. The time when the call was processed by the broker.

  3. The time when the call was routed from the broker back to the participant.

Silent Mode

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 Tutorial Trace Facility

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.

Display/Modify Send Buffer

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.

Display/Reset Receive Buffer

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.

ACI Test Tool: Single Broker Request

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.