This publication provides technical information about the IBM Terminal Services for DOS an Windows product Application Programming Interface (API). This product is also known as "DOS and Windows Terminal Services" or "DWTS" for short.
The DWTS product API support is used to develop DOS or Windows DCConnect data collection terminal (DCT) applications. DWTS is a component of the DCConnect family software products.
This section provides general information about how to use this online book, as well as the legal notices, service marks and trademarks used in this book.
To receive information about a topic, click on it:
Sixth Edition (June 2010)
References in this documentation to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service can be used. Any functionally equivalent product, program, or service that does not infringe upon any of IBM's intellectual property rights or other legally protectable rights can be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.
IBM may have patents or pending patent applications covering the subject matter in this documentation. The furnishing of this publication does not give you any rights to these patents. You can inquire, in writing, to:
IBM Director of Licensing IBM Corporation 500 Columbus Avenue Thornwood, NY 10594 U.S.A.
For online versions of this documentation, we authorize you to:
You are responsible for payment of any taxes, including personal property taxes, resulting from this authorization.
THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion might not apply to you.
Your failure to comply with the terms above terminates this authorization. Upon termination, you must destroy your machine-readable documentation.
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
IBM | OS/2 |
MAPICS |
|
Windows, Windows 95/98/Me, Windows NT/2000/XP/7/Server and Windows CE are trademarks of the Microsoft Corporation.
Other company, product, and service names may be trademarks or service marks of others.
The following information describes how to use this book.
How To Use the Contents
To view a topic, click on the topic.
How To Obtain Additional Information
After you select a topic, the information for that topic appears in a window. Underlined words or phrases indicate that additional information is available. You will notice that certain words in the following paragraph are underlined. Using a mouse, click on the underlined word. Additional information will appear in the window.
Traditionally, DCTs had small displays, custom operating systems and limited programming sets. These DCT's require specialized programming tools as well as unique programming skills. In today's environment, IBM's Terminal Services for DOS and for Windows product (also known as "IBM DOS and Windows Terminal Services" or "DWTS") can be used successfully for data collection when installed on off-the-shelf standard or industrial personal computers creating a much more versatile data collection system.
In addition, many of today's popular palm-sized handheld devices are based on Microsoft's Windows CE operating system which provides a graphical point-and-click user interface.
PCs and devices running DOS or one of the Windows operating systems can utilize the power of the C programming language and easy to use Visual Basic compilers which are popular with today's programmers. When you combine DWTS APIs and one of the popular programming languages, you are no longer limited by the unique programming environments of the traditional data collection terminals.
DWTS allows a computer that has DOS, Windows 3.1, Windows 95/98/Me, Windows NT/2000/XP/7/Server or Windows CE installed on it to communicate with the DCConnect server connected to a standard LAN network (wired or RF) using a standard TCP/IP stream socket. There are no requirements for specialized RS485 or RS232 wired networks which are needed by some older data collection terminals.
DWTS provides a set of application programming interfaces (24) (API's (23)) that allow user-written applications on a computer that has DOS or Windows installed on it to:
This set of API's enables a personal computer that has DOS, Windows 3.1, Windows 95/98/Me, Windows NT/2000 or Windows CE installed on it to send transactions to the DCConnect server. The DCConnect server handles these transactions just like other transactions received from IBM 752x terminals or terminals running the IBM DCConnect Client; they are stored in DCConnect Mailboxes (32) for retrieval and processing by Transaction Connection scripts or applications that use the mailbox DCConnect APIs.
DWTS provides an API that allows messages to be sent between user-written applications running on a DOS or Windows device and user-written applications running on the DCConnect server.
DWTS supports sending transactions, setting and retrieving terminal user variables, and validating data just like any other terminal. Thus, with well-written applications, DOS or Windows terminals can participate seemlessly along side traditional data collection terminals without changing any server based code.
If the DOS or Windows program needs to obtain information from a DCConnect application, it can use the DwsRequestData or DwsGetUserVariable API. DCConnect provides APIs which allow DCConnect applications to read and reply to data requests as well as set terminal user variables.
Starting with version 2.1.0 of the DCConnect Server and DWTS, support was added for dynamic configuration of DWTS terminals. This means a DWTS terminal can communicate with the DCConnect Server without having been previously configured - as long as it uses a terminal name that is not already in use. For more information, please see the discussion about the DWTS.INI keyword DYNAMIC_CONFIG (SeeDYNAMIC_CONFIG) .
Also new with version 2.1.0 of the DCConnect Server and DWTS is the ability to have multiple threads waiting on calls to DwsGetUserVariable. For more information, please see DwsGetUserVariable (SeeDwsGetUserVariable) .
Because the user variable content for DWTS terminals is actually maintained by the DCConnect Server, whenever the DCConnect Server is shut down and restarted, all user variables for all DWTS terminals are cleared out even if DWTS applications are running during the shutdown of the DCConnect Server.
Terminal user variables for DWTS terminals should be thought of as simply a means for transferring data between the DCConnect Server and the DWTS application rather than a storage place for application data. The C++ and Visual Basic languages already provide variables for that purpose.
With release 2.00 of DWTS, an installation procedure has been set up to install the DWTS files to a Windows NT/2000/XP/7/Server system. If the DCConnect Server is already installed on that system, the files will be installed to the DWTS subdirectory under the directory in which the DCConnect Server was installed. For example, if the DCConnect Server was installed into the C:\DCCONN directory, then the DWTS Client files will be installed to the C:\DCCONN\DWTS directory.
If the DCConnect Server is not installed, the installation of DWTS will prompt you for the directory into which the files should be installed.
Note: Unlike previous versions of the DWTS CD/diskettes, the files that are part of the DWTS installation are compressed on the version 2.0 (and later) CD. Therefore you must run the installation in order to get access to the product files.
To start this installation, insert the product CD and run:
setup.exeand then choose the "DCConnect Terminal Services for DOS and Windows" component when asked which component(s) should be installed.
Once the files are installed, the ones that you will need to use will depend on which device(s) your DWTS application will run on.
The installation of version 2.00 (and later) of DWTS also gives you the option to set up a sample Windows DWTS application as a terminal that can be part of the DCConnect Server configuration. You can use this option to install the sample Windows DWTS application on one or more PCs. If you choose this option, you will be prompted for the 'Name' of the terminal, the 'Server IP' and the 'Server Port'.
The name will default to 'SampleDWTS' but you can change it to whatever you like. You will need to add a DWTS terminal with this name to the DCConnect configuration.
For the 'Server IP', enter the IP address of the DCConnect Server. If the DCConnect Server is running on the same machine as the DWTS sample application, you can use the loopback address 127.0.0.1.
For the 'Server Port' number specify the TCP/IP Port number that the DCConnect Server is listening on for DWTS terminals. By default this is port 3001. This must match the 'Well known port number' that is defined using the DCConnect Configuration utility.
Once the sample DWTS Windows application is installed, a shortcut will be created, which can be accessed from the Start button as follows: Start -> Programs -> IBM Data Collection -> DWTS Sample Terminal (local).
Once you have built your DWTS application and you are ready to install it on the target device you will need to install not only your application executables but also the appropriate DWTS product .DLL (except for DOS devices) along with the license file and configuration file.
The section in this document which describes how to run the sample DWTS applications that are provided with the product covers all of the information needed to install, configure and run your DWTS application. Please see Running the Samples (SeeRunning the Samples) .
During installation of the DWTS product files to your harddrive, the installation process also defines the environment variable:
DWTSTOOLSso that it indicates the directory where the DWTS header and library files can be found. The sample DWTS project files and make files use this environment variable during the compile and link process.
If you choose to install the DWTS sample application locally on your Windows system, the environment variable:
DWTSwill be set up to indicate the location of the DWTS.INI file and the DWSCHECK.LIC that are required in order to run the sample.
The configuration of DWTS is done using a configuration file called:
DWTS.INI
This file includes the following configuration information, among other things:
[TERMINAL]This keyword is followed by the list of parameters that should be defined for the terminal. At this time, DWTS supports only one terminal definition in DWTS.INI. Here is an example; the details for each parameter will be covered below:
[TERMINAL]
TERM_NAME = SHIPPING_1
TCPIP_HOST = 99.99.99.101
TCPIP_PORT = 3001
BUFFER_FILE = TRANSBUF.DAT
BUFFER_CAPACITY = 50
BUFFER_CACHE = 10
BUFFER_RESEND_DELAY = 10
BUFFER_RESEND_TIMEOUT = 50
Here are the various keywords that must/can be included in DWTS.INI:
TERM_NAME = SHIPPING_1
This required keyword defines a valid terminal name that is available to the DWTS application for use in the DwsOpenTerminal API call. This terminal name must also be defined in the DCConnect Server configuration in order for the DwsOpenTerminal API call to be successful.
TCPIP_HOST = 99.99.99.101
or
SERV_ADDRESS = 99.99.99.101
One of these two keywords is required to specify the TCP/IP address of the host server - the DCConnect Server.
SERV_ADDRESS has been supported for a while, although it has never been documented. TCPIP_HOST was added as an alternative to match the keyword that is used in the DCConnect Client EMULATOR.INI file.
Note: When DWTS was originally released, another configuration file called CS2CBF01.CFS was used to specify the IP address and port number of the DCConnect Server. With the use of TCPIP_HOST and TCPIP_PORT in DWTS.INI, CS2CBF01.CFS is no longer needed.
TCPIP_PORT = 3001
or
SERV_PORT = 3001
One of these two keywords is required to specify the TCP/IP port number that the DCConnect Server uses to handle requests from DWTS terminals. The value specified for this keyword must match the 'Well known port number' that is specified in the DCConnect Configuration program which is found in the DCConnect folder. (In the DCX2.INI file that is in \DCCONN\DATA on the DCConnect Server, the keyword used for this port number is called the DAE_PORT).
SERV_PORT has been supported for a while, although it has never been documented. TCPIP_PORT was added as an alternative to match the keyword that is used in the DCConnect Client EMULATOR.INI file.
Note: When DWTS was originally released, another configuration file called CS2CBF01.CFS was used to specify the IP address and port number of the DCConnect Server. With the use of TCPIP_HOST and TCPIP_PORT in DWTS.INI, CS2CBF01.CFS is no longer needed.
There are actually two port numbers used by the server for supporting DWTS terminals. Both the port number specified and the one following it (e.g. 3001 and 3002) are used by the server to receive requests from DWTS terminals. So you should make sure that neither of these port numers are used by other applications running on the DCConnect Server.
The lower port number is used by the DCConnect Server to receive requests from earlier versions of DWTS terminals that used DAE (aka CS2) as the transport mechanism. The lower port number is used by the DCConnect Server to receive requests from later and current versions of DWTS terminals - that use a TCP/IP stream socket to communicate with the DCConnect Server. With fix pack E and later for version 1.40 of the DCConnect Server, you will see a start up message that indicates that the DCConnect Server has successfully bound to the second of the port numbers specified - assuming any DWTS terminals are configured and the TCP/IP DWTS line is active.
BUFFER_FILE = TRANSBUF.DAT
This keyword specifies the path and name of the file to be used for buffering transactions that the DWTS API is not able to send immediately to the DCConnect Server. This is also referred to as the transaction logfile.
| Note: | Buffering of transactions is supported if the DWTS application is running on Windows 95/98/Me/NT/2000/XP/7/Server or Windows CE; it is not supported for DOS or Windows 3.1 applications. |
You can specify a full path for this logfile - or just the name. If no path is specified, the file will be created in the directory specified by the environment variable DWTS. If the DWTS environment variable is not defined and no path is specified, the logfile is created in the current directory.
| Note: | IMPORTANT: Windows CE does not support the concepts of current directory or environment variables. Therefore you must explicitly specify the full path where the logfile should be created. If no path is specified the logfile is created in the root directory of the device - regardless of where your DWTS application is installed. |
If the DWTS application is running on a device that does not have a hard drive but does have other non-volatile storage such as a compact flash card, you should specify a path that is on that non-volatile storage. For example, the Intermec 700 terminal's non-volatile storage is given the directory name '\Storage Card'; so the BUFFER_FILE statement should specify a file somewhere in that directory, such as:
BUFFER_FILE = \Storage Card\transbuf.dat
In the example above notice that the directory name includes a space but the entire name is not enclosed in double quotes. When the BUFFER_FILE statement is processed, everything from the first non-blank character after the equal sign is taken as the path\filename. However, if you do enclose the path\filename in double quotes, the double quotes will be removed before the parameter is used.
Use the BUFFER_CAPACITY to specify the size of the transaction buffer. If not specified, the default size is 50 transactions.
BUFFER_CAPACITY = 50
This keyword specifies the capacity of the file that is used for buffering transactions that the DWTS API is not able to send immediately to the DCConnect Server. The value specified is the number of transactions that this transaction logfile can hold.
| Note: | Buffering of transactions is supported if the DWTS application is running on Windows 95/98/Me/NT/2000/XP/7/Server or Windows CE; it is not supported for DOS or Windows 3.1 applications. |
Each transaction can be up to 108 bytes in length. When the transaction logfile is created, each record is created with its length being set to that maximum plus two bytes to store the actual length. So the actual size on disk of the transaction logfile will be:
110 * BUFFER_CAPACITY bytes
If the transaction logfile fills up, the return code from the DwsSendTransaction API will be DWS_BUFFER_FULL.
If the BUFFER_CAPACITY keyword is not specified but the BUFFER_FILE keyword is, the default transaction logfile size will be 50 transactions.
BUFFER_CACHE = 10
This keyword specifies the size of the memory cache that is used for buffering transactions that the DWTS API is not able to send immediately to the DCConnect Server. The transactions are put into this queue in addition to the transaction logfile in order to speed up the reading of transactions from the logfile so that transactions can be sent to the DCConnect Server as quickly as possible as soon as it begins to respond again.
| Note: | Buffering of transactions is supported if the DWTS application is running on Windows 95/98/Me/NT/2000/XP/7/Server or Windows CE; it is not supported for DOS or Windows 3.1 applications. |
The memory cache provides the most benefit when the storage media on the terminal is very slow.
BUFFER_RESEND_DELAY = 10
This keyword specifies how long the underlying API code's resend thread will wait before attempts to resend transactions that are buffered. The value is specified in tenths of seconds. If this keyword is not specified or the value is set to 0, the resend thread is not used; in this case an attempt to send buffered transactions is made only when the APIs DwsSendTransaction band DwsSendBuffered are used.
This keyword is not valid for DOS or Windows 3.1.
BUFFER_RESEND_TIMEOUT = 50
This keyword specifies the timeout that is used by the resend thread when it attempts to send transactions to the DCConnect Server. The value is specified in tenths of seconds. If a response to the sending of the transaction is not received in time, the transaction will be resent after the next BUFFER_RESEND_DELAY time period elapses.
This keyword is ignored if BUFFER_RESEND_DELAY is not used or is set to 0.
This keyword is not valid for DOS or Windows 3.1.
USE_DWS_OPEN_LOCALLY = Y
Use this keyword to tell the DWTS API to give the return code DWS_OPEN_LOCALLY if the DwsOpenTerminal API call was not able to complete communications with the DCConnect Server. If your application receives DWS_OPEN_LOCALLY or DWS_NO_ERROR, a valid handle will be returned and that handle can be used for any of the API calls that take a handle as a parameter.
If you do not use the USE_DWS_OPEN_LOCALLY keyword, then DWS_NO_ERROR will be returned even if the DwsOpenTerminal API call was not able to complete communications with the DCConnect Server. Your application will not be able to determine whether communications were established.
Regardless of whether this keyword is defined, the DwsOpenTerminal API call will return an error if the the license file could not be found, if DWTS.INI could not be found, if the terminal name did not match the name in the .INI file, if terminal is already active, or a previous API call is still in progress.
DYNAMIC_CONFIG = Y
Use this keyword to tell the DWTS API that this terminal is not already part of the DCConnect Server configuration; the terminal will be dynamically configured in the Server when the application begins to call DWTS APIs.
When this keyword is in effect, the TERM_NAME keyword is ignored if it is also in the DWTS.INI file.
When the DWTS application issues the call to DwsOpenTerminal, the terminal name provided in that API call will not be compared against any name found in the DWTS.INI file. Instead it is passed to the DCConnect Server after making sure it is of a valid length (1-32 characters).
When the DCConnect Server receives the DwsOpenTerminal request, it will compare the terminal name against all static and dynamically configured terminals. If it matches any of those, the request will 'take over' this terminal name. So if two applications are trying to use the same terminal name, they will be competing with each other for the same resources in the DCConnect Server. With each change, the previous terminal's resources are cleaned up before the new request is honored.
Because dynamically configured terminals are not part of the DCConnect configuration, when a normal transaction is sent to the DCConnect Server, the Server will not be able to find the terminal name in its configuration in order to determine into which mailboxes the transaction should be put. To resolve this issue, the application must use an alternate form of the DwsSendTransaction API called DwsSendTransactionDynamic in which you provide a list of one or mailbox names into which the transaction should be stored by the DCConnect Server. For more information please see DwsSendTransactionDynamic (SeeDwsSendTransactionDynamic) .
For the period of time that a dynamically configured terminal is active in the DCConnect Server (between successful calls to DwsOpenTerminal and DwsCloseTerminal) this terminal's name can be used in DCConnect API calls such as:
However, after a dynamically configured terminal successfully calls DwsCloseTerminal, the APIs above will return DCX_INVALID_TERMINAL_ID (-527) if the name of that dynamically configured terminal is used.
The following input files are used by the DWTS API:
DWSCHECK.LIC | The license file that is required in order for the API to work. |
DWTS.INI | The configuration file described above. |
(CS2CBF01.CFS) | Although no longer neededd, if used, this file should be located in the same directory as DWTS.INI. |
The following output files are generated by the DWTS API:
MESSAGES.LOG | Any operational warning or error messages are written to this file. |
Transaction logfile | Storage for transactions until they are safely stored on the host. |
Unless otherwise indicated the DWTS API will look for its input files and generate its output files in the current directory. (On Windows CE, where there is no concept of current directory, the files will be looked for/generated in the root directory). The exception to this is the transaction logfile, whose location is determined by the keyword BUFFER_FILE in DWTS.INI.
In terminals running DOS or Windows 3.1 or Windows 95/98/Me/NT/2000/XP/7/Server you can change the location of these files using the environment variable DWTS. For example, if you want use the directory C:\DWTS to keep DWTS.INI and DWSCHECK.LIC on your DOS or Windows 3.1 terminal, then add the following statement to AUTOEXEC.BAT:
SET DWTS = C:\DWTS
For information about how to set environment variables on a Windows 95/98/Me/Nt/2000/XP/7/Server system, please consult the documentation for the operating system.
On Windows CE, where the concept of environment variables does not exist, the path for input and output files can be specified via the 'path' value for the following registry key:
HKEY_LOCAL_MACHINE\Software\IBM\DWTS
The 'path' value must be of the type REG_SZ, which is a null-terminated string.
Note: If your DOS-based terminal is using the original method of communication with the DCConnect Server, via DAE, then you will have the environment variable:
CS2DOSdefined and this will instead be used to locate the input and output files.
Note: The location of the transaction logfile is defined by the BUFFER_FILE parameter in DWTS.INI regardless of the setting of environment variables or the registy key discussed above.
When configuring a DWTS terminal in the DCConnect Server configuration, you must do the following from the Node Configuration screen:
Note: In versions of the DCConnect Server prior to fix pack E for the 1.40 CD, the term "DOS" or "DAE" was used instead of "DWTS" in several places in the User Interface - including the "TCP/IP DOS" adapter icon.
The adding of the TCP/IP DWTS adapter to the node will automatically add a TCP/IP DWTS line icon under the TCP/IP DWTS adapter icon.
When a DWTS terminal issues the DwsOpenTerminal API call, it passes its terminal name to the DCConnect Server. This is all that is needed to identify that terminal to the DCConnect Server.
The application programming interfaces (24) (API's) in this section enable a computer that has DOS, Windows 3.1, Windows 95/98/Me, Windows NT/2000/XP/7/Server or Windows CE installed on it to send transactions (43), messages, validation requests and data requests to the DCConnect Server.
For information about a specific API (23), click on it:
DwsOpenTerminal (Terminal Name, Address of Handle, Timeout)
DwsOpenTerminal is used to start data collection (30) processing on a computer that has DWTS installed on it. This must be the first DWTS API call (26) made by the user-written application. If the API call is successful, a handle (31) is returned to the caller. All additional DWTS API calls require a valid handle as one of their parameters (34).
For information about a specific topic, click on it:
This API is the first call made. It establishes a TCP/IP session between the DOS/Windows PC and the DCConnect Server. This API also ensures that the terminal name provided on the DwsOpenTerminal is configured on the DCConnect Server.
When this call is successful the status for the DOS/Windows terminal on the DCConnect Server changes to "in service".
However, DwsOpenTerminal will also return DWS_NO_ERROR even if the DCConnect Server could not be reached - as long as a valid terminal name was provided and another application is not already using that terminal name on the Client device. This allows an application to start generating transactions and have them buffered even when the terminal cannot communicate to the DCConnect Server.
If the application needs to know whether the DWTS API was actually able to communicate with the DCConnect Server, then include the following statement in DWTS.INI:
USE_DWS_OPEN_LOCALLY = YWhen this statement is in effect, the DWTS API will return DWS_NO_ERROR only if the DCConnect Server could be reached. If the DCConnect Server could not be reached but the terminal name was valid, then the API will return DWS_OPEN_LOCALLY.
Terminal Name (LPTSTR (11)) - input
A name that is configured by the DCConnect Server for the computer on which you have installed DOS/Windows Terminal Services. The terminal name parameter is a null-terminated string from 1 to 32 characters.
For Windows CE, this should be a double-byte, Unicode string; the API converts this to a string of single-byte ASCII characters before processing and routing the open request to the DCConnect Server. For all other operating systems, the name should be a string of single-byte ASCII characters.
Handle (LPHDWS (8)) - output
Address where the API should store the handle. Use the returned handle in all subsequent DWTS API calls to identify the calling user-written application.
Timeout (LONG (6)) - input
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The API call was successful and a valid handle was returned. If the keyword USE_DWS_OPEN_LOCALLY is being used in DWTS.INI, then receiving the return code DWS_NO_ERROR indicates the API call successfully went all the way to the DCConnect Server and back. |
DWS_ALREADY_OPEN | Another open call was issued using the same terminal name without an intervening DwsCloseTerminal call being issued. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_COMM_INIT_ERROR | Error starting communications system (not relevant if using TCP/IP). |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INVALID_NAME_LEN | The length of DOS/Windows terminal name is incorrect. The correct length of the DOS/Windows terminal name is from 1 to 32. |
DWS_INVALID_TERM_ID | The DOS/Windows terminal name is not defined locally with the DOS/Windows terminal. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_OPEN_ERROR | An error occurred trying to open/read from/write to one of the following files: CS2CBF01.CFS or DWTS.INI. A memory allocation error that occurs when trying to access these files could also result in this return code. |
DWS_OPEN_LOCALLY | The terminal name was validated locally but the API call did not make it all the way to the DCConnect Server and back. A valid handle is returned which can be used in the DwsSendTransaction API call. In this case, these transactions will be buffered on the terminal until a connection can be made with the DCConnect Server. Buffering of transactions is not done on terminals running DOS or Windows 3.1. For other Windows operating systems, buffering is only done if DWTS.INI includes the BUFFER_FILE keyword. For more information about this keyword please see BUFFER_FILE (SeeBUFFER_FILE) . |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
#include "dwts.h"
#define TERMNAME "PARTS_ROOM"
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
LONG timeout; /* Time out variable */
/*
* Open the DOS/Windows terminal for data collection processing. Use a
* 3 second timeout.
*/
timeout = 30;
rc = DwsOpenTerminal (TERMNAME, &handle, timeout);
if ((rc != DWS_NO_ERROR) && (rc != DWS_OPEN_LOCALLY))
{
printf("Error opening terminal. Return code = %d \n", rc);
// Handle error . . .
}
DwsSendTransaction (Handle, Transaction Sequence Number, Transaction ID, Transaction Data Length, Transaction Data Buffer, Timeout)
DwsSendTransaction sends your transaction data to the DCConnect Server where it is written to a transaction mailbox just like transactions from any data collection terminal.
Note: If the DWTS.INI file includes the DYNAMIC_CONFIG=Y keyword, then you must use the DwsSendTransactionDynamic API instead of DwsSendTransaction API in order to be able to tell the DCConnect Server the name(s) of the mailbox(es) into which the transaction should be stored. Most of the information below that is for DwsSendTransaction applies to DwsSendTransactionDynamic as well. For more information about DwsSendTransactionDynamic, please see DwsSendTransactionDynamic (SeeDwsSendTransactionDynamic) ..
For DwsSendTransaction only, the DCConnect Server determines to which mailbox(es) the transaction is written based on the terminal name (that was used in the DwsOpenTerminal call) and based on the Transaction ID parameter used in the DwsSendTransaction API call.
If an error occurred trying to send the transaction, the API interface has the ability to buffer the transaction and possibly automatically retry the transmission of the transaction - provided the terminal is not running DOS or Windows 3.1. For the 32-bit Windows operating systems, whether or not buffering or resending of transactions is done is based on what parameters are in DWTS.INI.
In order for transaction buffering to be done, the keyword:
BUFFER_FILEmust be defined in DWTS.INI. By default, the transaction buffer can hold 50 transactions. But you can override that using the keyword:
BUFFER_CAPACITY
As long as transaction buffering is active, you can also activate the automatic resending of transactions by including the keyword:
BUFFER_RESEND_DELAYin DWTS.INI. This tells the API interface how long it should wait before attempts to resend any transactions that are buffered. For more information about these keywords please see Configuration of DWTS on the Terminal (SeeConfiguration of DWTS on the Terminal) .
When transaction buffering is active and the DwsSendTransaction API call is made, a return code of DWS_NO_ERROR indicates the new transaction and any previously buffered transactions have been sent successfully to the DCConnect Server. But if the new transaction had to be buffered for any reason, the return code will be DWS_TRANS_BUFFERED.
If at the time DwsSendTransaction is called, a connection to the DCConnect Server does not exist and both buffering and automatic resending are enabled then DwsSendTransaction will return right away, setting the return code to DWS_TRANS_BUFFERED. This is true even if no transactions are currently buffered. This allows the API call to return right away so that more transactions can be generated rather than spending time trying to establish the connection to the DCConnect Server. The background resend process will worry about trying to establish the connection and will send all buffered transactions when the connection is established.
If the transaction buffer was full and no transactions could be sent to the DCConnect Server, the return code will be DWS_BUFFER_FULL. The return code will be DWS_BUFFER_SEND if transactions were already buffered at the time that DwsSendTransaction was called and some but not all of those transactions were able to be transmitted to the DCConnect Server before the timeout expired. In this case, the new transaction was added to the end of the transaction buffer.
Whether or not automatic resending is active does not affect the return codes for DwsSendTransaction. If it is active, attempts to resend queued transactions are done by the resend thread at the interval specified by the BUFFER_RESEND_DELAY parameter. The resend thread will use the BUFFER_RESEND_TIMEOUT value as the number of 0.1 seconds that it will wait for a response from the DCConnect Server for each transaction it sends. If BUFFER_RESEND_TIMEOUT is not specified in DWTS.INI, the timeout used is 5 seconds.
If buffering is active but automatic resending is not, attempts to send buffered transactions will only be made every time DwsSendTransaction is called. You can also use the API DwsSendBuffered to force an attempt to send buffered transactions.
If you do not or cannot have the API interface buffer and resend transactions for your application, your application must do that itself. If DwsSendTransaction returns DWS_TIMEOUT or DWS_COMM_ERROR your application will have to resend at a later time. A programmer can add code to the user-written program that will include logic to "do until return code == DWS_NO_ERROR" for the DwsSendTransaction API.
For information about a specific topic, click on it:
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
Transaction Sequence Number (LONG (6)) - input
The transaction sequence number is used to identify each transaction. It should be incremented each time a new transaction is sent. The transaction sequence number should not be incremented until the DCConnect Server indicates the transaction is stored in the appropriate mailbox by returning DWS_NO_ERROR. The transaction sequence number is in the range of 0 to 99999.
Transaction ID (USHORT (21)) - input
The Transaction ID identifies the type of transaction. This is a number in the range of 1 to 255. For DwsSendTransaction, it is used in conjunction with the terminal name to route the transaction to the correct DCConnect mailbox(es).
Transaction Data Length (USHORT (21)) - input
This is the length of the transaction data being sent to the DCConnect Server. This is a number in the range of 0 to 108.
Note: For Windows CE, the length specifies the number of Unicode characters, not the number of bytes.
Transaction Data Buffer (LPTCH (10)) - input
Pointer to the transaction data buffer. The API does not assume or look for a terminating null character at the end of the array.
For all operating systems except for Windows CE, the transaction data buffer must contain single-byte ASCII characters.
For Windows CE, the transaction data buffer must be an array of double-byte, Unicode characters; the API interface converts the Unicode array to an array of single-byte ASCII characters before sending it to the DCConnect Server.
Therefore regardless of the operating system of the DOS/Windows terminal, the DCConnect Server will always receive all transactions as an array of single-byte ASCII characters, never Unicode.
Timeout (LONG (6)) - input
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The new transaction and any buffered transactions were successfully sent to the DCConnect Server. |
DWS_BUFFER_FULL | The transaction was not sent to the DCConnect Server and it could not be added to the transaction buffer because that buffer is filled to capacity with previous transactions. An attempt was made to send the first buffered transaction but that was not successful. |
DWS_BUFFER_SEND | The transaction was not sent to the DCConnect Server yet. However, some, but not all buffered transactions were successfully sent to the Server before the timeout expired. The new transaction was added to the end of the transaction buffer. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DOES_NOT_EXIST | The transaction was not logged to any mailbox because no mailbox was configured for the terminal name/transaction ID combination. (This does not apply to DwsSendTransactionDynamic). |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_INVALID_SEQ_NUM | The Sequence number is not within the range of from 0 to 99999. |
DWS_INVALID_TRANSID | The transaction ID is not within the correct range of from 1 to 255. |
DWS_INVALID_LEN | The transaction length is greater than the range of from 0 to 108. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
DWS_TRANS_BUFFERED | The transaction was not sent to the DCConnect Server yet. Instead it was added to the end of the transaction buffer. See the discussion above for how to determine when an attempt will be made to resend it. |
#include "dwts.h"
#define BADGEDATA "0123345"
#define TRANSACTION_ID 8
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
ULONG seqnum; /* Sequence number */
TCHAR txdata[DWS_MAX_TRANS_LEN + 1]; /* Buffer for transaction data */
USHORT txdatalen; /* Number of characters in txdata */
/*
* Open the terminal to get the handle.
*/
...
/*
* Now set up the that the transaction is set up, it can be sent to DCConnect.
*/
time_out = 50; /* wait for up to 5 seconds */
seqnum = 1;
#if defined _WIN32_WCE
wsprintf(txdata, "%s", BADGEDATA);
txdatalen = wstrlen(txdata);
#else
sprintf(txdata, "%s", BADGEDATA);
txdatalen = strlen(txdata);
#endif
`
rc = DwsSendTransaction(handle, seqnum, TRANSACTION_ID, txdatalen, txdata,
time_out);
if (rc != DWS_NO_ERROR)
printf("Error sending transaction. Return code is %d \n", rc);
DwsSendTransactionDynamic (Handle, Transaction Sequence Number, Transaction ID, Transaction Data Length, Transaction Data Buffer, Timeout, Mailboxes)
This API provides the same function as DwsSendTransaction except that it must be used instead of DwsSendTransaction when the DYNAMIC_CONFIG=Y option is in effect in DWTS.INI. The dynamic version of this API has an additional parameter which is for a list of one or more mailboxes into which the DCConnect Server should store the transaction.
For information about the parameters and return codes that are common to both DwsSendTransaction and DwsSendTransactionDynamic and for general information about sending transactions to the DCConnect Server, including how transactions are buffered and the flow diagram, please see DwsSendTransaction (SeeDwsSendTransaction) .
For information about a specific topic, click on it:
Mailboxes (LPTCH (10)) - input
This is the list of one or mailbox names into which the DCConnect Server should store the transaction. Each name in the list must be a valid mailbox name in the DCConnect Server configuration. No more than DWS_MAILBOXES_PER_TRANS (10) mailboxes can be specified in a single transaction. If more are needed, you must issue multiple calls to this API.
The list of mailboxes is made up of a series of null-terminated mailbox names with one extra null-character at the end of the list. The extra null-character is required even when only one mailbox name is in the list; that extra null signals the end of the list.
For all operating systems except for Windows CE, the mailbox names (and nulls) must be specified using single-byte ASCII characters.
For Windows CE, the mailbox names (and nulls) must be specified using double-byte, Unicode characters; the API interface converts the Unicode characters to single-byte ASCII characters before sending the list to the DCConnect Server.
DWS_INVALID_MAILBOX | Either the list is empty or one of the names in the list is not the name of a mailbox that is defined in the DCConnect Server configuration. |
#include "dwts.h"
#define BADGEDATA "0123345"
#define TRANSACTION_ID 8
#define TARGET_MAILBOX1 TEXT("RECEIVING")
#define TARGET_MAILBOX2 TEXT("INVENTORY")
HDWS handle; // DWS handle
SHORT rc; // Return code from API call
ULONG seqnum; // Sequence number
TCHAR txdata[DWS_MAX_TRANS_LEN + 1]; // Buffer for transaction data
USHORT txdatalen; // Number of characters in txdata
TCHAR mailboxes[(DWS_MAILBOXES_PER_TRANS * (DWS_MAILBOX_NAME_LEN + 1)) + 1]
// List of mailboxes
TCHAR * nextMailbox; // Pointer to next place to copy mailbox name
/*
* Open the terminal to get the handle.
*/
...
/*
* Now set up the that the transaction is set up, it can be sent to DCConnect.
*/
time_out = 50; /* wait for up to 5 seconds */
seqnum = 1;
#if defined _WIN32_WCE
wsprintf(txdata, "%s", BADGEDATA);
txdatalen = wstrlen(txdata);
#else
sprintf(txdata, "%s", BADGEDATA);
txdatalen = strlen(txdata);
#endif
`
/*
* Now set up the list of mailboxes. Start by ensuring that the final,
* list-ending null is in place. This works for both Unicode and ASCII.
*/
memset(mailboxes, 0, sizeof(mailboxes));
nextMailbox = mailboxes;
_tcscpy(nextMailbox, TARGET_MAILBOX1);
nextMailbox += (_tcslen(nextMailbox) + 1);
_tcscpy(nextMailbox, TARGET_MAILBOX2);
rc = DwsSendTransactionDynamic(handle, seqnum, TRANSACTION_ID, txdatalen, txdata,
time_out, mailboxes);
if (rc != DWS_NO_ERROR)
printf("Error sending transaction. Return code is %d \n", rc);
DwsRequestValidation (Handle, Filename, Validation Data Length, Validation Data Buffer, Result, Timeout)
DwsRequestValidation sends a validation request to the DCConnect Server and waits for a reply that indicates whether the request data passed or failed validation. The application passes the data to be validated and the validation file name to use for validating against or for routing to a validation application.
The validation file name can specify one of the following: a validation file that was submitted to the DCConnect Server and resides in the DCConnect Server's %DCCONN%\VAL sub-directory, or a name that a DCConnect user-written application registered with the DCConnect Server for validation requests by calling DcxOpenValidation. The validation file name must use the validation file extension .VAL and cannot be longer than 12 characters including the .VAL file extension. Do not specify the path for the validation file name. If the format of the name is not valid, you receive the DWS_INVALID_FILE return code.
After this API returns, the Result field indicates whether the data passed or failed the validation. The value DWS_VALIDATION_PASS indicates that the data passed validation. Likewise, the value DWS_VALIDATION_FAIL indicates that the data failed validation. The value in the result field is set only if the return code for this API is DWS_NO_ERROR.
For information about a specific topic, click on it:
The DwsRequestValidation API sends the validation request containing the data to be validated and the specified validation file name to the DCConnect Server. The DCConnect Server will validate the data either against the specified validation file or an application validating the data. The DCConnect Server will return the result of the validation operation to the terminal PC when the return code is DWS_NO_ERROR.
Note that the DCConnect Server will only send a validation request to an
application if that application has registered to handle requests for the
specified validation file using the DcxOpenValidation API call and the
validation file does not currently exist in the %DCCONN%\VAL sub-directory
on the DCConnect Server PC.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
File Name (LPTSTR (11)) - input
The validation file name used for this request. This is a null-terminated string of 12 characters or less including the .VAL file extension.
For Windows CE, this is a double-byte, Unicode string; the API converts this to a string of single-byte ASCII characters before routing the validation request to the DCConnect Server. For all other operating systems, the file name should be a string of single-byte ASCII characters.
Validation Data Length (USHORT (21))- input
Length of the data to be validated. The validation data length is a range of from 1 to 99 characters.
Note: For Windows CE, the length is the number of Unicode characters, not the number of bytes.
Validation Data Buffer (LPTCH (10)) - input
Address of the buffer containing the data to be validated. The API does not assume or look for a terminating null character at the end of the buffer.
For Windows CE, the input buffer must be an array of double-byte, Unicode characters; the API interface converts the Unicode array to an array of single-byte ASCII characters before the validation request is sent to the DCConnect Server. For all other operating systems, the input buffer must contain single-byte ASCII characters.
Therefore regardless of the operating system of the DOS/Windows terminal, the DCConnect Server will always receive an array of single-byte ASCII characters, never Unicode. So if it is an application that is actually handling the validation request, that application will receive an array of single-byte characters.
Result (LPTCH (10)) - output
Result of the validation request. Valid values are:
DWS_VALIDATION_PASS | The file name specified included the necessary data. |
DWS_VALIDATION_FAIL | The file name specified did not include the specified data. |
Note: For Windows CE, the type of Result is a Unicode character. So be sure to define as a TCHAR, the variable that will receive the result. The definitions of DWS_VALIDATION_PASS and DWS_VALIDATION_FAIL are cast to the type TCHAR in DWTS.H.
Timeout (LONG (6)) - input
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive timeout value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
If you get a return code from the DwsRequestValidation indicating a DWS_TIMEOUT or DWS_COMM_ERROR, then you must retry the DwsRequestValidation. There is no retry of the sending of the validation request on behalf of the user-written application.
DWS_NO_ERROR | The API call was successful. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_DATA_LEN | The length of the validation data is not in the 1 to 99 range. |
DWS_INVALID_FILE | The validation file name is 12 or less characters including the .VAL file extension or the name does not include the .VAL extension (in upper case). |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
#include "dwts.h"
#define BADGEDATA "0123345"
#define VALIDATION_FILENAME "BADGE.VAL"
HDWS handle; /* DWS handle */
TCHAR result; /* Pass or Fail verification results */
SHORT rc; /* Return code */
TCHAR filename[DWS_VAL_FILE_NAME_LEN + 1]; /* Buffer for filename */
TCHAR data[DWS_MAX_VAL_LEN + 1]; /* Buffer for data to be validated */
USHORT datalen; /* Length of data in characters */
/*
* Open terminal and get handle . . .
*/
...
/*
* Set up the validation request.
*/
#if defined _WIN32_WCE
wsprintf(filename, "%s", VALIDATION_FILENAME);
wsprintf(data, "%s", BADGEDATA);
datalen = wstrlen(data);
#else
sprintf(filename, "%s", VALIDATION_FILENAME);
sprintf(data, "%s", BADGEDATA);
datalen = strlen(data);
#endif
rc = DwsRequestValidation(handle, filename, datalen, data, &result,
DWS_TIMEOUT_FOREVER);
if (rc != DWS_NO_ERROR)
printf("Cannot Validate Data. Return code = %d, Contact Systems Administrator \n", rc);
else if (result == DWS_VALIDATION_PASS)
printf("Badge Data was validated successfully. Opening Front Door\n");
else
printf("Invalid Badge Data. Try Again\n");
DwsRequestTime(Handle, Time Date Structure Pointer, Timeout)
or for Windows CE:
DwsRequestTime(Handle, Time String, Date String, Time Structure Pointer, Date Structure Pointer, Timeout)
DwsRequestTime sends a request to the DCConnect Server for the current date and time. The DCConnect Server's date and time are returned to the caller in the Time Date Structure Pointer field. The user of the DWTS program can then use this information to set the time of day clock for the DOS/Windows terminal.
If the user gets the DwsRequestTime return code indicating DWS_TIMEOUT or DWS_COMM_ERROR, then the user must retry the API call.
For terminals running Windows CE, there are a couple of differences in the use of this API call:
For information about a specific topic, click on it:
The DwsRequestTime API requests that the DCConnect Server send the DOS/Windows PC application the current date and time from the DCConnect Server's system unit clock. However, if the terminal is configured in DCConnect indicating its Time Zone is different from that of the Server, then the time and date returned by this API will be adjusted by the appropriate number of hours relative to the DCConnect Server's time and date.
If the return code is DWS_NO_ERROR, then the date and time are returned to the application. If the
application receives any other return code, it should retry the DwsRequestTime API call.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
Time Date Structure Pointer (LPTIMEDATE (12)) - output
For all but Windows CE programs: The address of a TIMEDATE structure. When the DwsRequestTime API call returns, it contains a time string, a date string and two filled in dostime_t and dosdate_t structures. The latter two are defined in the standard C header file DOS.H.
Note: The strings are in the following format and can be used by BASIC programmers to set the date and time in a BASIC program:
"MM/DD/YY\0"
"HH:MM:SS\0"
The date and time strings in the TIMEDATE structure are single-byte, ASCII strings.
Time String (LPTSTR (11)) - output
For Windows CE only: The time string returned which has the format:
"HH:MM:SS\0"
This is a string of 8 double-byte Unicode characters plus a terminating null character (a total
of 18 bytes). A buffer of this size must be allocated for this parameter prior to calling the API.
Date String (LPTSTR (11)) - output
For Windows CE only: The date string returned which has the format:
"MM/DD/YY\0"
This is a string of 8 double-byte Unicode characters plus a terminating null character (a total
of 18 bytes). A buffer of this size must be allocated for this parameter prior to calling the API.
Time Structure Pointer (struct dostime_t *) - output
For Windows CE only: Pointer to the dostime_t structure, which is defined in DWTS.H when building a Windows CE program. When the DwsRequestTime API call returns, the structure at this pointer is filled in with the appropriate hour, minute and second and the hundreds value is set to 99.
This pointer can be set to NULL (0) in order to tell the API not to try to fill in this structure. In fact, if calling the API from Embedded Visual Basic, this parameter must be set to 0.
Date Structure Pointer (struct dosdate_t *) - output
For Windows CE only: Pointer to the dosdate_t structure, which is defined in DWTS.H when building a Windows CE program. When the DwsRequestTime API call returns, the structure at this pointer is filled in with the appropriate day of the month, month, year and day of the week.
This pointer can be set to NULL (0) in order to tell the API not to try to fill in this structure. In fact, if calling the API from Embedded Visual Basic, this parameter must be set to 0.
Timeout (LONG (6)) - input
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The API call was successful. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
For DOS / Windows 3.1:
#if !defined _WIN32
#include <dos.h>
#endif
#include "dwts.h"
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
TIMEDATE dcmtime; /* Structure to contain the time and date */
LONG time_out; /* Time out variable */
/*
* Send a request for the DCConnect Server's time and date. Wait up to 2 seconds.
*/
time_out = 20;
#if defined _WIN32_WCE
rc = DwsRequestTime(handle, dcmtime.timestr, dcmtime.datestr, &(dcmtime.time),
&(dcmtime.date), time_out);
#else
rc = DwsRequestTime(handle, &dcmtime, time_out);
#endif
/*
* If the call was successful, set the terminal's date and time to match the
* DCConnect date and time.
*/
if (rc == DWS_NO_ERROR)
{
#if defined _WIN32 // For 32-bit Windows and Windows CE
SYSTEMTIME datetime;
memset (&datetime, 0, sizeof(datetime)); // Initialize whole structure
datetime.wSecond = dcmtime.time.second;
datetime.wMinute = dcmtime.time.minute;
datetime.wHour = dcmtime.time.hour;
datetime.wDay = dcmtime.date.day;
datetime.wMonth = dcmtime.date.month;
datetime.wYear = dcmtime.date.year;
if (SetLocalTime(&datetime) == FALSE)
{
...
}
#else
_dos_settime(&(dcmtime.time));
_dos_setdate(&(dcmtime.date));
#endif
}
DwsRequestData(Handle, Application Name, Request Data Length, Request Data Buffer, Response Length Pointer, Response Buffer, Timeout)
DwsRequestData sends a request for data to the DCConnect Server. Upon receiving the request, the DCConnect Server then routes the request to the user-written application named in the DwsRequestData API call. For the request to be successful, a user-written application must have previously issued a DcxOpenRequestHandler API call to the DCConnect Server, specifying the same application name.
Data will only be returned by the DwsRequestData API call if the return code is DWS_NO_ERROR.
For information about a specific topic, click on it:
The DwsRequestData API allows a DOS/Windows program to send a request for data to a DCConnect user
application and have that application provide response data back to the DOS/Windows program. This API
allows a DOS/Windows program to send a request for a database look-up to an application on the
DCConnect Server which can then perform the look-up and return the retrieved information to the
DOS/Windows program.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
This name must match a user-written application name that was registered with the DCConnect Server during a DcxOpenRequestHandler call. The user-written application name parameter is a null-terminated string from 1 to 32 characters.
For Windows CE, the name should be a double-byte, Unicode string; the API converts this to a string of single-byte ASCII characters before routing the data request to the DCConnect Server. For all other operating systems, the name should be a string of single-byte ASCII characters.
The length of the data in the request data buffer. The request data length cannot be greater than 16384 characters.
Note: For Windows CE, the length specifies the number of Unicode characters, not the number of bytes.
The request data buffer contains data that is sent to the receiving user-written application. This information is used by the receiving user-written application to determine what type of data the terminal is requesting. The API does not assume or look for a terminating null character at the end of the buffer.
For Windows CE, the request data buffer must contain an array of double-byte, Unicode characters; the API interface converts the Unicode array to an array of single-byte ASCII characters before the validation request is sent to the DCConnect Server. For all other operating systems, the request data buffer must contain single-byte ASCII characters.
Therefore regardless of the operating system of the DOS/Windows terminal, the DCConnect Server will always receive an array of single-byte ASCII characters, never Unicode. So the application handling the data request will only have to handle an array of single-byte ASCII characters.
A pointer to the value that specifies how many characters the response buffer can hold. On return of this API, this value will be set to the actual number of characters that were put into the buffer (if the return code is DWS_NO_ERROR).
Note: For Windows CE, the length specifies the number of Unicode characters, not the number of bytes.
If the value at this pointer is set to 0 when the API is called, the DWTS API returns the length of the response in the variable and sets the return code to DWS_NO_ERROR but it does not actually return anything in the Response Buffer. A second call to the API with a non-zero value for the response length will result in the data being returned. This allows an application to allocate the precise amount of memory needed before actually retrieving the data.
If the maximum length specified is not 0 but is shorter than the actual data received, the DWTS API does not return any data to the caller and returns a DWS_DATA_OVERRUN return code.
The response data length cannot be greater than 16384 characters.
The address of the data buffer to receive the response data from the user-written application registered with the DCConnect Server.
For Windows CE, the returned data will be in the format of a double-byte, Unicode character array. Even though the application that sends the response to the DCConnect Server using the DCConnect API DcxReplyDataRequest passes an array of single-byte ASCII characters, the API converts these characters to double-byte Unicode before it returns the data to the Windows CE application.
For all other operating systems, the data returned is an array of single-byte ASCII characters - exactly as it is received from the DCConnect Server.
In all cases, a terminating null character is not added to the end of the buffer by the API interface. However, if the replying application included a terminating null in the response data, that terminating null will be passed back.
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The API call was successful. |
DWS_APPL_NOT_REGISTERED | Application name in request is not registered with DCConnect. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DATA_OVERRUN | The response buffer is too small for the data received. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_INVALID_NAME | The application name is not from 1 to 32 characters. |
DWS_INVALID_REQ_LEN | The request data length is greater than 16384 characters. |
DWS_READ_FAILED | Application is registered but failed to issue a read request. |
DWS_READ_SUCCESS_NO_REPLY | The request data API timeout expired after the "Receiving application" issued a successful DcxReadDataRequest but, before the "Receiving application" issued a DcxReplyDataRequest. Or, the "Receiving application" issued a DcxReadDataRequest with the RequestData length equal to zero, then issued a DcxCloseRequestHandler API. In this case, no data is read, only the data length was returned. For a DcxReadDataRequest API to be successful, the API must have had a request length not equal to zero and received a DCX_NO_ERROR. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
#include "dwts.h"
#define REQ_DATA "PN12345"
#define PROGRAM "PARTS"
HDWS handle; /* DWS handle */
LPTCH pbuffer; /* Response data buffer pointer */
SHORT rc; /* Return code from API call */
USHORT reqlen; /* Request buffer length */
USHORT size; /* Response data length */
TCHAR appname[DWS_APPL_NAME_LEN + 1]; /* Application name */
static TCHAR reqbuffer[DWS_MAX_REQ_LEN + 1]; /* Large request buffer, not */
/* allocated on stack */
#if defined _WIN32_WCE
wsprintf(appname, "%s", PROGRAM);
wsprintf(reqbuffer, "%s", REQ_DATA);
reqlen = (USHORT)wstrlen(reqbuffer);
#else
sprintf(appname, "%s", PROGRAM);
wsprintf(reqbuffer, "%s", REQ_DATA);
reqlen = (USHORT)strlen(reqbuffer);
#endif
/*
* Call DwsRequestData twice. The first time to request the length of the
* response data - the second time to receive the data. After the first
* reply, we allocate a buffer large enough to hold the reply plus a
* terminating null.
*/
size = 0;
rc = DwsRequestData(handle, appname, reqlen, reqbuffer, &size,
NULL, DWS_TIMEOUT_FOREVER);
if (rc == DWS_NO_ERROR)
{
pbuffer = (LPTCH *)malloc((sizeof(TCHAR) * (size+1));
if (pbuffer)
{
rc = DwsRequestData(handle, appname, reqlen, reqbuffer,
&size, pbuffer, DWS_TIMEOUT_FOREVER);
/*
* If the data is retrieved successfully, terminate it with a null
* character and show it.
*/
if (rc == DWS_NO_ERROR)
{
pbuffer[size] = 0; /* Convert buffer to a string */
#if defined _WIN32_WCE
MessageBox(NULL, pbuffer, TEXT("Data received"), MB_OK);
#else
printf("The response data received is %s\n", pbuffer);
}
else
{
; // Handle error from data request
}
} // if (pbuffer)
else
{
; // Handle memory allocation error
}
} // First request successful
else
{
; // Handle request for length failure
}
DwsSetUserVariable(Handle, Variable Number, Data Buffer, Timeout)
DwsSetUserVariable attempts to set a terminal user variable to the value specified. Terminal user variables are stored on the DCConnect Server, so a message must be sent to the server to request that the variable be set. Terminal user variables should not be confused with variables in your C/C++ or Basic program. Terminal user variables are used to communicate information between the terminal and the DCConnect Server.
An application will most often use this API to clear out a user variable that it later expects an application to set in response to a transaction or validation request. But user variables can also be used for sending other information to an application on the PC - particularly if all the information can't fit into a transaction.
If the Server is unavailable, a DWS_TIMEOUT error will result.
Also see DwsGetUserVariable (SeeDwsGetUserVariable)
Note: The contents of all terminal user variables for DOS/Windows terminals are lost whenever the DCConnect Server is restarted - even if the DOS/Windows application continues to run while the DCConnect Server is shut down and started up.
For information about a specific topic, click on it:
The DwsSetUserVariable API allows a DOS/Windows program to set a terminal user variable. This API is
useful for transfering non-transacional data between a DOS/Windows terminal and fsthe DCConnect Server.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
The number of the user variable to set. This value must be in the range 1 to 999.
The value to set the user variable to. The data is interpreted as a null-terminated string, so control characters should not be imbedded in the string. The string can be a maximum of 118 characters long. The API looks for the terminating null character to determine the length of the data to be sent. The terminating null character is not considered part of the 118 characters of data.
For Windows CE, this is a pointer to a string of double-byte, Unicode characters; the API will convert this to a string of ASCII characters before sending the set user variable request to the DCConnect Server. For all other operating systems, the buffer should contain a string of single-byte ASCII characters.
Regardless of the operating system on the DOS/Windows terminal, the DCConnect Server will always receive the user variable data as a string of ASCII characters.
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The API call was successful. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_INVALID_LEN | The string specified is more than 118 characters long. |
DWS_INVALID_VARIABLE | The variable number specified was not in the range 1 to 999. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
#include "dwts.h"
#define SET_DATA "User variable data"
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
TCHAR uvData[DWS_MAX_VAR_LEN + 1]; /* Buffer containing UV data */
#if defined _WIN32_WCE
wsprintf(uvData, "%s", SET_DATA);
#else
sprintf(uvData, "%s", SET_DATA);
#endif
rc = DwsSetUserVariable(handle, 1, uvData, DWS_TIMEOUT_FOREVER);
if (rc != DWS_NO_ERROR)
{
; // Handle error
}
DwsGetUserVariable(Handle, Variable Number, Data Buffer, Wait for Data, Timeout)
DwsGetUserVariable attempts to retrieve the value of a terminal user variable from the DCConnect Server. Terminal user variables are maintained on the DCConnect Server, so a message must be sent to the Server to request that the variable be retrieved.
Terminal user variables should not be confused with variables in your C/C++ or Basic program. Terminal user variables are used to communicate information between the terminal and the DCConnect Server. Generally this is done so that the DCConnect Server can inform the terminal when a transaction is received and processed. User variables can also be used to indicate the success or failure of that processing or to return information to the terminal.
Using user variables to send data back to a terminal is the mechanism that is required by terminals that are running the DCConnect Client. So although a DWTS application can use a data request to get information from the DCConnect Server, if the application will be handling transactions / requests from both terminals running a DWTS application and terminals running the DCConnect Client, that application can send information to both kinds of terminals using user variables and the DWTS application can use DwsGetUserVariable to get that information.
If the Server is unavailable, a DWS_TIMEOUT error will result.
This caller of this API can specify that the API not return until the user variable contains data - or until the timeout expires. The 'Wait for Data' parameter is used for this purpose.
For 32-bit Windows and Windows CE platforms, this API can be issued simultaneously from different threads if it is necessary to wait for more than one user variable to be set. The 'Wait for Data' parameter must be set to ASYNCH_WAIT for each thread that must do this. See the 'Wait for Data' parameter below for more information.
Also see DwsSetUserVariable (SeeDwsSetUserVariable)
Note: The contents of all terminal user variables for DOS/Windows terminals are lost whenever the DCConnect Server is restarted - even if the DOS/Windows application continues to run while the DCConnect Server is shut down and started up.
For information about a specific topic, click on it:
The DwsGetUserVariable API allows a DOS/Windows program to retrieve a terminal user variable. This API is
useful for transfering non-transacional data between a DOS/Windows terminal and the DCConnect Server.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
The number of the user variable to retrieve. This value must be in the range 1 to 999.
Buffer to hold the data from the user variable. The returned string can be a maximum of 118 characters long plus the terminating null character. Therefore the size of this buffer should be at least 119 characters in length.
For Windows CE, the returned data is a string of double-byte, Unicode characters; the 118 character limit refers to the number of characters not the number of bytes.
For all other operating systems, the buffer will contain a string of single-byte ASCII characters.
Because the returned data is null-terminated, the C function strlen (wstrlen for Windows CE) can be used to determine the length of the data. If the user variable is empty, a single null character will be put into the buffer.
Indicates whether the call waits for data to be set in the user variable before returning. This is very useful when the terminal is waiting for the application on the DCConnect Server PC to complete some processing before the terminal continues its execution. One example is to wait for the application on the server to indicate that a transaction has been processed.
This parameter may be set one of three different ways:
0 | Means the API call should not wait for data if none is available. |
ASYNCH_WAIT (128) | This value is valid only for 32-bit Windows and Windows CE platforms and should be used if this API request is being made from a separate thread(s) with the intention that the main application thread can continue to do other work, including issuing other DWS API calls while the thread(s) wait for a user variable to be set. The main application thread cannot also call DwsGetUserVariable if there are other threads waiting for a DwsGetUserVariable call to complete. If the main application thread calls DwsCloseTerminal, all threads waiting for DwsGetUserVariable to complete will receive the return code DWS_CLOSING_TERMINAL. |
Any other value | Used by the main application thread to specify that the API should wait if not user variable data is available right away. |
If this flag is not 0, the maximum amount of time that the DCConnect Server will wait for data is specified by the Timeout parameter below. The API will return as soon as the data is available - which could be right away. If no data is available in the user variable before the timeout expires, the return code will be DWS_TIMEOUT.
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The API call was successful. |
DWS_CLOSING_TERMINAL | Another thread has called DwsCloseTerminal. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_INVALID_VARIABLE | The variable number specified was not in the range 1 to 999. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. If the 'Wait for data' flag is non-zero, this return code indicates that the user variable did not contain any data during the entire timeout period. |
#include "dwts.h"
#ifndef TRUE
#define TRUE 1
#endif
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
TCHAR var_data[DWS_MAX_VAR_LEN + 1]; /* Buffer for variable data */
/*
* Get the contents of user variable 1, wait up to 10 seconds for the variable to
* contain data.
*/
rc = DwsGetUserVariable(handle, 1, var_data, TRUE, 100);
if (rc == DWS_NO_ERROR)
{
; // Use the data as required
}
else
{
; // Handle error or timeout
}
DwsSendBuffered(Handle, timeout)
DwsSendBuffered is used to tell the DWTS API to try one more time to send any transactions that are still buffered on the terminal side. This API is only valid for 32-bit Windows applications - as long as transaction buffering has been enabled via the parameters in DWTS.INI. Please see DwsSendTransaction (SeeDwsSendTransaction) for information about what parameters must be in DWTS.INI in order to activate transaction buffering.
The timeout parameter specifies how long the API will wait for any buffered transactions to be sent, regardless of how many there are. Do not specify a negative value for the timeout (including DWS_TIMEOUT_FOREVER).
If the return code from this API is DWS_NO_ERROR, then all buffered transactions were successfully sent to the DCConnect Server, if there were any.
If the return code is DWS_BUFFER_SEND, then there was more than one transaction buffered and at least one of them was sent successfully to the DCConnect Server. But not all could be sent, either due to an error or a timeout. The API should be retried in order to have the rest of the transactions sent.
If the return code is DWS_TIMEOUT, then at least one transaction is buffered, but none were able to be sent to the DCConnect Server. The API can be retried, but it may be necessary to increase the timeout for the next attempt.
The API DwsQueryTransactionCnt can be used to find out how many transactions are currently buffered.
For information about a specific topic, click on it:
The DwsSendBuffered API actually results in one or more DwsSendTransaction
calls being sent to the DCConnect Server, one for each transaction that is
buffered - unless there are none to send or one attempt to send a transaction fails.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
Specifies the amount of time to wait for any buffered transactions to be sent to the DCConnect Server. This the maximum time that the API will wait, regardless of how many transactions need to be sent. A positive time-out value indicates the number of 0.1 seconds to wait. Do not specify a negative value or DWS_TIMEOUT_FOREVER.
If the return code is DWS_BUFFER_SEND, some of the buffered transactions were sent successfully. Therefore this API should be issued again, perhaps with a longer timeout, in order to have the remaining transactions sent to the DCConnect Server.
DWS_NO_ERROR | The API call was successful; all buffered transactions, if there were any, were successfully sent to the DCConnect Server. |
DWS_BUFFER_SEND | There were buffered transactions and one or more were successfully sent to the DCConnect Server. But there is also at least one transaction that still remains in the buffer. The API DwsQueryTransactionCnt will indicate how many are still buffered. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_INVALID_LEN | The length of the timeout specified is invalid. The timeout value for this API cannot be less than 0 (and it can't be DWS_TIMEOUT_FOREVER). |
DWS_STOP_COMM_ERROR | A problem terminating communications. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | There are buffered transactions but none were successfully sent to the DCConnect Server during the timeout period. |
#include "dwts.h"
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
LONG timeout; /* Time out variable */
/*
* Make sure any buffered transactions have been sent to the
* DCConnect Server.
*/
timeout = 50; /* Set time out value to 5 seconds */
rc = DwsSendBuffered (handle, timeout);
if (rc != DWS_NO_ERROR)
{
; // Handle error
}
DwsCloseTerminal(Handle, timeout)
DwsCloseTerminal is used to close the DWTS API handle that was returned on a previous call to DwsOpenTerminal. The user-written application can no longer call any of the DWTS API's until a new call to DwsOpenTerminal is completed successfully. Any resources associated with the handle are freed when the handle is closed.
For information about a specific topic, click on it:
The DwsCloseTerminal API is the last call required. This API closes the TCP/IP session between the DOS/Windows PC and the DCConnect Server. It also changes the status for the DOS/Windows terminal, on the DCConnect Server node, to "not responding".
Note: If a DOS/Windows program successfully issued a DwsOpenTerminal API call and
then later ends without calling DwsCloseTerminal, the DCConnect user
interface will still show the associated DWTS terminal as being in service.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal.
Specifies the amount of time to wait for a reply from the DCConnect Server. A positive time-out value indicates the number of 0.1 seconds to wait. This causes the application to wait the time specified or until there is a reply from the DCConnect Server. If the user-written application wishes to wait for a definite response from the DCConnect Server it must specify DWS_TIMEOUT_FOREVER.
DWS_NO_ERROR | The API call was successful. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_COMM_ERROR | The DOS/Windows terminal cannot communicate with the DCConnect Server. |
DWS_DCCONN_NOT_READY | The DCConnect Server is not ready to receive data or requests. |
DWS_INTERNAL_ERROR | Undetermined error. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. |
DWS_STOP_COMM_ERROR | A problem terminating communications. |
DWS_TERM_NOT_DEFINED | The DOS/Windows terminal is not defined with the DCConnect Server. |
DWS_TIMEOUT | The API call timed out before a response was received. |
#include "dwts.h"
HDWS handle; /* DWS handle */
SHORT rc; /* Return code from API call */
LONG timeout; /* Time out variable */
/*
* Close the DOS/Windows terminal and stop data collection processing
*/
timeout = 50; /* Set time out value to 5 seconds */
rc = DwsCloseTerminal (handle, timeout);
if (rc != DWS_NO_ERROR)
{
; // Handle error
}
DwsQueryTransactionCnt(Handle, numTxtns, numFree)
DwsQueryTransactionCnt is used to find out how many transactions are currently buffered in the terminal, waiting to be sent to the DCConnect Server.
The API interface not only returns the number of transactions in the buffer, it also returns the number of transactions that can be still added to the buffer (this is calculated by subtracting the number of transactions currently in the buffer from the buffer capacity).
Although this API specifies the handle for the first parameter, it can be called even before DwsOpenTerminal is issued by specifying 0 for that handle. In this case, the API interface gets the name of the transaction logfile from DWTS.INI, opens the file and then reads the header information to determine the number of transaction buffered and the capacity.
For information about a specific topic, click on it:
Because the work of this API does not entail any interaction with the DCConnect Server there is no flow diagram to show.
Handle (HDWS (5)) - input
The handle that was returned from DwsOpenTerminal. If calling this API when no valid handle is available (before DwsOpenTerminal is called), 0 must be passed in for the handle. 0 can also be passed in even when DwsOpenTerminal has successfully been called and a valid handle is available. In this case, the API acts just like it would had the correct handle been passed in.
DWS_NO_ERROR | The API call was successful; the values for 'numTxtns' and 'numFree' have been set successfully. |
DWS_BUFFER_ERROR | An error occurred trying to read from the transaction buffer file. |
DWS_DWTS_BUSY | A previous call is still in progress. |
DWS_INVALID_HANDLE | The handle that was returned in the DwsOpenTerminal API is the handle that must be used in the user-written application. 0 may also be used to avoid handle validation. |
DWS_OPEN_ERROR | The file DWTS.INI could not be opened or read or a memory allocation error occurred when trying to read the file contents into memory. |
#include "dwts.h"
SHORT rc; // Return code from API call
USHORT numTxtns = 0; // Number of transactions in buffer
USHORT numFree = 0; // Space available for more
if (DwsQueryTransactionCnt(0, &numTxtns, &numFree) == DWS_NO_ERROR)
{
printf("Number of transactions still buffered: %d\n", numTxtns);
printf("Number of transactions that can be added: %d\n", numFree);
}
At the end of this documentation is a series of footnotes, the first 21 of which describe various data types used by DWTS. These are either defined in DWTS.H or in the default operating system .h files provided with your compiler.
Some of the data types are pointers used by the DWTS APIs. Although several types are essentially pointers to character arrays, each implies a different meaning. For example PSZ implies a pointer to a null-terminated character array while PCHAR implies a pointer to a character array that is not necessarily null-terminated.
The footnotes at the end of this document provides definitions for terms used in this online book. The first 16 footnotes are for data type descriptions. The rest are for glossary terms.
The sample programs demonstrate the following DWTS data collection operations:
A dialog box is displayed for the user to type the name of the terminal being opened. The terminal name entered must match the name configured on the system unit.
The sample programs show when to and when not to increment the transaction sequence number. Each sample displays a data entry field where the user can input a string of data to be sent to the DCConnect server.
Normally validation requests are done during the input of transaction data. An example is, checking that a part number is valid before sending the transaction data. In the sample code performing validation is shown as a separate operation to make it clear to the programmer.
A validation file named "DWTSDATA.VAL" is installed on the DCConnect server during installation of the product. This validation file contains items to be used to compare with the validation request received by the DCConnect server from the sample programs.
The sample program demonstrates both a successful and unsuccessful validation requests. The program displays an entry field with a list of selectable items. The user has the option to select an item from the list provided to see an example of a successful validation. Or, the user can type an invalid string into the entry field resulting in an unsuccessful validation request.
The sample program can send a date and time request to the DCConnect server. The DCConnect server replies by returning the current date and time. An option is available to set the DOS or Windows system unit date and time to match that of the DCConnect server.
Additional operations are demonstarted in the Visual Basic and C/C++ samples for Windows 3.1, Windows 95/98/Me, Windows NT/2000/XP/7/Server and Windows CE:
The user can enter a string in the Data Request window, and that request is sent to the DCConnect server. A program running on the server must be registered to respond to the data. We have provided such a program in the SAMPLES directory called REQDATA which can be used to respond to the data requests. The sample responder program responds to the data request by returning the request string with "Reply to data request: " at the beginning of the string. Ie. if you send a request string of "12345", the response data will be "Reply to data request: 12345".
The sample demonstrates the ability to set and get a terminal user variable. The user can set a terminal variable and then read the value back. It is also possible to wait for a variable to contain data before returning to the data to the user (a timeout will of course override waiting for the data.) Terminal user variables are primarily useful when the terminal is communicating with an application on the DCConnect server (such as Transaction Connection).
The C/C++ sample for Windows 95/98/Me/NT/2000/XP/7/Server and Windows CE also demonstrates the use of the ASYNCH_WAIT parameter for the DwsGetUserVariable API. The dialog has an Asynch check box. If you check this box and fill in the timeout and then click the Get UV button, a thread is started to wait for data in that UV. You can then make additional asynchronous Get UV requests before the first one completes.
| Library Name | Description |
| DWTSWIN.LIB | This is an import library that is linked with the Windows data
collection programs. This library is required to provide program
access to the DWTS API that is supported in the Windows
environment. This library supports all of the standard Windows memory
models. Care should be taken to use the correct library for your platform.
Windows 3.1 programs (16-bit) should be linked against the library in the
Win16 directory, while 32-bit Windows programs (for Windows
95/98/Me/NT/2000/XP/7/Server) should be linked against the library in the
Win32
For Windows CE there is a different library for each of the supported devices - which represent different combinations of processor and Windows CE version. Listed below are the directory names with a comment for each:
The directory names above refer to various devices that we've tested and that have the indicated combination of Windows CE version and processor. Listed below, in the same order, are those devices:
Other devices should be able to use the libraries from the directories listed above provided they have the same combination of Windows CE version and processor. For example, the following two devices both run Windows CE 3.0 and have the Strong ARM 1110 processor from Intel:
|
| DWTSDOS.LIB | This library is a static library that is linked with DOS-only
data collection programs. It provides access to the DWTS API
while running in the DOS environment. This library supports
only large memory model DOS programs. This library is specific to the
TCP/IP stack that you are using, so choose the library from either:
|
16-bit DOS C Sample | This sample, located in the Samples\DwtDOS directory, includes the make file dwtdos.mak for building the DOS C sample with the Microsoft Visual C++ 1.5 compiler. When building this sample, you must specify which TCP/IP stack will be used by the sample. If using the IBM TCP/IP stack, use the following command to build the sample: nmake DwtDos.Mak STACK=IBM If using the FTP Software (NetManage) stack, use the following command to build the sample: nmake DwtDos.Mak STACK=FTP If the "STACK=" parameter is not provided, the DWTS library for the IBM stack will be linked. |
16-bit Windows 3.1 C Sample | This sample, located in the Samples\Win16 directory, includes the make file dwtsmp16.mak for building the Windows 3.1 C sample with the Microsoft Visual C++ 1.5 compiler. |
32-bit Windows C/C++ Sample | This sample, located in the Samples\Win32_CE directory, includes the workspace file dwtsmp32.dsw, the project file dwtsmp32.dsp and the make file dwtsmp32.mak for building the Windows 95/98/Me/NT/2000/XP/7/Server C/C++ sample with version 6.0 of the Microsoft Visual Studio C/C++ Compiler. The source for this sample is also used for the Windows CE samples. |
Windows CE C/C++ 3.0 Sample | This sample, located in the Samples\Win32_CE directory, includes the workspace file dwtsmpce.vcw, the project file dwtsmpce.vcp and the make file dwtsmpce.vcn for building the various flavors of the Windows CE C/C++ sample with version 3.0 of Microsoft eMbedded Visual C++ compiler. The source for this sample is also used for the 32-bit Windows C/C++ sample and the Windows CE C/C++ 4.0 Sample. |
Windows CE C/C++ 4.0 Sample | This sample, located in the Samples\Win32_CE directory, includes the workspace file dwtsmp40.vcw, the project file dwtsmp40.vcp and the make file dwtsmp40.vcn for building the various flavors of the Windows CE C/C++ sample with version 4.0 of Microsoft eMbedded Visual C++ compiler. The source for this sample is also used for the 32-bit Windows C/C++ sample and the Windows CE C/C++ 3.0 Sample. |
16-bit Windows 3.1 Basic Sample | This sample, located in the Samples\basic\win16 directory, includes the make file dwtsbas.mak for building the Windows 3.1 Basic sample with the 16-bit Visual Basic compiler. |
32-bit Windows Basic Sample | This sample, located in the Samples\basic\win32 directory, includes the workspace file dwtsbas.vbw and the project/make file dwtsbas.vbp for building the Windows 95/98/Me/NT/2000/XP/7/Server Basic sample with version 6.0 of the Microsoft Visual Studio Visual Basic compiler. |
Windows CE Basic Sample | This sample, located in the Samples\basic\wince directory, includes the workspace file dwtsbas.vbw and the project/make file dwtsbas.ebp for building the various flavors of the Windows CE Basic sample with version 3.0 of the Microsoft eMbedded Visual Basic compiler. At this time no VB .NET samples are provided. Note: If building of this sample from the command line results in an application exception, as it does for us, the sample must be built from within the Microsoft eMbedded Visual Basic IDE. |
Windows Runtime .DLLs Required By Some Sample Programs
If you try to run the sample DWTS application on your Windows 3.1 or Windows 95/98/Me system and you get an error that the following .DLLs were not found:
Samples\DLLs\SAMPLDLL.EXESimply run the executable in order for it to extract the .DLLs from the zip file.
DWTSWIN.DLL Required by the Sample Programs For Windows Platforms
The samples that run on Windows and Windows CE require the appropriate version of DWTSWIN.DLL to be located in the path in order for them to run successfully:
16-bit Windows 3.1 C or Basic Sample | requires WIN16\DWTSWIN.DLL |
32-bit Windows C/C++ or Basic Sample | requires WIN32\DWTSWIN.DLL |
Windows CE C/C++ or Basic Sample | requires one of the following based on the device type or Windows CE version/processor type:
Putting this .DLL in the \Windows directory of the Windows CE device ensures that it will be found. |
License and Configuration File Required By the Sample Application
Any application that calls DWTS APIs requires that the license file, DWSCHECK.LIC, and the configuration file, DWTS.INI, are found when DwsOpenTerminal is called.
For non-Windows CE devices, if the environment variable:
DWTSis defined, then the API will look for the files in the directory defined by that environment variable. If this environment variable is not defined, then the files must be located in the current directory.
For Windows CE devices where there is no concept of environment variables, if the following registry key:
\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\DWTSis defined and contains the value "path", then the API will look for the files in the directory defined by the 'path' variable. If this registry key and value are not defined, the the files must be located in the root directory of the device.
The product license file required on each device can be obtained from the top level directory that was created by the CD installation of the DWTS product to your harddrive. For example:
C:\DCCONN\DWTS\DWSCHECK.LIC
The configuration file is something you create, although a sample configuration file can be obtained from the top level directory that was created by the CD installation of the DWTS product to your harddrive. For example:
C:\DCCONN\DWTS\DWTS.INIFor more information about creating the DWTS:INI file, please see Configuration of DWTS on the Terminal (SeeConfiguration of DWTS on the Terminal) .
Using Cabinet Files (.CAB) to Install the Sample Applications to Windows CE Devices
Use of a cabinet file is a typical way to install an application to a Windows CE device. The installation of the product includes sample cabinet files for each of the various flavors of supported Windows CE devices. Also included is the .INF file that was used in conjuction with Microsoft's Cabinet Wizard (CABWIZ.EXE) to create the .CAB file.
The sample cabinet files do the following when installed:
The "DWTDOS.EXE" sample is a 16-bit DOS environment program. The following files needed to compile and link the sample are located in the SAMPLES\DOS directory where the product is installed:
| Filename | Description |
| dwtdos.c | "C" source file |
| dwtdos.h | Include file for constants, prototypes and structures used by the sample |
| dwtdos.mak | Make file for building the sample with the Microsoft Visual C++ 1.5 compiler. |
| ftp\dwtdos.exe | The DOS sample executable built to run with the FTP Software (NetManage) TCP/IP Stack. |
| ibm\dwtdos.exe | The DOS sample executable built to run with the IBM TCP/IP Stack. |
The header file is located in the %DWTSTOOLS% directory and the appropriate library files are in %DWTSTOOLS%\FTP and %DWTSTOOLS%\IBM.
The "DWTSMP16" sample is a 16 bit Windows environment only program (ie. Windows 3.1). The following files needed to compile and link the sample are located in the SAMPLES\WIN16 directory where the product is installed:
| Filename | Description |
| dwtsmp16.exe | Windows 3.1 executable file |
| dwtsmp16.c | Windows "C" source file |
| dwtsmp16.rc | Windows resource file |
| dwtsmp16.mak | Makefile used to compile and link the sample |
| dwtsmp16.def | Windows stack and heap sizes and export information |
| dwtsmp16.h | Include file with the program prototypes and defines |
| dwtssmp16.ico | Icon file |
The header file is located in the %DWTSTOOLS% directory and the appropriate library file is in %DWTSTOOLS%\Win16.
The "DWTSMP32" sample is a 32 bit Windows environment only program (ie. Windows 95/98/Me/NT/2000/XP/7/Server). The following files needed to compile and link the sample are located in the SAMPLES\WIN32_CE directory where the product is installed:
| Filename | Description |
| dwtsmp32.ico | Icon file (also used for Windows CE) |
| dwtsmp32.cpp | Windows "C++" source file (also used for Windows CE) |
| dwtsmp32.dsw | Microsoft Visual C++ workspace file |
| dwtsmp32.dsp | Microsoft Visual C++ project file |
| dwtsmp32.mak | Microsoft Visual C++ make file used to compile and link the sample |
| dwtsmp32.h | Include file with the program prototypes and defines (also used for Windows CE) |
| resource.h | Include file with resource constants (also used for Windows CE) |
| dwtsmp32.hpp | Class definitions for sample (also used for Windows CE) |
| dwtsmp32.rc | Windows resource file (also used for Windows CE) |
| nmwin32.bat | Batch file to use to run the make after setting up the compile environment. Expects the environment variable MSVC32DIR to be defined, pointing to the directory where the Microsoft Visual Studio, C++ compiler is installed (e.g. C:\VISUALSTUDIO\VC98). |
| win32\dwtsmp32.exe | Windows 95/98/Me/NT/2000/XP/7/Server executable file |
Additional files are located in the %DWTSTOOLS% and %DWTSTOOLS%\WIN32 directories.
The "DWTSMPCE" sample is for use on Windows CE devices only. There are multiple flavors of the Windows CE sample for different devices with different Windows CE version/processor combinations. The following files needed to compile and link the sample are located in the SAMPLES\WIN32_CE directory where the product is installed:
| Filename | Description |
| dwtsmp32.ico | Icon file (also used for 32-bit Windows) |
| dwtsmp32.cpp | Windows "C++" source file (also used for 32-bit Windows) |
| dwtsmpce.vcw | Microsoft eMbedded Visual C++ 3.0 workspace file |
| dwtsmpce.vcp | Microsoft eMbedded Visual C++ 3.0 project file |
| dwtsmpce.vcn | Microsoft eMbedded Visual C++ 3.0 make file used to compile and link the sample |
| dwtsmp32.h | Include file with the program prototypes and defines (also used for 32-bit Windows) |
| resource.h | Include file with resource constants (also used for 32-bit Windows) |
| dwtsmp32.hpp | Class definitions for sample (also used for 32-bit Windows) |
| dwtsmp32.rc | Windows resource file (also used for 32-bit Windows) |
| nmck30.bat | Batch file used to build the Intermec CK30 flavor of the sample from the make file dwtsmp40.vcn. |
| nmcv60.bat | Batch file used to build the Intermec CV60 flavor of the sample from the make file dwtsmp40.vcn. |
| nmi5020.bat | Batch file used to build the Intermec 5020 flavor of the sample from the make file dwtsmpce.vcn. |
| nmi600.bat | Batch file used to build the Intermec 600 flavor of the sample from the make file dwtsmpce.vcn. |
| nmi6651.bat | Batch file used to build the Intermec 6651 flavor of the sample from the make file dwtsmpce.vcn. |
| nmi700.bat | Batch file used to build the Intermec 700 flavor of the sample from the make file dwtsmpce.vcn. |
| nmlptce.bat | Batch file used to build the Intelligent Instrumentation LanPoint CE flavor of the sample from the make file dwtsmpce.vcn. |
| nms90xx.bat | Batch file used to build the Symbol MC90xx flavor of the sample from the make file dwtsmp40.vcn. |
| nmx86em.bat | Batch file used to build the X86 Pocket PC Emulator flavor of the sample from the make file dwtsmpce.vcn. |
| makecab.bat | Batch file to use build the various sample .CAB files. |
| ck30\dwtsmpce.exe | Sample executable for the Intermec CK30 |
| ck30\ck30.cab | Cabinet file containing the sample for installation on the Intermec CK30 |
| ck30\ck30.inf | File used to build the cabinet file for the Intermec CK30 |
| cv60\dwtsmpce.exe | Sample executable for the Intermec CV60 |
| cv60\cv60.cab | Cabinet file containing the sample for installation on the Intermec CV60 |
| cv60\cv60.inf | File used to build the cabinet file for the Intermec CV60 |
| imec5020\dwtsmpce.exe | Sample executable for the Intermec 5020 |
| imec5020\imec5020.cab | Cabinet file containing the sample for installation on the Intermec 5020 |
| imec5020\imec5020.inf | File used to build the cabinet file for the Intermec 5020 |
| imec600\dwtsmpce.exe | Sample executable for the Intermec 600 |
| imec600\imec600.cab | Cabinet file containing the sample for installation on the Intermec 600 |
| imec600\imec600.inf | File used to build the cabinet file for the Intermec 600 |
| imec6651\dwtsmpce.exe | Sample executable for the Intermec 6651 |
| imec6651\imec6651.cab | Cabinet file containing the sample for installation on the Intermec 6651 |
| imec6651\imec6651.inf | File used to build the cabinet file for the Intermec 6651 |
| imec700\dwtsmpce.exe | Sample executable for the Intermec 700 |
| imec700\imec700.cab | Cabinet file containing the sample for installation on the Intermec 700 |
| imec700\imec700.inf | File used to build the cabinet file for the Intermec 700 |
| lanptce\dwtsmpce.exe | Sample executable for the Intelligent Instrumentation LanPoint CE |
| lanptce\lanptce.cab | Cabinet file containing the sample for installation on the Intelligent Instrumentation LanPoint CE |
| lanptce\lanptce.inf | File used to build the cabinet file for the Intelligent Instrumentation LanPoint CE |
| sym81xx\sym81xx.cab | Cabinet file containing the sample for installation on the Symbol PDT81xx terminal. It actually contains the same sample executable that is used for the Intermec 700 because both terminals have the same version of Windows CE and the same processor. |
| sym81xx\sym81xx.inf | File used to build the cabinet file for the Symbol PDT81xx terminal. |
| sym90xx\dwtsmpce.exe | Sample executable for the Symbol MC90xx |
| sym90xx\sym90xx.cab | Cabinet file containing the sample for installation on the Symbol MC90xx terminal. |
| sym90xx\sym90xx.inf | File used to build the cabinet file for the Symbol MC90xx terminal. |
| x86emdbg\dwtsmpce.exe | Sample executable for the X86 Pocket PC Emulator |
| x86emdbg\x86emdbg.cab | Cabinet file containing the sample for installation on the X86 Pocket PC Emulator |
| x86emdbg\x86emdbg.inf | File used to build the cabinet file for the X86 Pocket PC Emulator |
The header file is located in the %DWTSTOOLS% directory and the appropriate library file is located in one of the following directories:
The files needed to compile and link the 16 bit sample are located in the SAMPLES\BASIC\WIN16 directory:
| Filename | Description |
| dwtsmain.frm | Main program form. |
| dwtsopen.frm | Open terminal request form. |
| dwtssend.frm | Send a data transaction form. |
| dwtsval.frm | Validation request form. |
| dwtstime.frm | Time request form. |
| dwtsuvar.frm | User variable set/get form. |
| request.frm | Data request form. |
| dwtsbas.bas | Global program declarations. |
| dwtsbas.mak | The DWTSBAS sample makefile. |
| dwtsbas.ico | Icon file |
| dwtsbas.exe | Visual Basic executable file |
The files needed to compile and link the 32 bit sample are located in the SAMPLES\BASIC\WIN32 directory:
| Filename | Description |
| dwtsmain.frm | Main program form. |
| dwtsopen.frm | Open terminal request form. |
| dwtssend.frm | Send a data transaction form. |
| dwtsval.frm | Validation request form. |
| dwtstime.frm | Time request form. |
| dwtsuvar.frm | User variable set/get form. |
| request.frm | Data request form. |
| dwtsbas.bas | Global program declarations. |
| dwtsbas.vbw | The Visual Basic workspace file. |
| dwtsbas.vbp | The Visual Basic project file. |
| dwtswin.ico | Icon file |
| dwtsbas.exe | Visual Basic executable file |
The files needed to compile and link the Windows CE sample are located in the SAMPLES\BASIC\WINCE directory:
| Filename | Description |
| dwtsmain.ebf | Main program form. |
| dwtsopen.ebf | Open terminal request form. |
| dwtssend.ebf | Send a data transaction form. |
| dwtsval.ebf | Validation request form. |
| dwtsval.frx | Validation request form companion file. |
| dwtstime.ebf | Time request form. |
| dwtsuvar.ebf | User variable set/get form. |
| request.ebf | Data request form. |
| dwtsbas.bas | Global program declarations. |
| dwtsbas.vbw | The Microsoft eMbedded Visual Basic 3.0 workspace file. |
| dwtsbas.ebp | The Microsoft eMbedded Visual Basic 3.0 project file. |
| dwtsbas.vb | Visual Basic executable file for use on all supported Windows CE devices |
| dwtsbas.inf | Sample file used for building .CAB files. |
| makecab.bat | Batch file to use build the various sample .CAB files. |
| imec5020\imec5020.cab | Cabinet file containing the Visual Basic sample for installation on the Intermec 5020 |
| imec5020\imec5020.inf | File used to build the cabinet file for the Intermec 5020 |
| imec600\imec600.cab | Cabinet file containing the Visual Basic sample for installation on the Intermec 600 |
| imec600\imec600.inf | File used to build the cabinet file for the Intermec 600 |
| imec6651\imec6651.cab | Cabinet file containing the Visual Basic sample for installation on the Intermec 6651 |
| imec6651\imec6651.inf | File used to build the cabinet file for the Intermec 6651 |
| imec700\imec700.cab | Cabinet file containing the Visual Basic sample for installation on the Intermec 700 |
| imec700\imec700.inf | File used to build the cabinet file for the Intermec 700 |
| lanptce\lanptce.cab | Cabinet file containing the Visual Basic sample for installation on the Intelligent Instrumentation LanPoint CE. |
| lanptce\lanptce.inf | File used to build the cabinet file for the Intelligent Instrumentation LanPoint CE. |
| sym81xx\sym81xx.cab | Cabinet file containing the sample for installation on the Symbol PDT81xx terminal. |
| sym81xx\sym81xx.inf | File used to build the cabinet file for the Symbol PDT81xx terminal. |
| x86emdbg\x86emdbg.cab | Cabinet file containing the Visual Basic sample for installation on the X86 Pocket PC Emulator |
| x86emdbg\x86emdbg.inf | File used to build the cabinet file for the X86 Pocket PC Emulator |
The BOOL data type is a boolean.
The CHAR data type is a signed char (8-bit) value.
The _dosdate_t type is a structure containing fields for the day, month, year and day of the week.
DWTS.H provides a typdef for _dosdate_t that is used when compiling 32-bit Windows and Windows CE applications.
The _dostime_t type is a structure containing fields for the hour, minute, second and hundredths of a second.
DWTS.H provides a typdef for _dostime_t that is used when compiling 32-bit Windows and Windows CE applications.
The HDWS data type is an unsigned short (16-bit) value.
The LONG data type is a signed long (32-bit) value.
The LPCHAR type implies a far pointer to an ASCII CHAR type array which is not null-terminated.
DWTS.H provides a typdef for LPCHAR that is used when compiling DOS and 16-bit Windows applications.
The LPHDWS type is a far pointer to a type HDWS.
The LPSTR type is a far pointer to a null-terminated ASCII CHAR type array. This is often referred to as a string.
DWTS.H provides a typdef for LPSTR that is used when compiling DOS applications.
The LPTCH type is a far pointer to a character array - but no null character is assumed to exist at the end. For Windows CE, the LPTCH pointer indicates a pointer to an array of double-byte Unicode characters. For all other supported operating systems, the LPTCH pointer indicates a pointer to an array of single-byte ASCII characters.
DWTS.H provides a typdef for LPTCH that is used when compiling DOS and 16-bit Windows applications.
The LPTSTR type is a far pointer to a null-terminated character array - often referred to as a string. For Windows CE, the LPTSTR pointer indicates a pointer to string of double-byte Unicode characters. For all other supported operating systems, the LPTSTR pointer indicates a pointer to a string of single-byte ASCII characters.
DWTS.H provides a typdef for LPTSTR that is used when compiling DOS and 16-bit Windows applications.
The LPTIMEDATE type is a far pointer to a TIMEDATE structure.
The LPUSHORT type is a far pointer to an unsigned short (16-bit) value
The PCHAR type implies a pointer to an ASCII CHAR type array which is not necessarily null-terminated.
The PHREQ is a pointer to the type HREQ.
The PSZ type implies a pointer to a null-terminated ASCII CHAR type array. This is often referred to as a string.
The PUSHORT type is a pointer to an unsigned short (16-bit) value.
The SHORT data type is a signed short (16-bit) value.
The TCHAR type is an array of characters - but no null character is assumed to exist at the end. For Windows CE, a TCHAR array contains double-byte Unicode characters. For all other supported operating systems, a TCHAR array contains single-byte ASCII characters.
DWTS.H provides a typdef for TCHAR that is used when compiling DOS and 16-bit Windows applications.
The TIMEDATE data type is a structure used to return the current time and date for the DCConnect Server during a DwsRequestTime API call.
The USHORT data type is an unsigned short (16-bit) value.
Address: A specific location in memory.
API: Application programming interface.
Application programming interface: A functional interface supplied by DCConnect that allows an application program written in a high-level language to use specific data or functions of DCConnect.
Buffer: A portion of storage used to hold input or output data temporarily.
Call: The action of bringing an API into effect.
Caller: The requester of an API.
Compiler: A program that translates instructions written in a high-level programming language into machine language.
Configure: To describe to a computer the devices, optional features, and programs installed on the computer.
Data collection: The process of bringing data together from one or more data collection terminals or DOS/Windows terminals acting as data collection terminals for storing and processing.
Handle: An integer value created by the DWTS API that identifies your user-written application to DWTS and the DCConnect Server.
Mailbox: A file used to store transaction data.
Null-terminated: Having a zero byte at the end. In C language, character strings are internally stored this way.
Parameter: A specific value needed by an API.
Pointer: A data element that indicates the location of another data element.
Register: To enroll a user-written application with the DCConnect Server for validation requests.
Request: A command to the DCConnect Server or DOS/ Windows terminal to send a single block of data over a connection.
Response: An answer to an inquiry.
Return code: A value returned to a program to indicate the results of an operation requested by that program.
String: In programming languages, the form of data used for storing and manipulating text.
Structure: A data type that contains an ordered group of data objects. Unlike an array, the data objects within the structure can have varied data types.
Terminal User Variable: Variable storage which is available to both the Data Collection Terminal and the DCConnect server.
Transactions: A specific set of input data defined by the customer, collected by the DCConnect Server and stored in a mailbox.
Validation: The checking of data for correctness or compliance.
Variable: In programming languages, a language object that may take different values, one at a time. The values of a variable are usually restricted to a certain data type.