ERP-Scale Handbook Version 3.0.5

Transcription

1 Handbook 1 March 2010

2 Trademarks and Copyright SapScale Pocket Programs All rights reserved. Pocket Programs All rights reserved. SAP & SAP ERP are registered trademarks of SAP AG. Pocket Programs is not affiliated to SAP AG or any of its subsidiaries. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Bonjour, the Bonjour logo, and the Bonjour symbol are trademarks of Apple Computer, Inc. The names of actual companies and products mentioned herein may be the trademarks of their respective owners

3 Contents 1. Installation components and architecture The Sap Scale Interface service Network Monitor Monitor Configuration Utility Pocket Programs Activation Relay Server Licences and Activation Trial Mode Purchasing licences Licence activation Pocket Programs Activation Relay Server Activation Server Set-Up Sap-Scale Server Upgrading from SapScale Using the Network Monitor Setting up Using Configuration Utility Server List Importing SAP Packing station profile Sap-Server Settings Loading and Updating settings Server control settings Server name and host address Event Logging to the Windows event viewer Log file creation Activation Relay Extensions Network settings ABAP settings RFC Destinations Device settings Add a new weighing device (scale) Device settings file Importing settings from a file Deleting a device Device communication settings Communications mode Transmit modes Constant mode Request mode Serial Port settings USB HID Pos settings... 25

4 TCP/UDP settings Receiving settings Requesting settings Data parsing Trimming, padding and splitting the input message Button Strip Inserting characters into the SAP fields Weight Value Extra Fields Motion monitor Creating RFC destination in SAP SM59 Detail settings Packing Station Profile Using in ABAP developer mode Appendix A Storage of settings Global settings RFC destinations Device Settings... 42

5 1. Installation See the separate Installation Guide for installation instructions 2. components and architecture The system consists of five main components: SAP ERP Host RFC requests & responses Status messages Network Monitor SapScaleServer (Windows service) Serial Data Licence activation requests Serial Device & RFC settings Monitor messages Pocket Programs Activation Relay Port and Proxy settings Monitor Configuration Tool Activation Relay Set-up Page 1

6 2.1. The Sap Scale Interface service The Sap-Scale Server performs the communication between the SAP host and the scale device. It runs as a windows service. It needs to be installed on every PC which has serial devices attached. If you are using serial-ethernet servers or networked weighing devices that communicate via UDP/TCP, you may wish to run a single instance of the Sap-Scale Server on a server Network Monitor The Network Monitor can be used to observe the status of the SAP-Scale Servers within your network. It relies on mdns (also known as zeroconf or Bonjour) to broadcast the RFC, activation and communication status of each Sap-Scale Server. From the monitor you can easily access the Monitor or Configuration Utility to remotely monitor or configure a Sap-Scale Server. You should install it on the administrators PC Monitor The Monitor can be used to monitor the activity of any Sap-Scale Server on your network. You can connect to any PC running the Sap-Scale Server and check any alerts and errors on that PC. You should install it on the administrators PC Configuration Utility Use the configuration utility to control the RFC destinations and set-up the weighing devices for any SAP-Scale Server installation on your network. You should install it on the administrators PC Pocket Programs Activation Relay Server The Activation Relay Server handles licence activation requests and forwards them to the Pocket Programs licensing system. Each installation of Sap-Scale Service requires a licence number. If a Sap-Scale Server is being used to handle RFC requests for multiple devices, then each device requires its own licence. Once the licence number has been entered, it must be activated against the Pocket Programs licence database. This occurs automatically via the internet. However, the Sap-Scale Server does not perform the internet activation itself; rather an activation server handles the request. You will need to install at least one activation server on your network. Page 2

7 3. Licences and Activation All installations of must be licensed, either by using it in trial mode or by purchasing licences at Trial Mode Trial mode allows companies to test the functionality of and ensure that it meets the business requirements before purchasing licences. In trial mode, is fully functional; however any output transferred to the SAP host will be scrambled. Once a licence number has been entered for a device, then it will no longer operate in trial mode. If the licence has not been activated, then no data will be returned to the SAP host Purchasing licences Licences can be purchased by visiting. When purchasing licences, you will be asked to specify a password which is used when activating the licence Licence activation The Hardware key is a unique number identifying the computer on which is installed. Enter the licence number and the licence password specified when purchasing licences into the corresponding fields and click Activate. Via the internet, the licence number and password will be validated and an activation key generated. This activation key is valid for three months and will be automatically revalidated after three months. Page 3

8 4. Pocket Programs Activation Relay Server Each installation of Sap-Scale Server requires a licence number. If a Sap-Scale Server is being used to handle RFC requests for multiple devices, then each device requires its own licence. Once the licence number has been entered, it must be activated against the Pocket Programs licence database. This occurs automatically via the internet. However, the Sap-Scale Server does not perform the internet activation itself; rather an activation server handles the request. You will need to install at least one activation server on your network Activation Server Set-Up The activation relay service will be installed and started as part of the installation process. Once installation is complete, please check and update the Activation Relay settings. For the Activation Server, you will need to define which TCP/IP port is used (to listen for activation requests) and if a proxy is required to access the Internet. To access the activation server set-up utility, click Activation Relay Setup under Start Programs The activation relayer listens on a TCP port for activation requests. The default port is 5134 which is registered with IANA, if you wish to use a different port, enter it here. Page 4

9 To validate the licence details entered, the activation relayer requires access to the internet. The licence is validated using the web service located at Ensure that the user account under which the activation relay service runs can reach this URL. You may need to change your corporate firewall settings, or define proxy settings (though as the service runs in the background, it is preferable to change firewall settings if required). Note: The activation relay uses a secure HTTPS connection when activating licences. Once you have entered the required settings, click Save to store the entries. Then stop and restart the service. Should an error occur, you can request that an event be logged in the Windows Event Viewer by checking corresponding box. You will need to restart the service, events are logged under Windows Application Logs, with log source Pocket Programs Activation. Note: After the activation relay service is installed, you may wish to set the service to restart should it fail. This can be done via the service properties: The settings required for the Sap-Scale Server to use the Activation Server are described in the section Page 5

10 5. Sap-Scale Server The Sap-Scale server is the core component of. It listens for the weighing requests from SAP and handles the communication with the device and the parsing of the data. The Sap-Scale server runs as a windows service and uses TCP/IP port 5135 for communication with the configuration utility and the monitor. Note: After the activation relay service is installed, you may wish to set the service to restart should it fail. This can be done via the service properties: Page 6

11 6. Upgrading from SapScale If you are upgrading from SapScale, you can import your settings into as follows: 1. Start the configuration utility, click configuration under Start Programs 2. Select your SAP-Scale server (typically localhost) and click 3. In the Server Definition, click the menu item select Import Settings from SapScale In the pop-up window, specify the location of your sapscale.ini file: Click OK to import the settings from SapScale. Page 7

12 7. Using the Network Monitor The network monitor displays the status of the Sap-Scale Servers on your network. The three columns on the right show the status of the Sap-Scale Server: RFC - Shows the status of the last RFC communication with the SAP host. Comms - Shows the status of the last communication with a device Act- Shows the activation status of all devices Click on to monitor the Sap-Scale Server. Click on to configure the Sap-Scale Server (only available if the configuration utility is installed on the PC). Page 8

13 8. Setting up Each installation of the Sap-Scale Server needs to have the settings defined for: 1. The RFC destinations it will accept requests for; and 2. The devices that it will communicate with to retrieve the weight Using Configuration Utility To access the configuration utility, click Configuration under Start Programs. You can also access the configuration utility from the network monitor (see section 0) Server List With the Configuration Utility, you can configure the settings for any Sap-Scale Server in your network. Page 9

14 Add a new Sap-Scale Server To add a new Sap-Scale Server, click the new Sap-Scale Server:. You can then enter a name and IP settings for Delete a Sap-Scale Server To delete a Sap-Scale Server, select the server to be deleted, and click Viewing and modifying the settings for a Sap-Scale Server To view or modifying the settings for a Sap-Scale Server, select the server, and click Page 10

15 Importing SAP Packing station profile This function simplifies the definition of the RFC and scale name settings. Firstly, you must complete: 1. creating the SAP RFC destination using transaction SM59 (see section 10). 2. the packing station profile using transaction HUPAST_C (see section 11), including assigning the hostname of the operator's PC. You can import the packing station profile using the menu item Import SAP Packing station configuration. Page 11

16 You can either select a SAP system (from the SAP logon pad), or enter the host details manually. Enter the username, password and target client. Click connect to retrieve the list of packing station profiles from the SAP system. Once you have connected to the SAP System, you can select the packing station profile corresponding to the operator's PC from the list. Alternatively click on or use the search function to automatically find the packing station profile assigned to this PC, to enter a search string for the packing station profile name (e.g. "*ERP*"), click on again to perform the search. Page 12

17 Once you have selected the packing station profile, click to verify the configuration: The verification process will highlight any inconsistencies in the SAP packing station profile configuration (transaction HUPAST_C), or the RFC destination (transaction SM59). Once the SAP configuration has been verified, you can import the settings directly into ERP- Scale: You can select to import either the RFC destinations, or the device names, or both. You can also create a new RFC destination or device, or update an existing one. Click on to import the configuration. Page 13

18 Sap-Server Settings The Sap-Scale server settings are in three sections: 1. Control settings for the server itself 2. RFC destinations 3. Weighing devices Page 14

19 Loading and Updating settings The communication between the configuration utility and the Sap-Scale server occurs via TCP/IP. When the form is first opened, all settings are loaded from the server. The Read and Send buttons on the form function as follows: Load all settings from the server Send Server control settings only to the server Restart the server, required after changes to the RFC destinations Send RFC destination changes to the server. Requires a server restart. Read device settings from the server Send device settings changes to the server Page 15

20 8.2. Server control settings The server control settings control the following: Server name and host address Event logging to the windows event logger Log file creation Action relay settings extensions Network settings Server name and host address Update Server name and network address Check host address Update Server listening port. This will require a server restart. Backup/Restore all server settings (including RFC destinations and devices) Server Name Host name or IP address Listening Port Filename Your name for this device The network address of the server. Can be entered as hostname or IP address. The TCP/IP port used for communication with the server. This should only be changed in exceptional cases. Any changes will require a server restart. All settings can be backed-up to a filename. The filename can be entered here. Page 16

21 Event Logging to the Windows event viewer The Sap-Scale server can log messages to the Windows event viewer. Use this tab to switch logging on and off, and to select which types of messages are logged. Note: Selecting all boxes will fill the event log very quickly. Ensure that you only tick the boxes required, and clear messages from the event viewer regularly Log file creation The Sap-Scale server can log messages to a file. You can switch logging on and off here, as well as specifying the directory for the log files. Page 17

22 Activation Relay Enter the network address (IP address or host name) and the port used by the activation relayer. See section 4. Pocket Programs Activation Relay Server for further details Extensions From V3.0.4 you can use extensions to add functionality to. Initially extensions are available to provide target weighing and scale selection. See for further details. Once an extension has been installed, it can be activated here. In this section you can activate extensions and change the maximum timeout for the extension to respond. Page 18

23 Network settings From v3.0.4, mdns (also known as zeroconf services) is supported to locate and manage the Sap-Scale servers on the network ABAP settings In all previous versions, if no data was received from the device (or the status was invalid), then the weight 0 was returned to the RFC HU_GET_RFC_DATA, but SY-SUBRC still contained 0. You can now configure to return RFC_ABAP_MESSAGE to the function call if no (valid) data is read from the device. This will then set SY-SUBRC to 2, this allows you to differentiate between a valid weight of zero, and an error in the communication with the device. Page 19

24 8.3. RFC Destinations The Sap-Scale server communicates directly with SAP using the RFC HU_GET_RFC_DATA. Each Sap-Scale server can accept RFC requests from multiple SAP systems simultaneously. This simplifies testing as it can communicate with the development and production SAP systems at the same time. See section 10 for details regarding creating RFC destinations in SAP. Start RFC Tick this box if the Sap-Scale server should register with the RFC destination specified Sap Program ID The RFC registered program name. See section 10. Creating RFC destination in SAP for further details Sap Gateway Host Sap Gateway Service Number Enter the network address of the SAP host. Routing information can be entered in front of the hostname e.g. /H/sapserv3.test.com/S/3296/H/cpff551.test.com The gateway service. See section 10. Creating RFC destination in SAP for further details The number of servers to register for the RFC destination. If the Sap-Server has a single weighing-device attached, use 1 server. If the Sap-Scale server provides the interface for multiple weighing devices, enter a larger number here. Page 20

25 8.4. Device settings The settings for a device consist of two parts: 1. Settings for the communication type, serial port or TCP/UDP settings, baud rates, parity and message terminators. 2. Data parsing rules, these describe how the messages from the device are interpreted to retrieve the weight and unit-of-measure. Create new device Load device settings from a file Save device settings to a file Delete device Communication settings Data parsing Load devices from the server Update server with device changes Licence number and activation Page 21

26 Add a new weighing device (scale) To add a new serial device, click on the button In the pop-up window, add the name for the new device: The name of the device must be unique and should match the name of the scale used in SAP configuration HUPAST: or the parameter LS_WEIGHT-WAAGE if using RFC HU_GET_RFC_DATA in your own developments. See section 10 for further details. Note: The device name can use upper and/or lower case letters Device settings file Click on the button to save the device settings Importing settings from a file To import settings from a different device, click on the button to import existing settings file. This feature can be used to easily copy device settings from one PC to another 8.5. Deleting a device To delete a device, select it in the grid. You can then delete it by clicking on the button. Page 22

27 8.6. Device communication settings Communications mode can communication with devices attached physically to the server's serial port or USB port, or to network devices using TCP or UDP Transmit modes A serial device can operate in two modes; it may constantly transmit the weight data, or it may require a request to be sent Constant mode Most serial devices transmit the weight message string constantly. The Sap-Scale server can simply open the serial connection and read the received data. However, as the initial string of data received may be not be a complete message, it is advisable to read two messages and use the second Request mode Some devices need a request to be sent before the weight is transmitted. This is termed Request mode Page 23

28 Serial Port settings The serial settings control the serial port to which the device is connected. Consult with the serial device manual for the required settings. Port Baud Databits Parity Stop Bits Handshake DTR enabled Select the (COM) port to which the serial device is connected. Select the baud rate to match the serial device Select the number of databits to match the serial device Select the parity to match the serial device Select the number of stop bits to match the serial device Select the handshake settings for data transmit and receive Some devices need to have DTR enabled in order to communicate with the PC. Set this flag only if required Page 24

29 USB HID Pos settings supports USB scales which use the HID POS protocol. This USB settings define the USB device to b used, and the valid scale statuses. USB Device Valid device statuses Select the USB device which you wish to use. If it is not displayed, connect it to the USB port of your computer and click to refresh the device list. If your device is still not shown, verify with the manufacturer that it uses the USB POS HID interface protocol The USB device can report various statuses to the PC host. Select the statuses that should treat as a valid weight. If the status is not marked as valid, then the data from the scale will be ignored. Note: You can add manufacturer specific status codes to the list, however these changes are stored on the local PC used for configuration. If you wish to configure this Sap-Scale Server from a different PC, you will need to maintain the manufacturer specific codes on that PC as well. Page 25

30 TCP/UDP settings Enter the host name or IP address and port. Page 26

31 Receiving settings In this section, the settings for control the receiving of messages from the device are defined. Check the user manual for the device to determine the relevant settings Terminator Terminate input after a number of characters Minimum number of reads Maximum number of reads If the message from the device has a termination character, enable this option and select the termination ASCII character from the list. Note: For TCP/UDP the terminator field is ignored. Some devices always send a fixed number of characters without a terminator. Use this setting only if no terminator is available. Note: Use of this setting is not recommended when using constant mode. This setting cannot be used for TCP/UDP communication. Use this setting to force the Sap-Scale server to read a number of messages and use the last to determine the weight. In constant mode a setting of 2 or higher is advised to ensure receipt of a complete message. In request mode, a setting of 1 is advised The number of times the Sap-Scale server should attempt to receive a valid message before aborting. Page 27

32 Timeout Remove control characters Flush port before reading Ignore blank input The timeout in milliseconds when waiting for a response Remove any non readable characters Note: Non readable characters are in the range ASCII 0 ASCII 31 and ACSII 128 ASCII 255 Flush the serial ports input buffer before reading data Note: You are advised to use this setting to avoid processing old messages If the message is empty, ignore it. Note: You are advised to use this setting Page 28

33 Requesting settings This section controls the settings for sending a transmit request to the device. It is only relevant if is communicating with the device using request mode. Request Text Terminator Minimum number of requests to send Maximum number of requests to send Enter the text which the device requires to trigger it to send the weight. You can enter control characters surrounded by {} brackets. E.g. {STX} {SP} Note: This text may be case specific. If the request message to the device requires a termination character, enable this option and select the termination ASCII character from the list. Note: You can also include the terminator in the Request text above Use this setting to force the Sap-Scale server to repeat the request a number of times before a valid response is returned The number of times the Sap-Scale server should attempt to receive a valid message before aborting. Page 29

34 8.7. Data parsing Data parsing defines how the Sap-Scale server takes the input message received from the serial device and extracts the weight, unit of measure and other values to be returned to SAP. It also has settings to detect if the scale has motion on it. Click on from the main console to access the parse settings The current input from the device is displayed at the top of the form. Click on the button to re-read the data from the device. Click the button to refresh the screen after changes. Page 30

35 Trimming, padding and splitting the input message Trimming input Use this option to remove spaces from the input message. The options are: Remove no spaces Remove all spaces Remove leading spaces Remove trailing spaces Remove leading and trailing space Note: This option should only be used if required. Right pad input Remove control characters Some devices may send a variable length message depending on the number of digits of the current weight on the scale. Use this option to pad the input string Note: This option should only be used if required Use this option to remove all control characters after the input message has been split. Split input If this input contains field separators, they can be entered here. If multiple characters are specified, the input message will be split at all occurrences of any of the separators. Page 31

36 Button Strip The input data is also displayed in the button strip: If a field separator has been specified, each field from the input message will be displayed on a separate line. These buttons are used to select the characters to be used for each value to be returned to SAP. The buttons in the left column are used to insert the complete field into one of the SAP fields. The buttons in the left column can be used to insert individual characters into one of the SAP fields. E.g. In the above button strip, the first field contains the weight on the scale. The second field contains the unit-of-measure preceded by an asterisk. The final field contains a movement character. To define the characters relevant for the weight value follow these steps: 1. Click in the weight value field: 2. Left-click the button: 3. The weight value field will then display and the resulting weight will be displayed to the right To define the characters relevant for the weight units follow these steps: 1. Click in the weight unit field: 2. Right-click the button, this signifies insert the character and all characters to the end of the field. 3. The weight units field will then display Page 32 and the resulting unit will be displayed to the right

37 Inserting characters into the SAP fields To insert Click SAP field will be displayed as One character from a field A complete field All characters starting from a position within a field Two characters from a field Left-click the character button in the right column Left-click the field button in the left column Right-click the character button in the right column Left-click the first character button in the right column and then the second character button in the right column {1:2} indicating the second character of the 1st field {1} indicating the first field {1:2+} indicating the second character of the first field and all following characters of the field {1:2}{2:3} indicating the second character of the first field followed by the third character of the first field Fixed text Type the required text KG Page 33

38 Weight Value Weight value Weight Units To select the characters from the input string for the weight, click in this field and then click the relevant buttons from the button strip in sequence. Each character is displayed in the field between parentheses. E.g. {2:2} To delete the current settings, select all the entries in the field, and delete them. The resulting weight value is shown to the right of the field To select the characters from the input string for the unit-of-measure, click in this field and then click the relevant buttons from the button strip in sequence. Each character is displayed in the field between parentheses. E.g. {3} Note: If the units-of-measure are fixed, and not contained in the input message, you can simply enter the units here. E.g. KG To delete the current settings, select all the entries in the field, and delete them. The resulting units-of-measure is shown to the right of the field Extra Fields The standard data structure for the RFC HU_GET_RFC_DATA supports three additional fields. You can enter values here to be returned to your own ABAP programs using the RFC. Enter the values either as fixed text or using the button strip The following extra fields are available: 1. Text 2. Dummy 1 3. Dummy 2 Page 34

39 Motion can determine from the input message if there is motion on the scale. If there is motion, it will repeat the receiving process until the timeout is reached. Movement To select the characters from the input string for motion indicator, click in this field and then click the relevant buttons from the button strip in sequence. Movement character Indicates still Enter the character that indicates motion. Note: If the device only returns a character when still, enter the character indicating still here and enable Note: This field is case specific and does not support control characters If the character returned indicates that the scale is still, tick this flag Return value if motion Timeout Set this indicator if the Sap-Scale server should return the current weight to SAP even if there is still motion at the end of the timeout period. If this indicator is not set, and there is still motion, then the text Motion will be returned. The timeout in milliseconds when waiting for the scale to reach a still state Page 35

40 9. monitor The monitor can be used to view messages and alerts from SAP-Scale servers on your network. To monitor a server, select the server from the drop-down box, and click connect. To select which types of messages are displayed, click the message type button. Page 36

41 10. Creating RFC destination in SAP To create an RFC destination in SAP, use transaction SM59. To create a new destination click on To edit an existing destination, select the destination and click on Page 37

42 10.1. SM59 Detail settings Page 38

43 11. Packing Station Profile The transaction HUPAST_C can be used to configure settings for scale integration for both the packing station transaction HUPAST as well as for custom ABAP s The device name must match the name of the device used in the RFC call from the SAP R/3 host, or in the packing station profile in configuration: Note: When entering the hostname of the user's PC, this is case dependent. Visit for sample ABAP programs. Page 39

44 12. Using in ABAP developer mode will run in developer Mode if the parsing and transmit settings do not require data to be sent to or read from the device. This is useful to allow ABAP developers to test their developments without the need to have a physical device connected to their PC. To use developer mode, ensure that you have not entered a request string in the Requesting settings (see section 8.6.8), and that all the fields in the Input parsing have fixed values (see below). When using test-mode, you can change the weight that the Sap-Scale server returns using the following steps: 1. Select the device you wish to change in the drop-down: 2. Click on 3. Enter the weight and unit (and any extra fields return values): Page 40

45 13. Appendix A Storage of settings The settings for the Sap-Scale Service are stored in the registry under HKEY_LOCAL_MACHINE/SOFTWARE/PocketPrograms/ErpScale Global settings The Global settings are stored under HKEY_LOCAL_MACHINE/SOFTWARE/PocketPrograms/ErpScale3.0/Settings The settings stored are as follows: RFC destinations Each RFC destination is stored as a registry key under HKEY_LOCAL_MACHINE/SOFTWARE/PocketPrograms/ErpScale3.0/SapRFCDestinations For each RFC destination, the following settings are stored: Page 41

46 13.3. Device Settings The settings for each serial or TCP/IP device are stored under HKEY_LOCAL_MACHINE/SOFTWARE/PocketPrograms/ErpScale3.0/Devices The settings for each device include the serial communication settings, the parse settings as well as the licence and activation data: Page 42

47 Page 43

48 Index A ABAP 38 ABAP Developer mode 39 Activation 18 Activation key 3 Activation relay 4 B Bonjour 19 Button strip 31 C COM port 24 Communication mode 23 Constant mode 23 Control characters 27, 30 D Developer mode 39 Device 21 Dummy 1 33 Dummy 2 33 E extensions 18 monitor 35 F Field separator 31 Fields separator 30 Firewall 5 Flush port 27 H HU_GET_RFC_DATA 20, 22, 33 Extra fields 33 HUPAST 22, 38 HUPAST_C 11, 13, 38 L Log file 17 M Maximum number of reads 26 mdns 19 Minimum number of reads 26 Minimum number of requests 28 Motion 29, 34 Movement 34 Movement character 34 P Packing station profile 12, 13 Packing Station Profile 11, 38 Import 11 Parse settings 29 PC hostname 12, 38 Purchasing licences 3 R Request mode 23, 28 Request Text 28 RFC destination 13, 20, 36, 37 Right pad input 30 S SAP Host 38 SapScale 7 Import 7 Sap-Scale server 6, 35 Serial port 24 Serial settings Baud 24 Databits 24 DTR enabled 24 Handshake 24 Parity 24 Port 24 SM59 11, 13, 36, 37 Stop Bits 24 I Import settings 22

49 Index T TCP 23 TCP hostname 25 TCP port 25 Terminator 26, 28 Text 33 Timeout 27, 34 Transmit mode 23 Trial mode 3, 5 Trimming input 30 UDP port 25 Units of measure 33 W Web service 5 Weight units 33 Weight value 33 Windows event log 5, 17 Windows service 5, 6 U UDP 23 UDP hostname 25 Z Zeroconf 19