Keyword

Explanation

[MRB_ENV] section:

BrokerPort

The port that the broker listens to and waits for requests from. The broker reserves the subsequent port (by default 5116) for internal purposes.

Syntax: BrokerPort = port number

Default: 5115

EnginesPriority

A list of up to nine computer names that are used to provide server engines. This list controls the order in which the MRB chooses engines to serve client requests. The Engines Priority list operates sequentially so that the engine for the first computer executes the client command, if available, before the engine of the second computer, and so on.

PasswordSupervisor

An optional value that restricts the user’s access to the MRB. If specified, security checks will occur during the following broker operations:

• Clearing or prioritizing any command request in the queue (a user can modify a command request based on the user name and password used when the request was submitted).

• Terminating the MRB.

• Loading new executables.

• If PasswordSupervisor is not specified, security validations for user name and password are inactive.

Note: The same Supervisor password must also be entered in the Password server property. These Supervisor passwords are set automatically during the Magic xpa installation, in the mgrb.ini file and in the Server properties for the Default Broker.

See also How Do I Define the Broker Password?

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 and Log to view their own requests, based on the user name and password entered or in effect when the request was submitted, without any security restrictions. The MRB accepts the user name and password of the service, the user name and logon password to the Magic xpa 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 are inactive.

Note: The Query Password is not set up during the installation. It has only limited application, allowing users to query the engine status and running applications.

See also How Do I Define the Broker Password?

Reload

When this setting is set to Yes, the MRB reloads any instance of a Magic enterprise server that was not terminated by the MRB (abnormal termination).

When Reload = Y, the broker acts as a simple watch dog, meaning that whenever an enterprise server that was activated from Mgrb.ini crashes (for any reason, such as an operating system issue or an application bug), the broker will automatically reload a new instance of the same instance listed in the Mgrb.ini file.

Example: Reload=Y

Default: N

Log

A reference to a file that logs high level MRB activities such as initialization, receiving requests, locating enterprise servers, passing enterprise server information to the requester, and so on.

This log can be used to check if a certain request was accepted by the MRB and how it was handled.

Syntax: LOG=([Log File Path and Name] [Sync] [Level])

Example: LOG=Broker.log Y C

Log File Path and 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. It also allows the log file to be shared among several modules.

N – The log file opens and closes only during the component initialization and termination operations.

F – Each line designated for printing is sent to the Log file. The Log file only opens and closes during the component initialization and termination operations.

Level:

B – Basic level. Only HTTP requests' arrival and departures. This level is meant to be used for troubleshooting of production (and also testing) systems, especially in the areas of communication and component handshaking. Since version: 2.4b

C – Customer level. The lowest log status.

S – Support level. An intermediate log status.

R – R&D level. The highest log status.

To let the broker log low level activities (such as connect, send, receive, and so on), you can define the log in the Mgreq.ini file located in the MRB directory.

EnableFilters

This keyword can be used to disable (=N) or enable (=Y) the filters mechanism.

If the mechanism is disabled, the keywords 'Filters' and 'AllowReserve' have no impact.

Syntax: EnableFilters = Y/N

Default: N

Filters

You can use this field to specify how threads are allocated for different types of requests, such as HTTP requests, SOAP requests, COM requests, and requests without a filter.

Example: The example below shows you how an enterprise server with a license of 20 threads can be designated to service different types of requests:

HTTP_endusers:40% | SOAP_primary:10% | SOAP_secondary:5% | RemoteCalls:10% | COM:5%

• HTTP_endusers – 8 threads (40% of 20 threads)

• SOAP_primary – 2 threads (10% of 20 threads)

• SOAP_secondary – 1 threads (5% of 20 threads)

• RemoteCalls – 2 threads (10% of 20 threads)

• COM – 1 threads (5% of 20 threads)

• Requests without filter – 6 threads (remaining 30% of 20 threads)

Note: If the accumulated percentage is greater than 100%, the last filter entry that exceeds the accumulated percentage of 100% will be adjusted to be equal to 100% and all subsequent filters will be discarded.

Refer to Filters for a detailed explanation about filters.

AllowReserve

When the accumulated percentage of designated filters is less than 100%, you can specify Yes (default) to reserve the remaining percentage for other filters.

When AllowReserve = No, only requests without a filter can use the remaining percentage.

QueueMaxSize

When the broker already has QueueMaxSize requests in its queue, each subsequent request that cannot be served immediately (sync or async) will not enter the queue, and the requester will receive the error -198 ("Queue Limit reached").

Default: 1,000 requests (Since version: 1.9. Before 1.9, the default was "no limit")

ReqHistorySize

The broker has a history log describing each request that was processed (accessible via RQ functions of the engine or via mgrqcmdl QUERY=LOG).

This keyword controls the number of requests for which the broker keeps details in its history log.

Syntax: ReqHistorySize = number

Default: 20,000 requests. The minimum value is 5,000. The maximum value is 100,000.

ActivityLog

The ActivityLog setting lets you specify the Magic Request Broker log file name and path.

An example of the ActivityLog setting is: ActivityLog=logs\broker.log

If the Activity log is not set, it is created by default as BrokerActivity.log.

The Activity Log lists activities, such as:

• The broker’s startup and shutdown.

• Instructions to spawn servers (e.g. from the Broker Monitor).

• Instructions to terminate servers (e.g. from the Broker Monitor).

• Servers’ startups (while being registered to the broker) and shutdowns.

• Errors, such as TCP/IP connections reset.

Log format:

Thread ID Current Time,last 5 digits of the time in milliseconds Current Date Message

LoadBalancing

Y – Distributes the load between servers according to a factored long term performance:

• The server with the lowest factored average request time will be selected.
  The factored average request time (as seen in the Broker Monitor) is the average execution time of all requests that were served by that server, divided by the LoadBalancingPriority value sent from the server.
  The higher the priority is, the lower the factored average request time will be during load balancing.

• In case of identical factored average request time values: The server with the least number of active contexts will be selected.

T – Distributes the load evenly between servers, according to the percentage of executing threads out of the maximum threads allowed for a server:

• The server with the lowest percentage value will be selected.

• In case of identical percentage values: The server with the higher maximum threads count will be selected.

N – No load balancing. The broker will direct all requests to the first available server.

Note: The broker’s load balancing in general is applicable only to the first request of each Rich Client or Browser Client session. During this phase, the balancing is not different from any other non-client request. Starting from the second request of each session, the broker is obligated to direct all requests of a session to the same server in which they were originated.

Syntax: LoadBalancing = Y/T/N

Default: Y

Since version: 1.5 SP2; T option since version: 1.9g

See also Load Balancing Priority

ServerTimeout

The interval, in seconds, within which the broker instructs the engines to send I-AM-ALIVE messages to the broker.

If the value is 0, then the engines will not send the I-AM-ALIVE messages to the broker.

Syntax: ServerTimeout = n

Default: 60 (seconds)

CommTimeout

The time, in seconds, that a TCP/IP operation (connect/send/recv) will retry before failing the operation.

This setting in the Mgrb.ini file overrides the setting in the Mgreq.ini file for messages sent by the broker.

Low-level messages of the generic requester layer still use the setting from the Mgreq.ini file.

Default: 10 (seconds). The minimum is 1 seconds.

ShutdownTimeout

This value is set in seconds, to instruct all servers to shut down gracefully within the specified duration.

By default (=1), the broker instructs all servers to shut down immediately, and then shuts itself down immediately.

When a server is instructed by the broker to terminate, and this keyword has a positive value, the server automatically triggers the Server Termination internal event, allowing the executing programs to execute a termination logic.

Syntax: ShutdownTimeout = number

Default: 1 (seconds)

TerminateEnginesDuringShutdown

If the keyword is set to Y, the broker will terminate all runtime engines spawned by that broker (after a period of time defined in the ShutdownTimeout keyword). The broker already records the process IDs of all runtime engines. The broker will use the process IDs to kill each runtime engine even if it was not shut down gracefully.

This setting is only effective if ShutdownTimeout > 0 (otherwise it is ignored).

Syntax: TerminateEnginesDuringShutdown=[N]|Y

Since version: 1.5

ContextsUsage

When this setting is set to Yes, the MRB will save the contexts usage details into a file. The data will be saved when the context is closed.

This feature is enabled when the Runtime engine's Deployment mode is set to Background. In this case, the context is always the main/only context.

Syntax: ContextsUsage = Y/N

Default: N

ContextsUsageLog

This keyword allows the controlling of the Contexts Usage output file name.

The value can be relative or absolute.

Default: ContextsUsage_YYYY_MM_DD.Log.

FloatingLicense

When this is set to Y, servers that are not in the floating license environment mode can then share licenses with Servers that are in the floating license environment mode. See also Floating License Support.

Default: N

[APPLICATIONS_LIST]

This is an 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: APPNAME=<command>,[<work dir>],[<OS username>], [<OS password>],[<number of times to perform upon broker initialization>],[<maximum number of engines supporting the application to launch on demand>]

If [OS username] and [OS password] are specified, then the command will use this OS account to start.

If [<number of times to perform upon broker initialization>] is set to 1, then it will load one instance of the declared application.

[<maximum number of engines supporting the application to launch on demand>] – This setting is used to let the MRB load additional enterprise server engines when incoming requests cannot find an available enterprise server. If set, the MRB will load additional enterprise server engines as specified to serve a new request that had no available enterprise server engines (either because all are busy or none are registered in the MRB).

Note: The value of the request parameter, such as -APPNAME= has to match the APPNAME as defined in the [APPLICATIONS_LIST] to have an autoload effect for that engine.

Example:

[APPLICATIONS_LIST]

Rich Internet Samples = MgxpaRuntime.exe /DeploymentMode=B /LicenseName=MGRIA /StartApplication = SampleProjects\Rich Internet Samples\Rich Internet Samples.ecf,,,,0,1

[REMOTE_APPLICATIONS_LIST]

The [REMOTE APPLICATIONS LIST] is an optional section for setting up a multi-computer environment with engines running on computers independent of the local broker. An instance of the broker, functioning as a loader, must be active for each computer from which engines are planned to be loaded. The local broker automatically connects to the remote broker, specified in the Remote Host Name portion, below, and instructs it to load an application from its list of applications.

Syntax: Application Name = Remote Host Name[/Port Number],[Password to the Remote Broker],Application Name,[number of times to perform upon broker initialization],[maximum number of engines supporting the application to launch on demand]

/Port Number – Required only if the remote broker is started on a non-default port number (the default port number in version 1.9 and later is 5115).

Password to the remote broker – Required only if the PasswordSupervisor of the two brokers are different; otherwise, the local broker passes its own password to the remote broker.

Examples:

[REMOTE_APPLICATIONS_LIST]

Rich Internet Samples = MyServer.MyCompany.Corp,,Rich Internet Samples,0,1

Rich Internet Demo = MyServer.MyCompany.Corp/5225,,Rich Internet Demo,0,1

BC_Methodology = MyServer.MyCompany.Corp,MyBrokerPassword,DemoBC_Methodology,0,1

[APPLICATION_CLIENTS_MAP]

The purpose of the [APPLICATION_CLIENTS_MAP] section is to let you control which server will receive requests from which clients. For example, when several developers are working on the same project file, a developer can check out an object and command the MRB to assign its own engine on the developer's local machine.

This section is used in source controlled environments, in which developers require that requests sent from their machine will be served by a runtime engine running on their machine (in which project resources were checked-out and modified) rather than by other runtime engines. This is useful during workgroup development, since without explicitly directing requests sent from one developer to its own copy of the application, the developer will have to check-in its change each time, in order to see the change. For example, when a developer activates a request from its Web browser, the developer will most likely prefer to activate its modified copy of the application and not the central copy.

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 user is not logged in to the engine, it is necessary to 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 xpa client to view the version of the application related to that logon.

The syntax of this section is:

<Server name 1>:<client name or IP a1>, <client name or IP a2>…,<client name or IP aN>

<Server name 2>:<client name or IP b1>, <client name or IP b2>…,<client name or IP bN>

...

Explanation:

<Server name 1> will receive requests only from <client name or IP a1>, <client name or IP a2>…,<client name or IP aN>

<Server name 2> will receive requests only from <client name or IP b1>, <client name or IP b2>…,<client name or IP bN>

and so on.

Note: IP addresses can be used only for the clients.

[SNMP] section:

AverageWaitTime

The average time in seconds that a request waits for an available enterprise server. If the average wait time exceeds the AverageWaitTime value, an SNMP trap message is sent to the Network Management Station (NMS).

Syntax: AverageWaitTime = N seconds

Default: 3 (seconds)

AverageProcessTime

The average time in seconds for a request to be processed in an enterprise server. The threshold is checked for all registered enterprise servers each time a request is sent. If the average process time exceeds the AverageProcessTime value, a trap message is sent to the NMS.

Syntax: AverageProcessTime = N seconds

Default: 30 (seconds)

DelayThresholdTraps

The time in minutes that a request of a specified type has to wait between threshold traps to avoid flooding the Network Management Station (NMS).

Syntax: DelayThresholdTraps = N in minutes

Default: 1 (minute)