Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Installation Guide
Release 1.0.8.4
March 2003
Contents
Oracle Mobile Application Server for Industrial Applications ................................. 1 Contents......................................................................................................................... 2 Preface ........................................................................................................................... 3
Intended Audience.............................................................................................................................. 3
Server Administration................................................................................................... 7
3.1 mwactl script ................................................................................................................................. 7 3.2 Starting up server ......................................................................................................................... 8 3.3 Shutting down server .................................................................................................................... 9 3.4 Running AutoConfig...................................................................................................................... 9 3.5 mwa.cfg ...................................................................................................................................... 10
1
Preface
The Mobile Application Server is available in two forms: Mobile Applications Server for Self-Service Applications Mobile Application Server for Industrial Applications
Although the Mobile Application Server for Self-Service and the Mobile Application Server for Industrial are shipped in the same category, they are two independent products that only share the same configuration file. Thus, a customer who intends to run the Industrial Applications only needs to read and perform the setup in this document. Similarly, a customer who intends to run the Self-Service Applications does not need to read and perform the setup in this document. This manual covers the installation and implementation of the Mobile Application Server for Industrial Applications. The server will be referred to as the Mobile Industrial Applications Server throughout this document.
Intended Audience
This manual is intended for people responsible for installing the Mobile Industrial Applications Server, such as: Database Administrators System Administrators Technical Specialists
2
Getting Started
The Mobile Industrial Application Server is basically a server process that provides the run-time engine for Industrial Applications such as Warehouse Management System, Inventory, Work-In-Process, and Quality Assurance. These Industrial Applications are modules that sits on top of the framework that is provided by the Mobile Application Industrial Server. The Mobile Industrial Application Server functions as a middle-tier between the hand-held devices that functions as clients and the database server. The following diagram shows an overview of the Mobile Industrial Application Server.
WMS
INV
WIP
Database Server
This chapter explains how to install the Mobile Application Server for Industrial and contains the following sections: Mobile Application Server for Industrial Requirements Mobile Application Server for Industrial Installation Confirming Successful Mobile Application Server for Industrial Installation
Java Development Kit (JDK) o Refer to the README-Config-JDK.html document in the patch for more information.
Oracle JDBC o Refer to the README-Config-JDBC.html document in the patch for more information.
Note that the Mobile Industrial Application Server does not need Apache server to run.
To install the Mobile Application Server for Industrial, complete the following 6 steps. 1. Change directory to <APPL_TOP> 2. Run the APPLSYS.env script, located in <APPL_TOP>, to set all the necessary environment variables. After this step, $MWA_TOP environment variable has been set to the right directory. 3. Now we are ready to start the server. Go to $MWA_TOP/bin directory and issue the following command: In Unix-flavored system: mwactl.sh start [port_number] In Windows-flavored system: mwactl start [port_number] 5
If the port_number parameter is not specified, the port number specified as mwa.TelnetPortNumber in mwa.cfg will be used. Note that in Unix-flavored system, depending on how many users you like to connect to the server, you might need to increase the limit of the file descriptors. To do this, go to korn shell by tying ksh and issue command ulimit n 1024. This step needs to be done before the mwactl.sh is run. 4. This step is optional. It involves starting up the dispatcher process that is used to support more users and perform load balancing. Before you can start the dispatcher, you need to specify the port number where the dispatcher process will be listening to in the mwa.cfg. In mwa.cfg, modify mwa.Dispatcher to reflect the hostname and the port number of the dispatcher. For example, the localhost is ap100sun and the port to run the dispatcher on is 3223, thus you specify the property as follows, mwa.Dispatcher=ap100sun:3223. Once that is done, to start the dispatcher, go to $MWA_TOP/bin and issue the following command: In Unix-flavored system: mwactl.sh start_dispatcher In Windows-flavored system: mwactl start_dispatcher
Again, in Unix-flavored system, depending on the number of users you like to connect to the dispatcher, you might need to increase the limit of the file descriptors. To do this, go to korn shell by tying ksh and issue command ulimit n 1024. This step needs to be done before the mwactl.sh is run. 5. Test to determine if your installation was successful.
2.4 Confirming Successful Installation of Mobile Application Server for Industrial Applications
To test the Mobile Application Server for Industrial install, use any telnet client and connect to the server with the corresponding hostname and port number. You should either see a Device List page or a Login page. If you dont, please check the troubleshooting section.
3
Server Administration
This chapter contains the following sections: mwactl script Starting up server Shutting down server mwa.cfg
Usage
This parameter is required only if you are shutting down the server. Use the username and password that has System Administration responsibility in Oracle Application. Used to set java options. For example, you can set the initial and maximum Java heap size by speficifying "ms" and "-mx" values. The java_config parameter is optional. If you don't specify it, -java_config defaults to "-ms64m -mx128m". Used to specify the location of your Mobile Applications root directory. For example, if Mobile Applications is in /d3/mwa, you would specify an mwatop of "/d3/mwa". This parameter is optional. If you don't set the parameter here, however, mwactl will look for
java_config
mwatop
an MWA_TOP environment variable. You must specify either "start" or "stop" or "stop_force" to start or stop gracefully or stop forcefully the server respectively. The "stop" option is used to shutdown the server gracefully while the "stop_force" option is used to start|stop|stop_force shutdown the server forcefully. Stopping the server gracefully will shut down the server after 60 seconds if there is no user logged in. Server will wait for all users to log out before stopping. Stopping the server forcefully will shut down the server without any delay. You can specify the port on which to start the server. This parameter is optional. If you don't specify it here, the server looks for the property in your mwa.cfg file. The default port number is 2323. Note that most traditional Telnet daemons are started on port 23, so you'll want to avoid starting your server on this port. Also note that the server uses port n+1 for communicating with the Server Manager, where n is the port on which you start the server. So if you start the server on port 2323, then port 2324 is also taken up and you won't be able to start the server on port 2324.
[port]
3.5 mwa.cfg
The mwa.cfg file, located in $MWA_TOP/secure, is used to store configure information for the server. Note that this file is used by both the Mobile Industrial Application Server and Mobile Self-Service Application Server. Please also note that this file is created by autoconfig during installation, and users should not be editing this file manually. You can also use a different mwa.cfg file than the one located in $MWA_TOP. To do this, use the java_config D mwa.cfg=<location of the cfg file>.This still requires the location of mwatop, but will use the cfg file provided in the config option and not the one located in $MWA_TOP/secure. If you need to make modifications to this file, you should be editing the Applications Context File (<TWO_TASK>.xml) and running the AutoConfig utility to propage these changes as explained in the Running AutoConfig section. You must do so before starting the server. If you make modifications to this file while the server is running, you must restart the server in order for the changes to take effect. Below is the description of each property in the Applications Context File (<TWO_TASK>.xml) that is relevant only to Mobile Industrial Application Server. All properties that are not between the <oa_mwa_server> and </oa_mwa_server> tags in this file belong to other products and thus, can be ignored for configuring Mobile Industrial Application Server. Applications Context File Properties Tag Description
The port on which to start the server. Traditional Telnet servers are started on port 23, so you should start the Mobile Application Server for Industrial on another port (like 2323). Note that you can also specify the port number when starting the server using the mwactl utility; the port you specify using mwactl overrides the port specified in this property. Also note that the server uses port n+1 for communicating with the Server Manager, where n is the port on which you start the server. So if you start the server on port 2323, then port 2324 is also taken up and you won't be able to start the server on port 2324. The time (in minutes) that a client from a broken session is allowed to take before reconnecting to the server. For example, if the value is "120", a client that has broken its connection to the server has 2 hours to reconnect to the server. After 2 hours, all data associated with the first connection will be lost.
mwaPortNo
mwaDropConnectionTimeout
10
mwaStaleSessionTimeout
MwaLogLevel
mwaDispatcherThreadCount
mwaDispatcherClientsPerWorker
MwaJVMb
The time (in minutes) to leave an idle Telnet session active. Set this property to set the appropriate level of messages logged to your System Log file. Possible values are: fatal, error, warning, debug, and trace. Fatal is the most restrictive: it will display only messages from fatal errors. Trace is the least restrictive: it will log all messages. Set this property to enable the log file rotation. Possible values are "Yes" or "No". The size (in bytes) that determines when log file should be rotated. The port on which to start the dispatcher. This property is read by dispacther only and it is used to find out how many worker thread a dispatcher should have. This property, together with mwa.DispatcherClientsPerWorker, will dictate how many total number of clients can connect to a dispatcher. This property is read by dispatcher only and it is used to control how many clients should be handled by one worker thread. This property, together with mwa.DispatcherClientsPerWorker, will dictate how many total number of clients can connect to a dispatcher. Some JVM implementation has a bug in its network implementation. This property tells the server that the bug is present in the JVM used so the server will perform a work-around for the problem. Possible values are "TRUE" or "FALSE". Please note that property value are case-sensitive.
Some values in the mwa.cfg configuration file are defined with respect to Applications standards, and should not be changed. Below is the description of these predefined parameters:
This specifies the directory where server log file should be located. When this property is not specified, server will use directory $MWA_TOP/log. Default value: Standard Applications log directory. The name to use for your server log file. The port number on which you have started the server will be prepended to the beginning of this file name. For example, if you start two servers, one on port 2323 and one on port 2325, and you specify a System Log file name of "system.log", then you'll find the following files in your $MWA_TOP/log directory: 2323.system.log and 2325.system.log Default value: system.log The directory that contains the dbc files
mwa.logdir
mwa.SystemLog
mwa.DbcFolder
11
mwa.DbcFile
mwa.InitialPoolSize
mwa.Dispatcher
mwa.TelnetServer
that are specified in mwa.DbcFile property. Default value: <FND_TOP>/secure This property (a string of comma-separated values) lists all the dbc files that server should use. Server will find the dbc files under directory that is specified by mwa.DbcFolder property. Default value: <Database Host Name>_<Database SID> This specifies the number of database connections created in the pool at server initialization. Default value: 3 This property tells the server where to find a dispatcher (hostname:port). At any time, server will always try to connect to the specified hostname and port to register itself. This will make the dispatcher truly plug-and-play. Default value: <Hostname on which AutoConfig is started>:<mwaDispatcherPort> This lists all the instances of Mobile Application Server for Industrial and the ports. It is only used by Server Manager tool to find out all the instances of server that it should manage. For this reason, the list should be maintained up-to-date. Otherwise, Server Manager will not work properly. Default value: <Hostname on which AutoConfig is started>:< mwaPortNo>
12
4
Device Configuration
This chapter describes how to perform device configuration to existing devices or add and register new devices. It has the following sections: deviceIP.ini default_key.ini How to add / register new device
4.1 deviceIP.ini
The deviceIP.ini file, located in $MWA_TOP/secure, is used to administer all the different devices that will be used as clients. Server can see your device only if you register your device through changing the file deviceIP.ini. Note that, deviceIP.ini file is also managed by AutoConfig, and special care must be taken to modify this file. Changes should be made only between Begin customizations and End customizations blocks, otherwise all changes made might be lost, or successive AutoConfig runs might invalidate this file: //# ******************** //# //# Begin customizations //# //# ******************** Changes must be made in this area //# ******************** //# //# End customizations //# //# ******************** 13
If you need to make modifications to this file, you must do so before starting the server. If you make modifications to this file while the server is running, you must restart the server in order for the changes to take effect. The file has two sections. The first section marked [devices] maps a device to a device configuration file. The second section marked [map] maps IP address to device configuration file. When a server receives a client connection, it tries to use the client's IP address and the information in the second section to find a device configuration file for that connecting device. When there is no match, a list of devices that are stored in the first section of the file will be presented to user for selection. Below is a description of the two sections of deviceIP.ini. deviceIP.ini Sections Description
This section contains all the devices that will be presented to the user for selection when server could not find a device configuration file for the connecting device. The format for each line is DeviceName=DeviceConfigFile. Only the DeviceName part will be shown to the user. When the user selects a device from the list, the corresponding device configuration file will be used. DeviceName is translateable through AK prompt. The prompt that will be shown is stored in AK prompt under region "MWARUNTIME" and attribute_code "INDUSTRIAL_" + DeviceName, e.g. "INDUSTRIAL_DEFAULT". This section lists mappings of IP address to device configuration file. It is used by server to determine which device configuration file to use for a connecting device. The format for each line is IP_Address=DeviceConfigFile. Wildcard at the end of IP address is supported.
Section
[device] section
[map] section
4.2 default_key.ini
The default_key.ini, located under $MWA_TOP/secure, is provided as a default device configuration. You should have one device configuration file for each different device that you like to customize. Otherwise, the default device configuration will be used. If you need to make modifications to this file, you must do so before starting the server. If you make modifications to this file while the server is running, you must restart the server in order for the changes to take effect. There are two parts of configuration in the file. The first part lists key binding that is used for the device. The second part of the file specifies the characteristic of the device, e.g. width, height, etc. After a client has connected to a server successfully, pressing help key (F1) will display the configuration of the device that is used for that specific client. Below is a description of each property in the device configuration file. 14
Property
The format for each line in key binding is ACTION=KEY. ACTION specifies a logical action that server will understand when KEY is pressed in the device. ACTION is translateable through AK prompt. The actual text of an action is taken from AK prompt under attribute code Key binding "INDUSTRIAL_" + ACTION, e.g. "INDUSTRIAL_MWA_HELP". The permissible ASCII value for the KEY are CONTROLA to CONTROLZ and F1 to F4, except as follows. The following key: CONTROLH, CONTROLI, and CONTROLM, should not be used at all as it conflicts with navigation key (backspace, tab, and enter respectively). The ASCII value that is used to indicate that data that DATASTREAMINDICATOR is coming from a stream, e.g. barcode. The default width of the device. This value is used if DEFAULT_WIDTH the device is not capable of negotiating its dimension (width and height). The default height of the device. This value is used if DEFAULT_HEIGHT the device is not capable of negotiating its dimension (width and height). The default terminal type of the device. This value is DEFAULT_TERM_TYPE used if the device is not capable of negotiating its terminal type. This property specifies the ratio between field prompt and field value. For example, if the value is "1:1", then PROMPT_RATIO the width will be shared equally between the prompt and value (if width is 20, then field prompt is restricted to 10 characters). This property specifies the character set that is used by the client. This property is used by the server so that CHARACTER_SET it will use the correct character-to-bytes conversion. Example: UTF8, CP1252, Unicode, etc. The ASCII value that corresponds to positive sound in the device. For example, when the value is "7", the device POSITIVE_SOUND will make a bell sound (ASCII 7 corresponds to bell sound in most device). The ASCII value that corresponds to negative sound in the device. When the value is comma separated string, then the server will send all of them sequentially. For NEGATIVE_SOUND example, when the value is "7,7,7", the device will make bell sound three times. This property specifies whether the device will be running in block mode or not. Possible values are yes or no. If this value is set to yes, the server will BLOCK_MODE not echo input that is coming from the client and the server will consume the enter key in places where the enter key is not required when the device is running in char mode.
There are two things that need to be done in order to add and register a new device to the server:
1.
You need to create a device configuration file. You can use default_key.ini as a template by copying it and modifying it as necessary. Some of the things that is usually modified in the new device configuration file are as follows: DATASTREAMINDICATOR: the ASCII value used to indicate that data is coming from a stream, e.g. barcode. The ASCII value that you entered here needs to match the ASCII value of the character that is prepended by the device to the barcode. DEFAULT_WIDTH: default width of the device. This value is used if the device is not capable of negotiating its dimension. DEFAULT_HEIGHT: default height of the device. This value is used if the device is not capable of negotiating its dimension. CHARACTER_SET: the character set that is used by the client. This property is used by the server so that it will use the correct character-to-bytes conversion. Example: UTF8, CP1252, Unicode, etc. BLOCK_MODE: tells whether the device will be running in block mode or not.
2.
You need to make modification to deviceIP.ini. The deviceIP.ini file, located in $MWA_TOP/secure, is used to administer all the different devices that will be used as clients. Server can see your device only if you register your device through changing the file deviceIP.ini. Add a new entry in the [device] section for your new device configuration file.
16
5
Troubleshooting
Q: The server doesnt start successfully. A: Make sure you have the right environment. Things that should be checked specifically are: environment variable $MWA_TOP make sure deviceIP.ini file exists in $MWA_TOP/secure directory. If it does not exist, run the AutoConfig utility as explained in the Running AutoConfig section. make sure mwa.cfg exists in $MWA_TOP/secure directory. If it does not exist, run the AutoConfig utility as explained in the Running AutoConfig section. make sure dbc folder and files exists make sure log directory/file is accessible for writing.
Q: I dont see any page coming up after I connect to the server. After I press any key, then the Login Page comes up. A: Try setting mwa.JVMAvailableBug property in mwa.cfg to TRUE and restart the server. Note that the value is case-sensitive. Q: I am having navigation problems. Most of the time, I am stuck and need to press Ctrl-C to move on. A: Try setting mwa.JVMAvailableBug property in mwa.cfg to TRUE and restart the server. Note that the value is case-sensitive. Q: The server doesnt allow me to connect if X users have already connected. A: If you are running the server in Unix-flavored system, try increasing the file descriptor limit. Q: There is a long response time between the server and the client. A: Try load balancing (starting multiple Telnet servers and the dispatcher). 17
Q: The server drops my connection to the server if I have been idle for more than a couple of minutes. A: Try increasing the "mwa.StaleSessionTimeout" value in the mwa.cfg file.
18
Appendix A
Dispatcher
A.1 Dispatcher overview
If users are facing slow response times, it might be necessary to distribute the load between servers. This is generally recommended if you have 20 or more clients connecting to the server. You can distribute the load merely by starting up a dispatcher and multiple mobile servers. Multiple servers can be started in a single machine with different ports or in multiple machines. Just follow the startup instructions to do this. Please remember when you start up the Mobile Application Server for Industrial with port n, port n+1 is also taken at that time. So, for example, you will be able to start two servers on ports 2323 and 2325, but not on 2323 and 2324. Each server you start effectively starts a different process and uses a different JVM. It is in this way that loadbalancing is achieved. In using dispatcher to perform load balancing, clients should be connecting to dispatcher instead of the individual server. Also note that the dispatcher and the servers can all be located in different machines. The following is a figure that shows N clients connecting to a single dispatcher and client requests are distributed to M Mobile Application Server.
19
Things to note in load balancing: <APPL_TOP> should be nfs shared between all the different machines where the dispatcher and the servers are running. This makes sure that server configuration file (mwa.cfg) is identical and shared throughout different instances of the server and the dispatcher. Make sure there is no collision of log file in the different instances of the server. One way to avoid this issue is to use different port for different instances or make the server log into a space that is local at the local machine (not nfs shared). Typically the system shell has a very conservative limit on the maximum number of sockets/files that can be open by all its children. Therefore if you run several Telnet Servers and/or the Dispatcher on the same machine, you should start them from different shells. In addition before you start up a Telnet Server or Dispatcher, you should adjust ulimit for that shell to a reasonably high value (for example "ulimit -n 1024" should be good enough). This holds even in cases when you just run a single Telnet Server with no dispatcher, since it is VERY easy to reach the limit of 64 file descriptors---the typical default value. Note also that some shells might not permit you to set ulimit properly. You might need to switch to "ksh" before setting the ulimit and running the Telnet Server or Dispatcher (see example below).
Before starting up dispatcher, make sure you set the environment correctly, i.e. all the installation steps mentioned in the beginning of the document have been performed and APPLSYS.env script has been run. One mandatory property in mwa.cfg that needs to be set up for dispatcher is the mwa.Dispatcher property. For example, if the port to run the dispatcher on is 3223, then you specify the property as follows, <mwaDispatcherPort oa_var="s_mwaDispatcherPort">3223</mwaDispatcherPort> After the environment is set up properly, to stop the dispatcher, go to $MWA_TOP/bin and type: mwactl stop_dispatcher
21
Server Manager
This chapter contains the following sections: Server Manager Overview Start/Stop Server Monitor Server
23
There are two regions in the "Start/Stop" server page. The "Server Dispatcher" region displays the status of the server dispatcher. If there is a server dispatcher running, two buttons will be provided to control the server dispatcher. Pressing "Shutdown" will shutdown the server dispatcher, while pressing "Bounce" will shutdown and restart the dispatcher. The "Start/Stop Server" region displays the status of Mobile Application Server for Industrial and provides controls to stop them. The region contains a pop list of machine names, a table that summarizes the server status on the selected machine, and three control buttons. To view Mobile Application Server for Industrial status on other machines, choose the machine name from the "Server Host" list and then press the "Change Server Host" button. To stop an Mobile Application Server for Industrial on a certain port, simply click the "Stop Server" link in the corresponding row of the "Server Status" table. To stop all Mobile Application Server for Industrial on current selected machine, click the "Stop All Servers" button. The server manager may ask you to enter a user name and password to perform the action. Please enter a user/password that have the "Administrator" privilege in Oracle Applications. This user/password pair may not be the same as the one you used to login to the server manager. The user name and password will only be asked once during a session. Currently, The server manager does not support starting the server dispatcher or Mobile Application Server for Industrial. Please refer to other section of the document for how to manually start them.
Information" contains a table that displays server dispatcher information such as servers registered, clients, clients per worker, etc.
The "Server & Session Information" displays status information about individual servers and user sessions if there is any. Controls for terminate a user session and for messaging are also provided in this region. Below is a screen shot of the region:
The "Server Host" list contains a list of server machines. To view information for a particular server machine, simply choose the machine name from the list and click the "Change Server Host" button.
25
The "Server Status" table summarizes the server status on all ports of the selected machine. The information includes, server uptime, current sessions, total sessions, total memory, used memory, etc. The "User Sessions" table shows information about user sessions on the selected machine and provides controls for messaging and terminating session. To terminate a user session, click the icon in the "Terminate" column of the corresponding row in the table. This will lead you to a confirmation page. Press the "Terminate" button near the page bottom to actually terminate the session, press "Cancel" to return to the "Monitor" page. There are three messaging methods provided around the user sessions table: To post a message to a particular user, click the "Post A Message" link in the corresponding row of the user sessions table. To broadcast a message to all user sessions on the selected server machine, click the "Broadcast to Host" button. To broadcast a message to all user sessions on all server machines, click the "Broadcast to All Hosts" button. In the message page (shown below), enter a short message in the edit box and click "Submit" to post/broadcast the message. When the Mobile Application Server for Industrial receives the message from the server manager, it would put the message in the event queue. When the handling event is called, the message would be popped on the client screen.
26
The "Database" region allows users to view the contents of dbc files. This region is made read only because users are not supposed to change dbc files. Select dbc file name from the "DBC file" list and click "View" will view the content of the selected dbc file. After making the changes, press the "Save" button to save the change to your mwa.cfg file. Please make sure that the file and the directory that contains the file are writable to the apache user. Press "Cancel" to discard the changes.
28