AltMessagingServer

Appl

AutoLoopBack

BindFirstIPAddress

BrokerTimeout

CacheEngineConnections

CloseWaitTimeout

CommTimeout

ConvertAlphaFromUTF8ToUnicode

DefApp

DefError

DefHtml

DefName

DefPath

DefProg

EncryptedCommunication

Filter

Handles

HttpSigVars

HttpVars

KeepAlive

LocalHost

LookupLocators

SpaceName

Log

MaxUploadKB

MessagingServer

Password

Priority

RequesterTimeout

RequesterTimeoutSec

RetryMainTime

SpecialAffinity

Username

Keyword

Explanation

Supported Middleware

LookupLocators

The location where each loaded component is situated. ?

GigaSpaces

SpaceName

The specific Space that the Magic xpa server is connected to.

GigaSpaces

HttpVars

For Internet requesters: A list of variables that are sent from the Web server to the activated task, using different requesters: ISAPI or CGI.

Syntax: httpVars=VarName1, VarName2,...

For example: Specifying HTTP_USER_AGENT as a variable causes the requester to pass the browse USER_AGENT string to the Magic xpa server, so that you can identify the client browser version and write your logic according to the version.

Note: Specifying MG_POST_BODY as a variable causes the requester to pass the entire body as a Blob to the Magic xpa server and the Blob is accessed using GetParam('MG_POST_BODY'). Without this variable, the requester extracts information from the body (appname and other arguments) and does not pass the entire body to the engine. Having this variable also means that the ClientFileToServer function will not work.

GigaSpaces and Broker

RequesterTimeoutSec

The maximum duration, specified in seconds. After a request is inserted into a space by the Web requester, this timeout determines the maximum duration that the Web requester waits for a response to be written into the space (by a Magic xpa server).

Default: 60

GigaSpaces

MessagingServer

The address of the broker that receives the requests.

Syntax: MessagingServer = host name/port number

Broker

AltMessagingServer

You may define an additional address for the broker. The requester will refer to this address if the connection to the main Messaging server fails.

The CommTimeout keyword in the Mgreq.ini file (that is located in the same folder as the requester) controls the transition from the primary Requests Broker to the alternate Requests Broker.

The RetryMainTime keyword in the Mgreq.ini file (that is located in the same folder as the requester) controls the transition from the alternate Requests Broker to the primary Requests Broker.

Syntax: MessagingServer = host name/port number

See also How Do I Define an Alternate Broker?

Broker

BrokerTimeout

The maximum time, in seconds, that the request waits for an available engine to be returned by the broker. If the broker cannot provide an available engine within this time, the requester returns one of the following three error codes:

-103 ERR APP NOT FOUND – The application is not listed in the broker’s internal database.

-104 ERR APP IN USE – The application is listed but the supporting engine is busy.

-119 ERR LICENSES EXCEEDED – All enterprise servers supporting the application have reached the values checked-out from the license.

For administration/queries, such as QUERY RT, QUERY APPS, and TERM, the requester waits for a period of time that is calculated as the broker timeout * 5, to allow the broker to handle very large queries. To solve a broker timeout error:

1. In the broker’s directory, increase the number of Magic engines to start (pre-loaded or auto-loaded) in the APPLICATIONS_LIST section of the Mgrb.ini file. You must restart the broker after modifying the Mgrb.ini file.

2. Edit the Mgreq.ini file in the requester’s folder (such as Scripts in case of Web requesters), or the Magic.ini file for running Call Remote operations. Set the Broker Timeout value to a value higher than 10 seconds.

Syntax: BrokerTimeout = n

Default: 10 (seconds)

Broker

KeepAlive

This flag uses the MGrqgnrc.dll file to set an option for each connection it opens, letting you use operating system settings to control the keep alive intervals. The flag only enables the use of the operating system settings. Each operating system has different flags.

When KeepAlive=Y, the Magic xpa Generic Messaging Layer module lets the system administrator use operating-system level-settings to control the keep-alive intervals for each open connection.

Only a system administrator should determine the settings for the operating system intervals.

If the Server Timeout is set to non-zero in the Magic.ini file, then the KeepAlive flag is set by the Magic xpa engine (even if it is not set in the Mgreq.ini file).

Syntax: KeepAlive = Y (default) or N.

Broker

RequesterTimeout

The maximum time, in seconds, that the requester waits for the enterprise server to finish executing a request.

If this timeout expires, the enterprise server does not interrupt the request. In that case, the requester is allowed to continue without waiting for the output.

If the value is 0, the completed task execution time is unlimited. However, requests may still be limited by the TCP/IP’s Stack settings, in which case the returned error will be –107 because the connection to the enterprise server will be reset by the TCP/IP stack. When this timeout is set to a non-zero value and the timeout expires, error –110 is returned.

When executing a remote call from the engine, the Requester Timeout in the Magic.ini file overrides this Mgreq.ini setting.

Syntax: RequesterTimeout = n

Default: 0 = infinite

Broker

CloseWaitTimeout

Defines a mechanism for closing “semi-closed” connections, that is, connections that were closed by a peer.

If you have any previously-connected brokers or engines that were shut down and then restarted at the same address, though the module initiating the connection was not shut down, semi-closed connections will exist. You can use the CloseWaitTimeout keyword and define whether the connections are either automatically closed when the next request is received or after a certain defined period of time.

Note: This keyword is recommended when normally your broker and engines are shut down but the Web server is not shut down.

Allowed values:

• Positive value: The duration, in minutes, between periodical closing of all semi-closed connections. For example, if you enter 5, any semi-closed connections will be closed every five minutes.
  In addition, each semi-closed connection is closed as and when it is encountered by the requester.

• -1: No periodical closing and semi-closed connections are only closed as they are encountered.

• 0: Semi-closed connections are never closed, either periodically or as they are encountered.

Default: 0

Broker

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.

Broker

Priority

Optional. The default priority for requests that were not assigned a specific queue priority, 0 to 9 with 9 as the highest priority. The priority is used by the MRB only, to assign free engines to un-prioritized requests.

Syntax: Priority = n

Broker

Username, Password

Optional. The default user name and password that is submitted with unidentified non-RIA requests.

Syntax: Username = string Password = string

Note: For the GigaSpaces middleware, refer to the system property -Dcom.magicsoftware.xpa.DefaultUserNameAndPassword.

Broker

DefPath, DefName

Optional. A directory and filename default for a requests specified without a filename.

Syntax: DefPath = DefName =

Broker

DefHtml

This keyword is deprecated and has been replaced with the DefError keyword.

Broker

DefError

Optional.

If the DefError has a value, the generic Web requester, such as MGrqispi.dll, returns errors in HTML or XML formats (according to the value).

In Rich Client tasks, only the HTML format is supported. (Since version: 1.8 SP1 for Browser Client and 1.9 for Rich Client)

The file can be an HTML file or an XML file.

For the HTML file, there are two methods:

• Mergeable – Use the full path name of an HTML file, such as DefError = c:\filename.html. This method will merge the details collected by the Web requester into the specified file. Refer to DefError File Structure for the tags that can be used.

• Dynamic – Use a URL that will return the result file, such as DefError = http(s)://server/alias/filename.html. This method initiates a two-request sequence, relying on the browser's ability to execute JavaScripts/Frames. In Rich Client task, this method is not supported – only mergeable HTML pages can be displayed to end users. Click here for a dynamic HTML example.

For the XML file, there are two methods:

• Mergeable – Use the full path name of an XML file, such as DefError = c:\filename.xml. This method will merge the details collected by the Web requester into the specified file. Refer to DefError File Structure for the tags that can be used.

• Constant – Use the constant 'XML', such as DefError = XML. This method will merge the details collected by the Web requester into a default XML file. Refer to DefError File Structure for the XML that will return.

Use the full path of an XML file and not Web server aliases.

Note: For the GigaSpaces middleware, refer to the system property -Dcom.magicsoftware.xpa.DefaultErrorFormatFileName.

Since version: 1.5

Broker

DefApp, DefProg

Using these two keywords, the requester allows you to define the default application name and program name to be used whenever the APPNAME or PRGNAME is missing in the URL. This removes the need to specify and manage the APPNAME and PRGNAME in the URL addresses in the Web pages and will also hide the entry point of the program.

You can define both of the keywords or just one of them.

If both the APPNAME and PRGNAME are missing in the URL, the ARGUMENTS will also be removed from the URL, so the URL will be much shorter and simpler.

Note: For the GigaSpaces middleware, refer to the system property -Dom.magicsoftware.xpa.DefaultApplicationAndProgramNames.

Since version: 1.8

Broker

.

Appl

Allowed application names separated by a comma. When not specified all applications are allowed.

Syntax: Appl=applic 1, test 2, abc,...

Exceptions: This keyword is not supported for Rich Client applications.

Broker

AutoLoopBack

Y/N (default = Y) The default until version 1.9 was N.

Even when partitioning modules (requester, broker, enterprise server) are on the same computer, there may be a problem when the network is disconnected. For example, when the network cable is unplugged, the Windows operating system aborts all established connections on a computer connected to the network. You can prevent this by using this flag.

Whenever a partitioning module connects to another partitioning module and this flag is used, Magic xpa uses the localhost IP address, 127.0.0.1, instead of trying to resolve the hostname using the DHCP. As a result, the connection between the modules stays intact when the network connection is lost.

Note: The host name is substituted by 127.0.0.1 in the lower TCP/IP level, which is logged only by the mgreq.ini file.

Broker

Log

A reference to a file that logs low level requester activities

Syntax: LOG = ( [log file path and name] [Sync] [Level] [Number of Lines Threshold] )

Example: LOG = Requester.log Y S 50000

log file path and name: Any valid name that does not include spaces. Make sure that the folder of the log file was added to the Authenticated Users group (Folder properties -> Security tab -> Add to the Authenticated Users group with Full Control permission).

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 and to share the log file with several modules.

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.

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 level of logging.

S – Support level – An intermediate level of logging.

R – R&D level – The highest level of logging.

Number of Lines Threshold: (Since version: 2.4c)

The threshold is hard-coded to 100,000 lines of log. You can change the number using this optional parameter. The default is no number and, in that case, 1000,000 will be used. This setting applies only to the server-side log and not to the RIA log.

Broker

BindFirstIPAddress

BindFirstIPAddress=Y/[N]

Y – During binding to a port, the server will resolve the host name and will bind to the resolved IP address.

N – The server will bind to any IP address (*.port - for backward compatibility).

Broker

MaxUploadKB

The MaxUploadKB setting determines the maximum size of a file upload – MaxUploadKB=nnnn. The size is defined by kilobytes.

If a file larger than the limit is submitted, the Magic requester does not process the request, and returns the following error message to the client:

File upload failed: file size exceeds maximum size limitation.

The error code is –260 and the error message text is: "File upload failed: file size exceeds maximum size limitation.".

If the MaxUploadKB parameter is not defined, set to zero, or to a negative value, Magic xpa will upload any file, regardless of size.

Uploading large files can create congestion in the enterprise server.

Broker

Handles

Specifies the maximum number of sockets that can be opened by the broker, enterprise server, or requester, depending on the location of the file.

Default = 1,000 (minimum value)

Broker

RetryMainTime

Determines the time interval that a requester connected to an alternate Request Broker waits before trying to reconnect to the main Request Broker. This setting applies only to persistent requesters, such as ISAPI and APACHE.

The time interval is specified in minutes.

The RetryMainTime default is 5. The minimum value that can be entered is 1.

If the requester is already connected to the main Request Broker, the RetryMainTime setting does not apply.

When RetryMainTime=0, the requester does not try to connect to the main Request Broker but remains connected to the alternate Request Broker.

Syntax: RetryMainTime=nn

Broker

SpecialAffinity

SpecialAffinity = Y/N/ numeric value (Windows specific)

This value can be used to force the current process (e.g. broker or enterprise server) to use only one CPU (multi-processor machines).

If a numeric value is used, it will force a CPU number. If the given value is numeric but exceeds the number of CPUs, the CPU number will be randomized (as is the case for Y). If the given value is not numeric, the behavior will be as for N. (Since version: 1.8 SP1)

The default is N.

Broker

Filter

You can use this keyword for the requester to send a filter with each request by entering:

[REQUESTER_ENV]
Filter = <key name>

For requests that did not originate from the runtime engine, such as command line or ISAPI, the <key name> from the Mgreq.ini file is sent to the broker with each request.

Refer to Filters for a detailed explanation about filters.

Broker

LocalHost

LocalHost = text

This keyword can be used to force a host name when accessing addresses that only have a port number.

By default, the current host name is used.

Broker

HttpSigVars

Setting requests for execution within a defined context without any client identification means that any user can create a user-defined request with the same context identifier. To avoid this, the browser context requires some or all of the following client-side identification:

• Client-side IP, such as REMOTE_ADDR

• Client-side host name, such as REMOTE_HOST

• Client-side user name, such as REMOTE_USER

• SSL related information, such as HTTPS, SSL_CLIENT_KEY_SIZE

• User-defined cookie variables

Broker

ConvertAlphaFromUTF8ToUnicode

Affects the conversion done from UTF8 to Unicode.

When set to Y, alphanumeric arguments are converted by the runtime-engine from UTF-8 to Unicode. They remain Unicode if the accepting parameter in the called program is Unicode; otherwise it is converted automatically according to the standard conversion rules from Unicode to Alpha.

If the conversion from UTF-8 to Unicode fails or when this parameter is set to N, arguments are passed to the called program without any modification.

Syntax: ConvertAlphaFromUTF8ToUnicode= Y (default) or N.

Broker

CacheEngineConnections

Determines whether connections from a requester to the runtime-engine will be cached.

When set to N, each request will open/close a new connection to the runtime-engine that was assigned to serve the request (not recommended).

When set to Y, the current behavior will be kept.

For Web requests, Mgreq.ini in the scripts folder needs to be modified.

For command line, broker-monitor, and remote-calls, Mgreq.ini in the default installation folder needs to be modified.

Syntax: CacheEngineConnections = Y (default) or N.

Broker

EncryptedCommunication

EncryptedCommunication = <Cipher Code>,<key Size (in bits)>

Instructs the requester, broker, and engine to encrypt all messages between them using a commercial symmetric encryption algorithm.

The symmetric key for each connection is randomized and transmitted encrypted using asymmetric encryption (RSA).

For example: EncryptedCommunication=3,64 will use the DES Algorithm with 64 bits key.

Note that you should define the same value in all of the mgreq.ini files.

The codes that can be used are:

Platform specific: This keyword is not currently supported for IBM i servers.

Since version: 1.8

Broker