AltMessagingServer

Appl

AutoLoopBack

BindFirstIPAddress

BrokerTimeout

CacheEngineConnections

CloseWaitTimeout

CommTimeout

Community

ConvertAlphaFromUTF8ToUnicode

DefApp

DefError

DefHtml

DefName

DefPath

DefProg

EnableAgent

EnableTraps

EncryptedCommunication

Filter

Handles

HttpSigVars

HttpVars

KeepAlive

LocalHost

Log

MaxUploadKB

MessagingServer

NMSAddress

Password

Priority

ReportStatusCode

RequesterTimeout

RetryMainTime

SpecialAffinity

Username

Version

Keyword

Explanation

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.

MessagingServer

The address of the broker that receives the requests.

Syntax: MessagingServer = host name/port number

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?

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)

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.

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

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

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.

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

Username, Password

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

Syntax: Username = string Password = string

DefPath, DefName

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

Syntax: DefPath = DefName =

DefHtml

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

DefError

Optional.

If the DefError has a value, the generic Web requester, such as MGrqispi.dll and MGrqcgi.exe, 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)

For Internet requesters: A filename that can be queried by an Internet requester and can be displayed if the called program does not return any result. The file can be an HTML file or an XML file.

For the HTML file, there are two methods:

• Static – Use the full path name of an HTML file, such as DefError = c:\filename.html. This method will send the HTML file as-is to the client.

• 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 static HTML pages can be displayed to end users. Click here for a dynamic HTML example.

For the XML file, there are two methods:

• Static – Use the full path name of an XML file, such as DefError = c:\filename.xml. This method will merge the details collected by the generic 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.

Aliases cannot be used.

Since version: 1.5

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.

Since version: 1.8

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.

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.

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.

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).

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.

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)

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

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.

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.

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.

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

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.

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.

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

[SNMP] section:

EnableAgent

EnableAgent = Y, N (default)

Determines whether the Magic xpa SNMP agent extension is active. If EnableAgent = Yes, the Network Management Station (NMS) is enabled to monitor Magic xpa.

The EnableAgent setting is automatically set to Yes during installation only if the Magic xpa SNMP extension is installed.

This is only valid in the mgreq.ini that is found in the SNMP directory.

EnableTraps

EnableTraps = Y, N (default)

Determines whether the requester will send trap messages to the SNMP monitor.

This is only valid in the mgreq.ini that controls the enterprise server, broker and requester. It is ignored in the mgreq.ini found in the SNMP directory.

NMSAddress

The Host name or TCP/IP address of the server that has the NMS installed.

The default is: localhost, the default SNMP port.

This is only valid in the mgreq.ini that controls the enterprise server, broker and requester.

Platform specific: The port option is for non-Windows platforms.

Version

Version = 1,2 (default: 1)

The supported NMS version.

This will send traps in the SNMP Protocol format of that version. This is only valid in the mgreq.ini that controls the enterprise server, broker and requester. It is ignored in the mgreq.ini found in the SNMP directory.

Community

A community name (default: public). The community name acts as a password to the NMS.

Valid values: Alphanumeric value, as specified by the NMS as its community token. This is only valid in the mgreq.ini that controls the enterprise server, broker and requester. It is ignored in the mgreq.ini found in the SNMP directory.

ReportStatusCode

ReportStatusCode = xxx

xxx – is the status code that will be trapped by the monitor.

The error codes that will be sent to the SNMP monitor. They can be displayed as a list separated by commas, a range of values, or as both; for example: 103,104,105, or 102-107,109. To monitor a full range of error codes, enter 0-9999.

Although the error codes are negative values, they are displayed as positive values to prevent confusion when the error codes are displayed as a range of values.

This is only valid in the mgreq.ini that controls requesters, such as ISAPI. It is ignored in the mgreq.ini found in the SNMP directory, or when being used by the enterprise server or the broker.