contents

6. The Broker

The Magic Request Broker component receives and processes requests from the network. Requests are calls for remote program execution that include parameters and options. A request is eventually sent to a Magic engine for execution.
There is a basic broker documentation from Magic.

6.1 Setup

Default installation path:
/usr/magicadm/broker
There are three files:
  • mgrqmrb   - the broker,
  • mgrqcmdl  - the command line requester
  • mgrb.ini. - the ini file for the broker
You should remember this is a daemon which should NOT have "root" privileges. This can be prevented if "magicadm" owns that programm and the "Set User ID" Bit" is set.
chmod 4700 mgrqmbr
chown magicadm mgrqmbr
You have to modify the mgrb.ini file:
[MRB_ENV]PasswordSupervisor = YourBrokerSupervisorPasswd (you need it later)
[MRB_EXECUTABLES_LIST]HelloWeb=/usr/magicadm/bin/magicrnt , , , 2

6.2 Manual start

Login as "magicadm" and change to the brokers default directory. This enables the broker to find the mgbr.ini file.
Starting the broker:
cd /usr/magicadm/broker
./mgrqmrb -ReusePorts &
  • -ReusePorts  - if you start the broker a second time.
  • &            - start as a back ground process
Check whether the broker was started:
ps -A -l| grep mgrqmrb
  F S   UID   PID  PPID  C PRI  NI ADDR SZ WCHAN  TTY          TIME CMD
000 S   501 97132     1  0  60   0 -  1012 rt_sig pts/1    00:00:00 mgrqmrb
040 S   501 97134 97132  0  60   0 -  1012 do_pol pts/1    00:00:00 mgrqmrb
040 S   501 97135 97134  0  60   0 -  1012 do_sel pts/1    00:00:00 mgrqmrb
040 S   501 97136 97134  0  60   0 -  1012 do_sel pts/1    00:00:00 mgrqmrb
040 S   501 97137 97134  0  60   0 -  1012 do_sel pts/1    00:00:00 mgrqmrb
040 S   501 97138 97134  0  60   0 -  1012 do_sel pts/1    00:00:00 mgrqmrb
040 S   501 97139 97134  0  60   0 -  1012 do_sel pts/1    00:00:00 mgrqmrb
As user we see the UID=501, in this example the user-id of "magicadm" and as process the PID=97132.
A list of seven processes is shown. You only need to terminate one and the others will be stopped automatically.
kill 97132

6.3 The command line requester

After the Broker is being started it can be controlled on the command line. You can get a help if you invoke the tool without any parameters:
./mgrqcmdl | less
We will now test if the broker is up:
./mgrqcmdl -query=rt
the answer should be:
  Application Servers of (localhost/2001)
--------------------------------------------------
#        Engine      Pid    Status     Application
==================================================
Now we will load the first runtime engine:
./mgrqcmdl -exe=HelloWeb -password=DoYouRemeberYourPassword
We will now test if the runtime is up:
./mgrqcmdl -query=rt
the answer should be:
  Application Servers of (localhost/2001)
--------------------------------------------------
#        Engine      Pid    Status     Application
==================================================
1  | localhost/####  4711 Avail Idle  |
But how to get an application? Be patient. Step by step. By the way: everything is up and running now. So you can skip the next step at this level. But remember you have to start the broker after every system start.

6.4 Broker and SuSE.

The system scripts are located in
/sbin/init.d/
And they have their own starting-algorithm. The change of a run level is controlled by a script called:
/etc/rc.config
You have to insert a new section at the end of the file:
---------- cut ---------
#
# Start the magic broker (yes,no).
#
START_MGBROKER="yes"
#
---------- cut ---------
This setting can be changed by "yast"
Administrating the System -> Changing Configuration File
Now copy the script "mgbrs" from archive to "/sbin/init.d/" and change the properties:
chmod 4700 mgbrs
chown magicadm mgbrs
At which run level the broker should be started is controled by a symbolic link into a directory:
  • kill and start the broker at run level 2
    ln -s /sbin/init.d/mgbrs /sbin/init.d/rc2.d/K91mgbrs
    ln -s /sbin/init.d/mgbrs /sbin/init.d/rc2.d/S92mgbrs
  • kill and start the broker at run level 3
    ln -s /sbin/init.d/mgbrs /sbin/init.d/rc3.d/K91mgbrs
    ln -s /sbin/init.d/mgbrs /sbin/init.d/rc3.d/S92mgbrs
(The license manager should be started (S91mglms) before the broker (S92mgbrs). And vice versa:  first stop the broker (K91mgbrs) and than the license manager (S92mglms). If you want to know more= RtFM.)
If you modified the location or the user of the broker, you have to modify the script:
---------- cut --------------
BR_PATH=/usr/magicadm/broker
BR_USER=magicadm
---------- cut --------------
You are now able to controll the broker:
/sbin/init.d/mgbrs start
/sbin/init.d/mgbrs stop
/sbin/init.d/mgbrs status
/sbin/init.d/mgbrs restart

6.5 Broker and Red Hat

The system scripts are located in
/etc/rc.d/init.d/
Now copy the script "mgbrr"  from archive to this location and change the properties:
chmod 4700 mgbrr
chown magicadm mgbrr
And it is controlled by "chkconfig". The "mgbrr" script has a section with three lines like this (the slash at the end of the second line concatenates the third line and must be there):
---------- cut --------------
# chkconfig:   23 92 91
# description: start the daemon at run level 2 & 3 as S92mgbrr \
#              and stop it at the other level as K91mgbrr
---------- cut --------------
(First start the license manager (S91mglmr) than the broker (S92mgbrr). And first stop the broker (K91mgbrr) and than the license manager (K92mglmr). If you want to know more "man chkconfig".)
For to add the service:
chkconfig --add mgbrr
chkconfig --list mgbrr
result: "mgbrr 1:off 2:off 3:on 4:off 5:off 6:off"
For to remove the service:
chkconfig --del mgbrr
chkconfig --list mgbrr
result: "mgbrr 1:off 2:off 3:off 4:off 5:off 6:off"
The script "/etc/rc.d/rc" control's the change of a run level. All symbolic links with a "K" ("K92mgbrr") in the beginning are taken to check  "/var/lock/subsys" for a lock file named "mgbrr". The script "mgbrr" has to create on start up an empty file into this directory and delete it on stop.  "magicadm"  doesn't has properties to write into this directory.
To solve this problem "root" has to change the properties of "/var/lock/subsys/" to "search/execute others" :
chmod o+x /var/lock/subsys/
If you modified the location or the user of the broker, you have to modify the script:
---------- cut --------------
BR_PATH=/usr/magicadm/broker
BR_USER=magicadm
---------- cut --------------
You are now able to controll the broker:
/etc/rc.d/init.d/mgbrr start
/etc/rc.d/init.d/mgbrr stop
/etc/rc.d/init.d/mgbrr status
/etc/rc.d/init.d/mgbrr restart

6.6 Broker Error Codes

4 NO-RESULT
The requested task did not return output to the requester output media (IO).
101 BAD-ARGS Remote Call Error - Invalid Remote Call
Application or program names were not entered for the remote call.
102 CNCT-MRB-REFUSED Remote Call Error - Connection to Broker Refused
Wrong host name or port for the Broker. Verify that the broker is connected to the port on the specified machine.
103 APP-NOT-FOUND Remote Call Error - Application Not Found
The engine does not support the Application; or the Appl=entry in MGREQ.ini file was specified and the required application did not appear in the list (not relevant to the Magic 8 Client).
104 APP-IN-USE Remote Call Error - Application in Use
All the engines that support the application are busy serving other requests; or the engine does not support the application. The Broker Time-out value may have expired. For the Magic Client, the time-out value is in the Server repository. From the MGREQ.ini file, the time out value is in the Timeout parameter.
105   see remark (*)
106 RT-NOT-RESPOND Remote Call Error - Runtime Not Responding
The Server Timeout parameter in the MAGIC.ini file or the MGREQ.ini file has expired. The server engine did not send an I-AM-ALIVE message during the specified time interval.
107   Connection reset by the AppServer
This Magic partitioning message is given when one or the following situations occur: (1) The application server was aborted abnormally during the execution of a request, or (2) The connection was reset due to a network connection failure.
110 REQUEST-TIMEOUT Remote Call Error - Request Timed-out
The Request Timeout entry has expired in the MAGIC.ini or the MGREQ.ini file. The requested task was not completed in the specified time interval.
111 RQGNRC_ERR_NOT_MRB  
113 RQGNRC_ERR_NOT_APPNAME_REQUIRED  
114 RQGNRC_ERR_NOT_PRGNAME_REQUIRED  
115 RQGNRC_ERR_REPLAY_QUEUE_MISSING  
116 RQGNRC_ERR_NO_ENGINE_READY  
130 APP-OPEN-FAIL Remote Call Error - Failed To Open Application
The server engine could not open the application control file.
131 PRG-NOT-FOUND Remote Call Error - Program Not Found
Cannot find the public name of the program specified in the application.
133 ACCESS-DENIED Remote Call Error - Access Denied
Invalid user name. No rights assigned to the user. No right to execute program.
135 LIMITED-LICENSE-HTTP Remote Call Error - License Limited to Internet Requests
Server engine is licenses to execute requests from internet requesters only.
136 LIMITED-LICENSE-CS Remote Call Error - License Limited by Requests Count
Server engine is licensed to execute a limited number of requests.
137 REQUEST-REJECT Remote Call Error - Request Rejected
Server engine cannot execute the request due to a timing problem of switching from runtime to toolkit modes.
138 RT-ERROR-MSG
During execution of a request, the executed program, or subprograms, displayed error messages such as SQL or locking errors. If the executed program failed to complete, these error messages were trapped by the AppServer & sent back to the requester. If the executed program was executed successfully, despite the error messages, the program's output is returned, overriding any error messages. When the requester is an Internet requester, the error messages are sent to the remote browser. When the requester is a command line requester, the error messages are displayed in the console. When the requester is a Magic 8 engine, this error message is not displayed.
145   see remark (*)
146 BIND-HOST-NOT-FOUND Remote Call Error - Bind Failed - Unknown Host
The Local Host entry in the MGREQ. ini file must specify the local internet address.
147 CNCT-HOST-NOT-FOUND Remote Call Error - Connection Failed - Unknown Host
The Broker address must explicitly contain the internet address (i.e. 88.0.184/2001)
150 CNCT-REFUSED-MRB An application server couldn't connect to the Broker
Check if the Broker was started, and that the host name of the Broker, as known in the computer of the AppServer (ping <mrbhost>), belongs to the correct IP address (as known in the computer of the Broker-ping <mrbhost>). Reproduce the problem with log "enabled" in mgreq.ini (log = req.log Y R), in the directory of  the AppServer.
151 CNCT-RESET-BY-REQ During execution of a request, the connection between the requester & the AppServer was reset
As a result, no output was sent back from the AppServer to the requester. Check the requester in the client machine & the AppServer. If possible, reproduce the problem with log "enabled" in mgreq.ini (log = req.log Y R) in the directories of the requester & of the AppServer.
160 RQSPAWN_ERR_EXE_NOT_FOUND These error codes may be returned to the command line requester and/or displayed in the log file of the Broker when the Broker both attempts to start executables ([MRB_EXECUTABLES_LIST]), and fails because of bad setup. A bad setup may be due to any of the
following: An unknown executable, a bad directory, wrong username/password (for the OS, see the syntax of [MRB_EXECUTABLES_LIST]), or network problems.
161 RQSPAWN_ERR_PATH_NOT_FOUND
163 RQSPAWN_ERR_BAD_LOGIN
164 RQSPAWN_ERR_PRIVILEGE_NOT_HELD
169 RQSPAWN_ERR_NET_UNREACHABLE
200 RQ-FATAL  Remote Call Fatal Error
Misc. Errors.
201 Code Partitioning Error - TCP/IP Not Initialized
TCP/IP services were not installed. Install TCP/IP.
202 ERR-OPEN-RESULT-FILE
This is a two-part problem: (1) The requester asked that the output be written into a file (either using a field in the call remote  dialog box in a Magic 8 client, or using keywords in mgreq.ini or mgrqcmdl -file=), and (2) The combined file name (directory and/or file name) is illegal.
220   Out of resources:
This error message is displayed when Winsock returns the error -10055 (out of buffers).

(*) Unexpected Errors: Errors that are not listed in the documentation, such as
    -105,
    -145,
are best handled by using the log file from mgreq.ini. This log file can show, for example, problems with host name resolution, which are the primary cause of these error messages.
It is important to know the difference between errors from the Web Server (which are not displayed in the blue/aqua error page of Magic) and those from Magic. Web Server errors are, for example, a missing requester or insufficient rights.

6.7 MGBR.INI

[MRB_ENV]  
BrokerPort =  2001 The ports that the MRB listens to and waits for requests from.
Syntax : BrokerPort = port number
(default number =2001)
EnginesPriority =    A list of up to 9 computer names that are used to provide server engines. This list controls the order that the MRB chooses engines to serve client requests. The Engines Priority list operates sequentially so that the engine for the first computer will execute the client command, if available, before the engines of the second computer, and so on.
ServerTimeout =    The interval, in seconds, that the Broker instructs the engines to send an I-AM-ALIVE message during the execution of ASYNC calls. 
If the value is 0, then the engine will not send the I-AM-ALIVE message to the broker. 
If the engine crashes or is terminated in an abnormal way during task execution, it will be understood by the broker as a no response from the engine.
PasswordSupervisor =  superpasswd An optional value that restricts the user's access to the MRB. If specified, security checks will occur during the following broker operations:
  1. Clearing or prioritizing any command request in the queue (a user can modify their command request based on the user name and password used when the request was submitted.
  2. Terminating the MRB.
  3. Loading new executables.
If PasswordAdmin is not specified, security validations for user name and password will remain inactive.
PasswordQuery =    An optional value that can be used to restrict access to the MRB. 
If specified, a password is checked before allowing a user to query a request of another user Any user can access the Query Queue & log to view their own requests, based on the user name and password when the request was submitted, without any security restrictions. The MRB accepts the user name and password of the service, the user name and password logon to the Magic application, or the user name and password stored in the MGREQ.ini file (for cmdl/internet only).
If PasswordQuery is not specified, security validations for user name and password will remain inactive.
AutoLoad =  WebApp,2 This new parameter (since v8.2) allows the Broker a certain level of automatic AppServers activation.
The parameter takes a simple format: AutoLoad=<exe_entry_name>,<cnt>.
The exe_entry_name is one name that exists either in the [MRB_EXECUTABLES_LIST] or in the [MRB_REMOTE_EXECUTABLES_LIST] sections of the MGRB.INI settings file (for explanations on these 2 sections, refer to the REF.PDF electronic manual).
The Broker will automatically activate the specified exe_entry_name, in one of the following 2 cases:
A request was submitted by a client, and there are no registered AppServers whatsoever.  In this case, the Broker will activate the specified exe_entry_name immediately, so that the activated AppServer will still be able to serve the incoming request.
A request was submitted by a client, and there are registered AppServers.  In this case, if no AppServer will become available during the request wait time, the request will fail (with an error message of either "No AppServers" or "AppServers are busy").  If at this point the number of AppServers is smaller than the value specified by the <cnt> parameter, then a new instance of the exe_entry_name will be loaded, to reduce the possibility that the future requests will fail to receive a matching AppServer.
Note: This simple mechanism does not take into consideration the name of the application that the incoming request specified.  The Broker simply activates a new instance of the exe_entry_name, regardless of what applications that each AppServer can serve.
 
ReLoad =  N MGRB.INI: ReLoad parameter
This new parameter (Planned to be added in v8.2h) allows the Broker another level of automatic AppServers activation.
When this flag is set (ReLoad = Y),  the Broker functions as a simple watch dog, meaning that whenever an AppServer that was activated from mgrb.ini crashes (from any reason − OS, Application bug or whatever),  the Broker will automatically reload a new instance of the same ExeEntry name listed in mgrb.ini.
Log =  /usr/magicadm/broker/mgbr.log Y A reference to a file that logs high-level MRB activities: messages sent and received to and from the MRB by both engines and requesters.
Syntax : LOG = [file specification] Sync Mode
File Name: Any valid name that does not include spaces.
Sync:
  • Y - The log file opens and closes for each line. This allows for the deletion of the file while the components are still loaded in memory.
  • N - The log file opens and closes only during the component initialization and termination operations.
  • F - Each line to be printed will be sent to the log file.The log file only opens and closes during the component initialization and termination operations.
Mode: The log level that is generated by the MagicGate DatabaseGatway for your RDBMS. The possible values are: 
None - no log file, 
Customer - only for the SQL commands generated, 
Developer - additional information, or 
Support - a full log file.
     
[MRB_EXECUTABLES_LIST]  
EXE_ENTRY_NAME= /usr/magicadm/bin/magicrnt ,
magicadm , 
mgpass , 
2
Optional section containing a list of command line executables or shell commands that can be activated from a remote requester, or upon MRB initialization.
Syntax:
EXE_ENTRY_NAME=<command>[<work dir>],[<username>], [<password>],[<number of times to perform upon broker initialization>]
     
[MRB_REMOTE_EXECUTABLES_LIST]  
Remote =  remote_server/2001,,Background,0 Section for setting up a multi-computer environment with engines running on computers independent of the MRB.
An instance of the MRB, functioning as a loader, must be active for each computer with engines running on that broker. The local MRB automatically connects to the remote MRB, specified in the exe entry of this section, and will instruct it to load an executable from its list of executables. The PasswordAdmin must be used if the remote broker has its own password (if not specified, use the password for the local MRB).
     
[MRB_ENGINE_CLIENTS_MAP]  
eran:eran,yoram   The purpose of the MRB Engine Clients Map is to allow the devleoper to control the engine that receives the request. For example, when several developers are working on the same MCF file, a developer can check out an object and command the MRB to assign its own engine.
Note: During the remote call execution (when the engine is mapped to this section), The Request Gateway utilizes the logon name and password that are sent with the request. If a devloper is not logged in to the engine, he must specify the user name and password from either the mgreq.ini file for Internet and Command Line requesters, or in the Service repository for the Magic 8 client to view the version of th MCF related to that developer's logon.
Example:
eran:eran
Any AppServer that runs on the computer named eran (left to the ':') will accept requests only from clients that run on the computer named eran (right to the ':').
It is also possible to use this option to restrict access to AppServers, for example: eran:eran,yoram - Any AppServer that runs on eran will accept requests only from clients that run on eran or on yoram.
IP addresses can be used only for the clients (for example, eran:88.0.0.84,88.0.0.85).
 

contents