To understand the usage of the networking environment variables, a brief introduction into MICROS Retail OSCAR POS networking is necessary.
Note:
The OscarPing command can be used for analysis
MICROS Retail OSCAR POS POS uses UDP sockets for the whole communication between process units. The advantage of UDP - or datagram - sockets is that MICROS Retail OSCAR POS has full control over error handling and short timeouts. In the world of TCP, time outs are in the range of minutes and not of seconds which seemed to be unacceptable for a cash register application.
Every part in MICROS Retail OSCAR POS which provides anything to other parts via network is called a service manager. Each service manager has its own socket with a fixed port number (its address). It passes requests and sends responses using a server. Those parts of MICROS Retail OSCAR POS which send requests to a service manager (and wait for the corresponding responses) are called clients. Every time a client connects a service manager, the service manager creates a server which performs the requests and generates the responses. To prevent MICROS Retail OSCAR POS from using too many system resources, each client fetches a socket from a so-called socket pool for every request, uses that socket to receive the corresponding response and releases the socket afterwards.
There are two special objects in MICROS Retail OSCAR POS, a ping client and a ping server, which are present in every process unit and use completely different message layouts. Both objects have their own sockets, and the ping server's socket has a fixed port number.
The ping server is always waiting for a request from a ping client and responds to the request immediately. It checks whether the incoming request is valid and informs the requesting client about the result. In case of an error, both (client and server) cancel all connections between both process units. Of cause, getting no response to a single ping request won't cancel all connections, but getting no response to a configurable number of ping requests within a configurable time will.
The following environment variables may be used in oscar.ini (Windows) or oscar.def (Linux) to change the behaviour of MICROS Retail OSCAR POS networking:
NETDEBUG=”abcdefgh”
Controls which debugging information will be produced by MICROS Retail OSCAR POS networking. All letters (a-h) must be replaced by a digit in the range 0-7. The default is “00000000”. Each digit controls a different part of MICROS Retail OSCAR POS networking, the values are interpreted bit-wise. The described bits can be added to get a combination of more than one debugging feature.
In case bit 3 or above must be set: Use value 8 or 9 to combine with bit 0. To combine with bit 1 or 2, the following values in the ASCII table can be used (:, ;, <, =, >, ?) because Oscar uses [ASCII-code of character - 0x30 (ASCII '0')] to compute the specifif control bits. For example, “NETDEBUG=010?0000” would be a valid value for NETDEBUG, setting bit 0 of component b and bits 0, 1, 2 and 3 of component d.
a controls low-level debug output:
|
Bit |
Value |
Description |
|
0 |
1 |
If set, information about creation and destruction of a socket will be generated. |
|
1 |
2 |
If set, information about sending and receiving data will be generated. |
|
2 |
4 |
If set, all data sent and received will be written to log file. |
b controls debug output of ping server and ping client:
|
Bit |
Value |
Description |
|
0 |
1 |
If set, information about ping server and ping client actions will be generated. |
|
1 |
2 |
If set, information about requests from clients, servers and server managers will be generated. |
|
2 |
4 |
If set, internal status information about the ping client will be generated. |
c controls debug output of clients and global networking functions:
|
Bit |
Value |
Description |
|
0 |
1 |
If set, information about initialisation and error conditions will be generated. |
|
1 |
2 |
If set, information about all networking activities will be generated. |
|
2 |
4 |
If set, all data sent and received will be written to log file. |
d controls debug output of servers:
|
Bit |
Value |
Description |
|
0 |
1 |
If set, information about creation and destruction of a server will be generated. |
|
1 |
2 |
If set, information about server operations will be generated. |
|
2 |
4 |
If set, all data sent and received will be written to log file. |
|
3 |
8 |
If set, RPCDEBUG-like output will be generated on server. |
e controls debug output of server managers:
|
Bit |
Value |
Description |
|
0 |
1 |
If set, information about connect and disconnect requests and error messages will be generated. |
|
1 |
2 |
If set, information about construction, initialisation, manager start/stop and connect requests will be generated. |
|
2 |
4 |
If set, information about data sent and received will be written to log file. |
f controls debug output about notifications about networking events:
|
Bit |
Value |
Description |
|
all |
>0 |
If set, information about notifications will be generated. |
g, h will not be used.
NETDEBUGDUMPSRV=”abcdefgh”
Same structure as NETDEBUG, but will be used if server debugging level has been automatically risen due to a specific event, e.g. failing connect to datalogger, exceeding message queue limit... Default is “700?7000”..
NETDEBUGDUMPCLI=”abcdefgh”
Same structure as NETDEBUG, but will be used if client debugging level has been automatically risen. Default is “70700000”.
NetCompression=x
If x = 1, all frames will be compressed before sending them to the target and de-compressed by the target after reception. In case of any other value, no compression / decompression occurs. Since source and target must perform the same operation, NetCompression must be set equal for all process units communicating with each other. MICROS Retail OSCAR POS 3.5 (>35_002_000_T6): If x=Y, it will be checked on a per-connection-base whether messages should be compressed. It is not necessary that NetCompression=Y is set for all processes communication with each other.
NetMaxTelSize=nnnn
nnnn gives the maximum size of a message transmitted by MICROS Retail OSCAR POS in the network. nnnn may be any value in the range 4096 >= nnnn >= 128 (default: 4096). Since source and target must use the same maximum size to understand each other, NetMaxTelSize must be set equal for all process units communicationg with each other (only MICROS Retail OSCAR POS versions < 3.5 and MICROS Retail OSCAR POS 3.5 versions < 35_002_000_T6).
OSCAR_LAN_ADDR=addr
Sets the ip address of the LAN where a process unit is running. Default LAN address is the LAN defined by OSCAR_SERVER and the net mask. addr can be any valid representation of an ip address, inclusive representations supported by name services. Examples: 10.0.0.0, 10.5.7.14, filiale1, filiale1.de.anker-systems.com.
OSCAR_NETMASK=a.b.c.d
Sets the net mask for the LAN. a, b, c and d are all values in the range 0 - 255. The net mask will be used to check whether any ip address is in the LAN or in the wide area (WAN). The check will be done as follows: The four components of the LAN address (specified by OSCAR_SERVER or OSCAR_LAN_ADDR), converted to the t.x.y.z form, will be bit-wise AND'ed with the corresponding components of OSCAR_NETMASK. The same procedure will be made with any source or target address to be checked. If both results have the same components, the checked address will be seen inside the LAN otherwise processing will be done for addresses in the WAN. Examples: LAN address = 10.1.2.3, Net mask = 255.255.0.0: 10.1.24.55 is inside the LAN, 10.2.47.11 is a WAN address (10 & 255 = 10, 1 & 255 = 1, 2 & 0 = 0, 3 & 0 = 0) and (10 & 255 = 10, 1 & 255 = 1, 24 & 0 = 0, 55 & 0 = 0), but (10 & 255 = 10, 2 & 255 = 2, 47 & 0 = 0, 11 & 0 = 0).
NetRetrys=nn
Maximum number of unacknowledged send requests before all network connections to the target process unit will be cancelled for LAN connections. Each connection uses its own retry count which will be incremented after sending a request and reset after the corresponding response. Maximum 1023, default: nn = 3.
WanRetrys=nn
Same as NetRetry, but for WAN connections. Maximum 1023, default: nn = 3.
NetReconnectRetrys=nn
Same as NetRetry, but only valid for reconnect requests after error condition. Maximum 63, default 1.
WanReconnectRetrys=nn
Same as NetReconnectRetrys, but for WAN connections. Maximum 63, default 2.
NetTimeout=tt
Maximum time (in milliseconds) to receive a response after any request in the LAN. After reaching the time out without getting a valid response, the request will be resent (see NetRetrys). Default: tt = 5000.
WanTimeout=tt
Same as NetTimeout, but for WAN connections. Default: tt = 20000.
WanConnectTimeout=tt
Specifies the time out, in milliseconds, for a connection request in the WAN. Since it might be necessary to establish a physical connection (dialing), this time out can be specified separately. The default value (tt = 20000) is enough for ISDN connections, but for dial up modem connections, tt >= 60000 is recommended.
NetInterleave=tt
Specifies the interleave between ping operations. Whenever a connection will be established between two process units, and whenever this is the first connection between both process units, they will establish a connection between their ping clients and ping servers as well. The ping clients will check one of their connections to other ping servers every tt milliseconds. Default: tt = 5000.
NetSlowInterleave=tt
Any process unit can give its ping client an order to observe whether a given MICROS Retail OSCAR POS server becomes active. For example, this will be used whenever the data base server becomes offline. For all servers to be observed, tt specifies the delay between two ping requests in milliseconds. Default: tt = 8000
ImmediateRetry=b
Normally, after checking the presence of a ping server, the ping client selects the next ping server from its list of connected ping servers for the next check even if the last check failed. If b has been set to 'Y', the ping client will continue checking the same ping server whenever the check fails (with respect to the corresponding time out and retry counters).
NetDebugLen=ll
If set to any value > 0, MICROS Retail OSCAR POS writes a maximum of ll bytes per message, starting at the first byte, to the error log file (corresponds to NETDEBUG=7x77xx).
DiscTimeout=tt
If set to any value >= 0, MICROS Retail OSCAR POS waits up to tt milliseconds during a reconnect request for a currently active request to be completed, if any request is in progress. If a request finds out that a reconnect request is pending, it finishes as fast as possible without sending a response. Keep in mind that this time out value should be as small as possible since all requests coming to the server performing the connection request will be blocked for this time. This value must be smaller than NetTimeout / 2. Default tt = NetTimeout / 50 (100).
PORTBASEUNITn=base
This environment variable can be set for every process unit started by oscard. n specifies the ProcUnitNo of the process unit. base specifies the base port no. for this process unit for dynamically allocated sockets. In other words: If this variable has been specified for a process unit, dynamically allocated sockets don't get a random port no. They get port numbers base, base+1, ... instead.
For details please read the documentations MICROS Retail OSCAR POS Port Setting.
PORTBASEUSER_name=base
This environment variable can be set for login units started with oscar command. name specifies the login name of the user starting the login client. base specifies the base port no. for this client process for dynamically allocated sockets. In other words: If this variable has been specified for a login client, dynamically allocated sockets don't get a random port no. They get port numbers base, base+1, ... instead.
For details please read the documentations MICROS Retail OSCAR POS Port Setting.
PORTBASEUNASSIGNED=base
This environment variable can be set to specify a port base for processes which are neither started from oscard nor from a specific user. This may be true for oscard. base specifies the base port no. for this process for dynamically allocated sockets. In other words: If this variable has been specified for a login client, dynamically allocated sockets don't get a random port no. They get port numbers base, base+1, ... instead.
For details please read the documentations MICROS Retail OSCAR POS Port Setting.
NetInactiveTimeLimit=limit
(Only Windows) Each time a ping request reaches the ping server, the request will be processed by a separate thread which passes relevant data to the Oscar worker thread. In addition – and during inactivity, every limit milliseconds - the ping server thread will check whether all previous server requests have been processed by the Oscar worker thread in the meantime. If not, the thread checks whether the oldest unprocessed request has been reached before more than limit milliseconds. If so, an warning message will be generated, specifying the current delay time, every limit milliseconds until the delay ends.
NetRequestTimeLimit=limit
(Only Windows) In addition to the inactive time limit described previously, this limit sets a maximum time for request handling. If a request needs more than limit milliseconds, a warning message will be generated every limit milliseconds until the request finishes. If the specific server uses an sql database, and the Oscar version supports NetRequestTimeLimit in its sql database module (BfSqlDb.C), the same handling will be made for sql database requests (in that case, the sql statement will be part of the warning instead of object name, class name, function name and task name).
NetRequestQueueLimit=limit
(Only Windows) If more than limit requests have been buffered by the networking helper thread without being processed by the Oscar main thread, a message will be generated and debugging level will be raised to server debugging level. If the number of queued requests falls below limit due to Oscar main thread continues request processing, another message will be generated and debugging level will be reset to default level. Default value for limit: 1000.
MaxRmDbAccessTime=limit
(Only Windows) If an RmDb request has been enqueued more than limit milliseconds ago, the server stops sending WACK answers to the client. This allows the client to go offline after some additional retries. This behaviour has been added because an offline client if better for a user as a client that is waiting for a very long time for a response due to database locks.