This publication provides technical information for using IBM Data Collection Connection (DCConnect) Toolkit and Server products Application Program Interfaces (APIs). IBM Data Collection Connection Server products and Toolkit are installed on an IBM Industrial Computer or Personal Computer, which serves as the system unit for the data collection system.
The IBM DCConnect APIs provide the same function that the 32-bit runtime modules of IBM Data Collection Control/2 (DCC/2) provided. The DCConnect toolkit and server products support running programs that use the original DCC/2 16-bit APIs.
December 2023
References in this publication 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 may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation 500 Columbus Avenue Thornwood, NY 10594 U.S.A.
This publication provides information and reference for system personnel responsible for the design and programming of user-written applications that interface to DCConnect.
One or more of the following IBM publications may be needed for reference when using this publication:
Data Collection Publications
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 AS/400 DB/2 DB2/2 OS/2 Advanced Function Printing MAPICS S/370
Windows and Windows NT/XP/7/2000/Server are trademarks of the Microsoft Corporation.
The following information describes how to use this book.
How to Use the Contents
When the Contents window is first displayed, some topics have a plus (+) sign beside them. The plus sign indicates additional topics are available.
To expand the Contents and view the additional topics, select the + if you are using a mouse; if you are using a keyboard, use the Up Arrow and Down Arrow keys to highlight the topic, and then press the plus key (+).
To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press Enter).
How to Obtain Additional Information
After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words in the following paragraph are highlighted. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information will appear in a window.
How to Use Menu-Bar Choices
Choices are available in the menu bar and in the Services menu that help you manage the information in this book. Select any of the choices below to learn about these features.
Choice | Definition |
Bookmark | Sets a placeholder so you can retrieve information of interest to you. (This choice is available from the Services menu.) |
Search | Finds occurrences of a word or phrase in the current topic, selected topics, or all topics. (This choice is available from the Services menu.) |
Prints one or more topics. (This choice is available from the Services menu.) | |
Copy | Copies a topic you are viewing to a file you can edit. (This choice is available from the Services menu.) |
Options | Changes the way the Contents are displayed. |
This manual is organized as follows:
Introduction and Overview of DCConnect (See Introduction and Overview of DCConnect.) , introduces data collection, as defined by DCConnect, and how DCConnect can help a user to perform data collection tasks. It provides a brief overview of the data collection environment.
Application Programming for Data Collection (See Application Programming for DCConnect) , discusses how programming for data collection is accomplished with DCConnect. This section introduces the methods used for accessing the application programming interfaces (APIs).
Application Programming Interface (API) Reference (See Application Programming Interface (API) Reference) describes the API, lists each API call, and explains how to program it.
Error Situations (See Error Situations) describes the error reporting philosophy and the error message format, and lists the errors that can be returned for the API calls.
What is Data Collection?
The term "data collection" can have many meanings, depending on the context of its usage.
The context of data collection that DCConnect addresses is one of collecting alphanumeric or binary data as input from a Data Collection Terminal (DCT). The data is collected using one or more of the following devices, which are part of or connected to the data collection terminal:
In addition, output can be returned directly to the following devices, that are connected to or are part of the data collection terminal without necessarily interacting with any host system:
The data collection terminal itself is a "stored-program" device with a microprocessor and incorporated memory. This device performs operations on data that is entered by way of the input devices in the above list. Data collected in the data collection terminal can then be sent to a host computer for local processing or routing elsewhere.
Programs are written on the host computer and downloaded to the data collection terminal. These transaction programs are written in a language that is unique to the data collection terminals supported by DCConnect.
Terminal Services for DOS and for Windows, running on a personal computer (PC), can behave as a DCT sending transactions, validation requests or messages to the DCConnect Server. In this case the above discussion about what a DCT is, does not apply. A PC using Terminal Services for DOS and for Windows instead uses commercially-written programming tools to create an application that works with PC-attached devices. All communication between a PC running Terminal Services for DOS and for Windows and DCConnect is originated by the Terminal Services for DOS and for Window PC. Some of the DCConnect APIs are not supported by a Terminal Services for DOS and for Windows PC. Refer to "API Functions not supported by Terminal Services for DOS and for Windows" for a complete list.
The combination of DCConnect and the family of IBM data collection terminals offers a system solution for:
Transactions returned to the IBM industrial computer or PC are saved on the hard disk in a transaction mailbox before being released from the DCT. This ensures integrity of the collected data over possible power interruptions. Collected data is secured in the DCTs until released, due to the battery backup of memory in these terminals.
Transactions that have been collected on the IBM industrial computer or PC hard disk can be retrieved by user-written DCConnect applications written in the C Language. These applications can access the collected data using the APIs provided by DCConnect. DCConnect APIs are calls that provide some of the following functions:
Data that has been collected in the transaction mailbox can be dealt with as needed by the DCConnect user-written application.
Note: The term "mailbox" used in DCConnect was referred to as an "export" or "transaction logfile" in the preceding DCC/2 products. In order to allow existing DCC/2 applications to continue to be compiled and run with DCConnect, the term export still exists in the DCConnect header files and libraries.
When defining a transaction mailbox, you must specify which transactions are to be sent to that Mailbox. The following criteria can be used:
For example, you can specify that all transactions generated by function keys 1 through 5 on terminals terma, term, and termc, should go to a particular Mailbox.
Each Mailbox stores its transactions in a file on disk in which they reside until they are read by the application that is handling transactions for the Mailbox.
Transactions read into the user-written DCConnect application can then be sent to a database or to a remote destination by way of an emulation program or whatever is needed, as supported by Windows or OS/2 and other installed programs. This is the responsibility of the application writer.
DCConnect provides the following optional interface services that enable transactions to be sent to various places:
DCConnect itself consists of the following facilities:
The communication tasks provided with DCConnect support the following kinds of terminal connections:
With the addition of the DCConnect 7524 Interface Support, 7524 Radio Frequency (RF) terminals can be attached (7524 batch terminal support is provided in the base DCConnect products.)
A system using DCConnect requires specific hardware and software in addition to DCConnect.
In general, a system using DCConnect requires one or more of the following hardware:
For writing DCConnect applications or for writing custom function routines (CFRs) for downloading into the attached DCTs, the following additional software is needed:
DCConnect is a follow-on product to DCC/2 and provides the following compatibility with DCC/2:
Note: Due to change in the implementation of the API DLLs, the required minimum stack size has increased for DCConnect. The recommended minimum stack size should be set to 12 KB. If an existing 16 or 32-bit application uses a stack size less than 12 KB, you need to relink the application utilizing the new stack size.
Alternatively, you could use the utility EXEHDR.EXE to change the stack size. The utility is part of the OS/2 2.1 Toolkit.
If you attempt to run an application with DCConnect and the application's stack size is too small, a Trap 5 error is displayed and that indicates a Stack Overflow.
Areas of improvement to the DCC/2 products are as follows:
An API for generating data requests is also available to DCConnect applications.
The 16-bit and 32-bit Application Programming Interfaces
There are two sets of APIs offered by DCConnect.
The Compatibility APIs are provided in order to allow existing DCC/2 applications to run with DCConnect without having to recompile or relink these applications. These APIs are not discussed in this publication. Refer to DCC/2 Technical Reference for information on these APIs and their return codes.
Any 32-bit DCC/2 application using the enhanced APIs (32-bit) can run with DCConnect without having to recompile or relink these applications.
Note: Due to change in the implementation of the API DLLs, the required minimum stack size has increased for DCConnect. The recommended minimum stack size should be set to 12 KB. If an existing 16 or 32-bit application uses a stack size less than 12 KB, you need to relink the application utilizing the new stack size.
Alternatively, you could use the utility EXEHDR.EXE to change the stack size. The utility is part of the OS/2 2.1 Toolkit.
If you attempt to run an application with DCConnect and the application's stack size is too small, a Trap 5 error is displayed and that indicates a Stack Overflow.
The rest of this section is devoted to the enhanced APIs (32-bit) offered by DCConnect. This is the same set of APIs that was provided with the DCC/2 32-bit runtime.
The APIs of DCConnect are provided to allow users to write programs to interact with their DCTs. The most common interaction is to request that data entered into the DCT be provided to the application. This data, known as transactions, can be handled at the IBM industrial computer, PC, or sent elsewhere by using the network for further processing or collection at a higher level.
Some other operations offered using the APIs are:
The API is written in C and was originally intended to be used with applications that are written in C and are compiled and linked using the development tools that are compatible with the appropriate operating system. However, applications can also be written in languages such as Rexx or Microsoft's Visual Basic or other languages that provide a means for calling C APIs.
DCConnect provides an "include" file that is necessary for using the APIs and sample programs demonstrating typical coding of the APIs. The sample programs are located in the directory:
<DCCONN>\samples
where <DCCONN> is the drive and directory where DCConnect was installed. Visual Basic samples are also in this directory.
DCConnect makes use of the shared library concept of OS/2 and Windows where multiple applications can share access to the APIs offered by DCConnect in a Dynamic Link Library (DLL).
Note: The performance of the IBM industrial computer or PC can be affected by the frequency that many of these APIs are called - if care is not taken to periodically sleep or otherwise relinquish control of the CPU. An example would be the frequent reading for transaction data with little or no wait-time specified. This amounts to polling from the application level, which is not a recommended procedure for good system performance. Specific recommendations for avoiding these performance impacts are provided with the description of each API.
The APIs are implemented as calls with parameters passed as simple C data types such as char, short, and so forth and some simple struct types and some unique data types defined in Data Types (See DCConnect Data Types) and declared in the include file DCX.H provided with DCConnect. DCX.H is located in the directory
<DCCONN>\INCLUDE
where <DCCONN> is the drive and directory where DCConnect was installed. The library to which DCConnect applications must link, DCX.LIB, is provided in the directory:
<DCCONN>\LIB
The library in the directory above is for use with the IBM Visual Age C++ compiler. If you are using the Microsoft VisualC++ compiler, use DCX.LIB found in the following directory instead:
<DCCONN>\LIB\VISUALC
The DCX.H include file is the same no matter which compiler you are using.
When using Visual Basic to call the C APIs, you must specify that the APIs are to be found in the wrapper DLL, VBDCX.DLL, instead of directly in DCX.DLL. This is because Visual Basic expects the C APIs to be declared using the _stdcall calling convention and DCX.DLL was originally created using the _cdecl calling convention. VBDCX.DLL was creating using the _stdcall calling convention. See the samples in <DCCONN>\samples\dcconn.bas for an example of how to declare the C APIs in your Visual Basic module.
Application programming for DCConnect involves the use of several functions provided in the DCConnect set of APIs. There are several categories of APIs.
The APIs are grouped into the following categories:
Transaction Data Access provides the ability for applications to open or close transaction mailbox(es).
Data transactions can be read from or written to the mailbox and released from that mailbox after the application determines that the data is secure.
A mailbox can be cleared and it can be queried to find out how many transactions are waiting to be read. In DCC/2, a mailbox was referred to as a destination or export.
Commands that can be sent to DCTs can be passed through the APIs. Thus terminals can be directly accessed from user-written applications. This includes operations such as writing data to be displayed on a DCT screen or to a User Variable in the DCT, or DCT status can be requested.
Note: The only terminal access APIs supported by Terminal Services for DOS/Windows are DcxAcquireTerminal, DcxUnAcquireTerminal, DcxSetTermUserVariable, DcxSetNTermUserVariables, and DcxGetTermUserVariable.
Terminals can be taken Out-of-Service or put In-Service and Polling can be Started or Stopped. Information and status can be returned from DCTs and the DCTs can be downloaded with the latest files.
Note: The only terminal management APIs supported by Terminal Services for DOS/Windows are DcxChangeTerminalState and DcxReportTerminalState.
Validation files can be submitted for use by DCTs or removed from use. User-written applications can register themselves as validators by opening a validation path. These applications can then read validation requests from and reply to the DCTs with the results of the validation.
Messages that are sent to the DCConnect system message log can be sent to an application. Applications can send messages to the DCConnect system message log and clear the system message log.
Data Request APIs support the Terminal Services for DOS and Windows DwsRequestData API. These APIs allow a Terminal Services for DOS or Windows user-written application to send data to and receive a response from a DCConnect user-written application. Unlike transactions and validation requests, up to 16K of data can be sent and received for each data request.
This category covers all of the rest of the APIs - most of which allow an application to query information about DCConnect including, a list of all configured jobs, applications, terminals assigned to a job, files assigned to a job, or the name and size of the current system message log. There are APIs to check whether DCConnect is running and to shut it down if it is. The system clock and terminal clocks can be updated.
Following is a list of all available APIs in each category with a brief description of each. Select the highlighted API to see it in detail.
Transactions generated in the terminals as a result of some user or device action can be accessed by this group of APIs. These transactions are stored in mailboxes by DCConnect, according to the definition of each mailbox that has been created.
Each mailbox can be customized, by way of the DCConnect Mailbox Notebook, to act as 'filters' for specified transaction IDs from specified terminals. The user can select which transaction IDs from some set of terminals are to be used to generate transactions for each Mailbox.
This capability can be used to ensure that only certain transactions from certain terminals are handled by a given application. Conversely, all Mailboxes could be configured to receive all transactions from all terminals if this is desired. In this case, each Mailbox receives its own copy of each transaction that is generated by any terminal in the system.
After a Mailbox has been created, the following API calls can be made:
Open the Mailbox (export) and return a handle representing this Mailbox. This handle is used for calls to read and release transactions and to close the Mailbox.
Read the next available transaction that has been polled from the DCTs and stored in this mailbox.
After a transaction has been read and the data is considered "safe" (recoverable, recreatable, or successfully sent to its ultimate destination), the application can release the transaction data from the protection of DCConnect. After this call has completed, the released transaction will be allowed to be deleted from the Mailbox maintained by DCConnect.
This API is used when an application no longer needs to read transactions for a particular Mailbox.
Using this API, transactions can be introduced into DCConnect, where they are treated exactly as if they had been received from a DCT. This can be useful where data must be entered manually or by some means other than a DCT, but yet handled exactly as it would be if it had come from a DCT.
Returns a list of all Mailboxes (exports) that are currently configured in DCConnect.
Used to find out how many transactions are in a Mailbox, waiting to be read or released. In addition, the API indicates if any application is currently using the open/read/release APIs to get transactions from the Mailbox and it returns the name of the physical logfile along with its capacity and percentage used.
Used to remove all transactions from the specified Mailbox. The logfile cannot be cleared if the Mailbox is currently open and there are transactions that have been read from the Mailbox but have not been released.
This set of APIs permits sending and receiving data to and from the DCTs. This data is not the transaction data generated in the terminal. It is data that influences the terminal operation or reports back some internal information from the terminal.
Because the APIs can be shared by multiple applications, a mechanism is provided for assuring single-thread access to any given terminal at a time. This mechanism prevents collisions where multiple applications could be trying to operate on a terminal at the same time. Unpredictable results could occur if this were allowed.
The mechanism allows an application to "acquire" a terminal prior to issuing any API calls to that terminal. When the API are completed, the terminal can be "unacquired", thus allowing other terminals to issue APIs to the terminal.
This mechanism is optional and can be bypassed by passing a value for terminal name and no "acquire" handle when making the call. If nobody else has acquired the terminal, the API call is executed. If anyone else has "acquired" the terminal, the API fails.
Reserves a terminal for exclusive use by one application. This ensures that multiple applications are not in contention when sharing a terminal. When the terminal has been acquired, only one application can modify the terminal environment at a time.
Releases a terminal from exclusive write-access by one application.
Allows an application to pulse the beeper on a terminal for a specified period of time.
Allows displaying a text message on the screen of a data collection terminal.
Sends an application-generated transaction program to a terminal for immediate execution. The program is not retained in the terminal after execution.
Simulates a local event (such as a key press) which causes immediate execution of an already-downloaded transaction program at the DCT.
Returns the current date and time from a DCT.
Returns current internal terminal status from the specified DCT.
Sets a user variable in a DCT to a specified value. This variable can then be used by transaction programs or CFRs running in that terminal.
Same as DcxSetTermUserVariable except that more than one user variable can be set at the same time. This API can be used to increase performance in a 7524 RF network because it reduces the number of messages between DCConnect and a 7524 RF terminal.
Returns the current value of a user variable from a DCT. This API can only be used with 7526 terminals.
Allows an application to send a response for an interactive transaction to the terminal that originated the transaction and that is waiting for the response.
These commands are used for managing the environment of each of the DCConnect terminals. The terminals can be reset or partially reloaded or completely reloaded. Information about the operational state and the characteristics of individual terminals can be returned.
Terminals can be set in or out of service, based on whether a terminal user should be allowed to use them at this time.
Polling of terminals can be started or stopped, based on whether DCConnect should be collecting transactions from those terminals.
Note: In an RF or TCP/IP network there is no actual polling being performed by DCConnect. Instead, terminals automatically send transactions to DCConnect when they are generated. However, the "polling" state maintained by DCConnect for terminals on these networks is used to tell terminals whether or not they are allowed to send transactions to DCConnect.
Performs the reset or full or partial loading of a terminal.
Stages and optionally loads a set of DCConnect Client files to one or more terminals.
Sets a terminal in-service or out-of-service (ability of the user to use the terminal) and polled or not-polled (ability of DCConnect to collect transactions from those terminals).
Reports back the state of the terminal relative to in-service or out-of-service and polled or not-polled. Reports the operating state of the terminal. If a terminal is downloading, the current step of the download is reported as well.
Reports back the physical characteristics of the specified DCT.
Reports back the version of the DCConnect Client or firmware version of the specified DCT.
These APIs are used to provide terminal data validation services.
Flat ASCII files that contain fields of validation data can be submitted. DCConnect converts these files for downloading to terminals where they can be used to check inputted data.
These files can be stored on the IBM industrial computer or PC where DCConnect can use them to handle remote validation requests.
There are commands described below which permit user-written applications to read validation requests from the terminals and then reply to those requests based on work done by the application.
Informs DCConnect that a user-written application want to handle validation requests from data collection terminals for one or more validation files. A handle is returned that uniquely identifies that application.
Allows an application to solicit validation requests from terminals which it then process.
Returns to the requesting terminal, a pass, fail or unknown result for a particular validation request.
Informs DCConnect that the application represented by this handle is no longer available for processing requests.
Removes a validation file from active use and deletes it. However, the file is not deleted from terminals.
Submits a validation file for use by terminals or for remote validation and downloads it to terminals that require it.
These APIs allow an application to access DCConnect system message logs as they are generated.
Informs DCConnect that a user-written application wants to receive any messages that are sent to the system message log.
Allows an application to read the next message that is logged to the DCConnect system message log.
Informs DCConnect that this application no longer wants to receive messages.
Allows an application to write a message to the system message log.
Allows an application to clear all messages from the DCConnect system message log.
This category covers:
Allows a user-written application to register itself to receive requests for data from DOS or Windows DCTs or DCConnect applications.
Allows an application to read a request for data from a DOS or Windows DCT or other DCConnect application.
Allows an application to send a response message to a DOS or Windows DCT or other DCConnect application in reply to its request for data.
Allows a DCConnect application to send a request for data to and wait for a response message from a DCConnect application that registered by way of the DcxOpenRequestHandler API.
Allows an application to send a data request that it just received from a call to DcxReadDataRequest to another application that registered by way of the DcxOpenRequestHandler API.
Informs DCConnect this this application no longer wants to be registered to receive requests for data.
This category covers the rest of the APIs .
Allows an application to find out whether or not DCConnect is running.
Allows an application to get a list of all applications configured in DCConnect.
Allows an application to get a list of all jobs configured in DCConnect.
Allows an application to find out what files make up a particular job.
Allows an application to find out what terminals are using a particular job.
Allows an application to find out the name and size of the system message log.
Allows an application to find out the terminal address parameters for a given terminal name.
Allows an application to get a list of all terminals configured in DCConnect.
Allows an application to find out the terminal name for a given set of terminal address parameters.
Allows an application to shut down the DCConnect server.
Allows an application to start one of the applications configured in DCConnect.
Allows an application to update the system unit clock as well as synchronize all terminal clocks with the system unit clock.
Note: The time on DOS and Windows DCTs is not affected by this API.
This section is intended to serve as a reference section when programming user-written applications using the DCConnect API. The APIs are grouped into the following categories:
For an overview of these categories, see Programming the APIs (See Programming the APIs) .
/c /Kf /Kt- /Ki- /Ka- /Kx- /G3 /Gm+ /Sp /Ss+ /Ge
Where:
| Switches | Definition |
| /c | Compiles only and does not link |
| /K... | Sets the warnings that the compiler generates |
| /G3 | Specifies this code runs on a 386 processor or above. |
| /Gm+ | Enables multithreading applications |
| /Sp | Aligns structures on a one-byte boundary. This is required. |
| /Ss+ | Allows the use of double-slashed comments |
| /Ge | Specifies a .EXE file to be built. When building a .DLL, use /Ge-. |
Use the following linker flags:
/NOI /MAP /ST:12000
Where:
| Switches | Definition |
| /NOI | No case-insensitivity for API names. The case is sensitive; upper and lower case letters must match. |
| /MAP | A detailed .MAP file is generated for debugging purposes. |
| /ST: | Defines the size of the stack that is required by the program. A minimum recommended size is 12000. |
Using the VisualAge 3.0
When using VisualAge 3.0 use the following compiler flags to build your application:
/c /W3 /G3 /Sp /Ss+ /Ge
Where:
| Switches | Definition |
| /C | Compiles only and does not link |
| /W3 | Indicates the severity level of messages the compiler produces. |
| /G3 | Specifies this code runs on a 386 processor or above. |
| /Sp | Aligns structures on a one-byte boundary. This required. |
| /Ss+ | Allows the use of double-slashed comments. |
| /Ge | Specifies an .EXE file to be built. When building a .DLL, use /Ge-. |
The linker flags for IBM C-Set/2 or IBM C-Set++ apply to VisualAge 3.0 applications.
Using MS VisualC++ 4.0 or later
When using MS VisualC++ 4.0 or later, use the following compiler flags to build your application:
/c /W3
Where:
| Switches | Definition |
| /C | Compiles only and does not link |
| /W3 | Indicates the severity level of messages the compiler produces. |
Use the following linker flags:
/MAP
Where:
| Switches | Definition case letters must match. |
| /MAP | A detailed .MAP file is generated for debugging purposes. |
The following differences can be noted between the 16-bit Compatibility APIs provided for DCC/2 and the Enhanced APIs (32-bit) implemented in DCConnect:
Note: The job field contains the name of the "Function group" to which the terminal is assigned.
Transaction data is put into a common format to minimize the differences between the format of transactions generated by the different terminal types. This format is defined by the TRF structure. Some data in the structure is rearranged from the format received from terminals so that it can be used in a uniform format by DCConnect regardless of the terminal type. All fields in the TRF structure are ASCII; there are no binary values in the structure.
As of October 2004, the DCConnect Server supports a longer transaction record as well as additional time and date information. A new structure, TRF2, was created to hold this information and the new APIs DcxReadTransactionEx and DcxWriteTransactionEx were created to read and write transactions containing these enhanced features. For more information Extended Transaction Record Format (See Extended Transaction Record Format) . In the table below, fields marked with *** are ones that have enhanced capability in the TRF2 structure.
As of August 2015, the DcxWriteTransactionEx2 API was added that enables writing to a database-based mailbox operating in Serial Key mode. The new API allows setting the serial keying value and the priority.
The transaction format is:
Transaction Record Format
| Offset from start | Length in bytes | Name | Description |
|---|---|---|---|
| 0 | 9 | DCConnect sequence number | This is a nine-digit serial number that DCConnect assigns to the transaction. The purpose of the number is to provide unique identification for the transaction. The sequence number starts at 000000000 and rolls over to 000000000 after reaching 999999999. This is the sequence number used in the DcxReleaseTransaction API. |
| 9 | 2 | Communications line location | This is either a two-digit number (00-03) that identifies the ARTIC card to which the DCT that originated the transaction is attached or it is two blanks indicating that the DCT is attached to a communications line which is native serial port. "RF" for a for a RF serial port, "IP" for a TCP/IP adapter, or "DW" for a DOS or Windows attached DCT. |
| 11 | 2 | Communications line number | This is a two-digit number that identifies either the communication line on
the ARTIC card (00-07), a native serial port communications line (01-04) to
which the DCT that originated the transaction is attached, "00"-"12" for RF
serial port (the hundreds and tens digits of the RF terminal address), or
"00"-"07" for TCP/IP and DOS or Windows attached DCTs.
For TCP/IP and DOS/Windows terminals this value can be different based on changes to your terminal configuration from one execution of DCConnect to the next. Because the terminal's real address, the IP address and port number, cannot possibly be represented in the 3 bytes available for the line number and address fields combined, an index value is used. That index value is based on the order that the terminal appears in the DCX2.INI file and can be in the range from "000" to "999". The hundreds and tens digit go into the the line number field and the ones digit goes into the address field. |
| 13 | 1 | Terminal address | This is the address of the terminal that originated the transaction. Valid
values are A-P for 7525 DCTs; A-Y and 0-6 for 7526, 7527 and DOS or Windows
DCTs. For 7524 RF attached DCTs, the value will be "0"-"9" (the one's digit of
the RF terminal addresses.) For TCP/IP and DOS/Windows attached DCTs, this
value will also be in the range "0"-"9".
If alphabetic, these addresses always are in uppercase even though, internally, 7525 and 7526 terminals use lower case addresses. See the note for the previous field for information about why the values in this field might change from one execution of DCConnect to the next. |
| 14 | 33 | Terminal name | This is the name of the terminal as configured in DCConnect, that originated the transaction. The name is padded with null characters to the end of the field so that it can be treated as a string. |
| 47 | 33 | Job name | This is the name of the Job that is used by the terminal that originated the transaction. The name is padded with null characters to the end of the field so that it may be treated as a string. The Job to be used by each terminal is specified in that terminal's setting notebook. If a terminal belongs to a function group, then the function group matching this transaction ID is returned in place of the job name. A function group is a group of terminals that perform the same function or job. |
| 80 | 5 | Terminal sequence number | This is the sequence number that the terminal assigned to the
transaction (00000-99999).
The sequence number for 7525 and 7526 terminals starts at 00000 and wraps back to 00000 after it reaches 00099. |
| 85 | 12 | Date and time stamp *** | This is the date and time of record for the transaction in the format yymmddhhmmss. (Year-month-day-hour-minute-second). |
| 97 | 1 | Transaction mode | This indicates the type of transaction:
I Interactive mode B Buffered Mode E Error Transaction - Interactive Mode F Error Transaction - Buffer Mode T Truncated Interactive Mode Transaction U Truncated Buffered Mode Transaction Note: Interactive transactions (mode = I) expect an interactive response to be sent to the originating terminal. |
| 98 | 3 | Transaction ID | This is the transaction identifier as reported by the terminal.
For normal transactions it identify the function key or other
event that started the transaction.
Transactions IDs 251, 252, 254, and 255 indicate error transactions. Transaction ID 253 indicates the transaction was sent to the terminal from a DCConnect application using the API DcxExecuteTermTransaction. Note: The transaction IDs in this structure will be consistent no matter what terminal the transaction came from. The raw value for the transaction ID from the different terminals may differ in format. However, DCConnect converts the raw data to a consistent format and value before that value is put into the transaction structure. |
| 101 | 4 | Transaction length *** | Number of bytes in the Transaction Data Area. This is a four-digit number (0000-0108). |
| 105 | 108 | Transaction Data Area *** | This is the data generated at the terminal either by the user input or from devices external to the terminal. It is possible for this field to be empty. This data is not null-terminated; instead the field is padded out to its full length with blanks. |
Note: Since the terminal name and job name fields are null-terminated the whole TRF structure cannot be treated as a string. For example, strcpy() cannot be used to copy a transaction.
The Extended Transaction Record Format (TRF2 structure) is used to handle the longer transaction data area as well as enhanced and additional time and date fields.
Note: In the TRF2 structure, the data length field is now a long integer instead of a 4 byte ASCII representation of the data length.
Each field in the TRF2 structure is list below with its offset and length. However, the description is only given for those fields that are different from their equivalent in the TRF structure.
Extended Transaction Record Format
| Offset from start | Length in bytes | Name | Description |
|---|---|---|---|
| 0 | 9 | DCConnect sequence number | Same as TRF |
| 9 | 2 | Communications line location | Same as TRF |
| 11 | 2 | Communications line number | Same as TRF |
| 13 | 1 | Terminal address | Same as TRF |
| 14 | 33 | Terminal name | Same as TRF |
| 47 | 33 | Job name | Same as TRF |
| 80 | 5 | Terminal sequence number | Same as TRF |
| 85 | 14 | Terminal date and time stamp | A 4 digit year is used in the TRF2 structure instead of the 2 digit
year that is used in the TRF strcture. The format of this date and
time stamp is yyyymmddhhmmss. (Year-month-day-hour-minute-second).
This is the date and time from the transaction as it was received from the terminal. |
| 99 | 14 | Adjusted date and time stamp | This is the date and time from the transaction adjusted to the
Server time. The adjustment is made using the relative time zone
information configured for the originating terminal. Using these
date fields allows operations on the server to correctly peform
functions such as determining the transactions age, even when the
terminal is in a time zone that is different from the Server.
The format of the adjusted date and time stamp is the same as the Terminal date and time stamp: yyyymmddhhmmss. (Year-month-day-hour-minute-second). |
| 113 | 1 | Transaction mode | Same as TRF |
| 114 | 3 | Transaction ID | Same as TRF |
| 117 | 4 | Transaction length | Number of bytes in the Transaction Data Area. This is a 4-byte (long)
integer in the TRF2 structure instead of the 4-byte ASCII string that it
was in the TRF structure.
As of October 2004, the DCConnect Server supports transactions containing up to 750 bytes of data. The previous limit was 108 bytes. |
| 121 | 750 | Transaction Data Area | The use of this field is the same as in the TRF structure; the only difference is that as of October 2004 it can now hold up to 750 bytes of data. |
The following are different types of data used by the DCConnect APIs and structures. These types are defined in compiler or operating system header files or the DCX.H file for DCConnect.
This section lists the rest of the data types that are specific to DCConnect.
These APIs provide interactive access to data transactions collected by DCConnect. They are used to direct groupings of transactions to a single place from which they can be retrieved by an application using the APIs described here. In DCC/2, transactions were stored in an export. In DCConnect, the term export was changed to the term mailbox. DCConnect supports both the new mailbox APIs and the DCC/2 export APIs.
DcxOpenMailbox (Mailboxname, Handlep) (Formerly called DcxOpenExport)
DcxOpenMailbox notifies DCConnect that an application want to receive transactions for a particular Mailbox defined in DCConnect. After a Mailbox is opened, the first transaction returned on a read is the first matching one after the most recently released transaction. The current position can be "backed up" to the released position by issuing a close then an open.
DCConnect requires the thread that opens a particular Mailbox to remain active until that Mailbox is closed. When the Mailbox is opened, DCConnect stores some information about the thread that is issuing the open. If this thread is still active when a second request to open the same Mailbox is issued, the second request is rejected with the return code DCX_INVALID_MODE. However, if the first thread has closed the Mailbox or the first thread ended without closing the Mailbox, the second request is allowed.
Note: The thread that opens an mailbox must be the same thread used to close it.
Mailboxname (PSZ) - input
Null-terminated name of one of the transaction Mailboxes that was created using the DCConnect user interface.
This name identifies terminal and transaction criteria specified by the user when the Mailbox was created, for sending transactions to the Mailbox.
Handlep (PHTRANS) - output
Address of the handle. The handle must be used during future APIs to:
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HTRANS mailbox_handle; CHAR mailbox_name[] = "MAILBOX1"; rc = DcxOpenMailbox(mailbox_name, &mailbox_handle);
DcxReadTransaction(Handle, Buffer, Timeout)
The next transaction matching the criteria for the Mailbox opened in the corresponding DcxOpenMailbox (See DcxOpenMailbox) API is returned. If no matching transaction data is available, the API does one of the following, based on the value of the Timeout parameter:
| Timeout is positive | Wait for the specified number of 0.1 seconds before returning. If a transaction is received before the timeout expires, the transaction is returned right away. |
| DCX_TIMEOUT_FOREVER | Block until a matching transaction is available |
| DCX_TIMEOUT_NONE | Return immediately, with or without a transaction |
If no transaction is available within the time specified, the return code will be DCX_NO_DATA. If a transaction is returned, the return code will be DCX_NO_ERROR.
| Note: |
If the terminal belongs to a function group, then the function group name
matching the transaction ID is returned in the transaction structure instead of
the job name.
The length returned in the .datalen field of the TRF structure is the length of the actual transaction data in the .txdata field of that structure. |
As of October 2004, support for transactions with up to 750 bytes of data and with enhanced date/time fields was added. In order to take advantage of these new features, use DcxReadTransactionEx instead of DcxReadTransaction. DcxReadTransactionEx must be used to read the new TRF2 structure which contains this extra information. DcxReadTransaction can still be used as long as the data in the transactions will not exceed the old length of 108 bytes and as long as the 4-digit year is not needed and the adjusted date and time fields are not needed.
If DcxReadTransaction is called and the next transaction has data longer than would fit in the TRF structure, the return code DCX_DATA_TRUNCATED.
Handle (HTRANS) - input
Handle from DcxOpenMailbox (See DcxOpenMailbox) .
Address of buffer area for the incoming transaction. The buffer must be large enough to accommodate the TRF / TRF2 structure. In fact, this parameter should be a pointer to a TRF / TRF2 structure that already has memory allocated for it.
See Transaction Record Format (See Transaction Record Format) or Extended Transaction Record Format (See Extended Transaction Record Format) for information about and values for these structures.
Timeout (LONG) - input
Specifies the amount of time to wait for a transaction if none is available when the API is issued. A positive timeout value indicates the number of 0.1 seconds to wait. The following two timeout values may be used:
| DCX_TIMEOUT_FOREVER | Causes the application making this call to block until a transaction is available. |
| DCX_TIMEOUT_NONE | Returns right away whether or not a transaction is available. This value should only be used if the application making the API is issuing other sleep or other blocking calls between invocations to DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) . If the application simply loops, calling this API with the DCX_TIMEOUT_NONE parameter, results in poor system performance. |
Note: If the application must end while a read is waiting, the thread that issued the DcxOpenMailbox call can issue the DcxCloseMailbox (See DcxCloseMailbox) API using the same handle. This causes the blocked read to end with the return code being set to DCX_NO_DATA.
The longer the timeout value is, the more efficient the transaction flow. For example, less CPU time is consumed if fewer calls are made over a given period of time because the overhead associated with each call is incurred less often.
In addition, if the application is waiting when a transaction is received by DCConnect, the transaction is 'handed-off' to that application after it has been safely stored in the Mailbox. This eliminates the need for DCConnect to read the transaction from the Mailbox - decreasing the number of disk accesses per transaction read.
The problem with long timeouts is that there is less opportunity for the application to perform other work while waiting for transaction data. Therefore if a lot of work needs to be done between transaction reads, it is recommended to start another thread to handle the DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) . A long timeout value should be used by this thread.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HTRANS mailbox_handle; TRF2 in_transaction; /* First call DcxOpenMailbox() to get the mailbox_handle. Wait */ /* up to 10 seconds for a transaction. */ rc = DcxReadTransactionEx (mailbox_handle, &in_transaction, 100L);
DcxReleaseTransaction (Handle, DcxSeqNum)
DcxReleaseTransaction is used to permit transactions to be released (deleted) from a Mailbox. Normally it is used after each API to DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) although it can be used less frequently.
All transactions up to and including the sequence number specified are marked as released for the Mailbox with which the handle is associated. Any transactions that have been released can now be overwritten by new transactions that are to be written to the Mailbox.
The DCConnect sequence number used here is the same one returned in the first field of the transaction structure that is returned on the DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) API.
Each time a Mailbox is opened, the read pointer into the Mailbox is set to the transaction after the last one released. This will be the transaction returned on the next DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) API.
More efficient transaction flow can be achieved if the DcxReleaseTransaction API is not issued for every transaction read, provided all outstanding transactions are released at that time. DCConnect keeps track of the sequence number of the last transaction read. Therefore, the Mailbox does not have to be searched if the last transaction read is the one that is released.
However, if the sequence number specified is for an outstanding transaction other than the last one read, DCConnect must access the disk in order to find the proper transaction(s) to release.
One drawback to releasing more than one transaction at a time is that the application runs the risk of receiving duplicate transactions if DCConnect is shut down or if the application is ended unexpectedly before the release command is sent for any transactions that were outstanding.
Handle (HTRANS) - input
Handle from DcxOpenMailbox (See DcxOpenMailbox) .
DcxSeqNum (PCHAR) - input
DCConnect sequence number of transaction to release. This is the first field of the transaction structure (TRF) that is returned on a DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) call.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HTRANS mailbox_handle; TRF in_transaction; /* First call DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) () to read the transaction into */ /* the 'in_transaction' structure */ rc = DcxReleaseTransaction(mailbox_handle, in_transaction.seq);
DcxCloseMailbox notifies DCConnect that an application no longer wants to receive transactions for a specific Mailbox opened in the corresponding call to DcxOpenMailbox (See DcxOpenMailbox) and releases any resources associated with the handle. Any transactions that have not been read or released from the Mailbox remain in the Mailbox.
DcxCloseMailbox must be issued from the thread that issued the DcxOpenMailbox (See DcxOpenMailbox) call. This allows the close API to unblock a thread that is waiting on a call to DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) . If a read unblocks as a result of the close call, the return code for the read call will be DCX_NO_DATA.
Handle (HTRANS) - input
Handle from DcxOpenMailbox (See DcxOpenMailbox) .
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HTRANS mailbox_handle; /* The handle was obtained from a previous DcxOpenMailbox() call */ rc = DcxCloseMailbox(mailbox_handle);
DcxWriteTransaction (Transaction)
DcxWriteTransactionEx (Transaction, MailboxList)
DcxWriteTransactionEx2 (Transaction, MailboxList, SerialKey, Priority)
DcxWriteTransaction / DcxWriteTransactionEx / DcxWriteTransactionEx2 writes a transaction to one or more mailboxes as though the transaction had come from a DCT. The terminal name and transaction ID in the transaction determine which mailbox the transaction will be written to.
The DCConnect sequence number, line location, line number, terminal address and terminal Job are all filled in by DCConnect based on the terminal name specified in the transaction. Therefore, this terminal name must be one that is currently configured in DCConnect. All other fields in the transaction must be supplied by the caller.
As of October 2004, support for transactions with up to 750 bytes of data and with enhanced date/time fields was added. In order to take advantage of these new features, use DcxWriteTransactionEx instead of DcxWriteTransaction. DcxWriteTransactionEx must be used to read the new TRF2 structure which contains this extra information.
Another feature added in October 2004, is the ability to provide a list of target mailboxes in the API call instead of specifying a valid terminal name in the transaction structure. This feature is only valid when using DcxWriteTransactionEx. If a mailbox list is defined, the DCConnect Server will not try to validate the terminal name provided in the TRF2 structure, nor will it change the line location, line number, terminal address or terminal job values in the TRF2 structure.
The transaction data must be in the same format used by DcxReadTransaction / DcxReadTransactionEx (See DcxReadTransaction / DcxReadTransactionEx) .
When a mailbox list is not provided, the following fields of the TRF / TRF2 structure can contain anything because they will be filled in by DCConnect.
.seq, .loc, .line, .address, .job
Note: If the terminal belongs to a function group, then the function group matching the transaction ID is used instead of the job name.
In all case, the following fields of the must contain data in the valid range for that field:
.termseq, .year, .month, .day, .hour, .minute, .second, .transid
The following requirements must be adhered to:
Refer to Transaction Record Format (See Transaction Record Format) or Extended Transaction Record Format (See Extended Transaction Record Format) for more information about valid data for each field.
The length specified in the .datalen field of the TRF / TRF2 structure should be the length of the data in the .txdata field of the structure.
Transaction (PTRF) - input
Address of transaction data to be written
MailboxList (PLISTZ) - input
This parameter, which applies only to DcxWriteTransactionEx, must be a pointer to a buffer which contains the list of names of mailboxes into which the transaction should be written. Each name in the list must be null-terminated and the list must end with an additional null character. Each mailbox name in the list must be one that is configured in DCConnect.
If a mailbox list is not to be provided, specify NULL for this parameter.
SerialKey (PCHAR) - input
This parameter, which applies only to DcxWriteTransactionEx2, must be a pointer to a buffer which contains the serialization key string. This API and parameter are intended for use with a master mailbox built with the serial-keying column set. It can be used with a non-conforming mailbox, but in that case it will operate in the same manner as the plain DcxWriteTransactionEX API.
A non-empty serialization key indicates that the DCConnect runtime should control distribution of the transaction to its pool mailboxes, such that only 1 pool session is processing a particular serial key value at a time. For example, you may want all of the transactions for a particular shop floor work order to be processed in chronological sequence ( issues, completions and back-flushes). Setting the serial key for all transactions for work order number 12345678 to "WO12345678" will serve to keep the work order's completions from being posted before its issues.
An empty string indicates that the transaction does not need to be serialized and may be processed in muliple, parallel pool mailboxes simultaneous with any other transactions.
Priority (INT) - input
This parameter, which applies only to DcxWriteTransactionEx2, must be an integer value. This API and parameter are intended for use with a master mailbox built with a serial-keying column set. It can be used with a non-conforming mailbox, but in that case it will operate in the same manner as the plain DcxWriteTransactionEX API.
A lower number gives a transaction a higher priority. Transactions of the highest priority are given preference in being dispatched to a pool mailbox. This is intended for promoting a 'live look-up' inquiry transaction ahead of an update/posting transaction, where the later has no worker awaiting the reply.
All transactions that you want to have kept in their original chronology should be submitted with the same priority value.
#include "dcx.h"
#define BADGEDATA "0123345"
#define TERMNAME "FRONT_DOOR"
SHORT rc; /* Return code from API call */
SHORT termseq = 45; /* Terminal sequence number */
TRF2 out_trans; /* Buffer for transaction being sent */
time_t clock; /* Stores time in seconds */
struct tm * timep; /* Pointer to time structure */
/*
* Set up the terminal name - padded with null characters. The terminal
* sequence number is 45.
*/
strncpy(out_trans.termname, TERMNAME,
DCX_TRF_TERMNAMELEN + 1);
sprintf(out_trans.termseq, "%05d", termseq);
/*
* Set up the date and time for the transaction.
*/
time(&clock);
timep = gmtime(&clock);
sprintf(out_trans.year, "%04d", timep->tm_year);
sprintf(out_trans.month, "%02d", timep->tm_mon + 1);
sprintf(out_trans.day, "%02d", timep->tm_mday);
sprintf(out_trans.hour, "%02d", timep->tm_hour);
sprintf(out_trans.minute, "%02d", timep->tm_min);
sprintf(out_trans.second, "%02d", timep->tm_sec);
sprintf(out_trans.yearAdj, "%04d", timep->tm_year);
sprintf(out_trans.monthAdj, "%02d", timep->tm_mon + 1);
sprintf(out_trans.dayAdj, "%02d", timep->tm_mday);
sprintf(out_trans.hourAdj, "%02d", timep->tm_hour);
sprintf(out_trans.minuteAdj, "%02d", timep->tm_min);
sprintf(out_trans.secondAdj, "%02d", timep->tm_sec);
/*
* Set up the transaction mode as buffered, and transaction ID as 7
*
*/
out_trans.mode = 'B';
memcpy(out_trans.transid, "007", DCX_TRF_TRANSIDLEN);
/*
* Finally the transaction data itself and the data length are
* set up. Our data is a badge number of length 7: 0123345. The
* data is padded with blanks to the end of the field
*/
out_trans.datalen = (long)strlen(BADGEDATA);
memset(out_trans.txdata, ' ', DCX_TRF_TXDATALEN_EX);
memcpy(out_trans.txdata, BADGEDATA, out_trans.datalen);
/*
* Now that the transaction is set up, it can be sent to DCConnect.
*/
rc = DcxWriteTransactionEx(&out_trans, NULL);
DcxClearMailbox (MailboxName) (Formerly called DcxClearExport)
DcxClearMailbox is used to remove all transactions from the specified Mailbox. The pointers into the Mailbox are set as if all transactions in the file have been read and released.
However, if the Mailbox is currently open by an application and that application has read one or more transactions without having released them yet, DCConnect will not allow the Mailbox to be cleared. This is not allowed because most likely the application will eventually tries to release those transactions and if they have already been cleared, the release can not work properly.
The Mailbox can be cleared whether an application has it open or not - just as long as there are no transactions that have been read and not released.
MailboxName (PSZ) - input
Null-terminated name of one of the transaction Mailboxes defined using the DCConnect user interface.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR mailboxname[] = "CLOCK_IN_TXTNS"; rc = DcxClearMailbox(mailboxname);
DcxQueryMailbox (MailboxName, MailboxInfo) (Formerly called DcxQueryExport)
DcxQueryMailbox / DcxQueryMailboxEx is used to find out the number of outstanding transactions, the state, the Mailbox log file name and the size for the specified Mailbox. This API can be called by any process; the Mailbox does not have to be open.
As of October 2004, support for transactions containing up to 750 bytes of data was added, along with support for some new date information. Because of the longer transaction record, the format of the transaction mailbox logfiles was changed to use variable length records instead of fixed length records. And as a result, the capacity of the logfile is now specified as a number of bytes (100,000 to 25,000,000) instead of a number of records.
So the capacity value in the QUERY_MAILBOX / QUERY_MAILBOX2 structure specifies a number of bytes, not a number of records.
The structure returned contains the following information about the Mailbox:
The instant after this call is issued, the information could become obsolete because a transaction could be written to, read from or released from the Mailbox at any time and the Mailbox could be opened or closed at any time.
MailboxName (PSZ) - input
Null-terminated name of one of the transaction Mailboxes defined using the DCConnect user interface.
MailboxInfo (PQUERY_MAILBOX) - output
The structure contains the following fields:
Reports the number of transactions that have not yet been read from the Mailbox.
Reports the number of transactions that have been read from the Mailbox and have not yet been released. This value is always 0 if the mailbox is not currently open.
Reports whether the Mailbox is currently open (active). The following values can be returned:
| DCX_MAILBOX_IS_INACTIVE | Mailbox is not open |
| DCX_MAILBOX_IS_ACTIVE | Mailbox is open |
Reports the name of the physical log file on disk.
The capacity of the mailbox as a number of bytes.
If calling DcxQueryMailboxEx, which returns the QUERY_MAILBOX2 structure, then this additional value is returned which specifies what percentage of the logfile's capacity is in use.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; QUERY_MAILBOX mailboxinfo; CHAR mailboxname[] = "CLOCK_IN_TXTNS"; rc = DcxQueryMailbox(mailboxname, &mailboxinfo);
DcxQueryMailboxList (ListLenp, MailboxList, ListCntp) (Formerly called DcxQueryExportList)
DcxQueryMailboxList provides the application program with a list of Mailboxes that have been configured for DCConnect.
The application can first call DcxQueryMailboxList with * ListLenp set to zero in order to find out how much storage is required for the data buffer. Having allocated the storage, the application then calls the function a second time in order to have the buffer filled with data.
ListLenp (USHORT *) - input/output
Reports the total number of bytes in the Mailbox list. If, when the call is made, this is set to 0, DCConnect returns the actual size of the list in this field.
MailboxList (PLISTZ) - output
Pointer to a buffer in which to put the list of Mailbox names. Each name in the list is null-terminated and the list ends with an additional null character. If the list is empty it contains a single null character.
ListCntp (USHORT *) - output
Number of entries in the mailbox list. This value is returned both when the mailbox list itself is returned and when just the length of that list is returned.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
USHORT list_length;
PLISTZ mailbox_list;
USHORT list_count;
/* First make call to find out storage required */
list_length = 0;
rc = DcxQueryMailboxList(&list_length, mailbox_list, &list_count);
/* Allocate space for list - this value was returned in 'list_length'*/
/* Then call function again to get the list of mailbox */
if (rc == DCX_NO_ERROR)
{
mailbox_list = (PLISTZ)malloc(list_length);
if (mailbox_list != NULL)
rc = DcxQueryMailboxList(&list_length, mailbox_list, &list_count);
}
The Terminal Access APIs provide applications with the capability to access information and control various features of a Data Collection Terminal. Due to the multi-tasking (multiple simultaneous application) capabilities of Warp and Windows, APIs are provided to allow an application to obtain exclusive use of a terminal when necessary.
DcxAcquireTerminal (TermName, Handlep)
DcxAcquireTerminal allows a user-written application to acquire a terminal for exclusive use of its Terminal Access or Terminal Management APIs. The other APIs for that terminal will still be accessible to other applications.
DcxAcquireTerminal should be used to insure exclusive access rights to a terminal where a series of API calls will be made or where collisions with other user-written applications could occur while accessing a terminal.
The DcxUnacquireTerminal (See DcxUnacquireTerminal) API should be issued when the application has finished the series of terminal accesses, in order to release exclusive use of the terminal.
Even when an application has acquired a terminal, that access will be overridden by a download to that terminal. The download of a terminal automatically invalidates any acquire handle for that terminal.
Refer to HTERM for more details about what return codes can be given for incorrect use of the acquire handle by the APIs that require this parameter.
Note: The thread that acquires a terminal must be the same thread used to unacquire it.
TermName (PSZ) - input
The name of the terminal to be acquired. This name must be one that has been defined using the DCConnect user interface.
Handlep (PHTERM) - output
Address where the handle parameter is returned. This handle parameter must be used during future calls to the Terminal Access or Terminal Management APIs.
Note: The thread that obtains the handle parameter must remain in existence as long as the handle parameter is to be used. The handle parameter may be passed to other threads to use, as long as the thread that originally obtained the handle parameter exists.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HTERM dct_handle; CHAR term_name[] = "LOADING_DOCK"; rc = DcxAcquireTerminal (term_name, data collection terminal_handle);
DcxUnacquireTerminal (Handle)
DcxUnacquireTerminal allows a user-written application to release its exclusive access to a terminal, previously obtained through the DcxAcquireTerminal (See DcxAcquireTerminal) call. Once released, other applications are free to acquire the terminal or use the Terminal Access or Terminal Management APIs to control the terminal.
Note: The thread that unacquires the terminal must be the same one that acquired it.
Handle (HTERM) - input
The handle parameter returned by a previous call to DcxAcquireTerminal (See DcxAcquireTerminal) .
Return code descriptions can be found in ReturnReturn Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HTERM dct_handle; rc = DcxUnacquireTerminal (dct_handle);
DcxBeepTerm(TermName, Acquire, Duration)
DcxBeepTerm is used to sound the audible tone on the specified terminal. The caller specifies the duration as the number of half seconds for which the tone should be turned on. This API corresponds to the "CMD 5" DCT Control Command.
DcxBeepTerm is executed only if the terminal is in idle mode when the command is received. Even though the terminal ignores this command if it is not in idle mode, the API still returns DCX_NO_ERROR.
To find out if the terminal performed the command, use the API DcxQueryTermStatus and check the status string. The command field of that string will be " 5" and the command status field indicates whether the command was successful or not.
Note: The terminal is able to receive other commands immediately after the tone is started; it does not have to wait for the tone to finish.
TermName (PSZ) - input
The name of the terminal to be beeped. This name must be one that has been defined using the DCConnect user interface.
Acquire (HTERM) - input
This is the handle returned by DcxAcquireTerminal (See DcxAcquireTerminal) . This handle parameter only needs to be provided if this application currently has this terminal 'acquired'. If not acquired, 0 must be used for the handle parameter.
Duration (USHORT) - input
An integer specifying the number of half second intervals (1-9) that the tone should sound.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" #define FOUR_SECOND_BEEP 8 USHORT rc; CHAR beep_terminal[] = "TIME_AND_ATTENDANCE"; rc = DcxBeepTerm(beep_terminal, 0, FOUR_SECOND_BEEP);
DcxDisplayTermText(TermName, Acquire, Row, Column, Attribute, Erase, Duration, Text)
DcxDisplayTermText is used to display a message on a data collection terminal. The message starts at the specified row and column and continues for as many characters as are in the text. The message continues onto additional lines as required to display the entire message. A message that continues beyond the end of the terminal screen is truncated at the end of the terminal screen. If the message starts at a line that is invalid for the terminal type (such as, line 12 of a 2-line display), an error occurs.
Displayed information can consist of all ASCII characters except for the following:
| 00h (null) | Used to terminate the string |
| 1Bh (ESC) | Used to embed graphic sequences and cursor control (see the 7527 Extended Terminal Services Technical Reference for details) |
For 7525 and 7526 terminals, the row, col, attribute, and erase parameters are ignored. However, they are checked for validity. The API returns DCX_INVALID_ROW_COL if the row or column are not valid for that terminal type. The message is always displayed in row 1, col 1 with normal attributes after clearing the screen.
For 7525 and 7526 terminals, this API corresponds to the "CMD 2" DCT Control Command; for the 7524 and 7527 terminals, this API uses the ETS "CMD O" DCT control command. This command is only executed when the terminal is in idle mode. If a 7525 or 7526 terminal receives this command when not in idle mode, the command is ignored. The 7524 and 7527 terminals buffer the command if the terminal is not in idle mode when the command is received. They then display the text when the terminal next returns to idle mode. The character set for the 7525 is the same as for the first 128 characters for the 7527 Model 001 terminal.
TermName (PSZ) - input
The name of the terminal on which to display the text. This name must be one that has been defined using the DCConnect user interface.
Acquire (HTERM) - input
This is the handle returned by DcxAcquireTerminal (See DcxAcquireTerminal) . This handle only needs to be provided if this application currently has this terminal 'acquired'. If not acquired, 0 must be used for the handle.
Row (USHORT) - input
The row on the screen that the text display is to start. The top row is row number 1. Use DCX_CURRENT_ROW to show the text at the row the cursor is currently on.
Column (USHORT) - input
The column within the row that the text display is to start. The left most column is column 1. Use DCX_CURRENT_COL to show the text at the column the cursor is currently on.
Attribute (USHORT) - input
The display attribute that is to be used for the text. The valid attributes are:
| DCX_ATTR_NORMAL | Display in standard form |
| DCX_ATTR_ULINE | Display underlined |
| DCX_ATTR_REVERSE | Display reverse video |
| DCX_ATTR_REVERSE_ULINE | Display reverse video underlined |
| DCX_ATTR_BLINK | Display blinking |
| DCX_ATTR_BLINK_ULINE | Display blinking underlined |
| DCX_ATTR_BLINK_REVERSE | Display blinking reverse video |
| DCX_ATTR_BLINK_REVERSE_ULINE | Display blinking underlined reverse video |
Erase (USHORT) - input
Indicates whether or not to clear the screen prior to displaying the text. The valid values are:
| DCX_CLEAR_SCREEN | Clear the screen |
| DCX_NO_CLEAR_SCREEN | Do not clear the screen |
Duration (USHORT) - input
Indicates whether the text should be displayed for a limited duration or indefinitely. The valid durations are:
| DCX_OPERATOR_DURATION | The text will remain on the screen until Clear or Cancel is pressed at the terminal or the text is overwritten by a transaction program or another display command. |
| DCX_TIMER_B_DURATION | Uses the "Non-prompt message display" time. |
Text (PSZ) - input
A null-terminated ASCII string that is to be displayed on the DCT screen. Maximum text lengths are:
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR my_term[] = "SECURITY_TERMINAL";
USHORT row;
USHORT col;
USHORT attribute;
USHORT erase;
USHORT duration;
CHAR show_text[] = "Time to go home, Dean!";
/* The message "Time to go home, Dean" is shown on the */
/* security terminal at row 1 column 1 with normal attributes */
/* after clearing the screen. It is shown indefinitely. */
row = 1;
col = 1;
attribute = DCX_ATTR_NORMAL;
erase = DCX_CLEAR_SCREEN;
duration = DCX_OPERATOR_DURATION;
rc = DcxDisplayTermText(my_term, 0, row, col, attribute, erase,
duration, show_text);
DcxExecuteTermTransaction (TermName, Acquire, Text)
DcxExecuteTermTransaction is used to send a transaction program to the specified terminal and have the program executed immediately on the terminal. Once execution completes, the transaction program is deleted from the terminal's memory.
DcxExecuteTermTransaction will be executed by the terminal only if it is idle when the command is received or if the terminal is in interactive mode waiting for a response to a transaction. Both this API and DcxInteractiveResponse can be used to respond to an interactive transaction.
If confirmation that the transaction program was executed is required, the caller should use DcxQueryTermStatus. This confirmation can only be used with 7524, 7526 or 7527 terminals.
This API corresponds to the "CMD D" DCT Control Command.
TermName (PSZ) - input
The name of the terminal on which to execute the program. This name must be one that has been defined using the DCConnect user interface.
Acquire (HTERM) - input
This is the handle returned by DcxAcquireTerminal (See DcxAcquireTerminal) . This handle only needs to be provided if this application currently has this terminal 'acquired'. If not acquired, 0 must be used for the handle.
Text (PSZ) - input
A null-terminated ASCII string that contains the transaction program to be executed. Refer to the appropriate manual listed below for information on transaction program commands that may be imbedded in the command text.
The length of the text (including anticipated expansion due to insertion of the ESC character for DCConnect network-specific control characters) must be less than or equal to 512 bytes for the 7527 terminal, 255 bytes for the 7526 terminal, or 120 bytes for the 7524 or 7525 terminal.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR my_term[] = "TIME_AND_ATTENDANCE"; HTERM acquire = 0; CHAR open_door_pgm[] = ":6/You may enter . . ./:P06T05"; /* The open_door_pgm displays the message "You may enter . . ." on */ /* the terminal and then toggles DO point 6 for 5 seconds. DO */ /* point 6 is wired to a lock on a door. This is a 7527 program. */ rc = DcxExecuteTermTransaction(my_term, acquire, open_door_pgm);
DcxInitiateTermEvent (TermName, Acquire, TransactionProgram)
DcxInitiateTermEvent causes simulation of the specified transaction program being initiated on the specified terminal.
DcxInitiateTermEvent corresponds to the "CMD G" DCT Control Command.
DcxInitiateTermEvent is ignored if the terminal receives the command when not in idle mode.
Use the API DcxQueryTermStatus to find out if the terminal was able to perform the command.
Note: DcxInitiateTermEvent is not supported by 7525 terminals.
TermName (PSZ) - input
The name of the terminal on which to initiate the program. This name must be one that has been defined using the DCConnect user interface.
Acquire (HTERM) - input
This is the handle parameter returned by DcxAcquireTerminal (See DcxAcquireTerminal) . This handle parameter needs only to be provided if this application currently has this terminal 'acquired'. If not acquired, 0 must be used for the handle parameter.
TransactionProgram (USHORT) - input
An integer in the range of 1-121 for 7527 and 7524 terminals, or 1-64 for 7526 terminals, specifying the number of the transaction program to be started.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" #define SHUTDOWN_PGM 25 SHORT rc; CHAR my_term[] = "BOILER_ROOM"; rc = DcxInitiateTermEvent(my_term, 0, SHUTDOWN_PGM);
DcxQueryTermDateTime(TermName, DateTime)
DcxQueryTermDateTime is used to obtain the current date and time of the specified terminal.
DcxQueryTermDateTime corresponds to the "CMD 7" DCT Control Command. DcxQueryTermDateTime can be used whether the terminal is in idle mode or not.
TermName (PSZ) - input
The name of the terminal to get the date/time from. This name must be one that has been defined using the DCConnect user interface.
DateTime (PSZ) - output
A 12-character (13 including the terminating null character) string containing the date and time. The format is YYMMDDHHmmSS where:
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" #define DATE_TIME_LEN 12 SHORT rc; CHAR term_name[] = "TIME_AND_ATTENDANCE"; CHAR date_time[DATE_TIME_LEN + 1] rc = DcxQueryTermDateTime(term_name, date_time);
DcxQueryTermStatus(TermName, Status)
DcxQueryTermStatus is used to obtain the current operational status of the indicated terminal. It can be used to determine status such as whether terminal commands sent to the terminal executed properly, whether the terminal is in service, or whether there are transactions in the terminal's buffer waiting for transmission to DCConnect.
DcxQueryTermStatus corresponds to the "CMD 1" DCT Control Command. DcxQueryTermStatus can be used whether the terminal is idle or not.
TermName (PSZ) - input
The name of the terminal from which to get the status. This name must be one that has been defined using the DCConnect user interface.
Status (PTERMSTATUS) - output
Status of terminal. See TERMSTATUS for a description of the TERMSTATUS structure.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR term_name[] = "TIME_AND_ATTENDANCE"; TERMSTATUS term_status; rc = DcxQueryTermStatus(term_name, &term_status);
DcxSetTermUserVariable (TermName, Acquire, UserVariable, Text)
DcxSetTermUserVariable is used to set a specific user variable in a specified terminal to a particular value. Once in a user variable, the value can be used by transaction programs or the CFR running in the terminal.
DcxSetTermUserVariable corresponds to the "CMD I" DCT Control Command. DcxSetTermUserVariable is executed whether the terminal is in idle mode or not.
Note: DcxSetTermUserVariable is not supported by 7525 terminals.
TermName (PSZ) - input
The name of the terminal in which to set the user variable. This name must be one that has been defined using the DCConnect user interface.
Acquire (HTERM) - input
This is the handle parameter returned by DcxAcquireTerminal (See DcxAcquireTerminal) . This handle parameter needs only to be provided if this application currently has this terminal 'acquired'. If it's not acquired, 0 must be used for the handle.
UserVariable (USHORT) - input The number of the user variable into which the data is to be stored. Valid values are 10 through 19 for a 7527 terminal, 1 through 998 for a 7526 terminal, or 10 through 99 for a 7524 terminal with flash level greater than 1.10. 7524 terminals with flash levels 1.10 or earlier are restricted to a maximum of 19 user variables - just like the 7527 terminal.
Text (PSZ) - input A null-terminated string containing the data to be assigned to the DCT user variable. The maximum length of the string is 118 bytes for all supported terminal types unless the terminal is running at least version 2.10 of the DCConnect Client and the DCConnect Server is also at version 2.10 or later. In this case the maximum string length is 975 bytes.
If you ultimately want to send a user variable to the 7527's printer or general purpose serial port, you may include a null character (ASCII 000) in the user variable by encoding it as a four-character sequence of "ESC 000" (1Bh followed by 3 ASCII 30h characters). The printer driver in 7527 ETS converts this to a null as it is sent to the output port. Similarly, an escape character (1Bh) may be loaded to a 7527 user variable and sent to the output port by encoding it as "ESC 027" (1Bh followed by 30h, 32h, 37h).
The 7526 terminal does not use the "ESC nnn" sequence for generating specific ASCII characters in a user variable. However, if the data in the user variable is intended to be sent to a printer attached to the 7526, then specific ASCII characters can be encoded using the 4-character sequence \x?? where ?? is a hex value from 00 through FF. This encoding is necessary in order to send a null character to the printer from the user variable. Since a null character in the user variable string indicates the end of the string to the DcxSetTermUserVariable the string must instead use \x00 in order to get that information and the rest of the user variable string into the terminal's user variable.
However, be aware that the user variable in the terminal will contain the \x00 characters rather than the single null character; it is the printer driver in the 7526 that converts the \x00 to a null character before sending it to the printer.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR my_term[] = "TIME_AND_ATTENDANCE"; HTERM acquire = 0; CHAR var_data[] = "November"; USHORT var_num; /* The TIME_AND_ATTENDANCE terminal will be looking for */ /* information in user variable 10. */ var_num = 10; rc = DcxSetTermUserVariable(my_term, acquire, var_num, var_data);
DcxSetNTermUserVariables (TermName, Acquire, NumVariables, VarArray, VarTextArray)
DcxSetNTermUserVariables is like DcxSetTermUserVariable except that more than one user variable can be set in the terminal in a single API calls.
There actually is no limit (except that of the range of user variables a terminal supports) to the number of user variables that you can specify to be set by this API. However, DCConnect does need to break up the list into chunks of approximately 450 bytes of data to be handled at one time. If all of the data for the variables to be set (including 3 bytes for each user variable number) fit into that 450 bytes, those user variables will all be set consecutively down at the terminal before any command to any other terminal is handled. This makes the processing faster than using multiple calls to DcxSetTermUserVariable, which requires data to be passed up and down from the API level to the terminal for every user variable.
This API was added primarily for support of 7524 RF terminals where communications is generally slower than fixed terminals. However, it can be used for all terminal types that can have user variables set (all but the 7525). DCConnect automatically figures out what the appropriate command is to send to the terminal.
DcxSetTermUserVariable corresponds to the "CMD IM" DCT Control Command for 7524 terminals and for 7526 terminals that are attached by way of the Ethernet. For other possibilities, this API corresponds to multiple calls to "CMD I" at the terminal.
Note: DcxSetNTermUserVariables is not supported by 7525 terminals.
The name of the terminal in which to set the user variables. This name must be one that is part of the DCConnect configuration.
Acquire (HTERM) - input
This is the handle returned by DcxAcquireTerminal. This handle needs to be provided only if this application currently has this terminal 'acquired'. If it is not acquired, 0 must be used for the handle.
NumVariables (USHORT) - input
This is the number of user variables that are to be set. Space should be allocated for the 'VarArray' and 'VarTextArray' greater than or equal to that necessary for the number of variables specified by the NumVariables parameter.
VarArray (USHORT *) - input
This is an array of USHORT values. Each value in the array is a user variable number which is to be set. The indices of the VarArray and VarTextArray correspond directly. The text for the user variable specified in index 0 of the VarArray will be pointed to by the pointer at index 0 of the VarTextArray.
The order in which the numbers appear in this array is the order in which they are set in the terminal.
The valid values in this array are 10 through 19 for a 7527 terminal, 1 through 998 for a 7526 terminal, or 10 through 99 for a 7524 terminal with flash level greater than 1.10. 7524 terminals with flash levels 1.10 or earlier are restricted to a maximum of 19 user variables - just like the 7527 terminal.
VarTextArray (PSZ *) - input
This is an array containing pointers to null-terminated strings that the corresponding user variables, specified in 'VarArray', should be set to. For example, the user variable specified in VarArray[0] is set to the string pointed to by VarTextArray[0]
The maximum length of the string is 118 bytes for all terminal types unless the terminal is running at least version 2.10 of the DCConnect Client and the DCConnect Server is also at version 2.10 or later. In this case the maximum string length is 975 bytes. If a user variable is to be cleared, a pointer to an empty string ("") should be put in the proper element of the VarTextArray. Do not use NULL as the pointer itself.
Refer to the explanation for the DcxSetTermUserVariable API for additional information about how to include special characters in the user variable string.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
#define DATA_LEN 100
#define USER_VARS_TO_SET 5
#define TERMINAL_NAME "TEST_TERMINAL"
SHORT rc;
USHORT vars[USER_VARS_TO_SET] =
{
10, 11, 12, 13, 14,
};
PSZ vartext[USER_VARS_TO_SET]
{
"This is variable 10",
"This is variable 11",
"", /* Clear # 12 */
"This is variable 13",
"", /* Set this later */
};
char var14text[DATA_LEN + 1]
strcpy(var14text, "This is variable 14");
vartext[4] = var14text;
rc = DcxSetNTermUserVariables(TERMINAL_NAME, 0, USER_VARS_TO_SET, vars,
vartext);
DcxGetTermUserVariable (TermName, UserVariable, Text)
DcxGetTermUserVariable is used to get the current value of a specific variable in a specified terminal. User variables can be set by transaction programs and custom function routines running in the terminal or by the DcxSetTermUserVariable API.
DcxGetTermUserVariable corresponds to the "CMD Q" DCT Control Command. DcxGetTermUserVariable is executed whether the terminal is in idle mode or not.
Note: DcxGetTermUserVariable is only valid for 7526 terminals and 7524 terminals with flash level at 1.1F or later.
TermName (PSZ) - input
The name of the terminal from which to get the user variable. This name must be one that has been defined using the DCConnect configuration.
UserVariable (USHORT) - input
The number of user variable from which the data will be retrieved. The valid range for 7526 terminals is 0 to 998. For 7524 terminals, the range is 0 to 99.
Text (PSZ) - output
Address of the buffer area designated to receive the value of the user variable. The maximum length of the string that can be returned is 123 bytes for all terminal types unless the terminal is running at least version 2.10 of the DCConnect Client and the DCConnect Server is also at version 2.10 or later. In this case the maximum string length that can be returned is 975 bytes.
The size of this buffer should be large enough to hold the maximum data length plus 1 byte for the null character that the API will put at the end of the data.
The system supports user variables whose value contains binary data. However, if the variable contains null characters, then only the data up to the first null character is returned to the caller of this API.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" #define MAX_VAR_SIZE 123 SHORT rc; CHAR term_name[] = "TIME_AND_ATTENDANCE"; CHAR var_data[MAX_VAR_SIZE + 1] USHORT var_num; /* The TIME_AND_ATTENDANCE terminal will provide */ /* information in user variable 10. */ var_num = 10; rc = DcxGetTermUserVariable(term_name, var_num, var_data);
DcxInteractiveResponse (TermName, Response, Beep, Duration, Text, File, Record)
DcxInteractiveResponse allows an application to respond to an interactive transaction with either a positive or negative response. The audible tone on the terminal can be optionally sounded and a message can be optionally displayed on the terminal. The message is displayed at row 1 column 1.
DcxInteractiveResponse corresponds to the "CMD B" and "CMD C" DCT Control Commands. DcxInteractiveResponse is valid only when the terminal is expecting a response to an interactive transaction.
Note: The API DcxExecuteTermTransaction can also be used to reply to an interactive terminal that is waiting for a response to a transaction.
DcxInteractiveResponse ignores the 'acquired' state of the terminal. In other words, a DcxAcquireTerminal (See DcxAcquireTerminal) and DcxUnacquireTerminal (See DcxUnacquireTerminal) are not required when using DcxInteractiveResponse.
TermName (PSZ) - input
The name of the terminal that should receive the interactive response. This name must be one that has been defined using the DCConnect user interface.
Response (USHORT) - input An integer that specifies whether this is a positive response or negative response.
| DCX_INTER_POSITIVE | Positive response |
| DCX_INTER_NEGATIVE | Negative response |
Beep (USHORT) - input An integer that specifies whether the audible tone is to be sounded when the response is processed on the terminal. The duration for the beep is defined in the terminal.
| DCX_INTER_BEEP | Sound tone on response |
| DCX_INTER_NO_BEEP | Do not sound tone on response |
Duration (USHORT) - input Indicates whether the text should be displayed for a limited duration or indefinitely. The valid durations are:
| DCX_OPERATOR_DURATION | The text remains on the screen until Clear or Cancel is pressed at the terminal or the text is overwritten by a transaction program or another display command. |
| DCX_TIMER_B_DURATION | Uses the "Non-prompt message display" time as defined under the General Terminal Parameters for this terminal. |
Text (PSZ) - input A pointer to a null-terminated string that contains the text to be displayed on the terminal. If no message is to be displayed, a null string (pointer to a buffer whose first byte is a null character) should be used for this parameter. If the File and Record parameters are to be used, this parameter should be NULL. The maximum lengths are:
| 7494/7525, 7524 | 40 |
| 7526 Model 100 | 16 |
| 7526 Model 200 | 80 |
| 7527 Model 001 | 80 |
| 7527 Model 002 | 115 |
File (USHORT) - input Number of the file from which to display string. 0 should be used if no string will be displayed, or if the string will be supplied in the text parameter. The file numbers can be in the range 2-8. Files 2-7 are validation files in the terminal. These would be the first 6 validation files that the job for this terminal indicates should be downloaded to the terminal. File 8 is the message file.
Record (USHORT) - input Record number of record to be displayed. 0 should be used if no string will be displayed, or if a string is supplied in the text parameter.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR term_name[] = "TIME_AND_ATTENDANCE";
CHAR good_response[] = "Good night! Say hello to your wife.";
/* A transaction was just read by this application from the Time and */
/* Attendance terminal. Some validation has been performed (against */
/* a very intelligent data base) to determine the employee badge was */
/* valid, the employee was a male, married and all his work was done */
rc = DcxInteractiveResponse(term_name, DCX_INTER_POSITIVE, DCX_INTER_BEEP,
DCX_TIMER_B_DURATION, good_response, 0, 0);
These calls are provided for the purpose of performing operations on the terminals, such as loading them or setting or checking their current state.
DcxLoadTerminal (TermName, WhichFiles, Wait)
DcxLoadTerminal allows a user-written DCConnect application to download a set of files to the specified TermName. The set of files is either the entire Job that is currently assigned to the terminal or a subset of that Job, as specified by the WhichFiles parameter. Jobs are assigned to terminals using the DCConnect configuration. In DCConnect, jobs are not specifically created by the user. Moreover, the entire terminal configuration is considered its job.
The 'WhichFiles' parameter can specify one of the following:
For all but the last option listed above, the terminal will be flushed of any buffered transactions prior to the download.
The DcxLoadTerminal will override any pending 'acquire' of the terminal. When the download starts, the terminal is automatically 'unacquired' and remains that way after the download completes. Therefore, any application that had acquired the terminal before the download started must reacquire the terminal after the download completes in order to again have exclusive access to that terminal.
DCConnect uses a configurable parameter to limit the number of simultaneous downloads that can take place. By default this value is 16. However, this value can be changed using the node settings notebook.
If a download is issued and the maximum number of simultaneous downloads are currently in progress and the Wait flag is not DCX_RET_WHEN_QUEUED, the return code for this API will be DCX_NO_MORE_ROOM. However, if the Wait parameter is set to DCX_RET_WHEN_QUEUED, the download request will be queued and the actual download will be started later when some of the currently running downloads have completed.
TermName (PSZ) - input
The name of the terminal to be loaded. This name must be one that has been defined using DCConnect configuration.
WhichFiles (UCHAR) - input
Indicates which set or subset of files should be loaded from the Job that is assigned to this terminal.
The following values are supported:
| DCX_DWNLD_ETS | Reset the terminal, download ETS and all files in the assigned job. |
| DCX_DWNLD_ALL | Load all files in the assigned job. |
| DCX_DWNLD_CFR | Load Custom Function Routine (CFR) |
| DCX_DWNLD_GRPH | Load Graphics File |
| DCX_DWNLD_VAL | Load all Validation Files that should be downloaded for the assigned job. |
| DCX_DWNLD_FORCE | Forced reset of terminal - all transactions and files are deleted and then ETS and all files in the assigned job are loaded. |
| DCX_DWNLD_SCRIPTS | Download text-based scripts; if a CFR or validation files are referenced by those scripts, do not reload the CFR or validation files. |
| DCX_DWNLD_CLIENT | Load any client files that were previously staged for this terminal using the API DcxSubmitClientFiles. |
Use of the WhichFiles parameter allows the downloading of a portion of the Job which has been changed, depending on the terminal type (7525 terminals require a complete download to change any of the files in the terminal). This option is intended to reduce data traffic on the data collection sub-network and therefore to improve system performance.
Wait (UCHAR) - input
This parameter is used to select when the API should return to the caller. If not waiting for the download to complete, the progress of the download can be checked periodically by using the DcxReportTerminalState API call and checking the load step.
| DCX_RET_WHEN_COMPLETE | Return when the download completes - whether successful or not. |
| DCX_RET_WHEN_STARTED | Return immediately after starting the download. The API returns after setting up some files for loading and then putting the terminal out of service in preparation for the load. If any error occurs before this point, the return code will indicate the problem and the download will not be retried by DCConnect. However, if the download fails after DCX_NO_ERROR has been returned to the API, DCConnect will retry the download up to 5 times - waiting up to minute between each attempt. |
| DCX_RET_WHEN_QUEUED | This is similar to DCX_RET_WHEN_STARTED however, the API will only return an error if there is no way the download could ever succeed - for example if the terminal name specified was invalid. But in cases such as the terminal is currently not responding or the maximum number of concurrent downloads are currently in progress, the download request will be queued and the API return code will be DCX_NO_ERROR. DCConnect will then start the download when (in the cases just mentioned) the terminal begins to respond again or when space is available to start another download. |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR dct_name[] = "FRONT_DOOR"; UCHAR which_files = DCX_DWNLD_ALL; UCHAR wait = DCX_RET_WHEN_COMPLETE; rc = DcxLoadTerminal (dct_name, which_files, wait);
DcxSubmitClientFiles (TargetType, TargetName, ClientFilesListPath, SubmitMode)
DcxSubmitClientFiles allows a user-written DCConnect application to submit an updated set of DCConnect Client files to be loaded to one or more terminals.
Note this API, which is new for version 3.1.0 of the DCConnect Server, can only be used to load new client files to terminals running version 3.1.0 or later of the DCConnect Client.
The affected target terminals can be specified as a specific terminal name or a specific terminal model (e.g. WIN32, Intermec_CV60, Symbol_91xx) or a specific function group, for which all associated terminals should be updated.
The client files to be loaded will typically be either a set of new client executables (etspt.exe, etspt.dll and etsscrpt.dll) or an updated emulator.ini.
When this API call is issued, the client files that are submitted and staged can be loaded right away or they can just be staged - to be loaded at another (typically off-peak) time using DcxLoadTerminal, specifying DCX_DWNLD_CLIENT for the WhichFiles parameter. If the files are to be loaded now, the load request is treated the same as using DCX_RET_WHEN_QUEUED for the API DcxLoadTerminal.
The third parameter specifies the full path to a file that describes the set of client files that are to be loaded. This client files list file is a text file containing entries similar to the format shown below which indicates 4 different client files that are to be loaded:
[FILE] NAME_ON_CLIENT = etspt.exe.new PATH_ON_SERVER = c:\updates\dcclient\win32\etspt.exe [FILE] NAME_ON_CLIENT = etspt.dll.new PATH_ON_SERVER = c:\updates\dcclient\win32\etspt.dll [FILE] NAME_ON_CLIENT = etscrpt.dll.new PATH_ON_SERVER = c:\updates\dcclient\win32\etscrpt.dll [FILE] NAME_ON_CLIENT = emulator.ini.new PATH_ON_SERVER = c:\updates\dcclient\win32\emulator.ini
Notice that the NAME_ON_CLIENT parameter for all entries above uses .new as a suffix for each file. This is required because the Client that receives these new files is actively using these files (without the .new extension). Once the set of files is downloaded, the client restarts itself in a 'light' mode that allows it to update its own files from the new ones that were downloaded.
Although it is unlikely that this would be done, if multiple sets of files are submitted to the same terminal before the first submitted set is loaded, those sets of files are merged into one set by the server, removing any duplicates. When determining what is a duplicate, the combination of the NAME_ON_CLIENT and PATH_ON_SERVER parameters are compared, independent of case.
The server saves to disk all client file load requests so that they are preserved through shutdowns and restarts of the server. But once the entire client list is successfully downloaded for a particular terminal, that list of files will not be downloaded to that terminal any more - unless a new DcxSubmitClientFiles request is made for that terminal.
Calling DcxLoadTerminal with the DCX_DWNLD_ALL parameter will not download any staged client files that have not yet been downloaded. This is because the size of a set of client files may be large and it may be necessary to redownload the transaction programs, CFR and the other files for that terminal during normal operations without incurring the cost of downloading the client files as well.
At the end of the download of the Client files, the server also sends down a scaled-down version of the client files list file, like the one shown above - but containing only the lines that have the NAME_ON_CLIENT parameter. This is how the server tells the client that it has completed the loading of all of the client files in the set and how the client knows which are the new files. After this list file is loaded, the server sends a reset command which causes the client to restart itself, unloading its .DLLs, updating the new files and then reloading its .DLLs and emulator.ini (any of which may have been updated) as it starts up again. At this time the Client either reloads its locally stored text-based transaction programs and related files or requests a download of those files from the server.
Before a download of client files is started, the terminal will be flushed of any buffered transactions.
If the terminal is to be downloaded (the last parameters is DCX_SUBMIT_STAGE_AND_LOAD), at the start of the download the server will override any pending 'acquire' of the terminal. When the download starts, the terminal is automatically 'unacquired' and remains that way after the download completes. Therefore, any application that had acquired the terminal before the download started must reacquire the terminal after the download completes in order to again have exclusive access to that terminal.
TargetType (UCHAR) - input
Indicates what the second parameter, TargetName, represents. The following values are supported:
| DCX_TARGET_TERMINAL | The second parameter is a specific terminal name in the DCConnect configuration. The client files will be submitted only for this one terminal. |
| DCX_TARGET_MODEL | The second parameter is a terminal model such as Win32, Intermec_CV60 or
Symbol_91xx. The client files will be submitted for all terminals that are assigned to the
specified model. Typically all terminals with the same model will use the same set of DCConnect
Client executables and the same emulator.ini.
Note that each terminal can be assigned its terminal model on page 1 of the General tab in the Terminal Settings notebook of the DCConnect User Interface. |
| DCX_TARGET_FUNCTION_GROUP | The second parameter is a function group in the DCConnect configuration. The client files will be submitted for all terminals that are assigned to the specified function group. This option should only be used if all terminals in the function group use the same set of DCConnect Client executables and emulator.ini. |
TargetName (PSZ) - input
The name of the terminal / model / function group for which the client files are to be submitted. This name must be one that is configured in the DCConnect configuration. The first parameter, TargetType, indicates which type of element in the DCConnect configuration the TargetName represents.
ClientFilesListPath (PSZ) - input
The full path to the file that contains the list of client files that are to be loaded. See above for the format of the content of this file. The server will not change this file in any way.
If this file does not exist when this API call is made, the return code will be DCX_INVALID_FILE.
SubmitMode (UCHAR) - input
This parameter can have one of two values indicating whether or not the files should just be staged or should be staged and loaded. The following values are supported:
| DCX_SUBMIT_STAGE_ONLY | The client files should just be staged right now for the specified terminal
or set of terminals.
If the client files are submitted using this option, then DcxLoadTerminal must be used later with the DCX_DWNLD_CLIENT option (whichFiles parameter) in order to initiate the download of the staged files to the affected terminals. |
| DCX_SUBMIT_STAGE_AND_LOAD | The client files should not only be staged but the download of the affected terminals should be initiated as well. The downloads that are initiated using this method are treated the same way as DcxLoadTerminal downloads that are requested using the DCX_RET_WHEN_QUEUED option; the server will retry these if any error occurs that is not an error with the parameters specified in the API call (and the DCConnect server is running). |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR model[] = "Win32"; CHAR listFile[] = "c:\\updates\\dcclient\\win32\\ClientFiles.lst"; rc = DcxSubmitClientFiles (DCX_TARGET_MODEL, model, listFile, DCX_SUBMIT_STAGE_AND_LOAD);
DcxChangeTerminalState (TermName, Acquire, Service, Polled)
DcxChangeTerminalState is used to change the desired service state and/or polling state of a terminal. Changes can be made from in-service to out-of- service or vice versa and polled to not-polled or vice versa. Either one or both of the states can be changed on a single call to DcxChangeTerminalState.
Note: In an RF or TCP/IP network there is no actual polling being performed by DCConnect. Instead, terminals automatically send transactions to DCConnect when they are generated. However, the "polling" state maintained by DCConnect for terminals on these networks is used to tell terminals whether or not they are allowed to send transactions to DCConnect.
The use of this API is governed by whether or not the terminal has been acquired using a previous DcxAcquireTerminal (See DcxAcquireTerminal) API. If the terminal has been acquired, the proper handle must be passed to allow access. Otherwise, the handle should be 0.
If the terminal is idle, the effect of the command will take place when the API is issued. However, if the terminal is not idle (downloading, not responding, ... ) the new desired state will be noted but will only take effect the next time the terminal returns to the idle state. This allows the desired service or polling state to be changed regardless of the current operating state of the terminal.
The state changes made by DcxChangeTerminalState will be saved to the DCConnect configuration file for this terminal. This allows DCConnect to remember the desired states so that if it is shut down and restarted, the terminal will put be in the last requested state.
TermName (PSZ) - input
The name of the terminal whose state is to be changed. This name must be one that has been defined using the DCConnect user interface.
Acquire (HTERM) - input
This is the handle returned by DcxAcquireTerminal (See DcxAcquireTerminal) . This handle needs to be provided only if this application currently has this terminal 'acquired'. If not acquired, 0 must be used for the handle.
Service (UCHAR) - input
Specifies the new service state for the terminal:
| DCX_SERV_NO_CHANGE | No change to service state |
| DCX_SERV_OUT | Out of service |
| DCX_SERV_IN | In service |
Polled (UCHAR) - input
Specifies the new polling state for the terminal:
| DCX_POLL_NO_CHANGE | No change to polling state |
| DCX_POLL_IS_INACTIVE | Not being polled by DCConnect |
| DCX_POLL_IS_ACTIVE | Being polled by DCConnect |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR my_term[] = "TIME_AND_ATTENDANCE"; UCHAR service = DCX_SERV_IN; UCHAR poll = DCX_POLL_IS_ACTIVE; rc = DcxChangeTerminalState (my_term, 0, service, poll);
DcxReportTerminalState (TermName, State)
DcxReportTerminalState is used to retrieve the desired service state, desired polling state and current operational state of the specified terminal. If that terminal is currently being downloaded, the step in the download that the terminal is at is returned.
DcxReportTerminalState is not affected by whether the terminal has been acquired.
TermName (PSZ) - input
The name of the terminal whose state is to be reported. This name must be one that has been defined using the DCConnect user interface.
State (PSTATE) - output
The address of a structure in which to return the state information. See STATE or file DCX.H for the definition of this structure.
The structure contains the following fields:
Reports whether the desired service state of the terminal is In-Service or Out-of-Service. The following values can be returned:
| DCX_SERV_OUT | Out of service |
| DCX_SERV_IN | In service |
This value reflects the actual terminal service state if the Operation value is currently DCX_OPER_IDLE. If the current operation is anything else, the actual terminal service state may be unknown or temporarily set to the opposite state. For example, during a download the terminal is always put out of service even though the desired service state may be DCX_SERV_IN. The desired service state determines what state the terminal will be put in when that download completes.
Reports whether or not the desired polling state of the terminal is being polled. The following values can be returned:
| DCX_POLL_IS_INACTIVE | Not being polled |
| DCX_POLL_IS_ACTIVE | Being polled |
If the Operation is currently DCX_OPER_DOWNLOADING_, DCX_OPER_STOPPED, DCX_OPER_TIME_SYNCH or DCX_OPER_LOAD_FAILED, the terminal will not actually be polled at the moment, even if the desired polling state is DCX_POLL_IS_ACTIVE. However, when the current operation state changes to something else, such as DCX_OPER_IDLE, the desired polling state will determine whether DCConnect should start polling the terminal.
When the terminal operation is DCX_OPER_NOT_RESPONDING or DCX_OPER_BAD_TERMINAL, the terminal will be polled at a much slower rate - approximately once a minute. The purpose of this polling is to periodically check the terminal to see if the terminal has begun responding or has been fixed - without tying up resources with continuous polling. This slow polling is not performed if the desired polling state is inactive.
Reports the current operational state of a terminal. The following values can be returned:
| DCX_OPER_NOT_IN_USE | Not being used |
| DCX_OPER_DOWNLOADING | Downloading files to the terminal |
| DCX_OPER_FLUSHING | Flushing transactions from terminal |
| DCX_OPER_INITIALIZING | Terminal is being configured |
| DCX_OPER_NOT_RESPONDING | Terminal not responding |
| DCX_OPER_BAD_TERMINAL | The attached terminal has a different type than that configured for it; the terminal could not be put in service; or the terminal is generating incorrect responses. |
| DCX_OPER_TIME_SYNCH | Terminal is currently having its clock updated with the current time. |
| DCX_OPER_IDLE | Terminal is operational - the current service state and polled state further specify in what state the terminal is. |
| DCX_OPER_STOPPED | Communications to this terminal have been stopped due to multiple consecutive download failures, transaction logfile filling up, or some other reason. |
| DCX_OPER_LOAD_QUEUED | One or more download requests are currently pending for this terminal. DCConnect attempts to start as many queued loads as possible once a minute. |
| DCX_OPER_LOAD_FAILED | A download attempt has failed for this terminal but the download request was queued so that it can be retried. DCConnect attempts to start as many queued loads as possible once a minute. |
Note: The state DCX_OPER_NOT_IN_USE is only used internally for all terminal addresses which are not being used. This value will never be returned by this API.
This field is only meaningful if the operation state is DCX_OPER_DOWNLOADING. It indicates what step the download process is currently at. The following values can be returned:
| DCX_STEP_SETTING_UP | Download process is initializing |
| DCX_STEP_FLUSHING | Flushing transactions from terminal |
| DCX_STEP_RESET | Resetting terminal |
| DCX_STEP_FIXUP_ETS | Preparing ETS for download |
| DCX_STEP_LOAD_ETS | Downloading ETS |
| DCX_STEP_INIT_FILES | Initializing files |
| DCX_STEP_PROGRAMS | Loading transaction programs |
| DCX_STEP_FASTCLOCK | Loading fast clocking |
| DCX_STEP_VAL_1 | Loading validation file 1 |
| DCX_STEP_VAL_2 | Loading validation file 2 |
| DCX_STEP_VAL_3 | Loading validation file 3 |
| DCX_STEP_VAL_4 | Loading validation file 4 |
| DCX_STEP_VAL_5 | Loading validation file 5 |
| DCX_STEP_VAL_6 | Loading validation file 6 |
| DCX_STEP_MESSAGES | Loading messages file |
| DCX_STEP_KEYCODES | Loading key codes |
| DCX_STEP_PFKEYS | Loading PF keys |
| DCX_STEP_LOAD_CFR | Loading CFR |
| DCX_STEP_GRAPHICS | Loading graphics file |
| DCX_STEP_VAL_MAP | Loading validation mapping file |
| DCX_STEP_FIXUP_CFR | Fixing up CFR |
| DCX_STEP_VAL_EXT | Loading extended validation files |
| DCX_STEP_START_TERM | Starting terminal after the load |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR term_name[] = "LOADING_DOCK";
STATE term_state;
rc = DcxReportTerminalState (term_name, &term_state);
if ((term_state.polled == DCX_POLL_IS_ACTIVE) && (rc == DCX_NO_ERROR))
{
}
DcxReportTerminalInfo (TermName, TermInfo)
DcxReportTerminalInfo is used to retrieve information about the hardware characteristics and current internal state of a terminal. It combines one or more of the following terminal commands into one call:
The result is returned in a single structure pointed to by TERMINFO. The structure is included in the DCX.H file.
TermName (PSZ). - input
The name of the terminal for which to report terminal information. This name must be one that has been defined using the DCConnect user interface.
TermInfo (PTERMINFO) - output
Address of buffer area for terminal information being returned to the caller, normally a pointer to a TERMINFO structure.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR term_name[] = "LOADING_DOCK";
TERMINFO term_info;
rc = DcxReportTerminalInfo (term_name, &term_info);
if ((term_info.display_type == DCX_DISPLAY_2x40) && (rc == DCX_NO_ERROR))
{
}
DcxReportTerminalVersion (TermName, VersionString)
DcxReportTerminalVersion is used to retrieve the version of the DCConnect Client software or firmware version (the latter for 7525, 7526 and 7527 terminals). The value is returned as a string.
TermName (PSZ). - input
The name of the terminal for which to report the terminal version. This name must be one that has been defined using the DCConnect user interface.
VersionString (PSZ) - output
Address of buffer for the version string being returned. Make sure there is VERSION_LEN + 1 bytes allocated for the returned data.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR term_name[] = "LOADING_DOCK";
CHAR version_string[VERSION_LEN + 1]
rc = DcxReportTerminalVersion (term_name, version_string);
printf("Terminal %s is running version %s of the DCConnect Client\n", term_name, version_string);
These are provided for two purposes. The first is to allow applications to submit or delete validation files for use by a DCT or DOS or Windows PC. The validation files can be downloaded to DCTs but not to DOS or Windows PC, or left in the IBM Industrial Computer or PC for validation requests handled by DCConnect.
The following APIs are provided for this purpose:
Secondly, APIs are provided for registering user-written DCConnect applications as 'validators' of DCT or DOS or Windows PC requests. Rather than having data validated against a terminal-resident or IBM Industrial Computer or PC-resident file, the data is given to the registered application so that it may be validated in whatever way is necessary. The application must then inform DCConnect of the result.
The following APIs are provided for this purpose:
DcxOpenValidation (ApplName, ValFiles, Handlep)
An application program uses DcxOpenValidation to notify DCConnect that the application will be processing validation requests for one or more validation files. A list of validation files may be supplied or the application may indicate it wants to handle all validation requests for all files.
The validation file names included in the list correspond to the validation file names that are assigned to Jobs that are downloaded to the terminals. All of these files must end with the .VAL file extension and cannot be longer than 12 characters when including that extension in the length. Do not specify the path in the validation file names.
Note: In order for DCConnect to send validation requests to an application for a particular validation file, that file cannot exist in the terminal or in the DCConnect validation directory. File validation takes precedence over application validation. The API DcxDeleteValidationFile (See DcxDeleteValidationFile) can be used to remove validation files from the DCConnect validation directory.
DcxOpenValidation returns a handle that must be used in any subsequent validation calls (see below).
DCConnect requires the thread that issues the DcxOpenValidation call to remain alive until DcxCloseValidation (See DcxCloseValidation) is called. The thread that issues DcxOpenValidation for a particular application is the only thread that can issue DcxCloseValidation for that application.
When this call is made, DCConnect stores some information about the thread that is issuing the open. If this thread is still alive when a second request to open the same validation application is issued, the second request will be rejected with the return code DCX_INVALID_MODE. However, if the first thread has closed the Validation Application or the first thread ended without closing the application, the second request will be allowed.
ApplName (PSZ) - input Address of the null-terminated name of the application. The length of the name used cannot be greater than DCX_VAL_APPL_LEN.
Each name can be used only once; if two applications call DcxOpenValidation with the same name, the second one will get the return code DCX_INVALID_MODE.
ValFiles (PLISTZ) - input Concatenated list of validation file names whose validation requests will be handled by this application. Each name in the list must be a null-terminated string. An additional null character must be used at the end of the list so that the end can be determined by DCConnect.
The validation file name(s) to be used in this call must be in upper case, must end with the validation file extension .VAL and cannot be longer than 12 characters when including that extension in the length. Do not specify the path in the validation file name. If any name is not valid the return code will be DCX_INVALID_FILE.
Each name should also be defined in one or more Jobs or within the CFR(s) being used by the terminals because validation requests can only be generated for validation file names that are referenced in Jobs or in CFRs.
If the application is to handle validation requests for all file names, this parameter should be set to NULL - rather than a pointer to a list of character strings. In this case all requests that do not go to applications that are handling specific files will go to this application.
Handlep (PHVAL) - output Address of the handle. This handle is used in subsequent calls to:
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HVAL valhandle; CHAR applname[] = "VALIDATOR"; CHAR vallist[] = "BADGES.VAL\x0SECURITY.VAL\x0"; /* This call routes all validation requests for the files */ /* BADGES.VAL and SECURITY.VAL to this application */ rc = DcxOpenValidation(applname, vallist, &valhandle);
DcxReadValidation (Handle, Request, Timeout)
DcxReadValidation is used to read the next validation request from DCConnect for any of the validation files that are being handled by a particular application. If no request is available, DcxReadValidation does one of the following, based on the value of the Timeout parameter:
| Timeout | Is positive wait up to the specified number of 0.1 seconds before returning. If a request is received before the timeout expires, the request is returned right away. |
| DCX_TIMEOUT_FOREVER | block until a validation request is available. This value should be used only if the application making the call is issuing sleep calls, or other blocking calls between calls to DcxReadValidation. |
| DCX_TIMEOUT_NONE | return immediately, with or without a request |
Only validation requests that match the list of files specified in the preceding DcxOpenValidation (See DcxOpenValidation) call will be returned from this call.
The request structure that is returned includes the file name for which validation is requested, the name of the terminal that made the request, the length of the data to be validated, and the data itself.
After a validation request is read, the application should determine if the data is valid and then reply to DCConnect with the result. A reply should be returned to DCConnect as soon as possible using the API DcxReplyValidation (See DcxReplyValidation) .
Note: Another call to DcxReadValidation should not be made until a call to DcxReplyValidation (See DcxReplyValidation) is made for the outstanding request. If two reads are issued in a row without replying to the first one and the first read returned a request, the return code for the second read will be DCX_DID_NOT_REPLY.
Handle (HVAL) - input
Handle from DcxOpenValidation (See DcxOpenValidation) .
Request (PVALIDREQUEST) - output
Address of buffer area for the incoming request. The buffer must be large enough to accommodate the VALIDREQUEST structure. In fact, this parameter should be a pointer to a VALIDREQUEST structure that already has memory allocated for it.
Timeout (LONG) - input
Specifies the amount of time to wait for a request if none is available when the call is issued. A positive timeout value indicates the number of 0.1 seconds to wait. The following two timeout values may also be used:
| DCX_TIMEOUT_FOREVER | Cause the application making this call to block until a request is available. |
| DCX_TIMEOUT_NONE | Returns right away whether or not a request is available. This value should only be used if the application making the call is issuing sleep or other blocking calls between calls to DcxReadValidation. If the application simply loops, calling this API with the DCX_TIMEOUT_NONE parameter may decrease system performance considerably. |
Note: If the application must end while a read is waiting, the thread that issued the DcxOpenValidation call can issue the DcxCloseValidation (See DcxCloseValidation) API using the same handle. This causes the blocked read to end with the return code being set to DCX_NO_DATA.
The longer the timeout value is, the more efficient the validation request flow will be. For one, less CPU time is consumed if fewer calls are made over a given period of time because the overhead associated with each call is incurred less often.
In addition, if the application is waiting when a request is received by DCConnect, the request is 'handed-off' to that application right away.
The drawback to long timeouts is that there is less opportunity for the application to perform other work while waiting for a request. Therefore if a lot of work needs to be done between validation request reads, it might be a good idea to start another thread to handle the DcxReadValidation. A long timeout value should be used by this thread.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HVAL valhandle; VALIDREQUEST request; /* First call DcxOpenValidation (See DcxOpenValidation) () to get the valhandle. Wait */ /* up to 10 seconds for a request. */ rc = DcxReadValidation(valhandle, &request, 100);
DcxReplyValidation (Handle, Result)
DcxReplyValidation is used to notify DCConnect of the result of the validation of the last request received via a DcxReadValidation (See DcxReadValidation) call made by a particular application. The result can be: pass, fail, or unknown. Each call to DcxReadValidation (See DcxReadValidation) that actually returns a validation request must be followed by a call to DcxReplyValidation before any subsequent calls to read another validation request are made.
The value DCX_VALIDATION_PASS corresponds to the term 'present' used in the phrases 'abort if present' or 'skip if present' that are used when defining data validation in a transaction program. Likewise, the value DCX_VALIDATION_FAIL corresponds to the term 'absent' used in the phrases 'abort if absent' or 'skip if absent' that are used when defining data validation in a transaction program.
The following explains what the transaction program will do if the reply is DCX_VALIDATION_PASS for each of the following types of validation:
| Abort if present | Program aborts |
| Abort if absent | Program continues with the next step |
| Skip if present | Program skips one step |
| Skip if absent | Program continues with the next step |
The following explains what the transaction program will do if the reply is DCX_VALIDATION_FAIL for each of the following types of validation:
| Abort if present | Program continues with the next step |
| Abort if absent | Program aborts |
| Skip if present | Program continues with the next step |
| Skip if absent | Program skips one step |
If the reply is DCX_VALIDATION_UNKNOWN, DCConnect will send the validation request to the next application that is waiting for requests with the same filename. If no other application is waiting for the request, DCConnect will send a reply to the terminal causing the validation to fail.
Handle (HVAL) - input Handle from DcxOpenValidation (See DcxOpenValidation) .
Result (UCHAR) - input Result of the validation request. Valid values are:
| DCX_VALIDATION_PASS | Request passed validation |
| DCX_VALIDATION_FAIL | Request failed validation |
| DCX_VALIDATION_UNKNOWN | Validation request should be passed to the next waiting application |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HVAL valhandle; UCHAR result; /* The handle was obtained from a previous DcxOpenValidation (See DcxOpenValidation) () call */ /* and DcxReadValidation (See DcxReadValidation) was called to read the request */ /* Some routine was called to validate the request and set 'result' */ /* to reflect whether the validation passed or failed */ rc = DcxReplyValidation(valhandle, result);
DcxCloseValidation (Handle)
DcxCloseValidation is used to close a validation handle. The application involved no longer accepts read validation requests and responds to them using this this handle, and any resources associated with the handle is freed.
DcxCloseValidation must be issued from the thread that issued DcxOpenValidation (See DcxOpenValidation) . If another thread is waiting on a call to DcxReadValidation (See DcxReadValidation) that thread unblocks and returns. If a read unblocks as a result of the close call, the return code for the read call is DCX_NO_DATA.
Handle (HVAL) - input Handle from DcxOpenValidation (See DcxOpenValidation) .
Return code descriptions can be found in ReturnReturn Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HVAL valhandle; /* The handle was obtained from a previous DcxOpenValidation (See DcxOpenValidation) () call */ rc = DcxCloseValidation(valhandle);
DcxDeleteValidationFile (ValFile)
The specified validation file is deleted both from the validation directory: <DCCONN>\val and, if DCConnect is running, from its internal tables.
Any validation file that has been submitted to DCConnect can be deleted. Note that any file that was in DCConnect's validation directory when DCConnect was started is also considered to be submitted to DCConnect and thus can be deleted using this API.
DcxDeleteValidationFile does not delete the validation file from the terminal. If a validation file must be deleted from a terminal, the Job that the terminal is using should be changed so that it no longer specifies that this validation file is terminal-resident and then the terminal should be re-downloaded with the entire job.
If the file does not exist in the DCConnect internal tables and it does not exist in the validation directory, the return code will be DCX_DOES_NOT_EXIST.
If the file could not be removed from the disk, it will still be removed from the internal tables but the return code will be DCX_DELETE_FAILED.
If the specified file is currently in the process of being loaded by a previous DcxSubmitValidationFile (See DcxSubmitValidationFile) , the return code will be DCX_FILE_LOADING.
If file validation is taking place on the IBM industrial computer or PC when this API is received, the validation is cancelled and a fail reply is given to the terminal.
ValFile (PSZ) - input The null-terminated name of the validation file to be deleted.
The validation file name to be used in this API should be the same as the name used when the file was submitted. The file name must be in upper case, must end with the validation file extension .VAL, and cannot be longer than 12 characters when including that extension in the length. Do not specify the path in the validation file name. If the name is not valid the return code will be DCX_INVALID_FILE.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR valfilename[] = "BADGES.VAL"; rc = DcxDeleteValidationFile(valfilename);
DcxSubmitValidationFile (SourceFile, ValFile, Load)
DcxSubmitValidationFile is used to submit a single validation file to DCConnect. DCConnect converts the file to its own format, storing the resulting file in the <DCCONN>\val directory. A new file entry is added to DCConnect's internal tables if it is running and if the file has not been previously submitted. Any terminals using this file is reloaded if the Load parameter so specifies.
The source file that is to be submitted must conform to a set of rules for text or binary files. If the source file is not of the proper format, the return code will be DCX_INVALID_FILE_FORMAT. For additional information on "Using Validation Objects", refer to the online document, DCConnect User's Guide.
Submitted validation files are stored on hard disk and therefore remain intact even when DCConnect is shut down or power is lost. When DCConnect starts up it looks for all validation files in its validation directory. These are all added to its internal tables and are considered to be submitted. Therefore, there is no need to re-submit all the validation files just because DCConnect has been restarted.
Each terminal defined in DCConnect will have a Job assigned to it. This Job contains references to validation files (plus other necessary files) used by that terminal - either directly or in the optional CFR that is part of the Job. References to the validation files submitted by this call should, therefore, already exist in the Jobs of those terminals expected to use these files.
SourceFile (PSZ) - input The fully qualified filename (including path name and extension) of the file that is being submitted.
Note: Do not copy a validation file with the .VAL extension directly into the <DCCONN>\val directory. Modifications must be made to files with this extension by DCConnect prior to their being displayed in this directory.
ValFile (PSZ) - input The ASCII name of the validation file to be submitted.
The validation file name to be used in this call must be in upper case, must end with the validation file extension .VAL and cannot be longer than 12 characters when including that extension in the length. Do not specify the path in the validation file name. If the name is not valid the return code will be DCX_INVALID_FILE.
Load (UCHAR) - input
Indicates whether the file should be downloaded to all terminals whose Job specified this file is terminal-resident:
| DCX_LOAD_NO | Do not download the file to any terminal |
| DCX_LOAD_YES | Download the file to all appropriate terminals |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR sourcefilename[]= "c:\\validate\\badges.lst"; CHAR dcxfilename[] = "BADGES.VAL"; rc = DcxSubmitValidationFile(sourcefilename, dcxfilename, DCX_LOAD_YES);
Application programs can read the messages that are sent to the DCConnect system message log as these messages occur. This may be useful for remote machines that need to find out about messages that have occurred on the DCConnect system unit.
Up to five different applications can be reading the system messages at a time. DCConnect buffers up to 10 messages for all applications so that applications do not miss any messages if a few of them occur at the same time.
Applications can write messages to the message log or clear it of all messages.
DcxOpenMsgLog (Handlep)
DcxOpenMsgLog is used by applications that wish to receive messages as they are generated by DCConnect. A handle is returned for use in subsequent calls to DcxReadMsgLog (See DcxReadMsgLog) and DcxCloseMsgLog (See DcxCloseMsgLog) . Only those messages that go to the DCConnect system error message log while a particular handle is open can be obtained with the DcxReadMsgLog call. You cannot open the system error message log and read messages that occurred in the past.
DCConnect allows up to 5 applications to open the system error message log for the purpose of reading messages to be logged. If 5 applications already have opened the system error message log and this call is issued by another application, the return code will be DCX_NO_MORE_ROOM.
Handlep (PHMSGLOG) - output
Address of the handle. The handle must be used during future calls to:
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HMSGLOG msglog_handle; rc = DcxOpenMsgLog(&msglog_handle);
DcxReadMsgLog (Handle, BuffLenp, MsgLenp, Buffer, Timeout)
The next message posted to the DCConnect message log is returned. If no message is available, DcxReadMsgLog does one of the following, based on the value of the Timeout parameter:
| Timeout Is positive | Wait for the specified number of 0.1 seconds before returning. If a message is received before the timeout expires, the message is returned right away. |
| DCX_TIMEOUT_FOREVER | Block until a message is available |
| DCX_TIMEOUT_NONE | Return immediately, with or without a message |
If no message is available within the time specified, the return code will be DCX_NO_DATA. If a message is returned, the return code will be DCX_NO_ERROR.
The application can first call DcxReadMsgLog with * BuffLenp set equal to zero in order to find out how much storage is required for the data buffer for the next message. Having allocated the storage, the application then calls the function a second time in order to have the buffer filled with data.
Note: When calling with the buffer length parameter set to 0, the return codes will still be DCX_NO_ERROR or DCX_NO_DATA even though no message is actually returned in this case.
At this time all messages will be 162 bytes in length. That includes two lines of data, each 79 bytes in length plus the ending carriage return/line feed sequence. The second line may actually contain only blanks for the data if the message text fits on the first line.
DCConnect will buffer up to 10 messages for all applications so that if a few messages occur at the same time applications will not miss any of them - provided each application issues its reads in a timely manner.
Handle (HMSGLOG) - input
Handle from DcxOpenMsgLog (See DcxOpenMsgLog)
BuffLenp (USHORT *) - input/output
Length of the buffer to store the message in. If this is set to 0, DCConnect will return the length of the message in this variable.
If the length specified is shorter than the actual message length, DCConnect truncates the returned message to fit in that size buffer. In this case the return code will be DCX_DATA_TRUNCATED.
This variable is set only if the return code is DCX_NO_ERROR or DCX_DATA_TRUNCATED.
MsgLenp (USHORT *) - output
Actual length of the message returned.
This variable is set only if the return code is DCX_NO_ERROR or DCX_DATA_TRUNCATED.
Buffer (PCHAR) - output
The address of the buffer into which the message is to be returned. The buffer will contain a message only in the case that the return code is DCX_NO_ERROR or DCX_DATA_TRUNCATED and the buffer length passed in was not 0.
Note: The message returned is not null-terminated.
Timeout (LONG) - input
Specifies the amount of time to wait for a message if none is available when the call is issued. A positive timeout value indicates the number of 0.1 seconds to wait. The following two timeout values may also be used:
| DCX_TIMEOUT_FOREVER | Causes the application making this call to block until a message is available. |
| DCX_TIMEOUT_NONE | Returns right away whether or not a message is available. This value should only be used if the application making the call is issuing sleep or other blocking calls between calls to DcxReadMsgLog. If the application simply loops, calling this API with the DCX_TIMEOUT_NONE parameter, may decrease system performance considerably. |
Note: If the application must end while a read is waiting, the thread that issued DcxOpenMsgLog can issue the DcxCloseMsgLog (See DcxCloseMsgLog) API using the same handle. This causes the blocked read to end with the return code being set to DCX_NO_DATA.
The longer the timeout value is, the more efficient the message flow will be. For one, less CPU time is consumed if fewer calls are made over a given period of time because the overhead associated with each call is incurred less often.
The drawback to long timeouts is that there is less opportunity for the application to perform other work while waiting for messages. Therefore if a lot of work needs to be done between message reads, it might be a good idea to start another thread to handle the DcxReadMsgLog. A long timeout value should be used by this thread.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
HMSGLOG msglog_handle;
PCHAR message;
USHORT buffer_length;
USHORT message_length;
/* First make call to find out storage required */
buffer_length = 0;
rc = DcxReadMsgLog(msglog_handle, &buffer_length, &message_length,
message, DCX_TIMEOUT_NONE);
/* If a message is available, allocate a buffer for it - the size */
/* was returned in 'buffer_length'. Then call the function again to */
/* get the actual message */
if (rc == DCX_NO_ERROR)
{
message = (PCHAR)malloc(buffer_length);
if (message != NULL)
rc = DcxReadMsgLog(msglog_handle, &buffer_length,
&message_length, message, DCX_TIMEOUT_NONE);
}
DcxCloseMsgLog (Handle)
DcxCloseMsgLog notifies DCConnect that the application no longer wants to receive messages.
DcxCloseMsgLog must be issued from the thread that issued the DcxOpenMsgLog (See DcxOpenMsgLog) call. This allows the close API to unblock a thread that is waiting on a call to DcxReadMsgLog (See DcxReadMsgLog) . If a read unblocks as a result of the close call, the return code for the read call is DCX_NO_DATA.
Handle (HMSGLOG) - input
Handle from DcxOpenMsgLog (See DcxOpenMsgLog) .
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; HMSGLOG msglog_handle; /* The handle was obtained from a previous DcxOpenMsgLog (See DcxOpenMsgLog) () call */ rc = DcxCloseMsgLog(msglog_handle);
DcxWriteMsgLog (Message)
DcxWriteMsgLog allows an application to write a message to the DCConnect system error message log. The message text should be null-terminated and should fit on two 79-character lines - taking into account the date-time stamp that DCConnect will append to the front of the message.
DCConnect takes care of splitting the message into two lines and adding the carriage return or line feed to the end of each line as well. If the message passed in does not fit in the two lines, it will be truncated.
Message (PSZ) - input
Pointer to null-terminated message to be logged.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
rc = DcxWriteMsgLog("Time-and-attendance application has started.");
DcxClearMsgLog(void)
DcxClearMsgLog is used to remove all messages from the DCConnect system error message log. DcxClearMsgLog can be made whether or not any applications are currently reading messages that are to be logged.
None.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; rc = DcxClearMsgLog();
An additional set of application APIs are required to support the Terminal Services for DOS and for Windows DwsRequestData API. User programs running on a DCConnect node would use the following set of APIs to respond to the DOS or Windows user program data requests.
The following data request API is available to allow a user-written DCConnect application to make data requests just like DOS or Windows PC can:
DcxOpenRequestHandler(Application Name, Handlep)
DcxOpenRequestHandler is used by a user-written application to notify DCConnect that the application wants to handle requests for data. The data request can be received from DOS or Windows-based user-written programs acting as DCTs, or programs running on the DCConnect node. DCConnect returns a handle that is to be used by the application for any subsequent data request calls.
This is the name of the application to begin receiving data requests from and sending response data back to the originator of the request. The originator may be a DOS or Windows program calling DwsRequestData or a user-written DCConnect program using the API DcxRequestData. The application making this call receives only data requests that specify the same application name used in this call.
The application name parameter is a null-terminated string with a length from one character to DCX_APPL_NAME_LEN.
Handlep (PHREQ) - output
Address of the handle.
The handle is used by this application in subsequent calls to:
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
#define APPLICATION "DOS/Windows_Responder"
HREQ handle; /* Data request handle */
SHORT rc; /* Return code from API call*/
/*
* Register for data requests
*/
rc = DcxOpenRequestHandler(APPLICATION, &handle);
if (rc != DCX_NO_ERROR)
printf(" Error opening request handler. The return code is %d\n", rc);
This API is used to read the next available request for data. A request for data can be received from a DOS or Windows program that has called the DwsRequestData API or a DCConnect based program that has called the DcxRequestData (See DcxRequestData) API. All programs that are to make a request for data from the application issuing the read, must specify the name of this application in the request call. Before this application can receive any data requests it must have previously registered with DCConnect by calling the DcxOpenRequestHandler (See DcxOpenRequestHandler) API. If no request is available, the call does one of the following based on the Timeout parameter:
Positive Timeout value | Wait up to a specified number of 0.1 seconds before returning. However, if a request is received before the timeout expires the request is returned immediately. |
DCX_TIMEOUT_FOREVER | Causes the application making this call to block until a data request is available. |
DCX_TIMEOUT_NONE | Returns immediately, whether or not a request for data is available. This value should only be used if the application making the call is issuing sleep calls or other blocking calls between calls to DcxReadDataRequest. |
If the application simply loops, calling this API with the DCX_TIMEOUT_NONE parameter, system performance may be considerably degraded.
The application can first call DcxReadDataRequest with the Data Request Length variable set to zero in order to find out how much storage is required for the data request buffer. When the call returns, the Data Request Length variable contains the length of the data request. The application can then allocate storage and call the function a second time in order to have the Request Buffer filled with data.
Note: If a data request is received, another call to DcxReadDataRequest should not be made until a call to DcxReplyDataRequest (See DcxReplyDataRequest) is made for the outstanding request. If two reads are issued in a row without replying to the first one, the return code for the second read is DCX_DID_NOT_REPLY.
Handle received from the DcxOpenRequestHandler (See DcxOpenRequestHandler) call.
Sending Program Name (PSZ) - output
The name of the program sending this request. If the request comes from a DOS or Windows node this is the terminal name. If the request is from a user-written DCConnect program this is the program name specified in the call to DcxRequestData. The sending program name parameter is a null-terminated string from one character in length to DCX_APPL_NAME_LEN.
Data Request Length (PUSHORT) - input or output
The length of the buffer to store the data request received from the requesting program. If set to zero, DCConnect returns the correct length of the data request. After receiving the data, this variable contains the actual length of the data request received. This variable is set only if the return code is DCX_NO_ERROR or DCX_DATA_TRUNCATED. The maximum amount of data supported is 16KB.
Request Buffer (PCHAR) - output
The address of the buffer into which the data received from the requesting application is to be returned. The buffer contains data only in the case that the return code is DCX_NO_ERROR or DCX_DATA_TRUNCATED and the data request length value passed in was not zero.
Timeout (LONG) - input
Specifies the amount of time to wait for the data request. A positive time-out value indicates the number of 0.1 seconds to wait. If the application wishes to wait for a definite response from DCConnect it should specify
| DCX_TIMEOUT_FOREVER | This causes the application making this call to block until a data request is received from DCConnect. |
| DCX_TIMEOUT_NONE | This causes an immediate return, with or without a data request. |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
CHAR originator[DCX_APPL_NAME_LEN+1]; /* Contains the caller name */
HREQ handle; /* Data request handle */
USHORT reqdatalen; /* Length of the request data */
PCHAR preqbuffer; /* request buffer pointer */
SHORT rc; /* Return code from API call */
/*
* Call DcxReadDataRequest twice. The first time to request the length of the request data. The
* second time to receive the data. .
*/
reqdatalen = 0; /* Set to zero to request the length of the request data. */
/* First call to ask for the request data length */
rc = DcxReadDataRequest( handle, originator, &reqdatalen, NULL, DCX_TIMEOUT_FOREVER);
if (rc == DCX_NO_ERROR) /* No error continue */
{
/* Allocate a buffer to receive the request data. */
preqbuffer = (PCHAR)malloc(reqdatalen+1);
if (preqbuffer) /* If pointer is NULL, the allocation failed. */
{
/* Second call asking for the data. */
rc = DcxReadDataRequest( handle, originator, &reqdatalen, preqbuffer, DCX_TIMEOUT_FOREVER);
DCX_TIMEOUT_FOREVER);
if (rc == DCX_NO_ERROR) /* No error continue */
{
preqbuffer+reqdatalen = '\0'; /* Convert buffer to a string */
/* print the received the data */
printf(" The request data received from %s is %s\n", originator ,preqbuffer);
}
else /* The second request failed. */
printf(" The data request failed. The return code is %d\n", rc);
}
else /* Memory allocation failed. */
printf( "The memory allocation failed\n");
}
else /* The response data length request failed. */
printf(" The request for the response data length failed. The return code is %d\n", rc);
DcxReplyDataRequest is used by the DCConnect application program to reply to the originator of a request for data. A successful DcxReadDataRequest call must have been previously issued by this application.
Once an application has successfully replied to a data request it cannot issue another reply for that same request nor can it issue a forward call for that request.
Handle received from the DcxOpenRequestHandler (See DcxOpenRequestHandler) API call.
Reply Length (USHORT) - input
The length of the data in the reply buffer. The maximum buffer length is 16KB.
Reply Data (PCHAR ) - input
The address of a buffer containing the reply data to be sent back to the originator of the request.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
#define REPLY_DATA "123456789"
#define REPLY_DATA_LEN (sizeof(REPLY_DATA)-1)
HREQ handle; /* Data request handle */
SHORT rc; /* Return code from API call */
/*
* Reply with the response data that the originator requested.
*/
rc = DcxReplyDataRequest( handle, REPLY_DATA_LEN, REPLY_DATA);
if (rc != DCX_NO_ERROR)
printf("Error replying to the request for data. The return code is %d\n", rc);
DcxForwardDataRequest is used by the DCConnect application program to forward to another application a data request that was just read using DcxReadDataRequest. The target application must be one that has successfully registered with DCConnect using the API DcxOpenRequestHandler.
Once an application has successfully forwarded a data request it cannot forward the request to another application nor can it reply to that request.
Handle received from the DcxOpenRequestHandler (See DcxOpenRequestHandler) API call.
Application Name (PSZ) - input
The name of the target application that should handle the request. An application with this name must have already registered with DCConnect using the API DcxOpenRequestHandler.
The target application is even allowed to be the name of the application that is doing the forwarding. In this case, the request is added to the current end of that application's queue.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
#define TARGET_APPLICATION "SHIPPING"
HREQ handle; /* Data request handle */
SHORT rc; /* Return code from API call */
/*
* Forward the data request to the Shipping application
*/
rc = DcxForwardDataRequest( handle, TARGET_APPLICATION );
if (rc != DCX_NO_ERROR)
printf("Error forwarding the request to the SHIPPING application. The return code is %d\n", rc);
This API sends a request for data to a receiving application. DCConnect routes the request to the receiving application named in the DcxRequestData API call. For the request to be successful, a user-written application that responds to the data request must have previously issued a DcxOpenRequestHandler (See DcxOpenRequestHandler) API to register with DCConnect using the specified receiving application name.
A reference name for the program making this request. The Sending Program name parameter is a null-terminated string from one character to DCX_APPL_NAME_LEN. This name holds no significance for DCConnect. It is passed on to the request handler as part of the information returned for the handler's call to DcxReadDataRequest.
Receiving Application Name (PSZ) - input
This a user-written application that has registered with DCConnect to handle data requests. The application name parameter is a null-terminated string from one character to DCX_APPL_NAME_LEN.
Request Data Length (USHORT) - input
The length of the request data buffer. The maximum value for the request data length is 16KB.
Request Data Buffer (PCHAR) - input
The request data buffer contains data to be given to the receiving application. This information is used by the receiving application to determine what data this sending program requires.
Reply Data Length (PUSHORT) - input or output
A pointer to a variable with the maximum length of the reply data buffer. If it is set to 0, DCConnect returns the length of the reply data in this variable. If the length specified is shorter than the actual data received, DCConnect truncates the data to fit in that size buffer. In this case the return code is DCX_DATA_TRUNCATED.
The maximum value for the reply data length is 16 KB.
Reply Data Buffer (PCHAR) - output
The address of the buffer to be used to store the data received in reply to the request.
Timeout (LONG) - input
Specifies the amount of time to wait for the reply data from the receiving application. A positive time-out value indicates the number of 0.1 seconds to wait. If the program wishes to wait for a definite response from the receiving application, it should specify:
| DCX_TIMEOUT_FOREVER | This causes the program making this call to block until a reply is received. |
| DCX_TIMEOUT_NONE | This causes an immediate return with or without a reply. |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
#define REQ_DATA "123456"
#define RECEIVER "ACCOUNTS"
#define SENDER "OFFICE"
PCHAR pbuffer; /* Reply data buffer pointer */
SHORT rc; /* Return code from API call */
USHORT reqlen; /* Request buffer length */
USHORT size; /* Reply data length */
/*
* Call DcxRequestData twice. The first time to request the length of the response data.*/
* The second time to receive the data. */
*/
size = 0; /* Set to zero to request the length of the reply data. */
reqlen = strlen(REQ_DATA); /* Request data length */
/* First call to ask for the reply data length */
rc = DcxRequestData(SENDER, RECEIVER, reqlen, REQ_DATA, &size, NULL, DCX_TIMEOUT_FOREVER);
if (rc == DCX_NO_ERROR) /* No error continue */
{
/* Allocate a buffer to receive the response data. */
pbuffer = (PCHAR)malloc(size+1);
if (pbuffer) /* If pointer is NULL, the allocation failed. */
{
/* Second call asking for the data. */
rc = DcxRequestData(SENDER, PROGRAM, reqlen, REQ_DATA, &size, pbuffer, DCX_TIMEOUT_FOREVER);
if (rc == DCX_NO_ERROR) /* No error continue */
{
pbuffer+size = '\0'; /* Convert buffer to a string */
/* print the received the data */
printf(" The reply data received is %s\n", pbuffer);
}
else /* The second request failed. */
printf(" The data request failed. The return code is %d\n", rc);
}
else /* Memory allocation failed. */
printf( "The memory allocation failed\n");
}
else /* The request for the length of the reply failed */
printf(" The request for the reply data length failed. The return code is %d\n", rc);
This API is used to stop receiving any requests for data from DOS or Windows terminal programs or DCConnect based programs. The application can no longer receive or reply to data requests. All resources associated with the handle are freed.
Handle received from the DcxOpenRequestHandler (See DcxOpenRequestHandler) call.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
HREQ handle; /* Request handle */
SHORT rc; /* Return code from API call*/
/*
* Stop receiving data requests
*/
rc = DcxCloseRequestHandler(handle);
if (rc != DCX_NO_ERROR)
printf("Error closing handle. The return code is %d\n", rc);
These APIs allow applications to get general information from DCConnect about such things as the list of mailboxes, applications and jobs that are configured. Included are calls to shutdown DCConnect, to set the date or time on the system unit and in the terminals, and to find out whether DCConnect is running or not.
DcxIsAlive (void)
DcxIsAlive provides a way to determine if DCConnect is running without having to be concerned about actions that may be taken by DCConnect as a result of the API call. The return code will be one of the following if no error occurs:
DCX_NO_ERROR is returned when DCConnect is running.
While all other APIs return these codes as well, the other APIs perform some other function.
None.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
if ((rc = DcxIsAlive()) == DCX_NO_ERROR)
{
}
DcxQueryApplList (ListLenp, ApplList, ListCntp)
DcxQueryApplList provides the application program with the list of applications that are currently configured for DCConnect.
DcxQueryApplList can first be called with * ListLenp set to zero in order to find out how much storage is required for the data buffer. When storage has been allocated, the API can be called a second time in order to have the buffer filled with data.
ListLenp (USHORT *) - input/output
Reports the total number of bytes in the application list. If, when the API is made, this is set to 0, DCConnect will return the actual size of the list in this field.
ApplList (PLISTZ) - output
Pointer to a buffer in which to put the list of application names. Each name in the list is null-terminated and the list ends with an additional null character. If the list is empty it will contain a single null character.
ListCntp (USHORT *) - output
Number of entries in the application list. This value is returned both when the application list itself is returned and when just the length of that list is returned.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
USHORT list_length;
PLISTZ appl_list;
USHORT list_count;
/* First make call to find out storage required */
list_length = 0;
rc = DcxQueryApplList(&list_length, appl_list, &list_count);
/* Allocate space for list - this value was returned in 'list_length'*/
/* then call function again to get the list of applications */
if (rc == DCX_NO_ERROR)
{
appl_list = (PLISTZ)malloc(list_length);
if (appl_list != NULL)
rc = DcxQueryApplList(&list_length, appl_list, &list_count);
}
DcxQueryJobInfo (JobName, JobInfop)
The files associated with the indicated job are returned by DcxQueryJobInfo. The file names returned are the physical Job file name plus the name of the CFR file, Graphics file and any Validation files that are to be downloaded to terminals using this job. This list of validation files can vary in length.
The application can first call DcxQueryJobInfo with the valdlen field of the QUERY_JOB structure set to zero in order to find out how much storage is required for the data buffer that will hold the list of validation files. Having allocated the storage for the buffer, the application then calls the function a second time in order to have the buffer filled with data.
JobName (PSZ) - input
Null-terminated name of one of the Jobs defined in DCConnect. In DCConnect the job name corresponds directly to what was called a cluster in 16-bit DCC/2.
JobInfo (PQUERY_JOB) - output
The address of a structure in which to return the Job information. See QUERY_JOB or file DCX.H for the definition of this structure.
The structure contains the following fields:
Pointer to a buffer in which to return the list of the validation files associated with this job that should be downloaded to terminals using this job. Each name in the list is null-terminated and the list ends with an additional null character. If the list is empty it will contain a single null character.
Reports the total number of bytes in the validation file list. If, when the call is made, this field is set to 0, DCConnect will return the actual size of the list in this field.
Reports the total number of files in the validation file list. This value is returned both when the validation list itself is returned and when just the length of that list is returned.
The 8.3 name of the job file located in the <DCCONN>\job directory. This field is padded with null characters so that the name can be treated as a string.
Each job has both the up-to-32 character name that is seen in the terminal settings Notebook and the name of the physical job file.
The job file name is not returned if the API call was only made to find out the length of the validation list (valdlen is 0).
The 8.3 name of the Graphics file associated with the specified job. Graphics files are stored in the <DCCONN>\graph subdirectory.
This field is padded with null characters so that the name can be treated as a string. If no Graphics file is associated with the job, this field will be filled with null characters.
The Graphics file name is not returned if the API call was made only to find out the length of the validation list (valdlen is 0).
The 8.3 name of the CFR executable file associated with the specified job. CFR executable files are stored in the <DCCONN>\cfr subdirectory.
This field is padded with null characters so that the name can be treated as a string. If no CFR file is associated with the job, this field will be filled with null characters.
The CFR file name is not returned if the API call was only made to find out the length of the validation list (valdlen is 0).
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
QUERY_JOB jobinfo;
CHAR jobname[] = "TIME_AND_ATTENDANCE";
/* First make call to find out storage required for the validation */
/* file list */
jobinfo.valdlen = 0;
rc = DcxQueryJobInfo(jobname, &jobinfo);
/* Allocate space for the list and then call function again to get */
/* the actual job information */
if (rc == DCX_NO_ERROR)
{
jobinfo.valdlist = (PLISTZ)malloc(jobinfo.valdlen);
if (jobinfo.valdlist != NULL)
rc = DcxQueryJobInfo(jobname, &jobinfo);
}
DcxQueryJobList (ListLenp, JobList, ListCntp)
DcxQueryJobList provides the application program with the list of jobs that are currently defined for DCConnect.
The application can first call DcxQueryJobList with * ListLenp set to zero in order to find out how much storage is required for the data buffer. Having allocated the storage, the application then calls the function a second time in order to have the buffer filled with data.
ListLenp (USHORT *) - input/output
Reports the total number of bytes in the job list. If, when the call is made, this is set to 0, DCConnect will return the actual size of the list in this field.
JobList (PLISTZ) - output
Pointer to a buffer in which to put the list of job names. Each name in the list is null-terminated and the list ends with an additional null character. If the list is empty it will contain a single null character.
ListCntp (USHORT *) - output
Number of entries in the job list. This value is returned both when the job list itself is returned and when just the length of that list is returned.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
USHORT list_length;
PLISTZ job_list;
USHORT list_count;
/* First make call to find out storage required */
list_length = 0;
rc = DcxQueryJobList(&list_length, job_list, &list_count);
/* Allocate space for list - this value was returned in 'list_length'*/
/* then call function again to get the list of jobs */
if (rc == DCX_NO_ERROR)
{
job_list = (PLISTZ)malloc(list_length);
if (job_list != NULL)
rc = DcxQueryJobList(&list_length, job_list, &list_count);
}
DcxQueryJobTerms (JobName, ListLenp, TermList, ListCntp)
DcxQueryJobTerms provides the application program with the list of terminals to which the job is currently assigned.
The application can first call DcxQueryJobTerms with * ListLenp set to zero in order to find out how much storage is required for the data buffer. Having allocated the storage, the application then calls the function a second time in order to have the buffer filled with data.
JobName (PSZ) - input
Null-terminated name of one of the Job names defined in DCConnect. In DCConnect the job name corresponds directly to what was called a cluster in 16-bit DCC/2.
ListLenp (USHORT *) - input/output
Reports the total number of bytes in the terminal list. If, when the call is made, this is set to 0, DCConnect will return the actual size of the list in this field.
TermList (PLISTZ) - output
Pointer to a buffer in which to put the list of terminal names associated with the job. Each name in the list is null-terminated and the list ends with an additional null character. If the list is empty it will contain a single null character.
ListCntp (USHORT *) - output
Number of entries in the terminal list. This value is returned both when the terminal list itself is returned and when just the length of that list is returned.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR jobname[] = "TIME_AND_ATTENDANCE";
USHORT list_length;
PLISTZ term_list;
USHORT list_count;
/* First make call to find out storage required */
list_length = 0;
rc = DcxQueryJobTerms(jobname, &list_length, term_list, &list_count);
/* Allocate space for list - this value was returned in 'list_length'*/
/* then call function again to get the list of terminals */
if (rc == DCX_NO_ERROR)
{
term_list = (PLISTZ)malloc(list_length);
if (term_list != NULL)
rc = DcxQueryJobTerms(jobname, &list_length, term_list, &list_count);
}
DcxQueryMsgLog (MsgLogInfo)
DcxQueryMsgLog allows an application to find out the name of the system message log and how many messages it can hold at a time.
The structure returned contains the following information about the System Message Log:
MsgLogInfo (PQUERY_MSGLOG) - output
The address of a structure in which to return the System Message Log information. See QUERY_MSGLOG or file DCX.H for the definition of this structure.
The structure contains the following fields:
Reports the file name of the system message log. This file is located in the <DCCONN>\data directory.
Reports the maximum number of messages that the system message log can hold at one time.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; QUERY_MSGLOG msgloginfo; rc = DcxQueryMsgLog(&msgloginfo);
DcxQueryTermAddress (TermName, Location, Line, Addressp)
DcxQueryTermAddress returns the Line Location, Line Number, and Address for the specified terminal name.
TermName (PSZ) - input
Name of the terminal for which to get the address parameters. The name must be one that is defined in the DCConnect configuration.
Location (CHAR [DCX_TRF_LOCLEN]) - output
Pointer to buffer in which to store the line location parameter for the specified terminal. The value returned either indicates an ARTIC card ("00"-"03"), a native serial port (" "), an RF serial port("RF"), a TCP/IP adapter ("IP")", or an attached DOS or Windows PC ("DW").
Line (CHAR [DCX_TRF_LINELEN]) - output
Pointer to buffer in which to store the line number parameter for the specified terminal. The value returned is "00" through "07" for ARTIC card lines and "01" through "04" for native serial port lines.
For 7524 RF-attached terminals, the line and address parameters are combined to form a value from "000" to "126". The line value holds the first two characters ("00"-"12") and the address value holds the last character '0'-'9'.
For TCP/IP and DOS/Windows terminals, the value will be in the range "00" through "99".
Note: This value can be different based on changes to your terminal configuration from one execution of DCConnect to the next for TCP/IP and DOS/Windows terminals. Because the terminal's real address, the IP address and port number, cannot possibly be represented in the 3 bytes available for the line number and address fields combined, an index value is used. That index value is based on the order that the terminal appears in the DCX2.INI file and can be in the range from "000" to "999". The hundreds and tens digit go into the the line number field and the ones digit goes into the address field.
Addressp (CHAR *) - output
Pointer to place to store the address character for the specified terminal. This value is in the range 'A'-'P' for 7525 terminals and in the range 'A'-'Y' or '0'-'6' for 7524 batch terminal, 7526, 7527.
For 7524 RF-attached DCTs, the value is "0" through "9". The line and address parameters are combined to form a value from "000" to "126". The line value holds the first two characters ("00"-"12") and the address value holds the last character '0'-'9'.
For TCP/IP and DOS/Windows terminal, this value will also be in the range '0' to '9'.
Note: See the note for the previous field for information about why the values in this field might change from one execution of DCConnect to the next.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR loc[DCX_TRF_LOCLEN] CHAR line[DCX_TRF_LINELEN] CHAR address; UCHAR name[DCX_TERM_NAME_LEN + 1] /* The terminal name is assumed to have been */ /* previously obtained and null-terminated */ rc = DcxQueryTermAddress(name, loc, line, &address);
DcxQueryTermList (ListLenp, TermList, ListCntp)
DcxQueryTermList provides the application program with the list of terminals that are currently defined for DCConnect. The list is not restricted to a particular job as is the case for the API DcxQueryJobTerms.
The application can first call DcxQueryTermList with * ListLenp set to zero in order to find out how much storage is required for the data buffer. Having allocated the storage, the application then calls the function a second time in order to have the buffer filled with data.
ListLenp (USHORT *) - input/output
Reports the total number of bytes in the terminal list. If, when the call is made, this is set to 0, DCConnect will return the actual size of the list in this field.
TermList (PLISTZ) - output
Pointer to a buffer in which to put the list of terminal names. Each name in the list is null-terminated and the list ends with an additional null character. If the list is empty it will contain a single null character.
ListCntp (USHORT *) - output
Number of entries in the terminal list. This value is returned both when the terminal list itself is returned and when just the length of that list is returned.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
USHORT list_length;
PLISTZ term_list;
USHORT list_count;
/* First make call to find out storage required */
list_length = 0;
rc = DcxQueryTermList(&list_length, term_list, &list_count);
/* Allocate space for list - this value was returned in 'list_length'*/
/* then call function again to get the list of terminals */
if (rc == DCX_NO_ERROR)
{
term_list = (PLISTZ)malloc(list_length);
if (term_list != NULL)
rc = DcxQueryTermList(&list_length, term_list, &list_count);
}
DcxQueryTermName (Location, Line, Address, TermName)
DcxQueryTermName provides a terminal's name to the caller from the specified Line Location, Line Number, and Address.
If any of the three address parameters are not in their valid range the return code will be one of DCX_INVALID_COMM_LINE, DCX_INVALID_COMM_LOC or DCX_INVALID_TERM_ADDR. If the parameters are valid but are not currently being used as a group for a particular terminal, the return code will be DCX_INVALID_PARAMETER.
Locationp (CHAR [DCX_TRF_LOCLEN]) - input
Pointer to a buffer containing the line location parameter. The value in this buffer must be two blanks to indicate a native serial port, in the range "00" through "03" to indicate one of the ARTIC cards, "IP" for a TCP/IP adapter, "RF" for an RF serial port or "DW" for a DOS/Windows terminal.
Linep (CHAR [DCX_TRF_LINELEN]) - input
Pointer to a buffer containing the line number parameter. The value in this buffer must be in the range "01" through "04" for native serial ports or must be in the range "00" through "07" for lines located on an ARTIC card, "00" through "12" for RF serial ports, "00" through "99" for TCP/IP and DOS/Windows lines.
For 7524 RF-attached terminals, the line and address parameters are combined to form a value from "000" to "126". The line value holds the first two characters ("00"-"12") and the address value holds the last character '0'-'9'.
Note: Refer to the Line parameter of the DcxQueryTermAddress API for information about how the line and address parameters are set up internally for TCP/IP and DOS/Windows terminals and how they might change from one execution of DCConnect to the next.
Address (CHAR) - input
The address character. This character must be in the range 'A'-'P' for 7525 terminals, 'A' through 'Y' or the range '0' through '6' for 7524 batch terminals, 7526, 7527 terminals, or DOS or Windows DCTs. If a letter is to be passed in it must be in upper case; DCConnect does not distinguish between lower case and upper case addresses for terminals.
For 7524 RF-attached terminals, the value must be in the range '0'-'9'. The line and address parameters are combined form a value from "000" to "126". The line value holds the first two characters ("00"-"12") and the address value holds the last character '0'-'9'.
For TCP/IP and DOS/Windows terminals the value must also be in the range '0'-'9'.
Note: Refer to the Line parameter of the DcxQueryTermAddress API for information about how the line and address parameters are set up internally for TCP/IP and DOS/Windows terminals and how they might change from one execution of DCConnect to the next.
TermName (PSZ) - output
Buffer in which to store the terminal name. This buffer should be at least as big as DCX_TERM_NAME_LEN + 1 in order to hold the largest possible null-terminated terminal name.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR loc[DCX_TRF_LOCLEN] CHAR line[DCX_TRF_LINELEN] CHAR address; UCHAR name[DCX_TRF_TERMNAMELEN + 1] /* The Line location, number and address are assumed to */ /* have been previously obtained. */ rc = DcxQueryTermName(loc, line, address, name);
DcxShutdown (Absolute)
DcxShutdown allows an application to shut down DCConnect. The parameter on the API specifies whether any downloads that may be in process should be cancelled.
Generally it is not a good idea to cancel downloads in progress because terminals will not operate properly if they are partially downloaded. However, if necessary, the 'absolute' parameter can specify that any downloads should be cancelled.
Absolute (UCHAR) - input
Indicates whether or not to cancel any downloads that may be in progress. This parameter may take one of two values:
| DCX_SHUTDOWN_NO | Check for any downloading terminals before shutting down. If any terminals are found to be downloading, the shutdown will not be done and the return code will be DCX_DOWNLOADING. |
| DCX_SHUTDOWN_YES | Shut down DCConnect and cancel any downloads that may be in progress. |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h"
SHORT rc;
CHAR cancelloads = FALSE;
/* First try to shut down without cancelling any downloads */
rc = DcxShutdown(DCX_SHUTDOWN_NO);
/* If that is not successful, prompt the user for permission */
/* to cancel the downloads and shutdown anyway. */
if (rc == DCX_DOWNLOADING)
{
/* Tell user downloads are in progress and get permission. */
/* If we got permission, cancelloads will be set to TRUE. */
if (cancelloads == TRUE)
rc = DcxShutdown(DCX_SHUTDOWN_YES);
}
DcxStartApplication (ApplName)
DcxStartApplication allows one of the applications configured using the DCConnect application Notebook to be started up. This might be useful if that application was not configured to be autostarted or if the application was autostarted but has since been shut down.
ApplName (PSZ) - input
Pointer to the name of the application to be started. This name must be one that has been defined using the DCConnect user interface.
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; CHAR applname[] = "ValidationHandler"; rc = DcxStartApplication(applname);
DcxSynchronizeDateTime (TimePtr, Mode)
DcxSynchronizeDateTime sets the system unit date or time and/or updates the terminals from the system unit date or time. If both functions are to be performed, the system unit date or time is set before updating the terminals.
| Note: |
If DcxSynchronizeDateTime is called with a mode that synchronizes terminals
and terminals are currently being downloaded, DCConnect sends the time synch command
to all terminals except those that are downloading. However, a time synch
command is part of the download sequence, therefore all terminals get the correct
time.
DOS or Windows PCs configured in DCConnect are not affected by this API. |
TimePtr (struct tm *) - input
Pointer to the C structure containing the current date and time. This structure is defined in <time.h> in IBM C-Set/2, IBM C-Set++, or IBM VisualAge 3.0 \include directory. This structure contains fields for the year, month, day, hour, minute, second, ... The file time.h is already included by DCX.H so the application program making this call does not need to (and should not) include <time.h>.
Mode (USHORT) - input
Specifies which function(s) to perform. Valid values are:
| DCX_SET_DATETIME | Set new date/time without terminal synchronization |
| DCX_SYNC_DATETIME | Set new date/time and synchronize terminals |
| DCX_SYNC_TERMINALS | Synchronize terminals with current system unit date/time (the TimePtr parameter is ignored) |
Return code descriptions can be found in Return Code Values by Category (See Error Situations) .
#include "dcx.h" SHORT rc; struct tm new_date_time; /* Get input from user for new date and time and convert it to the */ /* 'struct tm' format in the variable 'new_date_time' */ /* Make call to update the system unit time and all the terminals */ /* as well */ rc = DcxSynchronizeDateTime(&new_date_time, DCX_SYNC_DATETIME);
DCConnect APIs can not only be called from a C or C++ program but they can be called from a Microsoft Visual Basic (VB) application as well. DCConnect includes VBDCX.DLL which contains wrapper functions for all of the DCConnect APIs but built using __stdcall linkage so that VB applications can call them.
DCConnect includes a sample VB application to show how to define prototypes, structures and data types for the DCConnect APIs. This sample is in the \DCCONN\SAMPLES directory. Just load DCCSamp.vbp into the Microsoft Visual Basic development environment.
The sample uses the DCConnect APIs to do the following:
This section will point out specific parts of the sample to help illustrate key points about what must be done to call the DCConnect APIs.
To start here is a simple prototype from DCCONN.BAS:
Declare Function DcxIsAlive Lib "vbdcx.dll" Alias "vbDcxIsAlive" () As Integer
Note that the library that is specified is "vbdcx.dll" instead of DCX.DLL and also that the actual API name is preceded with 'vb'; all of the API names are preceded with 'vb'. All APIs are defined to return an 'Integer' (a four byte value) even though they actually return a short integer which is a two byte value.
In the prototype above, the Alias keyword is followed by the actual name of the API as it exists in vbdcx.dll. But following the Function keyword is the name you would use when calling this API in your VB application. For example:
Dim dcxRc As Integer dcxRc = DcxIsAlive
For APIs that pass pointers to structures you must of course first define the structure. For example, the QUERY_MAILBOX structure is defined as follows in C:
#define DCX_OS_NAME_LEN 12
typedef struct
{
long notread; /* # of transactions in file that have not been read */
long notreleased; /* # of transactions that were read but not released */
char active; /* Indicates whether export is open or not: */
/* DCX_EXPORT_IS_INACTIVE or DCX_EXPORT_IS_ACTIVE */
long size; /* # of transaction the export can hold */
char logfile[DCX_OS_NAME_LEN + 1]; /* Name of physical log file */
}
QUERY_EXPORT;
Here is the same structure in Visual Basic:
Public Const DCX_OS_NAME_LEN = 12 ' 8.3 file name length
Public Type QUERY_MAILBOX
notread As Integer ' # of transactions in file that have not been read
notreleased As Integer ' # of transactions that were read but not released
active As Byte ' Indicates whether export is open or not:
' DCX_MAILBOX_IS_INACTIVE or DCX_MAILBOX_IS_ACTIVE
size As Integer ' # of transaction the export can hold
logfile(DCX_OS_NAME_LEN + 1) As Byte ' Name of physical log file
End Type
The DCConnect API library is built with 1-byte alignment so you do not have to worry about padding structures. Here is an example of how to define an API prototype that passes this structure:
Declare Function DcxQueryMailbox Lib "vbdcx.dll" Alias "vbDcxQueryExport" _
(ByVal mailboxName As String, mailboxInfo As QUERY_MAILBOX) _
As Integer
The following table shows the mapping between C types that are passed and their Visual Basic counterparts.
PSZ nullTermString | ByVal nullTermString As String |
PCHAR / char * someCharPtr | If this is a pointer to an array of characters use: ByVal someCharPtr As String But if this a pointer to a single character you can also use: someCharPtr As Byte |
PLISTZ nullTermStringList | ByVal nullTermStringList As String Note that the nullTermStringList contains a series of strings each ending with a null character, Chr(0). There is one additional null character at the end of the list. |
USHORT someUnsignedShort | ByVal someUnsignedShort As Integer |
PUSHORT / USHORT * someUnsignedShortPtr | someUnsignedShortPtr As Integer |
long someLong | ByVal someLong As Long |
UCHAR someUnsignedChar | ByVal someUnsignedChar As Byte |
char someChar | ByVal someChar As Byte |
HTRANS / HTERM / HVAL / HMSGLOG / HREQ someHandle | ByVal someHandle As Long |
PHTRANS / PHTERM / PHVAL / PHMSGLOG / PHREQ someHandlePtr | someHandlePtr As Long |
PQUERY_EXPORT / PTERMSTATUS / PTERMINFO / TRF * / ... anyStructurePtr | First define the structure similar to how QUERY_MAILBOX is defined above. Then pass it by reference. For example: mailboxinfo As QUERY_MAILBOX |
Several DCConnect APIs, such as DcxQueryJobList, DcxQueryJobTerms, DcxQueryTermList and DcxQueryMailboxList, return lists of type PLISTZ which will vary in size. These APIs also include a length parameter that is used on entry to specify how much space is allocated for the list. When the function returns, this variable is set to the length of the data that is returned/available. If this variable is set to 0, this is a signal to the API to simply set the total length on return but not to actually return the list. This provides an opportunity to ensure enough space is allocated for the list so that on a second call to the API the data can be safely stored.
The following example illustrates the above procdure with the DcxQueryMailboxList API whose prototype is defined to be:
Declare Function DcxQueryMailboxList Lib "vbdcx.dll" Alias "vbDcxQueryExportList" _
(listLen As Integer, ByVal mailboxlist As String, _
listCnt As Integer) As Integer
The following subroutine, which is part of the sample, is used to obtain a list of all the mailboxes that are defined in DCConnect.
Sub FillMailboxList()
Dim listLen As Integer
Dim listCnt As Integer
Dim nameList As String
Dim nextMailbox As Integer
Dim dcxRc As Integer
listLen = 0
listCnt = 0
'
' First get the list of DCConnect jobs. This actually takes two calls. The first gets the length
' of the list and the number of jobs in it.
'
ReDim MailboxNames(0)
dcxRc = DcxQueryMailboxList(listLen, nameList, listCnt)
If (dcxRc = DCX_NO_ERROR) Then
nameList = Space(listLen)
ReDim Preserve MailboxNames(listCnt - 1)
dcxRc = DcxQueryMailboxList(listLen, nameList, listCnt)
For nextMailbox = 0 To listCnt - 1
GetFirstNameInList nameList, MailboxNames(nextMailbox)
Next nextMailbox
End If ' dcxRc from DcxQueryMailboxList was 0
End Sub
A couple of things to notice about this subroutine:
The API DcxSetNTermUserVariables presents a challenge because its prototype, as defined in C, includes an array of USHORTs and an array of pointers to strings:
short LINKAGE DcxSetNTermUserVariables(PSZ termname, HTERM acquire,
USHORT numvars, USHORT * vars, PSZ vartext[]
Visual Basic provides a way to pass an array of USHORTS:
Dim uvNums(5) As Integer
But VB does not provide a way to pass an array of pointers to strings. To resolve this problem, a second version of DcxSetNTermUserVariables was created in vbdcx.dll which has the following C prototype:
short LINKAGE vbDcxSetNTermUserVariables2(PSZ termname, HTERM acquire,
USHORT numvars, USHORT * vars, PLISTZ vartext);
Notice that the last parameter is now of the type PLISTZ which is a series of concatentated null-terminated strings with an additional null character at the end. The Visual Basic prototype for this API is:
Declare Function DcxSetNTermUserVariables Lib "vbdcx.dll" _
Alias "vbDcxSetNTermUserVariables2" (ByVal termname As String, _
ByVal acquire As Long, ByVal numvars As Long, varArray As Any, _
ByVal varText As String) As Integer
The following example shows how to set up the variables to call this API:
...
Dim dcxRc As Integer
Dim uvNums(5) As Integer
Dim uvText As String
uvNums(0) = 13
uvNums(1) = 23
uvNums(2) = 64
uvNums(3) = 48
uvNums(4) = 18
uvText = "UV 13 has been set: XIII" + Chr(0)
uvText = uvText + "UV 23 has been set: XXIII" + Chr(0)
uvText = uvText + "UV 64 has been set: LXIV" + Chr(0)
uvText = uvText + "UV 48 has been set: XLVIII" + Chr(0)
uvText = uvText + "UV 18 has been set: XVIII" + Chr(0) + Chr(0)
dcxRc = DcxSetNTermUserVariables("TermA", 0, 5, uvNums(0), uvText)
Notice that Chr(0) is added to the end of the text for each user variable and and an extra one is added after th last variable. Also notice that when passing the array of user variable numbers, you have to specify index 0 in order for it to work properly.
The error-reporting philosophy of DCConnect focuses on two destinations for error information: the system user and DCConnect applications.
For system user error information, see System Error Messages (See System Messages) .
For system return code information, see System Return Codes (See System Return Codes) .
For application error information, see API Return Codes (See Application Programming Interface Return Codes) .
The user can view error messages and other informational messages, generated by DCConnect during its operation, in the system message log. The message log resides in the .\DATA subdirectory of the DCConnect root directory and has the default name, MESSAGES.DAT.
Use the "System Message Viewer" to view the contents of the DCConnect system message log - whether or not DCConnect is running.
This system message log is an ASCII file that can be viewed using a text editor or printed as a normal flat file. Each message in the file takes up two lines.
Note: The first few bytes of the system message log are used by DCConnect to indicate where the next message is to be written in the file. The rest of the file, however, contains only the messages.
Because the first few bytes in the file are binary data rather than text, the system message log should not be modified by a text editor. The system message log can be cleared using the API DcxClearMessageLog.
If you are using an editor to view the message log, you can find the last message in the file by looking for a line that contains all dashes (-).
System Message entries are displayed as follows:
06-30-96 14:25:03
DCR0110: An error occurred while loading a terminal.
Where the following represents the system message format in the System Message Log:
| 06-30-96 | is the date the message was posted |
| 14:25:03 | is the time the message was posted |
| DCR0110: | is the message identifier |
An error occurred while loading a terminal.
Is a description of the situation
When the system message log fills up, DCConnect wraps to the beginning of the file, writing over those messages that were first written to the file.
Recovery Actions
Recovery from errors logged in the system message log vary widely according to the message presented.
To obtain additional information about a System Message on OS/2, at an OS/2 command prompt, type:
HELP DCRXXXXWhere:
XXXX is the number of the System Error Message.
To obtain additional information about a System Message on Windows/NT, at a command prompt, type:
CS2HELP DCRXXXXWhere:
XXXX is the number of the System Error Message.
Many of the messages indicate the value of 'errno' for the error that occurred. This is a value set by the Operating System when an error results trying to create or access a resource such as a file, shared memory, semaphore, or process.
Types of errors can range from invalid access permission, to invalid parameter, to no room, and so forth. A complete listing of the possible values for 'errno' and their meanings can be found in the file:
errno.h
that is part of the IBM VisualAge compiler. Some of the common values and their
meanings are listed:
| 10 | Does not exist |
| 13 | Out of memory |
| 16 | File exists already |
| 22 | File seek error |
| 24 | File access not allowed |
| 29 | Past end of file |
| 35 | Process interrupted |
| 43 | Bad file descriptor |
| 51 | Bad file attribute |
| 60 | OS/2 error |
Another class of error values returned is referred to as system errors. These values have specific meanings under OS/2. For a complete listing of these values, refer to the OS/2 Control Program Guide and Reference. Some of the more common values and their meanings are listed:
| 2 | File not found |
| 3 | Path not found |
| 5 | Access denied |
| 8 | Not enough memory |
| 19 | Write protect error |
| 32 | Sharing violation |
| 80 | File already exists |
| 112 | Disk is full |
The other mechanism for returning error status is Return Codes from APIs to the DCConnect application programming interface.
When calls to the APIs are coded, logic should always be included to handle the exception or error conditions. The return codes were selected to fall into the following groups:
| Positive (+) | Information Messages |
| Zero (0) | Good Completion |
| Negative (-) | Error Messages |
The return codes are just constant values, but they are organized into category and detail to allow different levels of error presentation to a user, if desired.
Generally, error return codes should either be retried or handled in the code as required or reported to the application user in whatever way is deemed appropriate (display, file, printer, and so forth).
The following tables list the return code values by category:
| Message Number | Message Name | Returned by API | Explanation |
|---|---|---|---|
| 0 | DCX_NO_ERROR | All |
Returned by all APIs if the call was successful. For DcxReadTransaction,
DcxReadValidation, DcxReadMsgLog, and DcxReadDataRequest this return code
indicates a transaction or request or message was returned in the specified
buffer.
For DcxIsAlive, this return code indicates DCConnect is currently running. |
|
1
2 3 4 5 |
DCX_ACK
DCX_DATA DCX_DC1 DCX_DC2 DCX_NAK | None | These return codes are defined in DCX.H but will never be returned by any of the API calls. These return codes are used internally by DCConnect along with all of the other return codes. |
| 6 | DCX_NO_DATA |
DcxReadMsgLog
DcxReadTransaction DcxReadValidation DcxReadDataRequest | Indicates the timeout period specified in the API call expired before a message, transaction, validation request, or data request was received. This return code is returned if the Message Log, Mailbox, or Application is closed or DCConnect is shut down while a read API is still waiting for data. |
| Error Number | Error Name | Returned by API | Explanation |
|---|---|---|---|
| -1 | DCX_INTERNAL_ERROR | All/none | This return code should never occur unless there is an internal problem that has not yet been fixed. Refer to the message log for a message describing the error. Then report the error to your support group. |
| -2 | DCX_NOT_RUNNING | Most |
DCConnect is not running right now. DCConnect must be started in order to
use most of the APIs.
Several APIs perform their function even if DCConnect is not currently running. Thus these APIs never return DCX_NOT_RUNNING - although they may return DCX_SHUTDOWN_IN_PROGRESS or DCX_STARTING_UP. The APIs that run even if DCConnect is not running are:
DcxSubmitValidationFile
See the descriptions of these APIs for more details about what they do and do not do when DCConnect is not running. |
| -3 | DCX_SHUTDOWN_IN_PROGRESS | All | DCConnect is in the process of shutting down. DCConnect will not handle any more API requests until it is restarted. |
| -4 | DCX_STARTING_UP | All | DCConnect is in the process of starting up. It cannot handle any API requests until it has completed its start-up. |
| Error Number | Error Name | Returned by API | Explanation |
|---|---|---|---|
| -100 | DCX_OS_ACCESS | DcxSynchronizeDateTime | This return code is used a only on AIX where super-user privilege is required to change the date/time of the system unit. |
| -101 | DCX_OS_GET_PROC |
DcxOpenMailbox
DcxOpenValidation DcxAcquireTerminal DcxOpenRequestHandler | An error occurred trying to get the process ID of the task which is issuing the API. These APIs use the process ID to identify the task which is requesting the handle for access to a resource. If another open/acquire is issued, the process ID is used to see if the original process is still active. |
| -102 | DCX_OS_MEMORY | All |
All APIs can get this return code if there is insufficient memory
to allocate buffers for messages that are sent to and received from DCConnect
as result of the API call. If this error occurred no message is logged.
DcxOpenMailbox, DcxOpenValidation, DcxAcquireTerminal, and DcxOpenRequestHandler may return this error if memory could not be allocated for the routine which retrieves the process information for the calling application. No message is logged in this case either. DcxLoadTerminal will return this error if it could not allocate memory for internal buffers used by the download task. In this case a message is logged. DcxSubmitValidationFile will also return this error if it could not allocate enough memory for internal buffers used when converting the file or when figuring out which terminals must be loaded with the new file. In this case a message is logged. DcxChangeTerminalState will return this error if it could not allocate memory for internal buffers when trying to update the configuration file with the new state. In this case a message is logged as well. DcxQueryJobInfo will return this error if it could not allocate memory for internal buffers when trying to read the job file. In this case a message is logged as well. |
|
-103
-104 -105 -106 |
DCX_OS_MSGPATH_CREATE
DCX_OS_MSGPATH_OPEN DCX_OS_MSGPATH_READ DCX_OS_MSGPATH_WRITE | All |
An error occurred trying to open/create/read/write a DAE Communication
systems application control block between tasks or processes. If the error
occurred in the shared library, then it occurred trying to send the API request
to the runtime process and thus no message will be logged.
Otherwise, the error occurred within DCConnect and a message has been logged describing the name of the DAE Communication systems application control block and more specifically what was the error. |
| -107 | DCX_OS_SEM | All | An error occurred trying to create or access an internal semaphore or the semaphore used for sending and receiving the API request. |
| -108 | DCX_OS_START_TASK |
DcxLoadTerminal
DcxStartApplication |
For DcxLoadTerminal, an error occurred trying to start a task to perform
the requested terminal download. View the system message log for more
specific details about the error.
For DcxStartApplication, DCConnect was not able to start the specified application. Check the system message log for a message explaining the reason for the failure. |
| -109 | DCX_CS2_NLS_ERROR | All |
For DcxLoadTerminal, an error occurred trying to start a task to perform
the requested terminal download. View the system message log for more
specific details about the error.
For DcxStartApplication, DCConnect was not able to start the specified application. Check the system message log for a message explaining the reason for the failure. |
| Error Number | Error Name | Returned by API | Explanation |
|---|---|---|---|
| -200 | DCX_DELETE_FAILED | DcxDeleteValidationFile | A request to delete the specified validation file was not completely successful. The file was removed from internal tables if DCConnect running. However, the file could not be deleted from the validation directory. Look at the message log for an error describing what the problem was. |
| -201 | DCX_DID_NOT_REPLY |
DcxReadValidation
DcxReadDataRequest | A reply was not sent back for the last validation request that was read. For each call to DcxReadValidation that returns an actual request, a call must be made to DcxReplyValidation before the next call to DcxReadValidation is made. |
| -202 | DCX_FILE_LOADING |
DcxSubmitValidationFile
DcxDeleteValidationFile | A request to submit the specified validation file is currently outstanding and has not yet completed. A particular validation file cannot be re-submitted or deleted while a submission is in progress. |
| -203 | DCX_NO_MORE_ROOM |
DcxSubmitValidationFile
DcxOpenValidation DcxLoadTerminal DcxOpenMsgLog |
There is no more room to store one or more of the validation files
specified in the 'valfiles' parameter in the internal tables maintained by
DCConnect. Up to 256 different validation files can be maintained in these
tables.
For DcxOpenValidation this could also mean that the application table, which can hold up to 64 validation applications, is full. For DcxLoadTerminal, this return code will be returned if the maximum allowed concurrent downloads are in progress. That maximum defaults to 16 but can be changed in the file EXTRA.CFG located in the <DCCONN>\data subdirectory. If the download should be done anyway, use the value DCX_RET_WHEN_QUEUED for the 'wait' parameter. This will cause the download request to be queued in the case that the maximum number of downloads are already in progress. If the load is queued, the return code for this API will be DCX_NO_ERROR. This return code can also be returned for DcxLoadTerminal if the amount of data attempted to be loaded for a particular file exceeds the space allocated in the terminal for that file. This should never happen because DCConnect should be checking to make sure it does not. But if in fact this is the problem, an error will be written to the message log indicating which file failed to load. DcxOpenMsgLog will return this error if there are already five applications which have issued this API and are still handling messages. Note: The DCConnect user interface may be one of the five possible applications. |
| -204 | DCX_NO_REQUEST_PENDING |
DcxReplyValidation
DcxReplyDataRequest DcxForwardDataRequest | The last validation/data request read by this application has already been replied to; DCConnect is not waiting for the application to reply to a request. |
| -205 | DCX_PARTIAL_SUCCESS | Only used internally | This return code is not returned by any of the APIs in this manual. |
| -206 | DCX_READ_PENDING |
DcxReadValidation
DcxReadTransaction DcxReadMsgLog DcxReadDataRequest | An API was issued to read a validation request/transaction/message/data request when a read request was already outstanding for the validation application/export/message/data request log application. Only one read can be waiting at a time for a given validation application/export/message log application. |
| -207 | DCX_TIMEOUT | DcxLoadTerminal | During the download, the download task issued a command to the Communications Interface but did not receive the response before an internal timeout value expired. This should never occur unless there is an internal error in DCConnect. |
| -208 | DCX_TXTNS_TO_RELEASE | DcxClearMailbox |
The mailbox that was requested to be cleared currently has transactions that
were read by an application but have not yet been released. A mailbox cannot
be cleared in this situation. Whatever program currently has the mailbox open
must release all transactions it has read before the mailbox can be cleared.
Closing the mailbox will also allow it to be cleared because when a mailbox is closed all transactions that had been read and not released will become available to be read the next time that mailbox is opened. |
| -209 | DCX_APPL_NOT_REGISTERED |
DcxRequestData
DcxForwardDataRequest | The target application name specified inn the DcxRequestData / DcxForwardDataRequest API has not issued a DcxOpenRequestHandler API. Therefore the request cannot be handled/forwarded. |
| -210 | DCX_READ_FAILED | DcxRequestData | The DcxRequestData API timed out before the "Receiving application" issued a DcxReadDataRequest. 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. |
| -211 | DCX_READ_SUCCESS_NO_REPLY | DcxRequestData | The DcxRequestData API timeout period expired after the "Receiving application" issued a successful DcxReadDataRequest but, before the "Receiving application" issued a DcxReplyDataRequest. Or, the "Receiving application" issued a successful DcxReadDataRequest but, then issued a DcxCloseRequestHandler API before issuing a DcxReplyDataRequest. 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. |
| Error Number | Error Name | Returned by API | Explanation |
|---|---|---|---|
| -300 | DCX_ACQUIRED | All APIs that have a terminal name parameter and an acquire handle parameter | Another process has already acquired the specified terminal. That process must unacquire the terminal before other processes can access it. |
| -301 | DCX_BAD_STATUS |
DcxSetTermUserVariable
DcxExecuteTermTransaction | Indicates that the terminal was not able to perform the action specified by the API call even though it did receive the command. This may happen for DcxExecuteTermTransaction if the terminal is currently executing another transaction program that was initiated from the terminal or from another DcxExecuteTermTransaction. |
| -302 | DCX_BAD_TERMINAL | Any API with a terminal name as a parameter (except for DcxAcquireTerminal). | The specified terminal is currently in a "Bad terminal" state. This may occur if the terminal did not go into service when requested to do so by DCConnect, if the terminal attached is not the same type/model that is configured in DCConnect, or the terminal is returning invalid or unusable data. Check the system message log for information as to why the terminal is in this state. |
| -303 | DCX_CMD_NOT_ALLOWED | Any API with a terminal name as a parameter (except for DcxAquireTerminal). | Terminal is in the process of downloading, flushing, performing a time synch or is waiting for a failed download to be retried. Only DcxQueryTermStatus and DcxChangeTermState can be issued to a terminal while that terminal is in one of these situations. |
| -304 | DCX_DOWNLOADING |
DcxShutdown
DcxLoadTerminal |
For DcxShutdown, the 'absolute' parameter was set to DCX_SHUTDOWN_NO and
one or more terminals are currently being downloaded, flushed or time synched.
For DcxLoadTerminal, the terminal specified is already in the process of being downloaded or time synched. |
| -305 | DCX_FLUSH_FAIL | DcxLoadTerminal | For every terminal download, the target terminal must be flushed of all transactions. An error occurred trying to flush the terminal of these transactions. See the system message log for more details. |
| -306 | DCX_FLUSHING | DcxLoadTerminal | The terminal specified in the API is currently being flushed of transactions. Wait a few minutes and issue the download again. |
| -307 | DCX_INVALID_TERMINAL_TYPE |
DcxInitiateTermEvent
DcxSetTermUserVariable DcxSetNTermUserVariables DcxGetTermUserVariable | The command is not supported by the type of terminal to which it has been issued. Refer to the command's documentation in Application Programming Interface (API) Reference for restrictions on supported terminal types for each of these APIs. |
| -308 | DCX_NOT_RESPONDING | Any API with a terminal name as a parameter (except for DcxAquireTerminal). | The terminal is currently not responding to commands issued by DCConnect. The terminal is being polled every minute to find out if the problem causing the lack of response has been corrected. When the terminal does begin responding, the internal state will be updated and these APIs will be allowed to go through to the terminal. |
| -309 | DCX_REJECTED_DATA | Any API with a terminal name as a parameter (except for DcxAquireTerminal). |
Terminal has NAKed the command that was sent to it as a result of
the API.
If this is a 7527 terminal, the terminal will reply NAK to most commands if
it does not currently have Extended Terminal Services loaded.
Otherwise the terminal might NAK a command if the parameters are not valid. Refer to the terminal manual for the specific meaning of a NAK reply by the terminal for the command being issued. |
| -310 | DCX_TERM_IN_WRONG_STATE | Any API with a terminal name as a parameter (except for DcxAquireTerminal). | The terminal is currently not in a state to accept the command that was issued to it. |
| Error Number | Error Name | Returned by API | Explanation |
|---|---|---|---|
| -400 | DCX_FILE_ERROR |
DcxLoadTerminal
DcxWriteTransaction DcxChangeTerminalState DcxSubmitValidationFile DcxReadTransaction DcxReleaseTransaction DcxQueryJobInfo DcxSubmitClientFiles | An error occurred trying to create, open, read from, write to or seek in a
file. A more specific error stating the file name and reason for the error
has been put in the message log.
For DcxWriteTransaction, this is the return code given if the log file is full. For DcxChangeTerminalState, there was an error updating the configuration file with the new state; however, the terminal has actually been put in the new state. For DcxSubmitClientFiles DCX_FILE_ERROR is returned if a file error occurs trying to open or read from the specified clientFilesListPath or invalid data was found in the file. Check the message log for an error message indicating the specific file error that occurred. |
| -401 | DCX_INVALID_FILE_FORMAT | DcxSubmitValidationFile | The text file specified does not have the proper format. |
| Error Number | Error Name | Returned by API | Explanation | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| -500 | DCX_DATA_TRUNCATED |
DcxQueryApplList
DcxQueryMailboxList DcxQueryJobInfo DcxQueryJobList DcxQueryJobTerms DcxQueryTermList DcxReadTransaction |
For all of these APIs except DcxReadTransaction a list of items is returned. For these
APIs, this return code indicates the list returned was shortened because the buffer length
specified in the parameter list was shorter than the length of the actual list. To
find out how long the list is, first call the API with the buffer length
parameter set to 0 and DCConnect will return the exact size of the list. Then
allocate memory for that size and call the API again using the exact list
size for the buffer length parameter.
For DcxReadTransaction, the DCX_DATA_TRUNCATED return code is given when the data in the transaction is longer than the 108 byte maximum that is allowed for the data element of the TRF structure. The data is filled in up to that 108 bytes and the length is set to 108. But to get all of the data (up to 750 bytes), the DcxReadTransactionEx API and the TRF2 structure structure need to be used. | ||||||||||||||||||||||||||||||||||||
| -501 | DCX_DOES_NOT_EXIST |
DcxSubmitValidationFile
DcxDeleteValidationFile DcxOpenMailbox DcxQueryMailbox DcxClearMailbox DcxLoadTerminal DcxReleaseTransaction DcxQueryJobTerms DcxQueryJobInfo DcxStartApplication DcxSubmitClientFiles |
Indicates the file/resource specified in the call does not exist:
For DcxSubmitValidationFile, the source text file was not found. For DcxDeleteValidationFile, the specified validation file was never submitted or has already been deleted. For DcxOpenMailbox, DcxClearMailbox and DcxQueryMailbox, the Mailbox specified has not been configured. All Mailbox must be defined through the DCConnect configuration before they can be opened, cleared or queried. For DcxLoadTerminal, the files specified are not part of the Job being used by the specified terminal. For example, if the 'whichfiles' parameter was DCX_DWNLD_CFR and there is no CFR assigned to the specified terminal's Job, the return code will be DCX_DOES_NOT_EXIST. For DcxReleaseTransaction, the sequence number specified does not match the sequence number for any of the unreleased transaction that have been read from the Export. For DcxQueryJobTerms or DcxQueryJobInfo, this error indicates the specified job is not part of the DCConnect configuration. For DcxStartApplication, this error indicates the specifies application name is not currently configured in DCConnect. For DcxSubmitClientFiles, DCX_DOES_NOT_EXIST is returned if there are no terminals that match the criteria specified in the first two parameters. For example, DCX_TARGET_MODEL and Win32 are the first two parameters but no terminals in the DCConnect configuration are assigned that model. | ||||||||||||||||||||||||||||||||||||
| -502 | DCX_INVALID_ATTRIBUTE | DcxDisplayTermText | An invalid Attribute has been specified. | ||||||||||||||||||||||||||||||||||||
| -503 | DCX_INVALID_COMM_LINE | DcxQueryTermName | The line parameter was not "00" through "07" for an ARTIC card or "01" through "04" for a native serial port and "00"-"07" for TCP/IP, DOS or Windows attached lines. | ||||||||||||||||||||||||||||||||||||
| -504 | DCX_INVALID_COMM_LOC | DcxQueryTermName | The location parameter was not one of "00", "01", "02", "03" or " " to indicate one of the ARTIC cards or a native serial port, or "RF" for RF serial port, "IP" for TCP/IP adapter, and "DW" for DOS or Windows PC. | ||||||||||||||||||||||||||||||||||||
| -505 | DCX_INVALID_DATALEN |
DcxWriteTransaction
DcxLoadTerminal |
For DcxWriteTransaction, the .datalen field must contain a valid
ASCII number in the range "0000" through "0108" - or whatever the
DCX_TRF_TXDATALEN parameter is defined to be.
For DcxLoadTerminal, the terminal does not have sufficient memory to load the requested files. Check the message log for an error describing which file was in error. | ||||||||||||||||||||||||||||||||||||
| -506 | DCX_INVALID_DATETIME |
DcxWriteTransaction
DcxSynchronizeDateTime |
For DcxWriteTransaction, the .year, .month, .day,
.hour, .minute, .second fields in the transaction
structure must specify a valid date/time on the planet Earth. All values
must be ASCII numbers with leading zeros to pad out the field. For example,
the .hour field must have a value in the range "00" through "23".
For DcxSynchronizeDateTime, the mode passed in was either DCX_SET_DATETIME or DCX_SYNC_DATETIME and the date/time specified in the 'timeptr' structure was not valid for the planet Earth. | ||||||||||||||||||||||||||||||||||||
| -507 | DCX_INVALID_DURATION |
DcxBeepTerm
DcxDisplayTermText DcxInteractiveResponse |
For DcxBeepTerm, the duration must be in the range 1 through 9 indicating the
number of half seconds the tone should last.
For DcxDisplayTermText and DcxInteractiveResponse, the duration parameter must be either DCX_OPERATOR_DURATION or DCX_TIMER_B_DURATION. | ||||||||||||||||||||||||||||||||||||
| -508 | DCX_INVALID_DWNLD_FILES | DcxLoadTerminal |
The 'whichfiles' parameter must be one of: DCX_DWNLD_ETS,
DCX_DWNLD_ALL, DCX_DWNLD_VAL, DCX_DWNLD_CFR,
DCX_DWNLD_GPH, DCX_DWNLD_FORCE, DCX_DWNLD_SCRIPTS or DCX_DWNLD_CLIENT.
This return code will also be given if the 'whichfiles' parameter is DCX_DWNLD_ETS and the terminal specified is not a 7527. | ||||||||||||||||||||||||||||||||||||
| -509 | DCX_INVALID_DWNLD_WAIT | DcxLoadTerminal | The 'wait' parameter must be one of: DCX_RET_WHEN_COMPLETE, DCX_RET_WHEN_STARTED or DCX_RET_WHEN_QUEUED indicating when the return code should be given to the application issuing this call. | ||||||||||||||||||||||||||||||||||||
| -510 | DCX_INVALID_ERASE | DcxDisplayTermText | An invalid Erase parameter has been specified. The Erase parameter must either be DCX_CLEAR_SCREEN to clear the screen or DCX_NO_CLEAR_SCREEN to refrain from clearing the screen. | ||||||||||||||||||||||||||||||||||||
| -511 | DCX_INVALID_FILE |
DcxOpenValidation
DcxSubmitValidationFile DcxDeleteValidationFile DcxSubmitClientFiles |
For any of the validation APIs the validation file(s) specified in the 'valfiles' parameter do not have
valid name(s). These file names must be upper case, must end with the
.VAL file extension and cannot be longer than DCX_VAL_FILE_LEN including
the extension.
For DcxSubmitClientFiles the specified clientFilesListPath does not exist. | ||||||||||||||||||||||||||||||||||||
| -512 | DCX_INVALID_GLOBAL_VARIABLE |
DcxGetTermUserVariable
DcxSetTermUserVariable DcxSetNTermUserVariables | The global variable is invalid. Valid values are 10 through 19 for a 7527 terminal, 1 through 998 for a 7526 terminal, or 10 through 99 for a 7524 terminal with flash level greater than 1.10. 7524 terminals with flash levels 1.10 or earlier are restricted to a maximum of 19 user variables - just like the 7527 terminal. | ||||||||||||||||||||||||||||||||||||
| -513 | DCX_INVALID_HANDLE |
DcxReadTransaction
DcxReleaseTransaction DcxCloseMailbox DcxReadValidation DcxReplyValidation DcxCloseValidation DcxReadMsgLog DcxCloseMsgLog DcxReadDataRequest DcxReplyDataRequest DcxForwardDataRequest DcxCloseRequestHandler All terminal access APIs |
For the non-terminal access APIs, this return code indicates the
handle is not one of the valid Mailbox/validation/message log/ data request
handles that are currently open.
For the terminal access APIs, this error indicates one of two things.
| ||||||||||||||||||||||||||||||||||||
| -514 | DCX_INVALID_LOAD_PARM |
DcxSubmitValidationFile
DcxSubmitClientFiles |
The 'load' parameter for DcxSubmitValidationFile must be either DCX_LOAD_YES or DCX_LOAD_NO
indicating whether the validation files should be loaded to all terminals which
are using that file.
The 'targetType' parameter for DcxSubmitClientFiles must be one of DCX_TARGET_TERMINAL, DCX_TARGET_MODEL or DCX_TARGET_FUNCTION_GROUP. The 'submitMode' parameter for DcxSubmitClientFiles must be DCX_SUBMIT_STAGE_ONLY or DCX_SUBMIT_STAGE_AND_LOAD. | ||||||||||||||||||||||||||||||||||||
| -515 | DCX_INVALID_MODE |
DcxOpenMailbox
DcxOpenRequestHandler DcxOpenValidation DcxWriteTransaction DcxSynchronizeDateTime |
For DcxOpenMailbox, DcxOpenValidation, DcxOpenRequestHandler the Mailbox
name/application has already been opened by another process. Only one
process may open a Mailbox/application at a time.
DcxOpenMailbox will also give this return code if the specified mailbox is a master mailbox; one of the associated pool mailboxes are the ones that should be opened instead. For DcxWriteTransaction, the .mode field in the transaction structure is not valid. It must be one of the following:
For DcxSynchronizeDateTime, the mode parameter was not one of DCX_SET_DATETIME, DCX_SYNC_DATETIME, or DCX_SYNC_TERMINALS. | ||||||||||||||||||||||||||||||||||||
| -516 | DCX_INVALID_NAME |
DcxForwardDataRequest
DcxOpenValidation | For both DcxForwardDataRequest and DcxOpenValidation this indicates the 'applname' parameter is either too long or too short. The length of the 'applname' must be in the range 1 to DCX_VAL_APPL_LEN / DCX_APPL_NAME_LEN. | ||||||||||||||||||||||||||||||||||||
| -517 | DCX_INVALID_PARAMETER |
DcxShutdown
DcxQueryTermName |
For DcxShutdown, the 'absolute' parameter must be either DCX_SHUTDOWN_YES
or DCX_SHUTDOWN_NO indicating whether or not the shutdown should proceed
if a terminal is found to be downloading.
For DcxQueryTermName, the combination of location, line and address parameters was not one of the currently configured terminals in DCConnect. | ||||||||||||||||||||||||||||||||||||
| -518 | DCX_INVALID_POLLING | DcxChangeTerminalState | The 'polled' parameter must be one of: DCX_POLL_IS_ACTIVE, DCX_POLL_IS_INACTIVE, or DCX_POLL_NO_CHANGE, indicating what the new 'polled' state of the terminal should be. | ||||||||||||||||||||||||||||||||||||
| -519 | DCX_INVALID_RELEASE | DcxReleaseTransaction | Indicates there are no transactions that have been read and not yet released. Therefore this call is invalid at this time. | ||||||||||||||||||||||||||||||||||||
| -520 | DCX_INVALID_RESPONSE | DcxInteractiveResponse | The response type is invalid. It must be either DCX_INTER_POSITIVE for a positive response or DCX_INTER_NEGATIVE for a negative response. | ||||||||||||||||||||||||||||||||||||
| -521 | DCX_INVALID_RESULT | DcxReplyValidation | The 'result' parameter must be one of DCX_VALIDATION_PASS, DCX_VALIDATION_FAIL or DCX_VALIDATION_UNKNOWN indicating the result of the validation or indicating that another application should do the validation. | ||||||||||||||||||||||||||||||||||||
| -522 | DCX_INVALID_ROW_COL | DcxDisplayTermText |
The Row or Column position specified is invalid for the terminal
type being operated on.
The valid row and column ranges are listed below.
| ||||||||||||||||||||||||||||||||||||
| -523 | DCX_INVALID_SEQNUM | DcxReleaseTransaction | The 'seqnum' parameter is not an ASCII number. This parameter should be taken from the .seq field of the transaction structure for the transaction that is being released. | ||||||||||||||||||||||||||||||||||||
| -524 | DCX_INVALID_SERVICE | DcxChangeTerminalState | The 'service' parameter must be one of: DCX_SERV_IN, DCX_SERV_OUT, DCX_SERV_NO_CHANGE, indicating what the new 'service' state of the terminal should be. | ||||||||||||||||||||||||||||||||||||
| -525 | DCX_INVALID_TERM_ADDR | DcxQueryTermName |
The address parameter was not in the range 'A' through 'Y' or '0' through '6'.
The letter addresses must be upper case.
| ||||||||||||||||||||||||||||||||||||
| -526 | DCX_INVALID_TERM_EVENT | DcxInitiateTermEvent | An invalid transaction program number has been specified. The valid range is from 1 through 255. | ||||||||||||||||||||||||||||||||||||
| -527 | DCX_INVALID_TERMINAL_ID | Any API with a terminal name parameter or DcxWriteTransaction. | The terminal specified is not configured in DCConnect. The terminal name specified must have already been defined using the DCConnect configuration before it can be used in an API call. Make sure that the case of the terminal name specified in the API call matches the case of the terminal name in the DCConnect configuration. | ||||||||||||||||||||||||||||||||||||
| -528 | DCX_INVALID_TERMSEQ | DcxWriteTransaction | The .termseq parameter was not valid in the transaction structure. This field must contain an ASCII number in the range "00000" through "99999". | ||||||||||||||||||||||||||||||||||||
| -529 | DCX_INVALID_TEXT_FILE | DcxSubmitValidationFile | The length of the name of the text file must be in the range 1 through DCX_MAX_SUBMIT_LEN. | ||||||||||||||||||||||||||||||||||||
| -530 | DCX_INVALID_TIMEOUT |
DcxReadTransaction
DcxReadValidation DcxReadMsgLog |
The 'timeout' parameter was not valid. This parameter must be one
of the following:
| ||||||||||||||||||||||||||||||||||||
| -531 | DCX_INVALID_TONE_SPECIFIER | DcxInteractiveResponse | An invalid response beep has been specified. The beep value must be either DCX_INTER_BEEP or DCX_INTER_NO_BEEP. | ||||||||||||||||||||||||||||||||||||
| -532 | DCX_INVALID_TRANSID | DcxWriteTransaction | The .transid must contain a valid ASCII number in the range "001" through "255". | ||||||||||||||||||||||||||||||||||||
| -533 | DCX_LIST_TOO_LONG | DcxOpenValidation |
Indicates the list of validation files specified in the .VAL
parameter has a length longer than can be handled by DCConnect This length is
based on the length of internal messages and is in the range 450 to 500 bytes.
Make sure the list of validation files is terminated by a null character. Remember that in addition to the null character that follows each name in the list, another null is required after the last name and its null. | ||||||||||||||||||||||||||||||||||||
| -534 | DCX_STR_NOT_FOUND |
DcxInteractiveResponse
DcxWriteMsgLog |
For DcxInteractiveResponse, this indicates that the combination of text string
pointer and file number specified for DcxInteractiveTransResponse is invalid.
For DcxWriteMsgLog, this error indicates the pointer to the string passed in is NULL or points to an empty string. | ||||||||||||||||||||||||||||||||||||
| -535 | DCX_STR_TOO_LONG |
DcxExecuteTermTransaction
DcxDisplayTermText DcxInteractiveResponse DcxSetTermUserVariable DcxSetNTermUserVariables |
DetailsFor DcxExecuteTermTransaction, the program passed in was too long. The following values indicate the maximum program length for each terminal type:
For DcxDisplayTermText, the text cannot exceed the following values for each terminal type:
For DcxInteractiveResponse, the text cannot exceed the following values for each terminal type:
For DcxSetTermUserVariable, the text cannot exceed the following values for each terminal type:
| ||||||||||||||||||||||||||||||||||||
| -536 | DCX_INVALID_FUNCTION_GROUP |
DcxSubmitClientFiles
| The first parameter for DcxSubmitClientFiles was DCX_TARGET_FUNCTION_GROUP, but the second parameter is not a valid function group in the DCConnect configuration. Make sure the case of the function group name matches. |
These messages are displayed on the LCD for your 7525/7526 terminals. These messages may be changed from the System Message page of the Associations tab of the Terminal Settings notebook.
7525/7526 System Message 0000: | Normal Idle Prompt: Press a key |
Description: | This message is displayed when the terminal is idle, waiting for a transaction program to start. |
Action: | No action is required. This message text may be changed to suit your application. |
7525/7526 System Message 0001: | Input Prompt Time-out: Your time is up |
Description: | This message is displayed when it took too long for you to respond to a transaction program prompt. |
Action: | This message text may be changed to suit your application. You can increase the amount of time allowed by changing the Input Prompt Duration. The Input Prompt Duration is located on the Timeouts page of the Miscellaneous tab in the Terminal Settings notebook. |
7525/7526 System Message 0002: | Invalid Length: Length of input is incorrect |
Description: | This message is displayed the input length exceeds what the transaction program expects. |
Action: | This message text may be changed to suit your application. You should verify that you have the correct input length, and that your transaction program is also requesting the same length input. |
7525/7526 System Message 0003: | Invalid Data: Input data is invalid |
Description: | This message is displayed when the input data does not verify properly with the data that is in the verification file. |
Action: | This message text may be changed to suit your application. You should check to see if you are using the correct type of validation: in file or not in file. Ensure that you have the same length record for the verification data as is used for length in the command that is requesting verification of input data. |
7525/7526 System Message 0004: | Invalid Operation: Invalid Operation--press key first |
Description: | This message is displayed when a terminal is not set up for either Fast-Clocking or Badge-Initiated transactions, and a badge is read. |
Action: | This message text may be changed to suit your application. The only way to start a transaction by reading a badge is to either use fast clocking or badge initiated transactions. If you are not using either of these, then you must press a key, activate a DI point or use some other means to start a transaction at the terminal. |
7525/7526 System Message 0005: | Fast Clocking Prompt: Fast clocking now active |
Description: | This message is displayed when the terminal is configured such that fast clocking should be active and the current time is within one of the fast clocking time intervals that is defined in the terminal settings. |
Action: | This message text may be changed to suit your application. When it is not during the clock times specified for fast clocking, the Normal Idle Prompt is displayed. |
7525/7526 System Message 0006: | Waiting for Host Reply: Waiting for response from PC |
Description: | This message is displayed when a terminal is in Interactive mode. The terminal has sent data to the PC, and the PC's response has not yet been received. |
Action: | This message text may be changed to suit your application. You can increase the amount of time allowed by changing the Communications Timeout in the Terminal Settings notebook and then re-downloading the terminal. |
7525/7526 System Message 0007: |
|
Description: | This message is not used. |
Action: | No action is required. |
7525/7526 System Message 0008: | Good Prompt: Successful transaction |
Description: | This message is displayed when a terminal is in Buffered mode. The transaction at the terminal has been successfully completed. If the terminal is in Interactive mode, the message that is displayed when the transaction is first generated is whatever message 0006 has been defined to be. Then when the interactive response is sent to the terminal by DCConnect, the message displayed is whatever is specified by the application that issued the DcxInteractiveResponse API call for this terminal. The transaction buffering mode of a particular terminal can be changed in the terminal settings notebook. |
Action: | No action is required. This message text may be changed to suit your application. |
7525/7526 System Message 0009: | Link Prompt: Start next transaction program |
Description: | This message is displayed when a SF command is used to link to a second transaction program. |
Action: | This message text may be changed to suit your application. If you have a standard action you want the user to do at this point, for instance Press Key X, or Weigh an Item, then this message should be changed to reflect the transaction program that is going to be activated. |
These messages displayed on the LCD for your 7524/7527 terminals. These messages may be changed from the System Messages page of the Associations tab of the terminal settings notebook.
7524/7527 System Message 0000: | Normal Idle Prompt: Press a key |
Description: | This message is displayed on the bottom line when the terminal is idle, for example, waiting for a transaction program to start. |
Action: | No action is required. This message text may be changed to suit your application. |
7524/7527 System Message 0001: | Input Prompt Time-out: Your time is up |
Description: | This message is displayed when it took too long for you to respond to a transaction program prompt. |
Action: | This message text may be changed to suit your application. You can increase the amount of time allowed by changing the Input Prompt Duration. The Input Prompt Duration is located on the timeouts page of the miscellaneous tab in the terminal settings notebook and then re-downloading the terminal. |
7524/7527 System Message 0002: | Not Used |
Description: | The 7524/7527 allows for retry when invalid length input is detected. |
Action: | No action is required. |
7524/7527 System Message 0003: | Not Used |
Description: | For a failure of data to match verification data, you will get one of the following messages: 9611-9617. |
Action: | No action is required. |
7524/7527 System Message 0004: |
|
Description: | This message is not used. |
Action: | No action is required. |
7524/7527 System Message 0005: | Fast Clocking Prompt: Fast clocking now active |
Description: | This message is displayed when the terminal is configured such that fast clocking should be active and the current time is within one of the fast clocking time intervals that is defined in the Terminal Settings. |
Action: | This message text may be changed to suit your application. When it is not during the clock times specified for fast clocking, the Normal Idle Prompt is displayed. |
7524/7527 System Message 0006: | Waiting for Host Reply: Waiting for response from PC |
Description: | This message is displayed when a terminal is in Interactive mode. The terminal has sent data to the PC, and the PC's response has not yet been received. |
Action: | This message text may be changed to suit your application. You can increase the amount of time allowed by changing the Communications Timeout in the Terminal Settings notebook and then re-downloading the terminal. |
7524/7527 System Message 0007: |
|
Description: | This message is not used. |
Action: | No action is required. |
7524/7527 System Message 0008: | Good Prompt: Successful transaction |
Description: | This message is displayed when a terminal is in Buffered mode. The transaction at the terminal has been successfully completed. If the terminal is in Interactive mode, the message that is displayed when the transaction is first generated is whatever message 0006 above is defined to be. Then when the interactive response is sent to the terminal by DCConnect, the message displayed is whatever is specified by the application that issued the DcxInteractiveResponse API call for this terminal. The transaction buffering mode of a particular terminal can be changed in the Terminal Settings notebook. |
Action: | No action required. This message text may be changed to suit your application. |
7524/7527 System Message 0009: | Link Prompt: Start next transaction program |
Description: | This message is displayed when a SF command is used to link to a second transaction program. |
Action: | This message text may be changed to suit your application. If you have a standard action you want the user to do at this point, for instance Press Key X, or Weigh an Item, then this message should be changed to reflect the transaction program that is going to be activated. |
7524/7527 User Message 9000-9029: | Idle menu--line nn: Idle menu line nn |
Description: | The message text for these messages may be changed to suit your application. The idle screen messages can be defined on the Idle Prompts page of the Association tab of the Terminal Settings notebook. A 7527 model 1 terminal can have only one idle prompt. A 7527 model 2 or 7525 terminal can have up to 19 rows of idle prompts. However, if the 7527 model 2 is configured for a 14x32 display, only 13 idle prompts can be used. |
Action: | The text of these messages may be changed to suit your application. |
7524/7527 System Message 9030--9038: |
|
Description: | These messages are not used. |
Action: | No action is required. |
7524/7527 System Message 9039: | Buffer full message: Transaction buffer is full |
Description: | This message is displayed when a 7524/7527 terminal's buffer is full. |
Action: | This message text may be changed to suit your application. The amount of space available in the transaction buffer is based on the amount of space left over after programs, messages and other files are downloaded to the terminal or by how much memory is specifically allocated for the transaction buffer in the terminal settings. More terminal buffer space could be made available if the PC were allowed to poll transactions out of the buffer. Check to ensure that polling for this terminal has not been stopped, and that it is properly connected (cabled). |
7524/7527 System Message 9040: | Out of service message: Terminal is out of service |
Description: | This message is displayed when a 7524/7527 terminal has been put out of service or a download is in progress. |
Action: | This message text may be changed to suit your application. If the terminal should be able to accept transactions at this time, put it in service. |
7524/7527 System Message 9041: | Linked key cannot link: Can't link to program containing link |
Description: | A transaction program tried to link to another transaction program containing a link. |
Action: | This message text may be changed to suit your application. |
7524/7527 System Message 9042: | Message not in file 8: Message number not downloaded |
Description: | A transaction program tried to display a message number that was not downloaded for this terminal. |
Action: | This message text may be changed to suit your application. Ensure that the command issued displays the proper message number. |
7524/7527 System Message 9043: |
|
Description: | This message is not used. |
Action: | No action is required. |
7524/7527 System Message 9044: | RS-232 input-var len no end: RS-232 input: if variable len, need end message |
Description: | A transaction program tried to read variable length input, but no trailing data was defined. |
Action: | This message text may be changed to suit your application. If variable length data is read, then the terminal needs to know what to expect at the trailing end of the read. These ASCII characters need to be defined on the RS232 Device page of the Devices tab of the terminal settings notebook. |
7524/7527 System Message 9045: | RS-232 in--up to max len: RS-232 input: max length reached |
Description: | A transaction program tried to read input, but the read length was greater than the data length specified by the READ command. |
Action: | This message text may be changed to suit your application. If fixed length data is read, then the input should be equal to the length for the READ command. |
7524/7527 System Message 9047: | RS-232 timeout--no start: RS-232 timeout: no start found |
Description: | A transaction program tried to read RS-232 input, but no header characters were found. |
Action: | This message text may be changed to suit your application. If RS-232 data is read, then the terminal needs to know what to expect at the heading of the read. These ASCII characters need RS232 Device page of the Devices tab of the terminal settings notebook. |
7524/7527 System Message 9048: | RS-232 timeout--no end: RS-232 timeout: no end found |
Description: | A transaction program tried to read RS-232 input, but no trailer characters were found. |
Action: | This message text may be changed to suit your application. If RS-232 data is read, then the terminal must find the characters specified as trailing at the end of the read. These ASCII characters need to be defined on the RS232 Device page of the Devices tab of the terminal settings notebook. |
7524/7527 System Message 9049: | RS-232 length not matched: RS-232 timeout: length not matched |
Description: | A transaction program tried to do a fixed length read of RS-232 input, but the input length, and the length specified in the READ command is greater than what was input. The terminal waits for more characters and eventually times out. |
Action: | This message text may be changed to suit your application. Verify that you are reading the same length of data as is specified for the READ command. |
7524/7527 System Message 9051: | No messages when disabled: Message cannot be shown while disabled |
Description: | An error has occurred, but the error cannot be displayed because the terminal is currently out of service. |
Action: | This message text may be changed to suit your application. Put the terminal in service. |
7524/7527 System Message 9052: | RS-232 retry: RS-232 retry |
Description: | An error has occurred during an RS-232 read. |
Action: | This message text may be changed to suit your application. Try to read the data again. |
7524/7527 System Message 9053: | RS-232 invalid length: RS-232 invalid length |
Description: | A transaction program tried to do a fixed length read of RS-232 input, but the input length, and the length specified in the READ command do not match. |
Action: | This message text may be changed to suit your application. Verify that you are reading the same length of data as is specified for the READ command. |
7524/7527 System Messages 9611 to 9617: | Validation failed in file n |
Description: | The text of these messages may not be modified. A transaction was entered at the terminal that used validation of input data. The data entered did match exactly with what was entered into validation file n. |
Action: | Enter the input data again. Check to ensure that the validation data file contains the data that is entered. Also, ensure that the length of the validation data record is equal to the length specified on the transaction program command doing the validation. If the validation file has upper and lower case text, then upper and lower case text must match for validation to be successful. Ensure that you are using the proper form of validation. |
7524/7527 System Message 9671: Only numeric data valid. |
|
Description: | A transaction program tried to do an alphanumeric read from sensor or RS-232 input and the input specified in the READ command is numeric data from the sensor or RS-232 device. |
Action: | Enter only numeric data from the sensor or RS-232 device. |
7524/7527 System Messages 9672: No CFR downloaded |
|
Description:: | A transaction program tried to execute a CCFR command and there was no CFR downloaded in the 7524/7527 terminal. |
Action: | Check to ensure that the proper CFR file has been assigned to the terminal. |
An unsigned single-byte character.
A signed single-byte character.
A signed integer in the range -2147483648 through 2147483647.
A pointer to a character array which is not null-terminated.
DCConnect uses a PLISTZ data type to return lists of strings. The number and width of elements are variable.
The PLISTZ type is defined to be zero or more null-terminated strings of one or more characters, concatenated and terminated with an additional null character. If the list is empty, it must contain a single null character.
A pointer to a null-terminated character array. This is often referred to as a string.
A pointer to datatype USHORT.
A signed integer in the range -32768 through 32767.
An unsigned integer in the range 0 through 4294967295.
An unsigned integer in the range 0 through 65535.
The HREQ data type is used for the handle parameter required by the following Data Request APIs:
Note: Zero or any positive number is a potentially valid value for the handle when returned by DCConnect. If the application code needs to set a handle to be 'unused', it is recommended to use a negative value such as -1 for the initialized value of the handle.
A pointer to the HVAL data structure.
A pointer to the HREQ data structure.
A pointer to the HMSGLOG data structure.
A pointer to the VALIDREQUEST data structure.
A pointer to the TERMINFO data structure.
A pointer to the STATE data structure.
A pointer to the TRF data structure.
A pointer to the TRF2 data structure.
A pointer to the HTRANS data structure.
A pointer to the HTERM data structure.
typedef struct {
| PLISTZ | valdlist; /* Validation file list */ |
| USHORT | valdlen; /* Length of validation list */ |
| USHORT | valdcnt; /* # of files in list */ |
| CHAR | JobFile[DCX_OS_NAME_LEN + 1]; /* Job file name */ |
| CHAR | GphFile[DCX_OS_NAME_LEN + 1]; /* Graphics file name */ |
| CHAR | CfrFile[DCX_OS_NAME_LEN + 1]; /* CFR file name */ |
Refer to the description of the API DcxQueryJobInfo (See DcxQueryJobInfo) for more information about the use of this structure. Note that in DCC/2, for the API DccQueryClusterInfo and its structure DCCCLUSTERINFO, there was a field for the list of terminals using that cluster. In DCConnect, the terminal list is instead returned for the API DcxQueryJobTerms (See DcxQueryJobTerms) .
typedef struct {
| USHORT | model; |
| USHORT | rom_version; /* CMD 3 */ |
| USHORT | rom_revision; /* CMD 3 */ |
| USHORT | display_type; /* CMD 6 */ |
| USHORT | ram_kbytes; /* CMD 6 */ |
| USHORT | clock_status; /* CMD 6 */ |
| USHORT | gp_port_status; /* CMD 6 */ |
| USHORT | parallel_port_status; /* CMD 6 */ |
| ULONG | memory_free_bytes; /* CMD F */ |
| ULONG | largest_block_bytes; /* CMD F */ |
| USHORT | display_mode; /* CMD J9 */ |
| USHORT | touch_state; /* CMD J9 */ |
| USHORT | keylock_state; /* CMD J9 */ |
| USHORT | operating_mode; /* CMD J9 */ |
| USHORT | coprocessor_status; /* CMD J9 */ |
Definition for model.
| DCX_MODEL_7494_7525 | 7494-ELF with ROM upgrade or 7525 |
| DCX_MODEL_7526_100 | 7526 Terminal Model 100 |
| DCX_MODEL_7526_200 | 7526 Terminal Model 200 |
| DCX_MODEL_7527_1 | 7527 Terminal Model 001 |
| DCX_MODEL_7527_2 | 7527 Terminal Model 002 |
| DCX_MODEL_7524 | 7524 Terminal |
Definitions for display types.
| DCX_DISPLAY_2x40 | Two line by 40 character display |
| DCX_DISPLAY_APA | 320 x 200 Graphics display |
| DCX_DISPLAY_1x16 | Single line - 16 character display |
| DCX_DISPLAY_1x32 | Single line - 32 character display |
| DCX_DISPLAY_1x40 | Single line - 40 character display |
Definitions for clock status.
| DCX_CLOCK_AVAILABLE | Terminal contains clock |
| DCX_CLOCK_UNAVAILABLE | Terminal does not contain a clock |
Definitions for GP port status.
| DCX_GP_AVAILABLE | Terminal contains GP RS-232 port |
| DCX_GP_UNAVAILABLE | Terminal does not contain GP RS-232 port |
Definition for parallel port (7526 and 7527 terminals only).
| DCX_PORT_IS_PRINTER | Parallel port setup for printer |
| DCX_PORT_IS_DIDO | Parallel port setup for DIDO |
Definition for display mode (7526 and 7527 terminals only).
| DCX_ONE_LINE_MODE | Display is 7526 Model 100 one-line |
| DCX_TWO_LINE_MODE | Display is 7526 Model 200 or 7527 Model 100 two-line |
| DCX_GRAPHICS_NORMAL_MODE | Display is 7527 Model 002 in normal video mode |
| DCX_GRAPHICS_REVERSE_MODE | Display is 7527 Model 002 in reverse video mode |
Definition for touch screen (7527 terminal only).
| DCX_TOUCH_ENABLED | Touch screen is enabled |
| DCX_TOUCH_DISABLED | Touch screen is disabled |
Definition for keylock state (7527 terminal only).
| DCX_LOCKED | Keylock in locked stated |
| DCX_UNLOCKED | Keylock in unlocked state |
Definition for coprocessor status (7526 terminal only).
| DCX_COPROC_AVAILABLE | Coprocessor installed on terminal |
| DCX_COPROC_UNAVAILABLE | Coprocessor not installed on terminal |
Definition for terminal operating mode (7526 terminal only).
| DCX_7525_MODE | Terminal is operating in 7525 compatibility mode |
| DCX_ENHANCED_MODE | Terminal is operating in enhanced mode |
Definitions for model
| DCX_MODEL_7494_7525 | 7494-ELF with ROM upgrade or 7525 |
| DCX_MODEL_7526_100 | 7526 Terminal Model 100 |
| DCX_MODEL_7526_200 | 7526 Terminal Model 200 |
| DCX_MODEL_7527_1 | 7527 Terminal Model 001 |
| DCX_MODEL_7527_2 | 7527 Terminal Model 002 |
| DCX_MODEL_7524 | 7524 Terminal |
| DCX_MODEL_DOS_WIN | DOS or Windows DCT |
| DCX_DISPLAY_1x16 | Single line - 16 character display |
| DCX_DISPLAY_1x32 | Single line - 32 character display |
| DCX_DISPLAY_1x40 | Single line - 40 character display |
| DCX_DISPLAY_2x40 | Two line by 40 character display |
| DCX_DISPLAY_APA | 320 X 200 Graphics display |
| DCX_CLOCK_AVAILABLE | Terminal contains clock |
| DCX_CLOCK_UNAVAILABLE | Terminal does not contain clock |
| DCX_GP_AVAILABLE | Terminal contains GP RS-232 port |
| DCX_GP_UNAVAILABLE | Terminal does not contain GP RS-232 port |
| DCX_PORT_IS_PRINTER | Parallel port setup for printer |
| DCX_PORT_IS_DIDO | Parallel port setup for DIDO |
| DCX_ONE_LINE_MODE | Display is 7526 Model 100 one-line |
| DCX_TWO_LINE_MODE | Display is 7526 Model 200 or 7527 Model 001 two-line |
| DCX_GRAPHICS_NORMAL_MODE | Display is 7527 Model 002 in normal video mode |
| DCX_GRAPHICS_REVERSE_MODE | Display is 7527 Model 002 in reverse video mode |
| DCX_TOUCH_ENABLED | Touch screen is enabled |
| DCX_TOUCH_DISABLED | Touch screen is disabled |
| DCX_LOCKED | Keylock in locked state |
| DCX_UNLOCKED | Keylock in unlocked state |
| DCX_COPROC_AVAILABLE | Coprocessor installed on terminal |
| DCX_COPROC_UNAVAILABLE | Coprocessor not installed on terminal |
| DCX_7525_MODE | Terminal is operating in 7525 compatibility mode |
| DCX_ENHANCED_MODE | Terminal is operating in enhanced mode |
typedef struct {
| CHAR | seq[DCX_TRF_SEQLEN] |
| CHAR | loc[DCX_TRF_LOCLEN] |
| CHAR | line[DCX_TRF_LINELEN] |
| CHAR | address; |
| CHAR | termname[DCX_TRF_TERMNAMELEN + 1] |
| CHAR | job[DCX_TRF_JOBLEN + 1] |
| CHAR | termseq[DCX_TRF_TERMSEQLEN] |
| CHAR | year[DCX_TRF_YEARLEN] |
| CHAR | month[DCX_TRF_MONTHLEN] |
| CHAR | day[DCX_TRF_DAYLEN] |
| CHAR | hour[DCX_TRF_HOURLEN] |
| CHAR | minute[DCX_TRF_MINUTELEN] |
| CHAR | second[DCX_TRF_SECONDLEN] |
| CHAR | mode; |
| CHAR | transid[DCX_TRF_TRANSIDLEN] |
| CHAR | datalen[DCX_TRF_DATALENLEN] |
| CHAR | txdata[DCX_TRF_TXDATALEN] |
See Transaction Record Format (See Transaction Record Format) for more information on the data returned.
typedef struct {
| CHAR | seq[DCX_TRF_SEQLEN] |
| CHAR | loc[DCX_TRF_LOCLEN] |
| CHAR | line[DCX_TRF_LINELEN] |
| CHAR | address; |
| CHAR | termname[DCX_TRF_TERMNAMELEN + 1] |
| CHAR | job[DCX_TRF_JOBLEN + 1] |
| CHAR | termseq[DCX_TRF_TERMSEQLEN] |
| CHAR | year[DCX_TRF_YEAR4LEN] |
| CHAR | month[DCX_TRF_MONTHLEN] |
| CHAR | day[DCX_TRF_DAYLEN] |
| CHAR | hour[DCX_TRF_HOURLEN] |
| CHAR | minute[DCX_TRF_MINUTELEN] |
| CHAR | second[DCX_TRF_SECONDLEN] |
| CHAR | yearAdj[DCX_TRF_YEAR4LEN] |
| CHAR | monthAdj[DCX_TRF_MONTHLEN] |
| CHAR | dayAdj[DCX_TRF_DAYLEN] |
| CHAR | hourAdj[DCX_TRF_HOURLEN] |
| CHAR | minuteAdj[DCX_TRF_MINUTELEN] |
| CHAR | secondAdj[DCX_TRF_SECONDLEN] |
| CHAR | mode; |
| CHAR | transid[DCX_TRF_TRANSIDLEN] |
| LONG | datalen; |
| CHAR | txdata[DCX_TRF_TXDATALEN_EX] |
See Extended Transaction Record Format (See Extended Transaction Record Format) for more information on the data returned.
typedef struct {
| UCHAR | post_status; |
| UCHAR | command_status; |
| UCHAR | download_status; |
| UCHAR | terminal_state; |
| UCHAR | error_status; |
| UCHAR | command[2] |
| UCHAR | xcommand_status[2] |
| UCHAR | file_id[2] |
| UCHAR | buffer_status; |
Refer to the discussion on CMD 1 in 7527 Extended Terminal Services Technical Reference, the 7525 Data Collection Terminal Physical Planning and Operations Guide, the 7526 Data Collection Terminal Programming Technical Reference, or the 7524 Extended Terminal Services Technical Reference for information on the values returned in this structure.
typedef struct {
| USHORT | datalen; |
| CHAR | data[DCX_VAL_DATA_LEN] |
| CHAR | filename[DCX_VAL_FILE_LEN + 1] |
| CHAR | termname[DCX_TERM_NAME_LEN + 1] |
The fields contained in the VALIDREQUEST structure are:
| datalen | Length of the data to be validated in the data field. |
| data | Data to be validated. |
| filename | The null-terminated name of the validation file to be used or referenced. |
| termname | The null-terminated name of the terminal which originated the request. |
typedef struct {
| UCHAR | service; |
| UCHAR | polled; |
| UCHAR | operation; |
| UCHAR | step; |
Refer to the description of the API DcxReportTerminalState (See DcxReportTerminalState) for more information about the use of this structure.
typedef struct {
| LONG | notread; |
| LONG | notreleased; |
| CHAR | active; |
| CHAR | logfile[DCX_OS_NAME_LEN + 1] |
| LONG | size; |
Refer to the description of the API DcxQueryMailbox (See DcxQueryMailbox / DcxQueryMailboxEx) for more information about the use of this structure.
typedef struct {
| LONG | notread; |
| LONG | notreleased; |
| CHAR | active; |
| LONG | size; |
| CHAR | logfile[DCX_OS_NAME_LEN + 1] |
| LONG | percentfull; |
Refer to the description of the API DcxQueryMailboxEx (See DcxQueryMailbox / DcxQueryMailboxEx) for more information about the use of this structure.
typedef struct {
| CHAR | name[DCX_OS_NAME_LEN + 1] |
| LONG | size; |
Refer to the description of the API DcxQueryMsgLog (See DcxQueryMsgLog) for more information about the use of this structure.
This type is used for the handle parameter required by the following Transaction Data Access APIs:
Note: 0 or any positive number is a potentially valid value for the handle when returned by DCConnect. If the application code needs to set a handle to be 'unused', it is recommended to use a negative value such as -1 for the initialized value of the handle.
This type is used for the handle parameter required by many of the Terminal Access APIs. This is the 'acquire' handle that must be used by applications that have used DcxAcquireTerminal (See DcxAcquireTerminal) to gain exclusive access to a terminal. If the application has not acquired the terminal, then this handle parameter should be set to 0.
For all API calls that use this handle, certain return codes will be given if the handle value is not set properly:
Note: 0 or any positive number is a potentially valid value for the handle when returned by DCConnect. If the application code needs to set a handle to be 'unused', it is recommended to use a negative value such as -1 for the initialized value of the handle.
This type is used for the handle parameter required by the following Validation APIs:
Note: 0 or any positive number is a potentially valid value for the handle when returned by DCConnect. If the application code needs to set a handle to be 'unused', it is recommended to use a negative value such as -1 for the initialized value of the handle.
This type is used for the handle parameter required by the following System Message Log APIs:
Note: 0 or any positive number is a potentially valid value for the handle when returned by DCConnect. If the application code needs to set a handle to be 'unused', it is recommended to use a negative value such as -1 for the initialized value of the handle.