Windows Communication Library Description

Transcription

1 Windows Communication Library Description Paint Mixing Windows Data Communication Library for PMA7200 & PMA7500 technology PMA7501 series ECOMIX-Terminals EM01-* SpeedMix PMC7500-* Version Windows Driver description File : CommunicationLibraryDescription.odt Page: 1/15

2 Contents 1 Document changes Data communication overview Interface to the scale server (scal_cli.dll functions) Special settings Function scale_open Function scale_asyn_behavior Function scale_asyn_write Function scale_write Function scale_read Function scale_command Function scale_command_unicode Function scale_close Function scale_test_server Function scale_visible_server Function scale_force_exit Function name usage and overview NET interface (scal_net.dll) ScaleOpen ScaleClose ScaleCommand Window message processing Error codes Srvcom Command line Menu items How to use the scale server interface (program samples) Synchronous Mode Asynchronous Mode Command Syntax Parameters Request Syntax Response Syntax Error messages Error Response Windows Driver description File : CommunicationLibraryDescription.odt Page: 2/15

3 1 Document changes Version Changes 5.2 Wrapper DLL for.net support added SCAL_NET.DLL Function scale_command_unicode added Description of scale_open() changed: SBI switch /i added Name changed Windows Driver description File : CommunicationLibraryDescription.odt Page: 3/15

4 2 Data communication overview The data communication between the paint application software and the Sartorius scale is achieved using a scale server interface DLL (Scal_cli.dll) or a.net wrapper DLL (Scal_net.dll), which handle the communication to the connected scale using a server task (Srvcom.exe). This server task will check the connected scale during a call of function scale_open() and load the matching scale DLL. It is possible to start the server process (Srvcom) separately but this isn t necessary. The server will be started automatically if it isn t already running at a call of function scale_open(). In this case the server will be closed automatically at a call of scale_close(). More information about Srvcom can be found in ch. 3 The communication between the client application and the scale communication server is achieved using a DDE (Dynamic data exchange, Microsoft Windows specific, is a form of inter process communication that uses shared memory to exchange data between applications.) Overview: Windows application process Windows application or Windows.NET application Wrapper DLL (Scal_net.dll) Interface DLL (Scal_cli.dll) Sartorius driver process Server (Srvcom.exe) Sartocom via DDE inter process communication Scale driver DLL s SrvPma75.dll SrvPma72.dll SrvInd20.dll COM port COM port COM Port or Ethernet PMA 7500 PMA 7200 Ecomix Speedmix PMA7501 Windows Driver description File : CommunicationLibraryDescription.odt Page: 4/15

5 2.1 Interface to the scale server (scal_cli.dll functions) The interface to the scale server is done through following functions. Remarks: It is recommended, to use scale_command, instead of scale_write and scale_read. If functions scale_write or scale_async_write are used, after each write call a corresponding scale_read MUST be called. This is necessary in every case, even if the answer isn't needed Special settings Some special settings are available. These settings will take effect if there are made appropriate entries in an initialisation file with the name SRVCOM.INI Following sections and keywords can be used: Section [srvind20] BAUD=<value> switch Ecomix / Speedmix communication to a fixed baud rate. Possible values are 9600, and (and for PMA7501) PROTOCOL=ON srvind20 driver module will generate a protocol (File srvind20.pro) Section [srvcom] PROTOCOL=ON Srvcom server will generate a protocol (File srvcom.pro) Section [scal_cli] WAIT_WRITE=1 Will support compatibility to application programs, which have been developed with earlier scal_cli.dll versions (From V up to V ). This is relevant only if the application program isn't doing the necessary scale_read() function call after each call of scale_write(). An example for SRVCOM.INI. In this case Srvcom will generate a protocol file and the communication with Ecomix will be startet with Baud regardless of the settings used during the scale_open() command. [srvind20] ; srvind20: switch to fixed baud rate BAUD=38400 [srvcom] ; srvcom: generate protocol PROTOCOL=ON Function scale_open long int WINAPI scale_open (const char * comport, const char * options) description: comport: options: begins communication with the Communication Server, opens communication port to the scale and reads identification data of the scale string of Comport, eg.: COM2 (in case of an Ethernet connection the same syntax has to be used for this parameter, but it may contain a non existent COM port number) option string with following possibilities: /B <baud rate> sets communication speed to baud rate, default 9600 (possible values are 9600, 19200, 38400) /R <Retry> sets number of retries; default: 3 /ip <IP-Address> sets Ethernet communication address, e.g. "/ip " /pt <Port>" sets Ethernet communication port, e.g. "/pt 21554" /i sets communication to SBI. Remark: the baud rate should be set, too. Its possible range is extended down to 1200 baud. return value: if ret>=0, the function execution was successful. The return value has to be used as handle for the functions: scale_command, scale_write, scale_read, scale_close Windows Driver description File : CommunicationLibraryDescription.odt Page: 5/15

6 2.1.3 Function scale_asyn_behavior long int WINAPI scale_asyn_behavior (const char * comport, const void * function, HWND hwnd, UINT Msg) description: comport: function: indata: incount: hwnd: Msg: return value: this call is necessary before call scale_asyn_write(). It defines which kind of behavior is wished to receive the response of scale_asyn_write(). You can decide to receive a windows message or the asynchronous response will be call a callback function. This function is only available for 32bit SCAL_CLI.DLL. string of Comport, example: COM2 is pointer to a callback function with attribute CALLBACK or WINAPI and arguments (char * indata, unsigned long int incount) buffer pointer of response data contains length of data actual put to argument indata Handle of the window that has to receive the response message Message number of the response message (normaly WM_USER + xxx) the lparam of the windows message is a pointer to the response string the wparam of the windows message is the length of the response string (Remark: either argument function or hwnd must not be zero, but one of both cannot be zero. If hwnd is not zero then Msg must be also not zero. ) >= 0 value is old setting of function or hwnd of previous call, or zero on first call. <0 see the documentation in chapter "Error Code" Function scale_asyn_write long int WINAPI scale_asyn_write (long int handle, const char * outdata, unsigned long int outcount) description: handle: outdata: outcount: return value: sends string outdata to the Communication Server, the response can be received with a asynchronous callback function or with a user defined windows message. (This behavior must be defined before with a function call to scale_asyn_behavior() ). This function is only available for 32bit SCAL_CLI.DLL. value that is returned from scale_open string to be send length of the string without the following <cr>,<lf> if >0 then function was successful and value must equal outcount Function scale_write long int WINAPI scale_write (long int handle, const char * outdata, unsigned long int outcount) description: sends string outdata to the Communication Server, the response must be received with the function scale_read handle: value that is returned from scale_open outdata: string to be send outcount: length of the string without the following <cr>,<lf> return value: if >0 then function was successful and value must equal outcount Function scale_read long int WINAPI scale_read (long int handle, const char * indata, unsigned long int maxdata) description: handle: indata: maxcount: return value: reads the result of an previous function-call scale_write. The return string will be put to buffer indata. If the length of the return string is less then maxdata a NULL character will be append to indata, the returned length value does not include this NULL character. value that is returned from scale_open buffer of size maxdata to obtain the scale_write result size of indata if > 0 then function was successful and value contains length of data actual put to argument indata Windows Driver description File : CommunicationLibraryDescription.odt Page: 6/15

7 2.1.7 Function scale_command long int WINAPI scale_command (long int handle, const char * outdata, unsigned long int outcount, char * indata, unsigned long int maxdata, unsigned long int *incount) description: handle: outdata: outcount: indata: maxcount: incount: return value: combination of functions scale_write and scale_read value that is returned from scale_open string to be send length of the string without the following <cr>,<lf> buffer of size maxdata to obtain the scale_read result size of indata contains length of data actual put to argument indata if > 0 then function was successful and value contains length of data actual put to argument indata and is equal incount Function scale_command_unicode long int WINAPI scale_command_unicode (long int handle, const wchar_t * outdata, unsigned long int outcount, wchar_t * indata, unsigned long int maxdata, unsigned long int *incount) The function corresponds to scale_command, except the Unicode input and output buffers Function scale_close long int WINAPI scale_close (long int handle) description: the communication to the scale is closed, also the communication channel to the Communication Server handle: value that is returned from scale_open return value: 1 function was successful completed communication channel closed, 0 communication channel closed, but server not reached this may occur, if the server is already stopped <0 see the documentation in chapter "Error Code" Function scale_test_server long int WINAPI scale_test_server (const char * comport, char * buffer, unsigned long int maxbuffer) Remark: this function can only be called, if scale is closed! description: begins communication with the Communication Server, gets time string from the server and puts it to buffer as NUL terminated string. Example of buffer: "Server Time: Tue 22 16:00: ", if the server is not started or maxbuffer is to short a NUL string will applied to buffer. comport : string of Comport, example: COM2 buffer: buffer of size maxbuffer to obtain the scale_visible_server result maxbuffer: size of buffer, should be greater equal 38 return value: >0 function was successful <0 see the documentation in chapter "Error Code" Windows Driver description File : CommunicationLibraryDescription.odt Page: 7/15

8 Function scale_visible_server long int WINAPI scale_visible_server (const char * comport, char * buffer, unsigned long int maxbuffer) Remark: this function can only be called, if scale is closed! note: the Communication Server has to be started first description: begins communication with the Communication Server, gets time string from the server and puts it to buffer as NUL terminated string. Example of buffer: "Server Time: Tue 22 16:00: " if the server is not started or maxbuffer is to short a NUL string will applied to buffer. Subsequently the server will be set to visible mode. comport : string of Comport, example: COM2 buffer: buffer of size maxbuffer to obtain the scale_visible_server result maxbuffer: size of buffer, should be greater equal 38 return value: >=0 function was successful <0 see the documentation in chapter "Error Code" Function scale_force_exit long int WINAPI scale_force_exit (const char * comport); Remark: this function should be carefully used, it exits then Communication server also, if a communication is established from the own or from another application! description: begins communication with the Communication Server and sends the command to exit itself. The server can only receive this command when the server is not busy or or is busy in asynchronous action. This means: during actions from scale_open(), scale_close(), scale_command() the order to exit is queued and executed, when the previous actions are finished. During actions from scale_asyn_write() the exit command is executed immediately. comport : string of Comport, example: COM2 return value: >=0 function was successful <0 see the documentation in chapter "Error Code" Windows Driver description File : CommunicationLibraryDescription.odt Page: 8/15

9 Function name usage and overview The functions can be called using the described names, if the C-conform import lib files are used (Scal_cli.lib). Other program languages may have to use the names as declared in the following table: DLL-Entry Name or Alternative DLL-Name. Ordinal number Documentation name DLL-Entry name Alternative DLL name 1 scale_write _scale_write@12 Scale_write 2 scale_close _scale_close@4 Scale_close 4 scale_command _scale_command@12 Scale_command 6 scale_test_server _scale_test_server@12 Scale_test_server 7 scale_open _scale_open@4 Scale_open 8 scale_read _scale_read@12 Sccle_read 9 scale_start_server _scale_start_server@8 Scale_start_server 10 scale_visible_server _scale_visible_server@12 Scale_visible_server 11 scale_asyn_behavior _scale_asyn_behavior@16 Scale_asyn_behavior 12 scale_asyn_write _scale_asyn_write@12 Scale_asyn_write 13 scale_force_exit _scale_force_exit@4 Scale_force_exit scale_command_unicode _scale_command_unicode Scale_command_unicode Windows Driver description File : CommunicationLibraryDescription.odt Page: 9/15

10 2.2.NET interface (scal_net.dll) The.NET interface supports the three methods ScaleOpen, ScaleClose and ScaleCommand of the class Scal_cli in the namespace DllWrapper ScaleOpen public static int ScaleOpen(string comport, string options) description: Please, refer to the Function scale_open in the chapter ScaleOen starts the communication to the Communication Server, opens the communication port to the scale and reads the identification data of the scale. comport: string of Comport, eg.: COM2 (in case of an Ethernet connection the same syntax has to be used for this parameter, but it may contain a non existent COM port number) options: option string with following possibilities: /B <baud rate> sets communication speed to baud rate, default 9600 (possible values are 9600, 19200, 38400) /R <Retry> sets number of retries; default: 3 /ip <IP-Address> sets Ethernet communication address, e.g. "/ip " /pt <Port>" sets Ethernet communication port, e.g. "/pt 21554" return value: if ret>=0, the function execution was successful. The returned value has to be used as handle for the functions ScaleCommand and ScaleClose. If it is <0, please refer to the documentation in chapter "Error Codes" ScaleClose public static int ScaleClose(int handle) description: Please, refer to the Function scale_close in the chapter The communication to the scale and the communication channel to the Communication Server is closed. handle: value that has been returned from ScaleOpen return value: 1 function was successful completed communication channel closed, 0 communication channel closed, but server not reached this may occur, if the server is already stopped <0 refer to the documentation in chapter "Error Codes" ScaleCommand public static int ScaleCommand(int handle, string senddata, StringBuilder recdata) description: handle: senddata: recdata: return value: Please, refer to the Function scale_command and Function scale_command_unicode in the chapters and It sends a command to the scale and reads the response. handle value that has been returned from ScaleOpen command string to be send. StringBuilder buffer to obtain the received result. A size of 256 is recommended. if the return value is > 0 then function was successful and the value contains the length of the data which had actual been put to the recdata buffer. If it is <0, please refer to the documentation in chapter "Error Codes" Windows Driver description File : CommunicationLibraryDescription.odt Page: 10/15

11 2.3 Window message processing While the scale_... functions are executing, window messages are processed and not blocked, so the application programmer should secure that these functions are not called twice. 2.4 Error codes This is a list of the error codes, that can be received as result of the functions: scale_open, scale_command, scale_read, scale_write, scale_close Name No. When does the error occur SCALE_ERR_DDE_BUFFLEN -1 write string is longer than internal buffers SCALE_ERR_DDE_CONNECT -2 Cannot connect server This can happen, if you assume that the Server is started, but this is not true. SCALE_ERR_DDE_INIT -3 Cannot initiate DDE interface This error may perhaps happen, if the Windows system is not complete installed or corrupt. SCALE_ERR_OPENSTRING -4 begins not "COM SCALE_ERR_OPENSTATUS -5 cannot receive Open status from server Internal error, please report to SARTORIUS SCALE_ERR_OPENSCALE -6 cannot connect to scale The server is working, but the scale on the announced COM-port is not accessible. The retry mechanism implies, that this error will be received after about 30 to 45 secs. SCALE_ERR_READTIMEOUT1-7 Read time out on COM-Port SCALE_ERR_READTIMEOUT2-8 Read time out on COM-Port SCALE_ERR_CONNECT_FIRST -9 Internal error communication module: may happen, if scale_command() is called before scale_open() SCALE_ERR_CONNECT_RECEIVE0-10 Internal error communication Client -> Server the connection channel is not opened, but a receive is initiated. SCALE_ERR_CONNECT_RECEIVE1-11 Internal error communication Client -> Server may happen, if the server process is stopped, although a connection from a client process is open you can try, to force a scale_close() call, so the assumed connection will be closed and a newly call of scale_open() will be successful. SCALE_ERR_CONNECT_RECEIVE2-12 Internal error communication Client -> Server Internal error, please report to SARTORIUS SCALE_ERR_CONNECT_RECEIVE3-13 Internal error communication Client -> Server The announced receive buffer is smaller than the length of the received data SCALE_ERR_CONNECT_RECEIVE4-14 Internal error communication Client -> Server Internal error, please report to SARTORIUS SCALE_ERR_OPENSTATUSCOUNT -15 Open status from server is too short Internal error, please report to SARTORIUS SCALE_ERR_ALREADYOPEN -16 Open status from server signals: Scale is already open the scale interface can be opened only once at a time SCALE_ERR_SERVERSTARTFAILED -17 Automatic server start was not possible the program SRVCOM.EXE must in the working directory of the calling program or must be accessible with the PATH environment variable SCALE_ERR_STARTNOTSUPPORTE -18 Automatic server start yet not supported for 16-bit D SCALE_ERR_OPENCOMPORT -19 Comport can not be opened, not available, or used by another application SCALE_ERR_DDE_READTIMEOUT -20 Read timeout in DDE-Interface SCALE_ERR_DDE_WRITEFAULT -21 No Success on Write to DDE-Server SCALE_ERR_LOAD_DLL -22 No Success on Loading Server-DLL SCALE_ERR_DLL_CORRUPT -23 No Success on Loading Server-DLL function calls SCALE_ERR_DLL_ILLEGAL_USE -24 Server-DLL function calls illegal used SCALE_ERR_UNKNOWN_SCALE -25 Connection successful, but scale unknown SCALE_ERR_COMMUNICATION -26 Problems on serial Communication SCALE_ERR_MAXPORTS -27 Com port number too high, at moment COM1... COM8 allowed SCALE_ERR_ASYN_BEHAVIOR_NOT -28 Call back function and Window handle not zero _UNIQUE SCALE_ERR_ASYN_BEHAVIOR_NOT -29 Call back function and Window handle are zero _SPECIFIED SCALE_ERR_ASYN_WRITE_NO_BEH -30 Call back function and Window handle are zero AVIOR_KNOWN SCALE_ERR_CONNECT_RECEIVE5-31 Internal error communication Client -> Server Internal error, please report to SARTORIUS Windows Driver description File : CommunicationLibraryDescription.odt Page: 11/15

12 3 Srvcom In the normal case (if you are using the interface Dll SCAL_CLI.DLL) SRVCOM is started automatically and unvisible at a call of scale_open(). For tests it is possible, too, to start SRVCOM by hand. Then you can use following command line options. 3.1 Command line SRVCOM uses COM1 as default comport, but there is available a command line parameter to set it. Otherwise it has to be set using the menu entry File SRVCOM normally starts with a visible dialog window. A menu item Invisible (menu entry File ) and a command line parameter (any odd digit) are available to hide it. Examples: SRVCOM SRVCOM COM2 1 SRVCOM COM3 0 will start the server on COM1 with visible option will start the server on COM2 with invisible option will start the server on COM3 with visible option 3.2 Menu items Mainitem subitem description File Invisible sets window of program invisible Set_COM 1..8 select comport COM1 to COM8 Exit terminates program ScaleTest tests communication to scale, gives some Information Help About Sartorius Appl. Version information of program package Windows Driver description File : CommunicationLibraryDescription.odt Page: 12/15

13 4 How to use the scale server interface (program samples) 4.1 Synchronous Mode An application example program is \clientst\clientst.c. The following extract of this program demonstrates how to use the scale_xxxxx functions: // Include files #include scal_cli.h // declaration part unsigned long int comhandle; char buffer[132]; long int itmp,incount; // execution part // commands to get some Scale information (Menu Item Scale_info) comhandle = scale_open (com_str,"test"); sprintf (buffer,"open Status: %ld\r\n",comhandle); outwindow (buffer); if (comhandle >= 0) { itmp = scale_command (comhandle,"si;m",4,buffer,120,&incount); buffer[incount]=0; outwindow (buffer); itmp = scale_command (comhandle,"si;n",4,buffer,120,&incount); buffer[incount]=0; outwindow (buffer); itmp = scale_command (comhandle,"w;s;",4,buffer,120,&incount); buffer[incount]=0; outwindow (buffer); itmp = scale_close (comhandle); } 4.2 Asynchronous Mode The following extract of \clientst\clientst.c demonstrates how to use the scale_xxxxx functions in asynchronous mode: // Include files #include scal_cli.h // declaration part unsigned long int comhandle; char buffer[132]; long int itmp, incount; // execution part // commands to get some Scale information (Menu Item Scale_info) comhandle = scale_open (com_str,"test"); sprintf (buffer,"open Status: %ld\r\n",comhandle); outwindow (buffer); if(comhandle >= 0) { #ifdef WINMESSAGE itmp = scale_asyn_behavior (com_str, NULL, m_hwnd, WM_USER + 5); #else itmp = scale_asyn_behavior (com_str, TestCallback, NULL, 0); #endif itmp = scale_asyn_write (comhandle,"si;m",4); // Waiting for windows message itmp = scale_asyn_write (comhandle,"si;n",4); // Waiting for windows message itmp = scale_asyn_write(comhandle,"w;s;",4); // Waiting for windows message itmp = scale_close (comhandle); } void CALLBACK TestCallback (char * response, unsigned long int resplen) { mydisplay (response, resplen); } Windows Driver description File : CommunicationLibraryDescription.odt Page: 13/15

14 5 Command Syntax All requests obey the following syntax: The requests (commands and all parameters) are written down as ASCII sequence. As well the returned response. All parts of a sequence (command, sub command, parameter 1..n) are separated by colons. Floating point parameters use the decimal point (not comma). A thousand separator comma is not allowed. Any command sequence must be terminated by a carriage return (ASCII code 13 / 0DH) Spaces in the command sequence are trimmed (except string parameters, which are double quoted). String parameters, which contain special characters (like the colon or spaces), should be double quoted. The structure of the return sequence is like the command sequence. If the command has been executed without errors, the response starts with a repetition of the command (part in front of the first colon) and if necessary followed by answer parameters, otherwise an error message starting with EF is returned. Spaces between command and parameters are allowed and should be trimmed before parsing the response. 5.1 Parameters Possible types of request or response parameters are: ENUM One or two uppercase letters, usually specifying a subcommand. INT Integer values as an ASCII string containing characters , -, +. Default value is 0 FLOAT Floating point values represented by an ASCII string containing the characters -, +,. and Default value is 0.0 STRING An ASCII string. 5.2 Request Syntax A scale request consists of a one to three characters long command identifier followed by several parameters. Example: W;S;5<CR><LF> requests for a weight value ( W ), subcommand stable weight value ( S ) within 5 seconds (time-out parameter). 5.3 Response Syntax The response of an error free executed request starts with the command identifier of the request possibly followed by some result values of the executed command. Example: W;S;10.0;g<CR> is the response to the command W, showing a stable ( S ) weight value of 10.0 gram ( g ). The returned length of scale_read() and scale_command() includes the terminating <CR>. Windows Driver description File : CommunicationLibraryDescription.odt Page: 14/15

15 6 Error messages 6.1 Error Response If the command execution was not successful an error response is sent back. Following error groups are distinguished: ERROR FUNCTION: Parameter- or Execution- Errors Code: 'EF' ERROR DEVICE: Hardware - Errors Code: 'ED' Syntax: EF;<code>;<command identifier>;<number of parameter (1..n)> or ED;<code>;<number of error> Function errors EF: <Code> Identifies error reason EF; B <B>locked: function cannot be executed at this time EF; L <L>ength: parameter 'parameter_number' is too long EF; T <T>imeout: function broken, because the given maximal waiting time was exceeded EF; U <U>nknown: unknown command identifier EF; W <W>rong: parameter 'parameter_number' has a non-acceptable value EF; + Too much parameters EF; - Not enough parameters EF; > Value of parameter is too big EF; < Value of parameter is too small Device errors ED: <Code> Identifies error reason ED; I <I>nitialization: scale initialisation is not completed ED; F <F>atal error: <number of error> <number of error> Identifies error reason Internal error number of scale. The actual error number depends on the scale device connected. Some error numbers are shown here: 2 Weight is not zero at start of calibration 54 Weight underflow 300 Internal error number of device driver 310 Scale communication time-out 311 Scale communication time-out 312 Initialisation of scale communication failed 399 Illegal scale type: the connected scale is not supported by the used scale driver. Windows Driver description File : CommunicationLibraryDescription.odt Page: 15/15