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/brokerThere are three files:
- mgrqmrb - the broker,
- mgrqcmdl - the command line requester
- mgrb.ini. - the ini file for the broker
chmod 4700 mgrqmbrYou have to modify the mgrb.ini file:
chown magicadm mgrqmbr
[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
ps -A -l| grep mgrqmrbAs user we see the UID=501, in this example the user-id of "magicadm" and as process the PID=97132.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
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 | lessWe will now test if the broker is up:
./mgrqcmdl -query=rtthe answer should be:
Application Servers of (localhost/2001)Now we will load the first runtime engine:
--------------------------------------------------
# Engine Pid Status Application
==================================================
./mgrqcmdl -exe=HelloWeb -password=DoYouRemeberYourPasswordWe will now test if the runtime is up:
./mgrqcmdl -query=rtthe answer should be:
Application Servers of (localhost/2001)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.
--------------------------------------------------
# Engine Pid Status Application
==================================================
1 | localhost/#### 4711 Avail Idle |
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.configYou have to insert a new section at the end of the file:
---------- cut ---------This setting can be changed by "yast"
#
# Start the magic broker (yes,no).
#
START_MGBROKER="yes"
#
---------- cut ---------
Administrating the System -> Changing Configuration FileNow copy the script "mgbrs" from archive to "/sbin/init.d/" and change the properties:
chmod 4700 mgbrsAt which run level the broker should be started is controled by a symbolic link into a directory:
chown magicadm mgbrs
- 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
If you modified the location or the user of the broker, you have to modify the script:
---------- cut --------------You are now able to controll the broker:
BR_PATH=/usr/magicadm/broker
BR_USER=magicadm
---------- cut --------------
/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 mgbrrAnd 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):
chown magicadm mgbrr
---------- 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".)
# 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 --------------
For to add the service:
chkconfig --add mgbrrFor to remove the service:
chkconfig --list mgbrrresult: "mgbrr 1:off 2:off 3:on 4:off 5:off 6:off"
chkconfig --del mgbrrThe 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.
chkconfig --list mgbrrresult: "mgbrr 1:off 2:off 3:off 4:off 5:off 6:off"
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 --------------You are now able to controll the broker:
BR_PATH=/usr/magicadm/broker
BR_USER=magicadm
---------- cut --------------
/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:
|
| 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:
None - no 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). |
|
