ComputerWise -- DCDOS

DCDOS - Data Capture Program

Program Reference Manual

CONTENTS: Overview; Version History; Theory of Operation; Attached Devices; Starting the Program; Prompting Logic; Alarm Events; Configuration File; Console Section; Files Section; Defaults Section; Alarms Section; Configuration Debugging; Event Log File; Error handling

The DCDOS program (DCDOS.EXE) is a data collection program that runs under the DOS operating system. Data can be captured directly from the computer keyboard/display or from a data collection device attached to a serial port on the computer. The program can present the operator with a logical series of programmable prompts. Operator responses can be validated and captured into records stored in ASCII delimited file(s). Applications include (but are not limited to):

Factory floor data collection
Time & Attendance
Access control

Version History

The DCDOS program has undergone, and will continue to undergo, upgrades and enhancements. The following table provides an overview of the program evolution.

Version Date Enhancements

1.10 02/15/1999 Add Alarm event capability.

1.00 07/28/1998 Original Version.

Theory of Operation

The DCDOS program is controlled by a configuration file which is read when the program is started. This file contains all of the prompting logic, operating parameters, and data storage information for program execution. When the program is started a default prompt message is presented to the operator. The operator can respond to the default prompt or use function keys to direct the program to a new series of prompts.

Once the operator enters a response it can be validated by input parameters and/or by a validation file entry. If the response passes all validation tests the next logical prompt is presented to the operator. Valid responses can trigger a special operation such as activation of the bell or a relay. If the response fails any validation test an error prompt can be presented to the operator.

Valid operator responses can be included as a data field in a captured data record. The response data field associated with each prompt can trigger the beginning of a new data record and/or saving of the data record to the data capture file. Each captured data record can include one or more response data fields and any combination of program record fields including a "prompt response type", "time stamp", "date stamp", "prompt number", or "record sequence number". Captured data records are stored in an ASCII delimited data file defined by the associated prompt.

The captured data file(s) can be stored locally or on a network file server. If data records cannot be stored in the specified primary device/path file (i.e. it becomes unavailable) they will be stored in the backup device/path file. If data records are stored in backup data files the DCDOS program will periodically check for the availability of the primary device storage path. When (if) it becomes available the backup file(s) will be copied to the primary device and the backup copies will be deleted.

In addition to capturing operator response data the DCDOS program can trigger alarm events which are typically used to activate the bell or a control relay. Alarms can be used to signal the beginning/ending of a work period or to start/stop a control process.

Attached Devices

One of the primary uses of the DCDOS program is to capture data from a data collection device connected to a serial port on the host computer. The DCDOS program can run as a background task capturing operator input and storing it to the data capture file(s). Examples of attached RS-232 devices include (but not limited to):

Data collection terminals (TransTerm 4 or TransTerm 5)
Bar Code or Magstripe readers (TSD1)
Scanners, Scales, or CRT terminals

Starting the Program

The DCDOS program (DCDOS.EXE) is started from the DOS prompt using the following format:

C:> DCDOS <configuration file name>

The configuration file name has a default extension (.CFG) and can be excluded. If no configuration file is specified the program will assume use of the default configuration file "DCDOS.CFG". If this file does not exist the program can only run with program default values (which normally will not be very useful). The DCDOS program can be used for any number of different applications by simply specifying a different configuration file name.

Prompting Logic

The DCDOS program is controlled by parameters in a configuration file which is specified when the program is started. Each prompt entry in the configuration file has a unique prompt number and contains parameters defining how the prompt is to be displayed, controlled, and logically sequenced to another prompt. This allows for an extremely flexible and powerful prompting system.

The prompting sequence is controlled by specifying which prompt number to use next. Each prompt includes a parameter defining the next prompt to use, thus creating a logical sequence. Function keys can be assigned a specific prompt number to force a "jump" to begin a new prompt sequence. A response validation file can be used with a field to force a "jump" based on the operator input. Response validation errors can also force a "jump" to an error prompt. In addition, each prompt can be enabled with a timer to force a "jump" if no operator input occurs within a given amount of time.

Each prompt entry includes a prompt message and location used to display the prompt on the input device screen. The operator prompt response can be validated by an entry in a specified ASCII text file and/or by alpha-numerical value limits. Storage parameters for the response data can be defined uniquely for each prompt. Each prompt can include options for special events such as a response timer, bell activation, and relay output control.

Alarm Events

The DCDOS program can also activate asynchronous alarm events. When the DCDOS program is started the program configuration file is scanned to create an alarm table. During program execution the table is scanned every minute looking for entries with a matching time of day. When a match is found the alarm is triggered and the specified output is activated. The duration of the activated alarm is adjustable and has a one second resolution.

Configuration File

The heart of the DCDOS program control is the configuration file. This file is specified as a command line argument when the program is started.

The default configuration file ("DCDOS.CFG") contains values for the DCDOS program defaults and can be modified for a particular application. However, it is best to use this file as a template for other application configurations. Copy the file to a new file name, change the specific parameter values, add additional prompt data, and start the DCDOS program with the new configuration file. The default file name extension (".CFG") can be omitted on the command line. Some example files are included with the program.

The configuration file is a typical ASCII parameter file with section names identified within square brackets ("[" "]") and parameter names followed by an assignment character ("=") followed by the parameter value. Comment lines can be included in the configuration file by preceding them with the comment delimiter character (";"). When the DCDOS program requires a new parameter from this file it must sequentially read the entries from the beginning of the file. Therefore, it is a good practice to keep comment lines to a minimum to enhance program execution speed.

Each section in the configuration file is delimited by a section name (for example, "[Console]"). Parameters in each section are unique to the section and are grouped by the specific program function they perform. Every prompt will have it's own section of parameters and the section name is constructed from the prompt number preceded by the pound character (for example, "[#23]"). The prompt sections can be placed at the beginning of the file to enhance program execution.

All section parameters are optional and any parameter not specified will use the DCDOS program default for that parameter. Parameters will be unspecified if they are omitted from the configuration file or if the assigned value (after the "=") is left blank. Following is a list of configuration parameters grouped by section names. The program default values are included and a detailed explanation of each parameter is provided.

Console Section

This section specifies the operator input/display device. These parameters are read once when the program is started.

ConsolePort=CON Defines the console I/O device. Normally, this would be set to the DOS default console device (CON) or to a serial port (COM1 or COM2) for an attached device. If set to SCREEN it will default to the computer keyboard/display monitor (useful for debugging).

Emulation=ANSI Defines the console terminal emulation. Normally, this would be set to the emulation mode of the attached console device (ConsolePort = CON, COM1, or COM2). Valid parameters include ANSI (default), TransTerm (TT4, TT5, TT6, or TT9), or left blank (use default).

DisplayRows=2
DisplayCols=24
Total number of rows and columns on the console display device.

EnterKey=13 Decimal value of the ASCII character used for the "ENTER" function. The default is the ASCII <CR> code.

BackspaceKey=8 Decimal value of the ASCII character used for the "BACKSPACE" function. The default is the ASCII <BS> code.

ClearKey=24 Decimal value of the ASCII character used for the "CLEAR SCREEN" function. The default is the ASCII <CAN> code (control X).

EndKey=26 Decimal value of the ASCII character used for the "PROGRAM EXIT TO DOS" function. The default is the ASCII <SUB> code (control Z).

FunctionKey=70 Decimal value of the ASCII character used to identify a function key input. A function key is identified as this character code followed by a decimal value. For example "F2" would equal function key number 2. The default is the ASCII <F> code.

TimeFormat=0 Format of automatic display the current time.
0 - no time displayed
1 - hh:mm
2 - hh:mm:ss

TimeRow=1
TimeCol=1
Row & column position to display the current time. If either of these values is invalid the time will not be displayed.

DateFormat=0 Format of automatic display the current date.
0 - no date displayed
1 - mm/dd
2 - mm/dd/yy
3 - mm/dd/yyyy
4 - dd/mm
5 - dd/mm/yy
6- dd/mm/yyyy

DateRow=1
DateCol=1
Row & column position to display the current date. If either of these
values is invalid the date will not be displayed.

Files Section

This section specifies the application environment files and paths. These parameters are read once when the program is started.

DataPath= Defines the primary path where data files are to be stored. This path can be either a local disk drive and/or path or it can be a mapped network device and/or path. The path name must include a trailing "\" if used.

BackUpPath= Defines the backup path where data files will be stored if the primary path becomes unavailable. Normally, this path would point to a local drive because it is only used for backup. The path name must include a trailing "\" if used.

BackUpTime=300 The time delay (in seconds) when the "DataPath" will be retested when data has been redirected to the "BackUpPath". The timer is restarted by any console activity to avoid interrupting operator input.

PromptFile= Defines an alternate file name used for the prompt data. Normally, the prompt data is included in the configuration file. However, an alternate prompt data file can be specified if desired.

FirstPrompt=0 Defines the first prompt to be displayed when the program starts. Normally, this would point to the default prompt (0) but could point to any valid prompt in the configuration file. If the specified prompt number is not found in the configuration file the default prompt is used.

Defaults Section

This section specifies the default prompt parameters and is read once when the program is started. Every time a new prompt is selected by the DCDOS program it resets all the program prompt variables with these values. Then the program will load the variables from the configuration file for the specified prompt. Any, all, or none of these parameters can be included in the individual prompt sections. Any prompt parameters found in the specified prompt section will overwrite the program variables with new values and then display the new prompt.

PromptMessage= Displayed prompt message string.

PromptRow=1
PromptCol=1
Row & column where the prompt message will be displayed on the console device screen.

ResponseRow=0
ResponseCol=0
Row & column where the cursor will be positioned ready for operator response. If either value is "0" the cursor will be left at the end of the prompt message.

NextPrompt=0 Number of the next prompt to use if all validation tests (if any) are successful. A value of "0" or an invalid prompt number will force use of the default prompt.

ValidateMode=0 Defines what validation mode will be used for the response input.
0 - no validation required (all responses valid)
1 - any response is valid (null response invalid)
2 - validation file (ASCII file defined by ValidateFile)
3 - within limits (defined by ValidateLimit1 and ValidateLimit2)

ValidateFile= Name of ASCII file used to validate response (if ValidateMode=2). If the file cannot be found or if no matching entry exists the response is invalid. A second field can be included in each record (following a comma delimiter) that defines the next prompt to use.

ValidateLimit1=0
ValidateLimit2=0
Limits for alpha-numeric ASCII compare to validate response (if ValidateMode=3). The response is valid if the following equation is true: ValidateLimit1 <= response <= ValidateLimit2.

ValidatePrompt=0 Number of the next prompt to use if any validation test fails. A value of "0" or an invalid prompt number will force use of the default prompt.

TimeExpired=0 Time out expiration value (in seconds) for the displayed prompt. If no operator response has been received within the amount of time specified the time out prompt (TimePrompt) will be displayed. If this value is "0" the displayed prompt will never time out.

TimePrompt=0 Number of the next prompt to use if current prompt timer expires. A value of "0" or an invalid prompt number will force use of the default prompt.

Fkey1=0 (to)
Fkey10=0
Number of next prompt to use when operator response is a function key. This is useful to create a "jump" to a new prompt sequence.

NewRecord=1 If non-zero will cause the response to begin a new data capture record. Normally, this would be set for the first prompt of a new sequence. A value of "0" will cause the response to be included in the current data capture record.

SaveResponse=1 If non-zero will cause the response data to be included as a data field in the current data capture record. A value of "0" can be used to trigger another prompt without saving the response.

SaveRecord=1 If non-zero will cause the accumulated data capture record to be written to the data capture file. Normally, this would be set for the last prompt in a sequence to save an entire data capture record.

PromptField=0 If non-zero will cause the prompt number to be included in the data capture record with a saved response field.

ResponseType= ASCII character string included with a saved response field. This can be useful to post-processing programs to identify what kind of data the response represents. If no string is defined no response type field will be included with the saved response.

SequenceField=0 If non-zero will precede the saved data record with a record sequence number. This number is incremented for every saved record and can be used by a post processing program to logically analyze the captured data.

TimeField=0 Record time stamp format. Used to define if/how a time stamp field is to be included in the saved data record.
0 - no time stamp field
1 - hh:mm
2 - hh:mm:ss

DateField=0 Record date stamp format. Used to define if/how a date stamp field is to be included in the save data record.
0 - no date stamp field
1 - mm/dd
2 - mm/dd/yy
3 - mm/dd/yyyy
4 - dd/mm
5 - dd/mm/yy
6- dd/mm/yyyy

FieldDelimiter=44 Decimal value of the ASCII character used as the data record field delimiter. Every field in a saved data record will be delimited with this character. The default is the ASCII <,> comma.

DataFile= File name use to store the saved data record. This file name will be combined with the DataPath (or BackUpPath) parameter to define where the data file resides. Normally, this parameter is not specified by individual prompt sections and all data is captured into a single data file. However, it is possible to save data records in multiple files for specific applications if desired.

ActivateBell=0 If non-zero will issue an ASCII <BEL> bell code when a response has been entered.
0 - No bell
1 - Activated on valid response
2 - Activated on invalid response

Relay1=0 (to)
Relay4=0
Amount of time (in seconds) to activate a relay in an attached device when a valid response has been entered. Requires attached device to be equipped with control relays.

Alarms Section

This section specifies the definitions to create the alarm events table. Each AlarmSet parameter will create one table entry using the last specified AlarmRelay and AlarmTimer values. Multiple set parameters are used to create different alarm time entries. More than one relay and/or duration timer value can be used as long as the parameters are placed in the configuration file ahead of the set parameters that will use the values.

AlarmRelay=1 Defines which relay will be activated when an alarm triggered. If no valid relay number (1 to 4) is specified the alarm will activate the bell. This parameter should be set before any of the AlarmSet parameters.

AlarmTimer=3 Defines the active duration of the relay when an alarm is triggered. The value is in seconds and must be greater than zero or the alarm will not trigger. This parameter should be set before any of the AlarmSet parameters.

AlarmSet=12:00 Creates an entry in the Alarm Table using the last defined AlarmRelay and AlarmTimer values. The format of the alarm trigger time is "hh:mm" with a range of "00:00" to "23:59".

Configuration Debugging

Configuration files can be tested and debugged directly on a PC running a DOS session. The "ConsolePort" parameter in the "[Console]" section should be set to SCREEN. In this mode, the PC keyboard and monitor are used for the DCDOS program console. Prompting logic, validation testing, and data storage can all be evaluated directly on the PC. Relay control functions are ignored in this mode.

Event Log File

The DCDOS program will maintain an event log file (DCDOS.LOG) to record major events during program execution. Each recorded event includes a current time and date stamp. Start and Stop events are recorded when the program is started and stopped. Program errors will record an error event in the log file. If data storage is redirected to the backup path an event is recorded for the backup and the redirection back to the primary path.

Error Handling

Most program errors will be handled within the program and will be recorded in the Event Log File. However, if a non-recoverable error occurs an error message will also be displayed on the program console and the program will be terminated.