ISI-52-110
PROGRAM MAINTENANCE MANUAL FOR
THE DATA COLLECTION SYSTEM
AUTOMATIC PROCESSING SYSTEM (DAPS)
DOMESTIC SATELLITE (DOMSAT)
RECEIVE ONLY TERMINAL (DROT)
DOMSAT QUALITY MONITOR (DQM)
April 1991
INTEGRAL SYSTEMS, INC.
5000 Philadelphia Way, Suite A
Lanham, MD 20706
NOTICE
The Government's DOC NOAA/NESDIS has developed a baseline DOMSAT Receive Only Terminal (DROT). The DROT software and its corresponding documentation are being made available to the DCS user community at no charge.
The documentation provided herein is believed to be true and correct as of the date of issuance. This material details the baseline software coding for the DROT. The Government assumes no liability as to the accuracy of this documentation and no responsibility as to its maintenance resulting from the DCS user community or after market DCS equipment supplier modification, enhancement, etc. Should the Government change or modify the DROT software, updates to this documentation will be available to the DCS DROT user community at itervals deemed appropriate by the Government.
#1
Purpose
This document provides all the information necessary to install, build, configure, and maintain the Domestic Satellite (DOMSAT) Receive Only Terminal (DROT) and the DOMSAT Quality Monitor (DQM). A single manual is provided for both systems because of the many overlapping software modules. DCS users need not be concerned with sections dealing with the DQM.
It is assumed that readers of this manual are familiar with the UNIX environment and the C programming language.
The National Environmental Satellite, Data, and Information Service (NESDIS) manages, operates and maintains the U.S. Geostationary Operational Environmental Satellite (GOES) system. The GOES system's primary mission is to continuously observe changing weather phenomena from satellite based sensors situated approximately 23,000 miles from Earth. As a collateral duty, the GOES system supports a radio relay or Data Collection System (DCS). The DCS enables a large variety of environmental data to be relayed from point sources, Data Collection Platforms (DCP), which are land, sea, or mobile based through GOES and back to Earth, from where these data are disseminated to the various system users.
The DCS Automated Processing System (DAPS) was developed for the National Oceanic and Atmospheric Administration (NOAA) to support the increased volume and complexity of the DCS since its inception. The DAPS now supports the receipt of messages from up to 100,000 platforms and can redistribute them to up to 5,000 users.
The primary means of data dissemination on the old DCS were telephone circuits. In the new DAPS this has been changed to a leased channel on a GE Americom, K-1, Ku-band domestic communications satellite (DOMSAT). The DAPS is located at the NOAA Command and Data Acquisition (CDA) facility at Wallops Island, Virginia. From here platform messages are continuously broadcast using a subset of the X.25 protocol at 56,000 bits per second (56 Kbps). The data stream is received by the DOMSAT Quality Monitor (DQM), also at Wallops, where it is checked for completeness and transmission quality. The DQM will inform the DAPS of messages containing transmission errors so they can be automatically scheduled for retransmission.
To utilize DAPS DOMSAT DCS users require a Ku-band receiving station, an industry-standard 386/PC running the UNIX(1) operating system and custom DROT software provided by the Government, and a Franklin ICP188C intelligent communications card. Figure 2-1 illustrates the data path from the DCP through the DAPS and to the user's DROT.
DCP messages are broadcasted by the DAPS in a subset of the X.25 protocol. The protocol provides the DQM with a CRC check and sequence check for each incoming packet. Furthermore, each DCP message is transmitted with a 16-bit message sequence number which continually increments from one message to the next, wrapping around from 65,535 to 0. The DQM uses all of this information to check for CRC errors, missing X.25 packets, and missing DCP messages.
The DQM is connected directly to the DAPS via a serial line, operated asynchronously at 9600 baud. Through this serial line, the DQM sends the following three types of 'quality reports' to DAPS:
o CRC Error Reports indicate that CRC errors were found on a contiguous range of messages. The first and last message sequence numbers of the range are included in the report.
o Sequence Error Reports indicate that a contiguous range of DCP messages was missing or contained packet sequence errors. The first and last message sequence numbers of the range are included in the report.
o Periodic Reports are sent once per minute to the DAPS. They include the message sequence number of the last good message received.
(1) UNIX is a registered trademark of AT&T. DATA PATH OF DCP MESSAGE FROM DCP TO USER
The DROT is designed for continuous operation and can selectively archive messages from up to 1,600 platforms specified by the user. The amount of disk storage used by the DROT can be configured by individual users depending upon their local requirements and capacities. The default at installation is 20 million bytes, which should hold several days-worth under normal operation. While data is being received, the user can search for desired messages based on a variety of criteria such as time of arrival, originating platform, etc. Desired messages can then be displayed on the CRT screen, printed, saved to separate storage on the hard (or floppy) disk, or transmitted to a local host via RS-232 Output Interface.
Many users have their own local processing facilities hence the DROT will be used primarily as a front-end filter/translator to selectively extract desired messages and forward them to another computer via a serial output interface using one of several protocols. This can be done in real-time (as the messages are received), or manually at periodic intervals. To do this manually the user will use the non-real-time features of the DROT to search for any new DCP messages which may have arrived, and then to display, print, save-to-disk, or forward these messages via the serial output interface.
Hardware Overview
Section 3.1.1 describes the specific hardware used in the DQM and in the DROT prototype. DCS users need not use the exact hardware listed here to run the DROT software. Section 3.1.2 lists the minimum DROT hardware configuration.
DQM and DROT Prototype Components
The DQM and the DROT prototype consist of the following hardware components:
o NEC PowerMate(TM) 386Computer (PC/AT bus)
o 4 megabytes of RAM
o Two RS-232 serial ports (DB-9)
o One parallel printer port
o One high-density (1.2 MB) floppy disk drive
o 66 MB hard disk
o 101-Key Keyboard
o VEGA Video Seven (EGA compatible) video controller
o NEC MultiSync II Color Monitor
o Franklin Telecom ICP188C Communications Processor o ComStream LNB (Low Noise amplifier/downconverter Block)
o ComStream DBR401 (Digital Broadcast Receiver)
o RS-422 to RS-232 converter box
o a small paraboloidal reflecter (1.8 meter recommended)
The DQM system unit and monitor are rack-mounted into the center rack of the DAPS. The non-rack-mounted DROT prototype also resides at Wallops with hardware identical to the DQM. The DROT prototype can serve as a backup DQM in the event of failure.
Minimum DROT Hardware Requirements
The following hardware is necessary to run the DROT software:
o Industry Standard 386Computer (PC/AT/EISA bus)
o At least 8 megabytes of RAM
o One RS-232 serial port
o One parallel printer port
o One high-density (1.2 MB) floppy disk drive
o Hard disk of at least 100 MB for 20 MB of DCP message storage (140 MB if Development System installed)
o Keyboard
o Any standard video controller and monitor (HGC, CGA, EGA, or VGA)
o Printer
o *Franklin Telecom ICP188C Communications Processor o **ComStream LNB (Low Noise amplifier/downconverter Block)
o **ComStream DBR401 (Digital Broadcast Receiver)
o RS-422 to RS-232 converter box
o a small paraboloidal reflecter (1.8 meter recommended)
The vendor supplied software consists of the ***SCO UNIX System V/386 Operating System and Development System. The delivered revision is Release 3.2v2.0.
The operating system contains the run-time kernel, hierarchical file system, command interpreters, support for many devices, and a large collection of utility programs. The development system contains a C-Language compiler, 80386 assembler, and various debugging and development tools.
* Available from Franklin Datacom, 733 Lakefield Rd., Westlake Village, CA 91361, (805) 373-8688.
** Available from ComStream Corporation, 10180 Barnes Canyon Road, San Diego, CA 92121, (619) 458-1800
*** Available from The Santa Cruz Operation, Inc., 400 Encinal St., P.O. Box 1900 Santa Cruz, CA 95061, (800) 626-8649.
DEVELOPMENT ENVIRONMENT
This section describes how to set up the environment necessary to do development or maintenance work on the DROT or DQM software. This includes such things as operating system installation, source code installation, directory structure, and the major development utilities used.
UNIX Installation
The SCO UNIX System Administrator's Reference provides instructions for the installation of the operating system and development system. The installation program provides on-screen instructions and a series of configuration menus. For the configuration choices appropriate for the DROT and DQM see the User Interface Manual for the DAPS DROT or the Operating User Interface Manual for the DAPS DQM.
Source Code Installation
The source code for the DROT and DQM is distributed on two1.2 MB 5-1/4 inch floppy disks labeled DOMSAT RECEIVE ONLY TERMINAL SOURCE CODE.
To set up the source code directories, first create a new user called "daps" (see the chapter on Administering User Accounts in the SCO UNIX System V/386 Operating System System Administrator's Guide. Then log in as "daps".
The source code floppy was created and is read using the UNIX 'tar' utility. After loging in as "daps", place the first disk in the floppy drive and type the command:
tar xv2
This will extract the source code and create the necessary sub-directories. After the first disk has been read, you will be prompted fro the second disk.
Source Code Directory Structure
Figure 4-1 depicts the directory structure for development of DROT/DQM code.
Source Code Control System Utilities
All versions of UNIX System V come with a collection of utilities called the "Source Code Control System" (SCCS). These utilities help to manage the various versions of code as it is developed and updated. See the UNIX System V/386 Development System Programmer's Guide for a complete description of SCCS.
When a source file is changed and saved under SCCS, only the differences from the previous version are saved (along with dates and other administrative information). This enables the developer to retrieve any previous version of the file at any time by specifying its unique version number.
The SCCS utilities work at a very low level and expect rather cryptic file-names as arguments. For this reason several UNIX shell-procedures have been included with the DROT/DQM to make the SCCS interface less unwieldy. These shell-procedures are all found in the 'sccs' subdirectory. The following paragraphs describe these procedures in detail.
DROT/DQM DEVELOPMENT DIRECTORY STRUCTURE
sccscreate
Usage: sccscreate <file1> <file2> ...
This creates the initial delta for the named source files. The resulting SCCS files are stored in the 'SCCS' sub-directory to the current directory.
sccsedit
Usage: sccsedit <file1> <file2> ...
This extracts the latest version of the named source files from the SCCS sub-directory for editing. After the files are modified, they should be placed back into SCCS using 'sccsdelta'.
sccsdelta
Usage: sccsdelta <file1> <file2> ...
This is used after modifying source files which were previously extracted using 'sccsedit'. It places the named files back into the SCCS sub-directory.
sccsget
Usage: sccsget <file1> <file2> ...
This extracts the latest version of the named source files from the SCCS sub-directory for read-only. The should be done prior to a compilation.
qc (Quick Change)
Usage: qc <file1> <file2> ...
The latest versions of the named files are extracted from the SCCS sub-directory for editing. Then the 'vi' text editor is invoked for each. Finally the files are placed back into SCCS and a read-only version is extracted.
This is useful for making quick, simple changes to a source file. For for massive updates involving several edits, use 'sccsedit' followed by 'sccsdelta'.
The MAKE Utility
All versions of UNIX come with a utility program called 'make'. This program provides an easy way to automate the creation and maintenance of large programs and program groups. See the UNIX System V/386 Development System Programmer's Guide for a complete description of the MAKE utility.
To use MAKE, the developer creates a description file called 'makefile' which defines the various object and executable files to be created, and the source files on which they depend. As files are modified, MAKE will use the last-modify-time to determine if the source files need to be re-compiled or re-assembled.
To run MAKE, one simply types 'make' at the shell prompt. Or, to make a specific target, type 'make' followed by the name of the target file.
The DROT/DQM source code is divided between the following sub-directories. Each of these directories contains a separate 'makefile' describing its hierarchical dependencies.
dqmsrc Source code for the DQM
drotsrc Source code for the DROT
icp Franklin ICP188C-resident code
icpdrv Franklin ICP188C device driver code
lib General-purpose object library
wlib Windows/screen output object library
kermit Source code for Kermit (obtained from Columbia
University Center for Computing Activities)
For example, the 'makefile' in the wlib directory defines all of the object, executable, and source files which make up the Windows Library. To build the library, one would enter the following commands:
cd ~/wlib
make
Also, there is a 'makefile' in the daps home directory for doing system-wide operations. This makefile contains the following targets:
extract Extract all source files from SCCS.
all Compile all source files. clean Remove unneeded object files after a compile.
sourcefloppy Save the source code on a floppy disk using the 'tar' utility.
drotinstall Make an installation floppy for the DROT.
dqminstall Make an installation floppy for the DQM.
Hence to extract and then compile and link all of the software for the DROT and DQM, enter the following commands:
cd
make extract
make all
UNIX Interprocess Communication
UNIX System V processes can communicate and coordinate their actions through a variety of UNIX interprocess communications (IPC) resources including:
o Shared files
o Message queues
o Shared memory
o Semephores
o Signals
Figure 4-2 shows the symbols that will be used for these resources in the data flow diagrams in this manual.
File Naming Conventions
This section discusses the file name structure imposed by UNIX, various UNIX utilities, and by the DAPS development system.
A file name under UNIX System V consists of up to 14 non-blank alphanumeric characters. Some utilities such as compilers and linkers require that certain types of files have a specific suffix. These suffixes are listed in table 4.1.
The SCCS utility has many conventions of its own for file names. See the UNIX System V/386 Development System Programmer's Guide for a complete description of SCCS.
SYMBOLS USED FOR UNIX IPC RESOURCES
UNIX FILE SUFFIXES
SUFFIX FILE TYPE
====== =========
.c C-Language program source file
.h C-Language program header file
.o Linkable object file
.s Assembly Language source file
.a Object library archive file
where are three files which have a special meaning to the C-shell command interpreter. All three contain shell commands and are placed in the user's home directory. Commands in the ".login" file are executed when the user logs in. Commands in the ".cshrc" file are executed whenever a new shell is spawned (or when the user logs on). Commands in the ".logout" file are executed when the user logs off. These files are useful for customizing the environment by setting shell variables and aliases. For the "drot" and "dqm" users, these files are used to initialize various parameters for support of the application software.
Table 4.2 lists the prefixes which have been used for all of the source code developed for the DROT and DQM:
DROT/DQM SOURCE FILE PREFIXES
Prefix File Type
====== =========
t_ DROT source file
q_ DQM source file
g_ General purpose library file
w_ Windows library file
icp ICP188C device driver file
188 ICP188C-resident code file
b_ Test or Debugging file
The DROT software consists of a collection of cooperating concurrent processes. The processes are divided into two groups: those which perform the real-time ingest, archival, and transmission of DCP messages (called "real-time" processes), and those which perform various non-time-critical functions (called "non-real-time"). Figure 5-1 depicts at a very high level the data flow for the entire DROT.
The left side of the figure shows the real-time message ingest, archival, and transmission functions. Data is received over the DOMSAT link and filtered for desired messages using the user-provided network lists. Messages are saved in the "Message Storage" file and a sorted directory entry is created for each in the "Message Directory". If real-time serial output is enabled, incoming messages are also placed in the serial output queue to await transmission.
The right side of the figure shows the non-real-time functions. Without disturbing the real-time functions, the user can edit the network lists and interactively search for DCP messages in storage. Messages found can then be displayed on the CRT screen, saved in separate disk storage, printed, or transmitted over the serial port.
Figure 5-1 is intended to show the flow of DCP-message data through the entire DROT system. It is therefore necessarily simplified such that the rectangular boxes shown for "Message Ingest" and "Message Retrieval" are actually made up of several cooperating UNIX-processes.
The real-time processes are:
o DROT Control Process (t_ctrl)
o DOMSAT Receive Process (t_recv) HIGH-LEVEL DROT DATA FLOW DIAGRAM
o Real-Time User Interface Process (t_rtuser)
o Serial Output Process (t_serout)
o Domsat Enable/Disable Utility (domsat)
o Real-Time Screen Output Process (w_scrout)
o DROT Shutdown Process (killdrot)
The non-real-time processes are:
o Non-Real-Time User Interface Process (t_oluser)
o Non-Real-Time Screen Output Process (w_scrout)
o Periodic Functions Process (t_periodic)
o On-Screen Clock Process (w_clock)
In addition to the above, there is a utility called "fixup" which can be run when the other DROT software is not running. This utility is used to recover from an improper shutdown or power failure.
All of these processes are described in detail in the paragraphs below.
DROT Control Process (t_ctrl)
The DROT control process is started when the user logs into the "drot" account and invokes the "drot" command file. It sets up all of the IPC resource to be used by the DROT and then spawns all of the DROT concurrent processes. After all of the DROT processes are running, it coordinates some of the interprocess communication such as user-requested configuration changes, and the logging and displaying of alarm messages. When the user "drot" logs off, the DROT control process coordinates the shutdown of the DROT software.
Data Flow
Figure 5-2 is a data flow diagram for the DROT control process.
Processing Description
The DROT control process performs the following functions:
o Check for the existence of, and then create a lock-file called "/usr/drot/drot_running" to prevent more than
one iteration of the DROT or DQM software to be runningat the same time.
o Initialize all of the DROT IPC resources and create a file called "/usr/drot/t_cnfgkey" containing the IPC key to the configuration shared memory area.
o Load the information from the "drotconfig" file into the configuration shared memory area.
o Load the active network list into the configuration shared memory area.
o Spawn all of the cooperating DROT processes. Then wait for each to report READY_TO_GO via the control message queue.
o Receive and process messages from other process via the control message queue. Control messages usually result in some kind of configuration change such as enabling/disabling the DOMSAT link, changing serial parameters, etc.
o When the SHUTDOWN message is received over the control message queue from the "killdrot" process, send the interrupt-signal to all of the child processes. Then wait for each to respond with a DYING message.
o Save the current configuration in the "drotconfig" file.
o Remove the "/usr/drot/drot_running" lock-file.
DROT CONTROL PROCESS DATA FLOW DIAGRAM
Data Structures
The DROT control process is the only process with write-access to the configuration shared-memory area. This area is of type 'struct CONFIG_SHM' and is defined in the file g_config.h.
Messages received from other DROT processes via the control message-queue are of type 'struct CTRL_MSG' which is defined in the file g_ctrl_q.h. This is a flexible structure which can contain many types of messages and information.
Inputs
The DROT control process reads from the following input files:
a. drotconfig is opened at startup and its contents are loaded into the configuration shared memory area. This is handled through the g_parscnfg.c library module.
b. Each of the four network list files (nl1, nl2, nl3, nl4) which is marked active (in the configuration file) is opened and its contents sorted into the active network list array in the configuration shared memory area.
Outputs
The DROT control process writes to the following outputs:
a. /usr/drot/t_cnfgkey is created when the program starts up. It contains the IPC key of the configuration shared memory area. This enables the other DROT processes to attach to this area.
b. /usr/drot/drot_running is created when the program starts up. This lock file insures that two copies of the DROT/DQM cannot be running at the same time. This is handled through the g_tq_run.c library module.
c. drotconfig is overwritten when the program shuts down with the current (possibly changed) configuration. This is handled through the g_savecnfg.c library module.
d. errlog.a or errlog.b is appended to as needed for the logging of system events and alarms. This is handled through the g_error.c library module.
e. Standard Output is used to display alarms and error messages.
Interprocess Communication
The DROT control processes uses the following IPC resources:
a. The configuration shared memory is initialized and then updated periodically as needed.
b. The control message queue is read continuously for various configuration/control requests from the other DROT processes.
c. A signal (SIGUSR1) is used to interrupt the other DROT processes when the shutdown message is received. This is handled through the g_kidlist.c library module.
d. All other IPC resources are created by this process when it is started up, and then removed when it is shut down. These are the serial output message queue, the search-limits shared memory area, the network list lock semephore, and the directory-lock semephore. This is handled through the g_parscnfg.c library module.
Source Files
The source files comprising the DROT control process are as follows.
a. t_ctrl.c contains the initialization, clean-up, main, and main-loop functions.
b. t_netlist.c contains functions for loading and updating the active network list.
c. t_params.h defines some of the settable DROT parameters.
DOMSAT Receive Process (t_recv)
The DOMSAT Receive Process is spawned by the DROT Control Process. It interfaces with the Franklin Telecom ICP device driver to receive incoming DCP messages. The messages are then saved in the message storage file and a corresponding directory entry is created in the message directory file. If real-time serial output is enabled, the serial output task is informed of the arrival of any new messages so they can be queued for transmission. The real-time status display is updated showing last message received, DOMSAT quality, and number of messages currently in storage.
Data Flow
Figure 5-3 is a data flow diagram for the DOMSAT receive process.
Processing Description
The DOMSAT Receive Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
o Attach to both the real-time and non-real-time terminals for sending status updates.
DOMSAT RECEIVE PROCESS DATA FLOW DIAGRAM
o Allocate receive buffers and tables.
o Open the specified DOMSAT device name.
o Initialize the archiving functions so that message archiving can continue where it left off when the DROT was last shut down.
o Attach to the network list lock semephore.
o Send the READY_TO_GO message to the DROT control process.
b. Main Processing Loop:
o Wait for the DOMSAT-Enable flag in the configuration area to be set.
o Download the X.25 program to the ICP device.
o While DOMSAT is enabled:
o If active network list has changed, download the new list to the IPC.
o Issue a read system call to the ICP device driver.
o Keep statistics on message quality.
o Archive each message that arrived.
o Check for timeout on the link if no messages have arrived.
c. Shutdown:
o Close message storage and message directory files.
o Send the shutdown message to the serial output process.
o Detach from the configuration shared memory area.
o Detach from the real-time and non-real-time terminals.
o Send the DYING message to the DROT control process.
a. Read-requests are made to the ICP device driver by passing it a pointer to a large buffer of type 'struct ICPREADREQ'. This structure is defined in the file g_icpdrv.h. It is allocated by the DOMSAT receive process and passed empty to the ICP device driver. The driver fills in the empty structure and returns the number of complete messages received.
b. Each message stored by the ICP device driver in the read-request buffer is stored in type 'struct DCPMSG_BUF'. This structure contains a 6-byte header added by the ICP board-resident code, and the actual message data.
c. The archiving functions keep track of the contents of the message storage file by maintaining a 'message map'. The map is simply an array of offsets (long integers) to messages currently in storage. It is used to find storage in the circular file for incoming messages.
d. Messages are archived in the message storage file in a structure of type 'struct REC'. This structure contains two lower-level structures of type 'struct REC_HEADER' and 'struct DCPMSG_DATA'. All of these structures are defined in the file t_archive.h.
e. A directory entry is created for each incoming message of type 'struct DIR_ENTRY' and is saved in the message directory file. This structure is defined in the file t_archive.h. The directory entry contains the receipt times of the message, the DCP address, a flag indicating the message type and quality, and the offset of the message data in the message storage file.
f. The search limits shared memory area is of type 'struct SEARCH_SHM' and is used to coordinate the arrival of new messages with the non-real-time message access functions (which may be going on concurrently). This structure is defined in the file t_archive.h.
Inputs
The DOMSAT Receive Process reads from the following input files:
a.The ICP device node "/dev/icp" is opened.
b. The specified ICP-resident program is opened and downloaded to the ICP device.
c. The message directory file is read during initialization to determine where archiving left off the last time the DROT was shut down.
Outputs
The DOMSAT Receive Process writes to the following outputs:
a. The specified message storage file is opened and updated as new messages arrive.
b. The specified message directory file is opened and updated as new messages arrive.
Interprocess Communication
The DOMSAT Receive Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters. It contains the DOMSAT-ENABLE flag which is checked after every read call. It also contains a flag indicating whether the active network list has changed.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DROT Control Process at start-up and shut-down time, respectively. It is also used to send an acknowledgment message in response to a change in the active network list. This is handled by the g_sendctrl.c library module.
c. When the shutdown signal (SIGUSR1) is received (from the DROT control process), the main processing loop is terminated and this process is gracefully halted.
d. The search-limits shared memory area and the directory lock semephore are used to coordinate the arrival of new messages with the message-access functions of the Non-Real-Time User Interface Process.
e. The network list lock semephore is used to control access to the active network list array contained in the configuration shared memory. The array is loaded by the DROT control process in response to user action. The array is then read and down-loaded to the ICP device driver by the DOMSAT receive process.
f. The real-time screen output message queue and the non-real-time screen output message queues are used to display various status information. This is handled through various function in the Windows Library.
g. The serial output message queue is used to inform the Serial Output Process of the arrival of new DCP messages. This is only done when real-time serial output is enabled.
Source Files
The source files comprising the DOMSAT Receive Process are as follows.
a. t_recv.c contains the initialization, shutdown, main, and main loop functions.
b. t_recvarch.c contains functions for managing the updates to the circular message storage file. It contains the 'message map' described above, which is used to determine when older messages have been overwritten in the circular file. c. t_archbuf.c provides application-level buffering of output to the message storage file. This buffering makes the archival more efficient by cutting down the number of system calls made.
d. t_archwrit.c contains low-level functions for writing to the circular message storage file.
e. t_dcpmsg.c contains functions for extracting information from DCP message data, such as the DCP address and the time the message arrived at the DAPS.
f. t_recvdir.c contains functions for managing updates to the circular message directory file. It also handles the coordination of updates with the Non-Real-Time User Interface Process and the Serial Output Process.
Real-Time Functions User Interface Process (t_rtuser)
The Real-Time Functions User Interface Process is spawned by the DROT Control Process. It handles the user-interface for the real-time portion of the DROT by making heavy use of the Windows Library package to define and update areas on the screen, and to interact with the user via the keyboard.
Data Flow
Figure 5-4 is a data flow diagram for the DROT Real-Time Functions User Interface Process.
Processing Description
The DROT Real-Time Functions User Interface Process performs the following functions:
DROT REAL-TIME FUNCTIONS USER INTERFACE PROCESS
DATA FLOW DIAGRAM
a. Initialization:
o Attach to the configuration shared memory area.
o Attach to the specified real-time terminal.
o Define color attributes for user interaction.
o Start the clock in the upper left corner.
o Paint the screen template.
o Define an overlay window for displaying alarms.
o Send a message to the DROT Control Process containing the various screen tags for real-time update. The Control Process then places these in the configurations area so that other processes can update the screen.
o Create the interactive configuration-change windows.
o Define special keystrokes for alarm-cancel (F10) and to repaint the screen (CTRL-L).
o Send the READY_TO_GO message to the DROT Control Process.
b. Main Processing Loop:
o Wait for a keystroke from the user.
o If it is ESCAPE, activate the top-level configuration change window using the Windows Library functions.
o If it is one of the special keystrokes defined above, perform the appropriate functions.
o Otherwise it's an undefined keystroke, beep furiously.
c. Shutdown:
o Detach from the real-time terminal.
o Detach from the configuration shared memory area.
o Send the DYING message to the DROT Control Process.
Data Structures
a.During initialization, this process uses the Windows Library functions to define various 'windows' on the screen to be used later for screen update. For example, one window contains the constantly updating GMT clock. Another contains a tally of messages currently in storage. Each window has a unique (integer) 'tag' associated with it. This process places these tags in a structure of type 'struct RT_TAGS', and sends them via the control message queue to the DROT Control Process, where they are placed in the configuration shared memory area. This structure is defined in the file g_ctrl_q.h.
b. This process defines and maintains various structures of type 'WINDOW' and 'WINDOWOBJECT'. These types are defined in the file w_windows.h. This process does not access the contents of these structures directly, but uses the Windows Library functions to do so by passing pointers.
Inputs
The DROT Real-Time Functions User Interface Process reads from the following input file:
The specified real-time terminal is opened for reading from the keyboard. This is handled through the Windows Library w_keyboard.c module.
Outputs
The DROT Real-Time Functions User Interface Process does no direct file output. Screen outputs are handled through the screen-output process in the Windows library.
Interprocess Communication
The DROT Real-Time Functions User Interface Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DROT Control Process at start-up and shut-down time, respectively. It is also used to send configuration change requests in direct response to user action (e.g. changing the serial parameters).
c. When the shutdown signal (SIGUSR1) is received (from the DROT Control Process), the main processing loop is terminated and this process is gracefully halted.
d. The real-time screen output message queue is used to send screen updates to interact with the user. This is handled through various function in the Windows Library.
Source Files
t_rtuser.c contains the initialization, shutdown, main, and main loop functions.
Non-Real-Time Functions User Interface Process (t_oluser)
The Non-Real-Time Functions User Interface Process is spawned by the DROT Control Process. It handles the user-interface for the non-real-time portion of the DROT by making heavy use of the Windows Library package to define and update areas on the screen, and to interact with the user via the keyboard. The non-real-time functions include message search/select/access, and network list editing.
Data Flow
Figure 5-5 is a data flow diagram for the DROT Non-Real-Time Functions User Interface Process.
Processing Description
This process is mainly user-driven. It waits for keyboard input and then, depending on whether a menu item was chosen or a parameter entered, takes appropriate action. The activation of the various functions is all handled through the Windows Library. Hence this process sets up the window structures and then passes control to the windows library.
The DROT Non-Real-Time Functions User Interface Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
o Attach to the search-limits shared memory area.
o Attach to the directory-lock semephore.
o Attach to the serial-output message queue.
o Attach to the specified non-real-time terminal.
o Define color attributes for user interaction.
o Paint the screen template.
o Define an overlay window for displaying alarms.
o Send a message to the DROT Control Process containing the various screen tags for real-time update. The Control Process then places these in the configurations area so that other processes can update the screen.
o Create the interactive message search/select/access windows.
DROT NON-REAL-TIME FUNCTIONS USER INTERFACE PROCESS
DATA FLOW DIAGRAM
o Create the network list edit windows.
o Start the clock in the upper left corner.
o Define special keystrokes for alarm-cancel (F10) and to repaint the screen (CTRL-L).
o Send the READY_TO_GO message to the DROT Control Process.
b. Main Processing Loop:
o Activate the top-level window using the Windows Library functions.
c. Shutdown:
o Detach from the non-real-time terminal.
o Send the DYING message to the DROT Control Process.
o Detach from the configuration shared memory area.
o Close the message storage and directory files if they had been open for message search/select/access.
Data Structures
a. During initialization, this process uses the Windows Library to define various 'windows' on the screen to be used later for screen update. Each window has a unique (integer) 'tag' associated with it. This process places these tags in a structure of type 'struct RT_TAGS', and sends them via the control message queue to the DROT Control Process, where they are placed in the configuration shared memory area. The struct RT_TAGS is defined in the file g_ctrl_q.h.
b. This process defines and maintains various structures of type 'WINDOW' and 'WINDOWOBJECT'. These types are defined in the file w_windows.h. This process does not access the contents of these structures directly, but uses the Windows Library functions to do so by passing pointers.
Inputs
The DROT Non-Real-Time Functions User Interface process reads from the following input files:
a. The specified non-real-time terminal is opened for reading from the keyboard. This is handled through the Windows Library w_keyboard.c module.
b. When the user searches/selects/accesses DCP messages, the message storage file are opened for read-only access.
c. When the user searches/selects/accesses DCP messages, the message directory file is opened for read/write access.
d. When the user edits a network list, the specified list is opened and read into a temporary buffer in memory.
Outputs
The DROT Non-Real-Time Functions User Interface Process writes to the following output files:
a. The user can save selected DCP messages to a disk file of his choice. If the file previously exists, the user can choose to overwrite the file or append to it.
b. When the user chooses to transmit selected DCP messages over the serial port, a temporary file is created containing the offset of the DCP messages to be transmitted. The name of this file is then sent via message queue to the Serial Output Process. The temporary file is used to reduce traffic on the message queue.
c. When the user chooses to print selected DCP messages, a temporary file is created containing the DCP message data. This file is then processed by a user-defined command line. By default this is 'pr <filename> | lp'.
d. After a network list has been edited, it can be written back to disk. The previous version of the list is overwritten.
e. Each entry in the message directory file contains four access-flags indicating whether the message has been displayed, printed, transmitted, or saved. After messages have been accessed, these flags are set by this process.
Interprocess Communication
The DROT Non-Real-Time Functions User Interface Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DROT Control Process at start-up and shut-down time, respectively.
c. When the shutdown signal (SIGUSR1) is received (from the DROT control process), the main processing loop is terminated and this process is gracefully halted.
d. The non-real-time screen output message queue is used to send screen updates to interact with the user. This is handled through various function in the Windows Library.
e. The search limits shared memory and the directory lock semephore are used to coordinate message access with the DOMSAT Receive Process as new messages are received.
f. The serial output message queue is used to send transmission requests to the Serial Output Process.
Source Files
The source files comprising the DROT Non-Real-Time Functions User Interface Process are as follows.
a. t_oluser.c contains the initialization, shutdown, main, and main loop functions.
b. t_search.c contains functions which are activated from the Windows Library when the user performs a search for DCP messages.
c. t_select.c contains functions which are activated from the Windows Library when the user selects individual DCP messages.
d. t_showmsg.c contains functions which are activated from the Windows Library when the user displays DCP messages on the screen.
e. t_printmsg.c contains functions which are activated from the Windows Library when the user prints DCP messages.
f. t_savemsg.c contains functions which are activated from the Windows Library when the user saves DCP messages in separate disk storage.
g. t_xmitmsg.c contains functions which are activated from the Windows Library when the user transmits DCP messages over the serial port.
h. t_nledit.c contains functions which are activated from the Windows Library when the user edits a network list.
i. t_netlist.c contains functions for reading and writing the network list files.
j. t_archread.c contains low-level functions for reading the message storage file.
k. t_dcpmsg.c contains functions for extracting information from DCP message data, such as the DCP address and the time the message arrived at the DAPS.
l. t_diracces.c contains functions for writing to the message directory file. This process sets the four access-flags as messages are displayed, printed, saved, or transmitted. Serial Output Process (t_serout)
The Serial Output Process is spawned by the DROT Control Process. It handles the serial link to some unspecified other computer. It reads the serial parmaters such as device name, baud rate, etc., from the configuration shared memory area to initialize the device. It then reads messages from the serial output message queue. Each message is one of the following types of request:
SER_CNFGCHANGE Serial port configuration change
SER_DCPMSGOUT Send a DCP message out
SER_DCPMSGFILE Send DCP messages from a file of offsets
SER_SHUTDOWN Clean up and die
All of the requests on the message queue are read and stored in a local buffer, then the next message in the buffer is processed. This scheme insures that the message queue doesn't fill up. (Note that if the UNIX-System wide limit on bytes or messages in all queues is reached, unpredictable and disastrous things might happen.)
Data Flow
Figure 5-6 is a data flow diagram for the Serial Output Process.
Processing Description
The Serial Output Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
SERIAL OUTPUT PROCESS DATA FLOW DIAGRAM
o Initialize the serial port with the parameters from the configuration are.
o Attach to the serial-output message queue.
o Attach to the real-time screen output message queue for sending periodic status information.
o Initialize a buffer for holding the serial requests locally.
o Send the READY_TO_GO message to the DROT Control Process.
b. Main Processing Loop:
o Get any requests off of the serial output message queue and store them in the local buffer.
o Process the next request in the local buffer.
o If currently outputting from a file of message offsets, output the next message.
o If output is via Kermit protocol, spawn a Kermit child
process to handle the transfer.
c. Shutdown:
o Detach from the real-time terminal.
o Close the serial port.
o Send the DYING message to the DROT Control Process.
o Detach from the configuration shared memory area.
Data Structures
a. Output requests are received via the serial output message queue in the type 'struct SEROUT_MSG'. This structure is defined in the file g_serial.h.
b. A circular array of type 'struct SEROUT_MSG' is used to store requests locally. When this array becomes full, an alarm is generated.
Inputs
The Serial Output Process reads from the following input files:
a. The message storage file is opened for read-only access.
b.When SER_FILEOUT requests are received, the specified temporary message offset file is opened.
Outputs
The Serial Output Process writes to the serial port specified in the configuration shared memory area.
Interprocess Communication
The Serial Output Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DROT Control Process at start-up and shut-down time, respectively. It is also used to send acknowledgments to serial configuration change requests.
c. The real-time screen output message queue is used to send serial output status updates.
d. The serial output message queue is read continually during the main processing loop.
Source Files
The source files comprising the Serial Output Process are as follows.
a.t_serout.c contains the initialization, shutdown, main, and main loop functions.
b. t_archread.c contains low-level functions for reading the message storage file.
c. t_dcpmsg.c contains functions for extracting information from DCP message data, such as the DCP address and the time the message arrived at the DAPS.
Periodic Functions Process (t_periodic)
The Periodic Functions Process is spawned by the DROT Control Process. Its purpose is to perform miscellaneous tasks on a periodic bases. It contains a 'job table' which is a list of functions to call and periods (number of seconds) in which to call them. Currently it is only used to perform a mail-tally every two hours.
Data Flow
Figure 5-7 is a data flow diagram for the Periodic Functions Process.
Processing Description
The Periodic Functions Process performs the following functions:
PERIODIC FUNCTIONS PROCESS DATA FLOW DIAGRAM
a. Initialization:
o Attach to the configuration shared memory area.
o Reduce priority in relation to other processes (accomplished by increasing the 'nice value').
o Call the initialization function for each entry in the job table.
o Send the READY_TO_GO message to the DROT Control Process.
b. Main Processing Loop:
o Sleep for a predetermined period of time (default = 60 seconds).
o Check the job table to see if its time to do anything. If it is, do it.
c. Shutdown:
o Call the clean-up function for each entry in the job table.
o Send the DYING message to the DROT Control Process.
o Detach from the configuration shared memory area.
Data Structures
a. The job table is an array of type 'struct JOB'. This type is defined in the file t_periodic.c. Each entry in the table is initialized with pointers to three functions and a period. The three functions are for job-initialization, job-cleanup, and the function to be called periodically.
Inputs
The message directory file is opened for read-only access.
Outputs
The Periodic Functions Process does no direct file output.
Interprocess Communication
The Periodic Functions Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DROT Control Process at start-up and shut-down time, respectively.
c. The search limits shared memory area and directory lock semephore are used to inform the DOMSAT Receive Process when a mail tally is finished.
Source Files
The source files comprising the Periodic Functions Process are as follows.
a. t_periodic.c contains the initialization, shutdown, main, and main loop functions.
DOMSAT Enable/Disable Utility (domsat)
This program is a utility which can be run from the UNIX shell after the DROT has been started. It simply asks the user if he wants to enable the DOMSAT link. If the '-n' option is used, it is assumed that the DOMSAT link is currently disabled, hence if the user enters 'n' in response to the query, no action is taken. Otherwise either the DOMSAT_ENABLE or DOMSAT_DISABLE message is sent over the control message queue.
This program is run with the '-n' option from the DROT's ".login" file.
Data Flow
Figure 5-8 is a data flow diagram for the DOMSAT Enable/Disable Utility.
Processing Description
The DOMSAT Enable/Disable Utility performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
b. Main Processing:
o If the first argument is 'Enable' then send the DOMSAT_ENABLE message over the control message queue.
o Else if the first argument is 'Disable' then send the DOMSAT_DISABLE message over the control message queue.
o Else ask the user if he wants to enable the DOMSAT link and read the response from the keyboard.
o If the user entered 'n' and the '-n' option was not used, send the DOMSAT_DISABLE control message.
o Else if the user entered 'e', send the DOMSAT_ENABLE control message.
DOMSAT ENABLE/DISABLE UTILITY DATA FLOW DIAGRAM
Data Structures
No complex structures are used.
Inputs
The DOMSAT Enable/Disable Utility reads from standard input to get the user's response to the query.
Outputs
The DOMSAT Enable/Disable Utility writes to standard output to ask the user if he wants to enable the DOMSAT link.
Interprocess Communication
The DOMSAT Enable/Disable Utility uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the DOMSAT_ENABLE or DOMSAT_DISABLE message to the DROT Control Process depending on the arguments used and the response to the query.
Source Files
t_domsat.c contains the initialization, shutdown, and main functions.
DROT Shutdown Utility (killdrot)
This program is a utility which can be run from the UNIX shell after the DROT has been started. It simply sends the SHUTDOWN message over the control message queue to the DROT Control Process. It then monitors the system-status field in the configuration shared memory area to make sure the shutdown was successful. If it was not, more drastic action is taken.
Data Flow
Figure 5-9 is a data flow diagram for the DROT Shutdown Utility.
Processing Description
The DROT Shutdown Utility performs the following functions:
a. Initialization:
o Make sure the DROT is currently running. If not, exit with an error message.
o Attach to the configuration shared memory area.
b. Main Processing:
o Send the SHUTDOWN message over the control message queue to the DROT Control Process.
o Sleep for four seconds.
o Check the 'sys_stat' variable in the configuration shared memory area. If it is not either CLEANING or DEAD, remove all of the DROT's IPCs by hand. This will effectively halt any processing still going on. Then remove all temporary files created by the DROT.
DOMSAT ENABLE/DISABLE UTILITY DATA FLOW DIAGRAM
Data Structures
No complex structures are used.
Inputs
The DROT Shutdown Utility does no file input.
Outputs
The DROT Shutdown Utility does no file output.
Interprocess Communication
The DROT Shutdown Utility uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters. It is also used to determine whether the shutdown was successful.
b. The control message queue is used to send the SHUTDOWN message to the DROT Control Process.
Source Files
t_kill.c contains the initialization, shutdown, and main functions.
The DROT Fixup Utility (fixup)
This program is a utility which can be run from the UNIX shell when the DROT is not running. It is used to recover from an improper shutdown such as a power failure or system crash. It checks following discrepancies between the message directory and message storage files, and if any are found, they are corrected.
Table 5.1 lists the command-line options that can be used with the utility.
Data Flow
Figure 5-10 is a data flow diagram for the DROT Fixup Utility.
Processing Description
The DROT Fixup Utility performs the following functions:
a. Initialization:
o Parse the command line options, if any.
o Make sure the DROT is currently not running. If it is, offer the user a chance to abort.
o Read the DROT configuration file for the names of the message storage and message directory files, and various other operational parameters.
o Allocate storage for a directory map.
o Open the message storage and message directory files.
o Load portions of the directory entries into the directory map.
o Sort the directory map by offset in ascending order.
DROT FIXUP UTILITY COMMAND LINE OPTIONS
Option Meaning
============ =============================================
-d Remove duplicate directory entries only. Do not compare message directory to message storage.
-r Read-only. Just report the discrepancies. Don't fix anything.
-q Quiet. Don't report anything to standard output.
-t <tmpdir> Use the specified directory for the temporary file containing the fixed directory. The default is /usr/tmp.
DROT FIXUP UTILITY DATA FLOW DIAGRAM
b. Main Processing:
o Remove duplicate entries from the directory map. 'Duplicates' are entries with the same offset.
o If any duplicates were found, resort the directory map.
o Compare each entry in the directory with the corresponding DCP message in the message storage file. Insure that they agree on DCP address, receipt times, and X.25 status. If not, change the directory entry.
o Re-write the fixed directory.
Data Structures
The 'directory map' is of type 'struct D' which is defined locally in the file t_fixup.c. Each entry contains a directory index and a message storage file offset. Hence each entry relates a unique directory entry with a unique DCP message in storage.
Inputs
The DROT Fixup Utility reads from the following input files:
a. The DROT configuration file 'drotconfig'.
b. The message storage file (default: 'messages'.)
c. The message directory file (default: 'messages.D'.)
Outputs
The DROT Fixup Utility writes to the following output files:
a. Standard output is used to display a message for each discrepancy found. b. The message directory file is overwritten completely after the directory is fixed.
Interprocess Communication
The DROT Fixup Utility runs when the DROT is not running and hence does not communicate with other process.
Source Files
The source files comprising the DROT Fixup Utility are as follows.
a. t_fixup.c contains the initialization, shutdown, and main functions.
b. t_archread.c contains low-level functions for reading the message storage file.
c. t_dcpmsg.c contains functions for extracting information from DCP message data, such as the DCP address and the time the message arrived at the DAPS.
DOMSAT INTERFACE SUBSYSTEM PROCESS DESCRIPTION
This section describes the software and hardware used to implement the DOMSAT Interface Subsystem. This subsystem serves the purpose of converting the incoming X.25 packets into complete DCP messages for processing by the DROT and DQM applications, and is divided into two parts: code running on the Franklin Telecom ICP188C board, and a UNIX device driver.
The ICP188C board depacketizes incoming message blocks and stores them in a series of buffers in memory that is shared with the PC's processor. The device driver then provides the link between the ICP188C and the UNIX applications programs which make up the DROT and DQM.
Figure 6-1 depicts the data flow from the serial DOMSAT data stream, through the DOMSAT Interface Subsystem, and to the UNIX application program. The components of this subsystem are described in the paragraphs below.
ICP188C-Resident Code
The Franklin Telecom ICP188C board contains an Intel 80188 processor running at 8MHz, 512 KB of dual-ported RAM (shared with the PC via a 64 KB window), two Zilog SCC chips, and two Intel 8237 DMA controllers. Other then a small amount of ROM-based code for performing system initialization, all of the code which runs on the board is downloaded from the PC via the shared memory. This section describes the custom code used to depacketize DCP messages. The executable code resides in a single file called 188x25.exe and is used by both the DROT and the DQM.
DCP messages are transmitted from DAPS to the DROT using a subset of the X.25 protocol. Link Access Procedure B (LAP-B) and a DOMSAT INTERFACE SUBSYSTEM DATA FLOW DIAGRAM
Permanent Virtual Circuit (PVC) are used at the link and packet levels. The data stream is transmitted in broadcast mode, with no opportunity for the receiving station to acknowledge data reception, hence this method of transmission represents only a partial implementation of the X.25 protocol.
Processing Description
The initialization code for the ICP188C sets up an interrupt handler causing the SCC chip to continually read X.25 I-frame packets, placing them in the completion queue. The main thread of execution then waits for packets in the completion queue and moves them to the shared buffers. The following paragraphs described these operations in more detail.
Initialization
After the the ICP188C-resident code is downloaded to the ICP188C by the device driver, the entry-point address of the code is placed in a special location in shared memory (determined by the boot-ROM on the ICP188C). A flag is then set enabling the ICP188C to begin execution.
The entry-point code is found in the file 188misc.asm. It performs the following steps:
o Set up segment registers.
o Set up the local stack.
o Set up the interrupt vector table. Interrupts from the SCC chip and the internal 80188 DMA are processed as well as several interrupts used by the boot ROM code.
o Jump to the '_main1' C-Language function which then calls the 'init' function. The 'init' function performs the following: o Wait for the 'configure_ok' flag to be set by the PC.
o Initialize the packet free-queue and completion-queue.
o Set up a DMA request to receive the first packet via the SCC chip.
Queueing of X.25 Packets
The SCC and DMA controllers are set up to receive an X.25 packet into a buffer in the completion queue. When the I-frame is complete, the SCC will interrupt the 80188 with a 'special receive condition' interrupt. The interrupt handler performs the following steps:
o Retrieve the number of bytes transferred by the DMA and place it in the packet header.
o Get a new buffer from the free-queue and place it in the completion-queue.
o Set up the SCC and DMA controllers to receive the next packet into this new buffer.
o Check packet for CRC errors. Discard packet and set error flag if any. Put SCC into seach mode for next packet.
Moving Packet Data to Shared Buffers
The main thread of execution waits for packets to be placed in the completion queue by DMA and the interrupt handler. When a packet is ready, the following steps are performed:
o Construct the status flag variable for this packet by checking the packet sequence number, packet size, and message sequence number.
o Copy the packet data into the next shared-memory buffer. o Place the packet back onto the free queue.
o If this packet was the last packet of a DCP message:
o Fill in the message sequence number, message status flag, and message size in every shared buffer comprising this message.
o Set the HOST_CAN_USE flag in each buffer. This informs the PC device driver that it can transfer the buffer into the PC's memory.
o Set up pointers for the next packet.
Data Structures
a. For information on the ICP188C memory map, I/O address map, PC I/O map, and PC address map refer to the Franklin Telecom Technical Reference Manual for the ICP188C Communications Processor.
b. The X.25 packets are received in a structure of type 'struct pkt_'. This structure is defined in the file 188c.h.
c. Packets are received using DMA into a queue. The queue consists of a pool of buffers of type 'struct message_structure'. This structure is defined in the file 188misc.asm. Each entry in the pool contains pointers to the next and previous element in the queue, buffer size, CRC status, and buffer contents. Two queue headers are kept pointing into the pool of buffers: one called _freeq pointing to the first unused buffer in the pool, and one called _cmplq pointing to the first buffer containing a complete packet in the pool.
d. Packets are dequeued and stored in the buffers in shared memory with the PC. These shared buffers have type 'struct msg_' which is defined in the file 188c.h. The structure contains a status flag, the buffer size, and the message sequence number of the DCP message in the buffer. The status flag indicates the result of the packet sequence checks, as well as other possible conditions such as a packet which was larger than the maximum allowable packet, etc. Definitions of the status flag bits are also found in the file 188c.h.
e. The ICP188C's memory is comprised of eight banks of 64K each. The lowest 64K bank contains the ICP188C executable code, the interrupt table, the free and completion queues, and the processor stack. The upper seven 64K banks contain 'shared buffers' as described above. Each buffer is 256 bytes long yielding a pool of 1792 buffers. The buffers are used in ascending order. When the last buffer is reached, the first one is reused. The ICP188C fills the buffers, setting the 'HOST_CAN_USE' flag. The PC then transfers the buffer contents into its own memory and clears the flag.
Source Files
The source files comprising the ICP188C resident code are as follows.
a.188main.c contains the 'main1' function called at startup. This function calls a C-Language 'init' function and then continually calls the 'procq' function to wait for, and dequeue the next packet.
b. 188c.h contains various definitions and structures used in the C-Language portions of the code.
c. 188scc.c contains functions for controlling the Zilog SCC chip including initialization and interrupt handling.
d. 188misc.asm defines the layout of ICP188C memory and contains the entry point code which is called right after the program has been downloaded. This entry point code sets up the interrupt vector table in low memory, initializes some global variables, and then jumps to the 'main1' function contained in 188main.c. This file also contains miscellaneous functions such as interrupt handlers, enqueuing, and dequeuing functions.
e. 188io.asm contains C-Language callable functions for reading and writing to the Intel 80188's I/O ports.
f. 188asm.ha contains various definitions and structures used in the assembly language portions of the code.
g. 188procq.c contains the C-Language function which is called continually to dequeue X.25 packets, placing them in the shared memory buffers.
Kernel-Resident Device Driver
The Kernel-Resident Device Driver provides the operating system interface between the UNIX application programs and the ICP188C device. Under UNIX, a device appears to the application as a file. The application opens a special file called a device node, which causes the operating system to activate the 'open' service of the device driver. Similarly, when the application reads, writes, or closes the device node file, the corresponding services of the driver are invoked. A special service for devices called 'ioctl' (I/O control) is usually implemented in addition.
By convention the functions of a device driver have a common prefix followed by the name of the service (e.g. reading from the ICP188C device invokes the icpread function, writing invokes icpwrite, etc.). These functions are compiled and then placed in an archive library called icpdrv.a. When the DROT or DQM is installed in a new machine using the UNIX custom utility, this archive library is linked with the UNIX kernel. A device node file called /dev/icp is also created on the new machine.
Processing Description
See the UNIX System V/386 Development System Device Driver Writer's Guide for details on the kernel interface to the device driver and for a description of kernel services provided to device drivers. The device driver implemented for the ICP188C provides the init, open, close, read, write, and ioctl services to the DROT and DQM application programs. Each of these services is described below.
The INIT Entry Point (icpinit)
This function is called by the kernel when the UNIX system is booted. It checks for the existence of the ICP188C device by attempting to reset it at all of its possible I/O addresses. When successful, it sets the global variable icp_iobase and returns. If unsuccessful, icp_iobase will be set to an error value and all subsequent attempts to access the driver will fail with the ENODEV error.
The OPEN Entry Point (icpopen)
This function is called by the kernel when an application program issues an 'open' system call on the ICP188C device node (/dev/icp). It performs the following steps:
o Make sure the device is present and map the 64K window of shared RAM into the kernel's address space.
o If this is the first open call:
o Allocate buffers used in reading DCP messages.
o Reboot the ICP188C device.
o Otherwise make sure some other process isn't already using the device.
o Set the driver mode variable to RAW.
The CLOSE Entry Point (icpclose)
This function is called by the kernel when an application program issues a 'close' system call on the previously opened ICP188C device. It simply sets the driver mode variable to CLOSED.
The WRITE Entry Point (icpwrite)
This function is called by the kernel when an application program issues a 'write' system call on the previously opened ICP188C device. The kernel passes the driver a pointer to the data to be written, the number of bytes to be written, and the location in the ICP188C's address space to write to.
For the purposes of writing, the ICP188C appears to the application like a 512KB file. The application can use the lseek system call to position the destination pointer, and then the write system call to transfer data directly into the ICP188C's memory. This is used by the DROT and DQM to download the X.25 program which runs on the ICP188C.
The IOCTL Entry Point (icpioctl)
The ioctl system call provides miscellaneous device services to a UNIX application program. When the application issues an ioctl system call, the kernel passes the driver ioctl function a command word and a pointer to a structure possibly containing arguments to the command. The structure is interpreted differently depending on the command.
The commands implemented for the ICP188C ioctl function are as follows:
DRIVER_RAW Place the driver in raw-read mode.
DRIVER_DROT Place the driver in DROT-read mode.
DRIVER_DQM Place the driver in DQM-read mode.
REBOOT Reboot the ICP188C device.
NEW_NETWORK_LIST Download a new network list for the DROT. The structure passed contains the new list.
READ_TIMER Set the delay used for read-calls. The structure passed contains the delay count.
Other commands are implemented for various debugging and testing functions. See the icpioctl reference in Appendix G for details.
The READ Entry Point (icpread)
This function is called by the kernel when an application program issues a 'read' system call on the previously opened ICP188C device. This function acts differently depending on what 'mode' the driver is currently in. The 'icp_driver_mode' variable is set by the ioctl system call, described above. The driver can be in one of four modes, described below:
a. In DRIVER_RAW mode, the icpread function works much like the icpwrite function. The kernel passes the driver a pointer to a buffer in which to store the data, the number of bytes to be read, and the location in the ICP188C's address space to read. The ICP188C appears to the application like a 512KB file. The application can use the lseek system call to position the destination pointer, and then the read system call to transfer data directly from the ICP188C's memory.
b. In DRIVER_DROT mode, the application passes to the driver (via the kernel) a pointer to a 'read-request structure'. The structure contains two buffers which are filled by the driver. As the driver fills one buffer with the actual DCP message data, it constructs an array of pointers-to-messages in the other buffer. The structure also contains slots for the driver to return various statuses to the application such as the number of messages with errors received since the last read-call, and the message sequence number of the last good message received.
Normally an application would pass the 'read' system call the number of bytes to read, and would be returned the number of bytes actually read. In DRIVER_DROT mode, the application passes the number of DCP messages to read, and is returned the number of DCP messages actually read.
c. In DRIVER_DQM mode, the icpread function works much like it does in DRIVER_DROT mode. The difference is that instead of filling the buffer with entire DCP messages, only the message headers are transferred. The message header contains the message sequence number and the results of the packet- sequence check. This is all the information that the DQM requires to determine if it should send a retransmit-request to DAPS.
Data Structures
a. A pointer to a structure of type 'struct ICPREADREQ' is passed to the read system call when the driver is in DRIVER_DROT or DRIVER_DQM modes. This structure is defined in the file icpdrv.h.
b. Each of the 256-byte shared buffers in the ICP188C's address space begins with a message header of type 'struct DCPMSG_HEADER' which contains a message status flag, the message sequence number and the size of the message data. This header will be identical in each buffer of the same DCP message except for the DUP bit in the message status flag.
c. The data of the first 256-byte buffer of each DCP message starts with a structure of type 'struct DCPMSG_DATA'. This structure contains the DCP address, the date and time of arrival at DAPS, and various transmission quality indicators and is defined in the file g_icpdrv.h.
Source Files
The source files comprising the ICP188C Kernel Resident Device Driver are as follows.
a. icpinit.c contains the icpinit entry-point function.
b. icpopen.c contains the icpopen entry-point function and many global variable definitions used by several driver functions.
c. icpclose.c contains the icpclose entry-point function.
d. icpioctl.c contains the icpioctl entry-point function.
e. icpwrite.c contains the icpwrite entry-point function.
f. icpsleep.c contains a function used at several points in the driver to do a timed sleep.
g. icpbuf.c contains several utility functions for interpreting the 256-byte shared buffers with the ICP188C.
h. icpnetlist.c contains function for storing and searching the active network list when the driver is used by the DROT.
i. icpread.c contains the icpread entry-point function as well as functions to handle the various methods of reading in the different driver modes.
j. icpctrl.c contains functions for accessing the ICP188C's control ports.
h. init.icp contains the shell commands which are executed by the custom utility when the driver is installed in a new machine.
The Windows Library provides the DROT and DQM application processes with a structured way of interfacing with the user via the display screen and the keyboard. The Windows Library is divided into four distinct parts: The Screen Interface Function Library, the Windows Interface Function Library, the Screen Output Process, and the Clock Process.
By using facilities in the Screen Interface Function Library, several processes can write to the same display screen without interfering with each other. By using the Windows Interface Function Library, a single process can interface with the user via keyboard responses to on-screen menus. The Screen Output Process services the display requests from other processes and does the direct writing to the screen device. The Clock Process is an application which can maintain an on-screen clock in a variety of formats.
The four parts of the Windows Library are described in the paragraphs below.
Data Flow
Figure 7-1 is a data flow diagram for the entire Windows Library, showing how the four distinct parts described above interact. Application processes (including the Clock Process) place display-requests in the Screen Output Message Queue. The Screen Output Process services these requests in the order they arrive by sending the appropriate output to the display screen.
Meanwhile, a single application process will have access to the keyboard via the Windows Interface Functions. These functions in turn use the Screen Interface functions to display menus and dialog boxes on the screen. WINDOWS LIBRARY DATA FLOW DIAGRAM
The DROT and DQM both use two display devices called the "Real-Time Terminal" and "Non-Real-Time Terminal". Each terminal has a separate screen output message queue and a separate Screen Output Process. The same Clock Process writes to both.
Screen Output Process (w_scrout)
The Screen Output Process is spawned by the w_initscr function in the Screen Interface Function Library (in the file w_scrif.c). Before spawning the process, the function checks to see if a Screen Output Process already exists for that terminal, and if so, the existing one is used. Hence only one screen output process and one screen output message queue exist for a display terminal.
The w_initscr function is called with several arguments which it then uses in spawning the Screen Output Process. The Screen Output Process is called with the following command line syntax:
w_scrout [-c] [-i <init>] [-d <device>] [-t <term>] <key>
The only required argument is the final one which is the numeric key of the screen output message queue to be used. The other options have the following meanings:
[-c] The terminal is a console (as opposed to a detached serial terminal). This enables the extended ASCII character set used for drawing boxes and lines.
[-i <init>] Send the string <init> to the display terminal after it is opened. This is useful for sending initial escape sequences to set up colors, etc.
[-d <device>] This specifies the device name of the terminal to be used. If not present, standard output is used.
[-t <term>] This specifies the terminal type in the TERMCAPS or TERMINFO databases.
This process writes to the screen using the functions in the UNIX CURSES library package. Use of this package insures portability to other versions of unix, portability to other machines, and enables an external serial terminal to be used. For details on this package, see the chapter called Screen Processing in the UNIX System V Development System C Library Guide.
Processing Description
The Screen Output Process performs the following:
a. Initialization:
o Process command line arguments and set global variables.
o Place the terminal type in the environment for use by the UNIX CURSES library functions.
o Attach to the screen output message queue.
o Initialize the UNIX CURSES library.
o Send the initialization string to the terminal.
o Initialize the screen-overlay data structures.
b. Main Processing Loop:
o Read a display-request from screen output message queue.
o Process the request. If the request is CLEANUP_AND_DIE, then break out of the loop.
c. Termination:
o Clear the screen
o Close the output device
o Terminate the UNIX CURSES library.
Data Structures
a.Display requests received via the screen output message queue are of type 'struct SCREEN_MSG'. This structure is defined in the file w_scrout.h. It contains the UNIX process-ID's of the sender and addressee, then a command word followed by several descriptors to the command. The PIDs enable the usage of the queue for two-way communication (some of the commands elicit a response). Not all of the descriptors are used by all the commands. Table 7-1 contains a list of the commands.
b. When a window (overlay, scrolling, or subwindow) is defined, the Screen Output Process adds an entry to a linked list of overlays. Each entry in the table is of type 'struct OVLY_ENTRY', which is defined in the file w_scrovly.c. It contains a pointer to the (CURSES) WINDOW structure, the position of the window, the size of the window, and a unique window-tag assigned on creation. The 'tag' is returned to the process creating the window. Each subsequent update to the window specifies the window-tag.
Inputs
The Screen Output Process does no direct file input.
SCREEN OUTPUT REQUEST COMMANDS
COMMAND MEANING
======= =======
DEF_SUBWINDOW Define a subwindow to stdscr.
DEF_OVLYWINDOW Define an overlay window to stdscr.
DEF_SCROLLWINDOW Define a scrolling window
RM_WINDOW Remove an overlay, scrolling, or subwindow.
DEFINE_ATTR Define a display attribute
TEXT_OUTPUT Text output to beginning of a window
POS_TEXT Text output a specified position
ATTR_TEXT Text output with specified attributes
POS_ATTR_TEXT Positional, attribute text output
TEXT_CONTINUE Text out, don't reset cursor
HORZ_SINGLINE Single horizontal line
HORZ_DOUBLINE Double " "
VERT_SINGLINE Single vertical line
VERT_DOUBLINE Double " "
SINGBOX Single box
DOUBBOX Double box
CLEAR Clear entire screen
CLRTOBOT Clear to bottom of a window
CLRTOEOL Clear to end-of-line
DELETELN Delete a line (scroll subsequent up)
SCROLLUP Scroll a window up
SCROLLDN Scroll a window down
RINGBELL Ring the terminal's bell
DO_REFRESH Refresh the screen
MOVE_CURSOR Move the terminal's cursor.
REPAINT Repaint entire screen.
CLEANUP_AND_DIE Break out of main processing loop. Outputs
The specified terminal device is opened and written to using functions in the UNIX CURSES library.
Interprocess Communication
The screen output message queue is created by an application prior to spawning the Screen Output Process. The system-unique key is then passed to the Screen Output Process as a command line argument.
Source Files
The source files comprising the Screen Output Process are as follows.
a. w_scrout.c contains initialization, main loop, and termination functions.
b. w_scrovly.c contains functions for manipulating the screen overlay structures and for refreshing the screen.
On-Screen Clock Process (w_scrclock)
The On-Screen Clock Process is spawned by DROT and DQM user interface processes to maintain the GMT clock in the upper left corner of the screens. This is done through a library module called w_clock which accepts arguments for the position and format of the clock. If there is not a clock process already running, one is spawned and passed the arguments on the command line.
A single clock process can update time fields on several different terminals and windows. The On-Screen Clock Process creates a file that contains one line for each time field being updated.
Rather than spawning a new process, if this file already exists, the w_clock library module appends a line to this file and then sends the CLOCK_INTR signal to the On-Screen Clock Process, causing it to re-read the file for any changes.
Processing Description
The On-Screen Clock Process performs the following:
a. Initialization:
o If the /tmp/scrclock already exists, append a line to it and interrupt the running clock, then exit.
o Create /tmp/scrclock, adding a single line to it containing information from the command line arguments.
o Fill the action table from the contents of /tmp/scrclock.
o Trap the CLOCK_INTR signal to the function called intr.
o Ignore the SIGINT signal to prevent being killed as part of a process group.
b. Main Processing Loop:
o Get the current time.
o If the current time is at least one second greater than the previous time, do every action in the action list.
o Sleep for one second.
c. Upon receiving the CLOCK_INTR signal:
o Flush and then fill the action table from the contents of /tmp/scrclock. If this file does not exist, just exit.
o Re-trap the CLOCK_INTR signal.
o Continue with the main processing loop.
Data Structures
a. The clock process maintains a linked list called the 'action list'. Each entry in the list is of type struct ACTION which is defined in the file w_scrclock.c. Each entry contains all the information necessary to update a single time field in a specific window on a specific terminal.
When the clock process receives the CLOCK_INTR signal, it flushes this list and then refills it from information in the /tmp/scrclock file.
Inputs
The On-Screen Clock Process reads from the following files:
a. /tmp/scrclock contains a list of time fields to be updated.
Outputs
The On-Screen Clock Process writes to the following files:
If it doesn't already exits, /tmp/scrclock is created when the process initializes.
Interprocess Communication
The On-Screen Clock Process updates a time field by sending a TEXT_OUTPUT display request over a screen output message queue.
Source Files
w_scrclock.c contains the initialization, main loop, and termination functions.
Screen Interface Function Library
The Screen Interface Function Library provides an interface between an application process and a Screen Output Process. The library hides the details of the screen output message queue and its message structure from the application.
Each process wanting to write to a display terminal will call w_initscr once at the beginning, passing it the terminal device name, the terminal type, and an initialization string. After this the process uses the other functions in the library to define and display windows, text, lines, etc. Finally it calls the w_killscr function when finished.
A process can attach to several terminals simultaneously by calling w_initscr several times with different terminal names. In this case, each terminal will have a unique IPC-key for its screen output message queue. This key is returned by w_initscr. Only one terminal is the 'current screen' at a given time. The process can make any terminal the current screen by calling the w_swapscr function with the corresponding key. When finished, the process should detach from each terminal by making it the current screen and then calling w_killscr.
Processing Description
Most functions in the library result in one or more messages being sent over a screen output message queue. The functions in the module are listed Table 7-2 below and correspond for the most part with the display request commands listed in Table 8-1 above. See Appendix G for a detailed description of the calling sequence and actions of each function.
Data Structures
The display requests sent over the screen output message queue are of type struct SCREEN_MSG. This structure is defined in the file w_scrout.h.
Inputs
The w_initscr function, before spawning a new Screen Output Process for the requested terminal, and checks the file to see if one is already running. If one does, the existing message queue is attached.
Outputs
The w_initscr function, before spawning a new Screen Output Process for the requested terminal, checks the file /tmp/scrout to see if one is already running. If one does not, the screen output message queue is created, an entry is added to the file, and the Screen Output Process is spawned. If the file does not exist, it is created.
SCREEN INTERFACE FUNCTIONS
FUNCTION PURPOSE
======== =======
w_attrtext Write text with specific attributes.
w_bell Ring the bell.
w_box Draw a box.
w_curkey Return IPC-key of screen output message queue.
w_define_attr Define screen attributes.
w_defovlywindow Define overlay window.
w_defsubwindow Define a sub-window.
w_dorefresh Do a screen-refresh.
w_horzline Draw horizontal line.
w_initscr Attach to a screen.
w_killscr Detach from the current screen.
w_movecursor Move cursor.
w_posattrtext Write text at specific position with specific attributes.
w_postext Write text at a specific position.
w_repaint Repaint the entire screen.
w_swapscr Make another screen the current screen.
w_rmwindow Remove a previously defined window.
w_text Write text at window origin.
w_vertline Draw vertical line.
w_wclear Clear a window.
w_wclrtobot Clear to bottom.
w_wclrtoeol Clear to end-of-line.
w_deleteln Delete a line in a window.
w_scrolldn Scroll a window down.
w_scrollup Scroll a window up.
Interprocess Communication
Screen output message queues are used to send display-requests to the various Screen Output Processes.
Source Files
w_scrif.c contains all of the functions listed in table 8-2 above.
Windows Interface Function Library
The functions described in the previous section can be used by several processes, which are concurrently writing to the same screen for the purpose of displaying real-time status updates. The functions in the Windows Interface Library are called by one-process-per-terminal. They give the process access to the keyboard and facilitate a user-friendly interface through overlapping windows.
The process first calls functions to define the interactive windows and the objects contained therein. It then can activate a window, allowing the user to move the cursor within the window with the arrow keys. The 'objects' within a window are one of the following types:
o Menu Item: The user can select a menu item by moving the cursor to it, and then pressing ENTER.
o Text Entry Field: The user can move the cursor to the field and then enter text from the keyboard.
o Cycle Field: The user can cycle through a predetermined sequence of values using the space bar.
o Labels & Lines: Static text in a window.
After a menu item is selected, a text entry field changed, or a cycle field set, a pre-defined function is called with appropriate arguments. This function can cause lower level windows to be activated, resulting in a hierarchical menu system.
Functions are also provided for giving a process direct, raw access to the keyboard, and for defining tokens to be returned when various escape-sequences are received from the keyboard.
Processing Description
The functions in this library fall into several types, described below:
a. Initialization/Termination:
w_init Initialize and attach to a display device.
w_wrapup Detach from a display device.
b. Direct Keyboard Interface:
w_openkeyboard Open keyboard device.
w_closekeyboard Close keyboard device.
w_getkey Return one keyboard token.
w_keytrans Define a token to be returned for an escape sequence.
w_speckeyadd Define a function which is called immediately on the receipt of special keystrokes.
The open and close functions do not need to be called if the w_init function was called.
c. Window and Window-Object Definition:
w_mkwindow Define a new window.
w_addmenu Add a menu-item to a window.
w_addcycle Add a cycle-field to a window.
w_addtextinput Add a text-input field to a window.
w_addlable Add a label field to a window.
w_addline Add a horizontal line to a window.
w_rmobject Remove an object (of any type) from a window.
d. Window Activation:
w_activate_windowActivate a previously defined interactive window.
w_displayhelp Display a help/error/warning message on the screen bottom.
e. Miscellaneous:
w_viewfile Interactively view a files contents in a window on the screen.
w_yesno Get a yes/no response from the user.
w_keymenu Format and display a menu of keystrokes on the screen bottom.
Data Structures
a. All information necessary to display a window is kept in a structure of type 'WINDOW', which is defined in the file w_windows.h. This structure contains the position, size, and attributes of the window. It contains pointers to functions which are called when the window is entered and exited. It also contains a pointer to a linked list of window-objects and a pointer to the currently-active object in the window. b. Information about each window object is kept in a structure of type 'struct Windowobject', which is defined in the file w_windows.h.
Inputs
The specified keyboard device is opened and read. Input is converted to integer tokens before being passed to the application. The tokens are simply the ASCII value for the alphanumeric keys. Function and arrow key tokens are defined in the file w_keyboard.h.
Outputs
The Window Interface Function Library does no direct file output.
Interprocess Communication
The Window Interface Function Library uses the screen output message queue via the Screen Interface Function Library described above.
Source Files
The source files comprising the Screen Interface Function Library are as follows.
a. w_keyboard.c contains functions for initializing and reading the keyboard.
b. w_keytrans.c contains functions for converting keyboard input into tokens.
c. w_action.c contains default action functions which can be used by the application.
d. w_activate.c contains functions for activating a window on the screen.
e.w_edlin.c contains functions for using text-input-field objects in a window.
f. w_cycle.c contains functions for using cycle-field objects in a window.
g.w_init contains functions for initializing the Windows Interface Library.
h. w_speckey.c contains functions for defining functions to be called when special keystrokes are received.
i. w_windata.c contains functions for defining and manipulating windows and window objects.
j. w_keymenu.c contains functions for displaying a menu of keystrokes on the screen bottom.
k. w_yesno.c contains a function for getting a yes/no response from the user.
l. w_viewfile.c contains functions for interactively viewing a file's contents on the screen.
A1
ERROR AND ALARM MESSAGES
Each message in the list below is preceded by the name of the process which generated it. The text of the alarm is given followed by a brief explanation. If '(FATAL)' appears after the message text it means that the occurrence of the alarm will also cause the DROT/DQM to terminate.
q_ctrl: Error on control Queue (FATAL)
The system call for receiving a control message failed.
q_ctrl: Could not spawn kids. (FATAL)
Control process was unable to spawn a DQM process.
q_ctrl: Timeout waiting for children to die (FATAL)
A child process did not report with a DYING message.
q_ctrl: Unknown child process <N> reports ready-to-go.
A process with the given PID reported ready-to-go over the control message queue.
q_ctrl: Unknown child process <N> reports ready-to-die.
A process with the given PID reported DYING over the control message queue.
q_ctrl: Child process <name> unexpected death. (FATAL)
A DQM process reported with a DYING message unexpectedly.
q_ctrl: Unknown message type on control queue <N>
A message of the given, unknown type was received over the control message queue. It is ignored.
q_ctrl: Cannot lock into memory
The system would not let q_dapsif lock into memory. The executable file must have the set-UID-bit set and be owned by root.
q_ctrl: Could not send DQM_DOMSAT_DIS
The control process could not inform q_dapsif that DOMSAT was disabled.
q_ctrl: Could not send DQM_DOMSAT_ENA
The control process could not inform q_dapsif that DOMSAT was enabled.
q_dapsif: g_getconfig() failed (FATAL)
Could not attach to configuration shared memory area.
q_dapsif: Could not attach to serial output queue (FATAL)
The DAPS interface process could not attach to the serial output message queue.
q_dapsif: Cannot open <term-name> (real-time terminal) (FATAL)
q_dapsif: Cannot send DYING message (FATAL)
The DAPS interface process could not report DYING over the control message queue as part of a DQM shutdown.
q_dapsif: Could not initialize serial port (ALARM)
This can be caused by erroneous serial parameters such as a non-existant device name.
q_dapsif: Serial port write error (ALARM)
The DAPS interface process could not write to the serial port.
q_dapsif: Cannot open DQM log file <name> (ALARM)
The DAPS interface process could not open the named file.
q_dapsif: Cannot lock into memory
The system would not let q_dapsif lock into memory. The executable file must have the set-UID-bit set and be owned by root.
q_dapsif: Error on serial message queue (FATAL)
The system returned an error on an attempt to read the queue.
q_oluser: Cannot get configuration shared memory (FATAL)
Could not attach to configuration shared memory area.
q_oluser: Cannot send DYING message (FATAL)
The Non-Real-Time User Interface process could not report DYING over the control message queue as part of a DQM shutdown.
q_oluser: Cannot lock into memory
The system would not let q_oluser lock into memory. The executable file must have the set-UID-bit set and be owned by root.
q_oluser: Cannot send OL_SCROUT message (FATAL)
The Non-Real-Time User Interface Process could not send the OL_SCROUT control message containing the terminal tags.
q_oluser: Cannot make interactive window (FATAL)
This is due to an error in wlib.
q_oluser: Could not start clock
The GMT-clock in the upper-left corner of the screen could not be started.
q_oluser: Cannot send READY_TO_GO message (FATAL)
This is due to an error on the control message queue.
q_recv: g_getconfig() failed (FATAL)
Could not attach to configuration shared memory area.
q_recv: Cannot lock into memory
The system would not let q_recv lock into memory. The executable file must have the set-UID-bit set and be owned by root.
q_recv: Cannot open <term-name> (real-time terminal) (FATAL)
q_recv: Cannot open <term-name> (off-line terminal) (FATAL)
q_recv: Cannot send DYING message (FATAL)
The DQM Receive Process could not report DYING over the control message queue as part of a DQM shutdown.
q_recv: Read error (FATAL)
Due to an error in the DOMSAT Interface (ICP188C device or device driver).
q_recv: ICP Error: CRC error(s)
CRC errors in X.25 packet(s) received from DOMSAT link. This
message may occur from noise on the link and does not necessarily indicate messages have been dropped.
q_recv: ICP Error: Host too slow -- message dropped.
The DQM Receive Process could not read messages fast enough to keep the ICP188C from filling all its buffers. This can happen if the system is extremely loaded down with extraneous (non-DQM) processes.
q_recv: ICP Error: Fixed ICP out-of-phase.
The ICP188C and the device driver were out of phase. This should never happen.
q_recv: Timeout on DOMSAT Link.
Nothing has been received over the DOMSAT link for the amount of time specified for time-out in the configuration file.
q_recv: Cannot open <file-name> (ICP Program) (FATAL)
The DQM Receive Process could not open the file specifed for the ICP Program in the configuration file.
q_recv: Ioctl error: Could not reset. (FATAL)
While attempting to enable the DOMSAT link, the DOMSAT Receive Process could not reset the ICP188C.
q_recv: Ioctl error: Could not change mode (FATAL)
While attempting to enable the DOMSAT link, the DOMSAT Receive Process could change the device driver mode.
q_recv: Cannot allocate buffers! (FATAL)
The DOMSAT Receive Process could not allocate receive-buffers during its initialization.
q_recv: Cannot open <device-name> (FATAL)
The DOMSAT Recevie Process could not open the device-special file for the ICP188C specified in the configuration file.
q_recv: Cannot get serial output message queue. (FATAL)
q_rtuser: Cannot get configuration shared memory (FATAL)
Could not attach to configuration shared memory area.
q_rtuser: Cannot send DYING message (FATAL)
The DQM Real-Time User Interface Process could not report DYING over the control message queue as part of a DQM shutdown.
q_rtuser: Cannot lock into memory
The system would not let q_recv lock into memory. The executable file must have the set-UID-bit set and be owned by root.
q_rtuser: Could not start clock
The GMT-clock in the upper-left corner of the screen could not be started.
q_rtuser: Cannot add menu item to window! (FATAL)
q_rtuser: Could not define overlay (FATAL)
This is due to an error in wlib.
q_rtuser: Cannot send RT_SCROUT message (FATAL)
The Real-Time User Interface Process could not send the RT_SCROUT control message containing the terminal tags.
q_rtuser: Cannot make interactive window (FATAL)
This is due to an error in wlib.
q_rtuser: Cannot send READY_TO_GO message (FATAL)
This is due to an error on the control message queue.
t_ctrl: Could not send SER_CNFGCHANGE
Unable to send configuration change to serial output task
t_ctrl: Cannot add list <list number>
The specified network list could not be made active.
t_oluser: Cannot open network list file <nl?>
The Non-realtime Functions Task could not open the specified network list for for reading. Either it doesn't exist or there is a permission problem.
t_oluser: Cannot open network list for writing
Non-Real Time Functions Task could not open the specified network list for for writing, probably due to a permission problem.
t_oluser: Error searching directory
A system read-error occurred while searching the directory entries.
t_recv: Read error (FATAL)
Error reading Franklin ICP188C.
t_recv: Timeout on DOMSAT Link
No DCP messages have been received in the time period specified in the drotconfig file (default = 90 seconds).
t_recv: ICP Error: CRC error(s)
CRC errors in X.25 packet(s) received from DOMSAT link. This
message may occur from noise on the link and does not necessarily indicate messages have been dropped.
t_recv: ICP Error: Host too slow -- message dropped
Internal buffers on Franklin ICP188C became full before the PC could empty them. Hence some DCP messages may have been dropped. This could happen if the system is heavily loaded with non-DROT processes.
t_recv: ICP Error: Fixed ICP out-of-phase
This is related to the "Host too slow" message above.
t_recv: Cannot open <program-name> (ICP Program)
The file specified in 'drotconfig' for ICP_PROGRAM is not readable by the DROT.
t_recv: Directory overflow -- messages deleted
The message directory filled up before the message storage file did. The value of 'max_records' in 'drotconfig' is too small.
t_recv: Serial output overflow
This can happen when real-time serial output is enabled and a very slow serial line rate (e.g. 300 baud) is specified.
t_serout: Cannot open <message-file-name>
Serial output task is unable to open the message file.
t_serout: Serial output overflow
Internal buffers in serial output task overflowed. Some DCP messages queued for output may have been dropped. This can happen when many messages are queued and a very slow serial line rate (e.g. 300 baud) is specified.
t_serout: Could not initialize serial port
Invalid parameters were specified for serial port (name, baud, bits per character, parity, stop-bits)
t_serout: Cannot open DCP list file
Serial output task could not open a temporary file queued for transmission.
t_xmitmsg: Cannot allocate buffers
The Non-realtime Functions Task could not allocate memory for internal buffers.
t_xmitmsg: Cannot create tmp file
The Non-realtime could not create a temporary file for queuing messages for transmission. Either the hard disk is full or there is a permissions problem.
t_xmitmsg: Error writing to file
The Non-realtime Functions Task could not create, or write to a temporary file in order to queue DCP messages for transmission.
t_xmitmsg: Error sending on message queue
The Non-realtime Functions Task could not send a trigger-message to the serial output task.
REFERENCES
The following references are pertinent to maintenance and development for the DROT and DQM.
a. UNIX System V/386 Operating System Manuals for SCO UNIX System V/386 Version 3.2v2.0. The manual set includes a System Administrators's Guide, User's Reference, and User's Guide.
b. UNIX System V/386 Development System Manuals for SCO UNIX System V/386 Development System Version 3.2v2.0. The manual set includes a C-Language Guide, a C-Library Guide, a C- Language Reference, Programmer's Guide, Macro Assembler User's Guide, and Programmer's Reference.
c. Kernighan and Ritchie, The C Programming Language, second edition, AT&T Bell Laboratories, Murray Hill, New Jersey, 1988.
d. Franklin Telecom, Technical Reference Manual for ICP188C Communications Processor, 1987.
e. User Interface Manual for the DAPS DOMSAT Receive Only Terminal (DROT), prepared by Integral Systems, Inc. for contract # 50-DDNE-7-0037, April 1991.
f. User Interface Manual for the DAPS DOMSAT Quality Monitor (DQM), prepared by Integral Systems, Inc. for contract # 50-DDNE-7-0037, June 1989.
DOMSAT MESSAGE FORMAT
Platform messages shall be transmitted to the DCS users via DOMSAT using the formats described herein.
The data transmission format resembles the CCITT standard X.25 protocol using Link Access Procedure B and Permanent Virtual Circuit at the Link and Packet levels. Data shall be transmitted at 56 KBPS. Since the data stream is to be transmitted in broadcast mode, with no opportunity for the receiving station to acknowledge data reception, this method of transmission represents a partial implementation of the X.25 protocol.
Each link-level frame will have the following format:
Element Name Bytes Format
------------ ----- ------
Flag 1 01111110
Frame Address 1 --
Command 1 --
Packet 4 to 256 --
Flag 1 01111110
Each X.25 packet shall begin with the standard three bytes, the first two of which shall be constant in this implementation. The third byte contains the "more dat bit" and "sequence" fields labelled "M" and "SSS", respectively. The "sequence" field is the X.25 send sequence number. The "more data bit" shall be zero if this packet completes the transmission of a DCP message and one otherwise.
Following these three bytes, the 16-bit "Message Sequence Number" shall be transmitted (2-bytes), followed by the "Dup Flag & Packet Sequence" (1 byte). The "Message Sequence Number" is incremented by one as each new DCP message is transmitted, and is zeroed at overflow. Thus, it will remain constant for all packets of a given DCP message. Its primary function is to provide an additional check that all transmitted messages have been received. The "Dup Flag & Packet Sequence" consists of a one bit flag (D) indicating that this message is a retransmitted duplicate of a previous message, followed by a seven bit sequence number (SSSSSSS), which starts at one with the initial packet for each message and increments until the entire data block has been transmitted. The remainder of the packet consists of up to 250 bytes of the message.
Each packet will have the following format:
Element Name Bytes Format
------------ ----- ------
Group 1 00010000
Channel 1 00000000
Type 1 000MSSS0
Message Sequence Number 2 Binary
Dup Flag & Packet Sequence 1 DSSSSSSS
DCP Message Segment 1 to 250 --
A complete DCP message is formed by concatenating all of the successive DCP Message Segments. The message contents has the following format:
Length
Item (in bytes) Format
=============== ========== ============================
DCP Address 8 ASCII hex digits (0-9, A-F)
Arrival Date/Time:
Year 2 ASCII digits
Day 3 ASCII digits (Julian day)
Hour 2 ASCII digits (00 - 23)
Minute 2 ASCII digits (00 - 59)
Second 2 ASCII digits (00 - 59)
Failure Code 1 ASCII character:
G Good Message
? Parity Error
W Received on wrong channel
D Duplicate (multiple chan)
A Correctable Address Error
B Bad Address
T Timeerror (early/late)
U Unexpected Message
M Missing Message
I Invalid Address
N Non-complete entry in PDT
Q Bad Quality Measurements
C Comparison error on test
transmission
Signal Strength 1 ASCII digits
Frequency Offset 2 ASCII digits
Modulation Index 1 ASCII character
Data Quality 1 ASCII character
Channel Received 3 ASCII digits
Spacecraft Received 1 ASCII char: 'E' or 'W'
Uplink Carrier Status 2 ASCII hex digits: Status for spacecraft on which message was received.
Message Data Length 5 ASCII digits
Message Data <variable> <variable>
LIST OF ACRONYMS
BCH Bose, Ray-Chaudhuri, and Hocquengheim (an encoding scheme for DCP addresses)
CGA Color Graphics Adapter
CRT Cathode Ray Tube (display monitor)
DAPS DCS Automated Processing System
DCP Data Collection Platform
DCS Data Collection System
DOMSAT Domestic Satellite
DQM DOMSAT Quality Monitor
DROT DOMSAT Receive Only Terminal
EGA Enhanced Graphics Adapter
EISA Extended Industry Standard Architecture
GMT Greenwich Mean Time
GOES Geostationary Operational Environmental Satellite
HGC Hercules Graphics Card
KBPS Kilobits per second
MB Megabyte (1,048,576 bytes)
MS-DOS MicroSoft Disk Operating System
NESDIS National Environmental Satellite, Data and Information Service
NOAA National Oceanic and Atmospheric Administration
PC Personal Computer
RAM Random Access Memory
SCO Santa Cruz Operation
TBD To Be Determined
VGA Virtual Graphics Array
DROT CONFIGURATION FILE
The following is the DROT configuration file as provided in the installation floppy.
#
# DROT Configuration File
#
#
# X.25 Parameters:
#
XLINE: /dev/icp 56000 DROT
#
# Timeout for DOMSAT:
#
DOMSAT_TIMEOUT: 90
#
# Program to download to ICP:
#
ICP_PROGRAM: bin/188x25.exe
#
# Serial Line Parameters:
#
SERIAL_LINE: /dev/tty1a 9600 8 none 1
# Strings sent at beginning and end of each message:
MSG_BEG: ""
MSG_END: "\n\n\n"
#
# Realtime Terminal:
#
RT_TERMINAL: /dev/tty02 ansi "\033[2;15;1m\033[7;0;2m" 1 15 1
ALARMCOLOR: 4
#
# Off-Line Terminal:
#
OL_TERMINAL: /dev/tty03 ansi "\033[2;15;1m\033[7;0;2m" 1 15 1
#
# Various Operational Parameters:
#
MESSAGEFILE: messages
max_storage: 20000000
max_records: 300000
ACTIVE_LIST: 1 2 3 4
PRINTCMD: 'pr %s | lp'
RT_SERIAL_OUTPUT: disabled
GLOBAL_BULLETINS: 11111111
DCP_BULLETINS: 22222222
MAIL: 33333333
DAPS_ALIVE: DADADADA
USER_IDS: ID0001 ID0002 ID0003 ID0004
DQM CONFIGURATION FILE
DQM CONFIGURATION FILE
The following is the DQM configuration file as provided in the installation floppy.
#
# DQM Configuration File
#
#
# X.25 Parameters:
#
XLINE: /dev/icp 56000 DQM
#
# Timout for DOMSAT:
#
DOMSAT_TIMEOUT: 90
#
# Program to download to ICP:
#
ICP_PROGRAM: bin/188x25.exe
#
# Serial Line Parameters:
#
SERIAL_LINE: /dev/tty1a 9600 8 even 1
#
# Real-Time Terminal:
#
RT_TERMINAL: /dev/tty02 ansi \033[2;1;7m\033[7;0;2m 1 1 7
ALARMCOLOR: 4
#
# Off-Line Terminal:
#
OL_TERMINAL: /dev/tty03 ansi \033[2;1;7m\033[7;0;2m 1 1 7
#
# DQM DAPS Report Log File:
#
DQM_LOG: dqm_log 10000
#
# Seconds between periodic DAPS reports:
#
PERIODIC_RPT: 60
The DQM software consists of a collection of cooperating concurrent processes. The processes are divided into two groups: those which perform the time-critical ingest, validation, and quality reporting, and a single process (non-time-critical) for viewing the log of past quality reports. Figure F-1 depicts the data flow for the entire DQM.
DCP Messages are received over the DOMSAT link and checked for sequence errors, CRC errors, and missing-packet errors. If errors are detected, a 'quality report' is sent to the DAPS via a serial link. Also, a 'periodic report' is sent once per minute to DAPS containing the message sequence number of the last valid DCP message received.
The real-time processes are:
o DQM Control Process (q_ctrl)
o DOMSAT Receive Process (q_recv)
o Real-Time User Interface Process (q_rtuser)
o DAPS Interface Process (q_dapsif)
o Domsat Enable/Disable Utility (domsat)
o Real-Time Screen Output Process (w_scrout)
o DROT Shutdown Process (killdrot).
The non-real-time process are:
o Non-Real-Time User Interface Process (q_oluser)
o Non-Real-Time Screen Output Process (w_scrout)
o On-Screen Clock Process (w_clock)
All of these processes are described in detail in the paragraphs below.
HIGH-LEVEL DQM DATA FLOW DIAGRAM
DQM Control Process (q_ctrl)
The DQM Control Process is started when the user "dqm" logs in and invokes the dqm command file. It sets up all of the IPC resource to be used by the DQM and then spawns all of the DQM concurrent processes. After all of the DQM processes are running, it coordinates some of the interprocess communication such as user-requested enable/disable of the DOMSAT link, and the logging and displaying of alarm messages. When the user "dqm" logs off, the DQM Control Process coordinates the shutdown of the DQM software.
Data Flow
Figure F-2 is a data flow diagram for the DQM control process.
Processing Description
The DQM Control Process performs the following functions:
a. Initialization:
o Check for the existence of, and then create a lock-file called "/usr/dqm/dqm_running" to prevent more than one iteration of the DROT or DQM software to be running at the same time. This is handled through the g_tq_running library function.
o Initialize all of the DQM IPC resources and create a file called "/usr/dqm/q_cnfgkey" containing the IPC key of the configuration shared memory area.
o Load the information in the "dqmconfig" file into the configuration shared memory area.
DQM CONTROL PROCESS DATA FLOW DIAGRAM
o Spawn all of the cooperating DQM processes. Then wait for each to report READY_TO_GO via the control message queue.
b. Main Processing Loop:
o Receive and process control messages from other process via the control message queue. Control messages usually result in some kind of configuration change such as enabling/disabling the DOMSAT link, etc.
c. Shutdown:
o When the SHUTDOWN message is received over the control message queue from the "killdqm" process, send the interrupt-signal to all of the child processes. Then wait for each to respond with a DYING message.
o Save the current configuration in the "dqmconfig" file.
o Remove the "/usr/dqm/dqm_running" lock-file.
Data Structures
a. The DQM control process is the only process which write-access to the configuration shared-memory area. This area is of type 'struct CONFIG_SHM' and is defined in the file g_config.h.
b. Messages received from other processes via the control message-queue are of type 'struct CTRL_MSG' which is defined in the file g_ctrl_q.h. This is a flexible structure which can contain many types of messages and information.
Inputs
dqmconfig is opened at startup and its contents are loaded into the configuration shared memory area. This is handled through the g_parscnfg.c library module.
Outputs
The DQM control process writes to the following outputs:
a. /usr/dqm/q_cnfgkey is created when the program starts up. It contains the IPC key of the configuration shared memory area. This enables the other processes to attach to this area.
b. /usr/dqm/dqm_running is created when the program starts up. This lock file insures that two copies of the DROT/DQM cannot be running at the same time. This is handled through the g_tq_run.c library module.
c. dqmconfig is overwritten when the program shuts down with the current (possibly changed) configuration. This is handled through the g_savecnfg.c library module.
d. errlog.a or errlog.b is appended to as needed for the logging of system events and alarms. This is handled through the g_error.c library module.
e. Standard Output is used to display alarms and error messages.
Interprocess Communication
The DQM control processes uses the following IPC resources:
a. The configuration shared memory is initialized and then updated periodically as needed.
b. The control message queue is read continuously for various configuration/control requests from the other processes. c. A signal (SIGUSR1) is used to interrupt the other DQM processes when the shutdown message is received. This is handled through the g_kidlist.c library module.
d. The serial output message queue is created by this process when it is started up, and then removed when it is shut down. This is handled through the g_parscnfg.c library module.
Source Files
t_ctrl.c contains the initialization, clean-up, main, and main-loop functions.
DOMSAT Receive Process (q_recv)
The DOMSAT Receive Process is spawned by the DQM Control Process. It interfaces with the Franklin Telecom ICP device driver to receive incoming DCP messages. Incoming message blocks are checked for CRC and sequence errors. If errors are found, a quality report is sent to the DAPS Interface Process (q_dapsif). Every minute a report is sent to the DAPS Interface Process with the message sequence number of the last good DCP message received. The real-time status display is updated showing the message sequence number of the last good message received and the current DOMSAT quality.
DOMSAT FLOW
Figure f-3 is a data flow diagram for the DOMSAT Receive Process.
Processing Description
The DOMSAT Receive Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
o Attach to both the real-time and non-real-time terminals for sending status updates.
o Attach to the serial-output message queue.
o Allocate receive buffers and tables.
o Open the specified DOMSAT device name.
o Send the READY_TO_GO message to the DQM Control Process.
b. Main Processing Loop:
o Wait for the DOMSAT-Enable flag in the configuration area to be set.
o Download the X.25 program to the ICP device.
o Initialize the sequence-number check.
o While it is enabled:
o Issue a read system call to the ICP device driver.
o Keep statistics on message quality.
o Check for timeout on the link if no messages arrived.
oCheck sequence number of each received message. If gaps are found, send report.
o If it's time for a periodic report, send one.
o Update the status display.
c. Shutdown:
o Detach from the configuration shared memory area.
o Detach from the real-time and non-real-time terminals.
o Send the DYING message to the DQM Control Process.
DQM DOMSAT RECEIVE PROCESS DATA FLOW DIAGRAM
Data Structures
a. Read-requests are made to the ICP device driver by passing it a pointer to a large buffer of type 'struct ICPREADREQ'. This structure is defined in the file g_icpdrv.h. It is allocated by the DOMSAT receive process and passed empty to the ICP device driver. The driver fills in the empty structure and returns the number of complete messages received.
For the DQM, the driver only fills the buffer with the message headers containing the message sequence number and X.25 receive status.
Inputs
The DOMSAT Receive Process reads from the following input files:
a.The ICP device node (/dev/icp) is opened.
b. The specified ICP-resident program is opened and downloaded to the ICP device whenever DOMSAT is enabled.
Outputs
The DQM DOMSAT Receive Process does no direct file output.
Interprocess Communication
The DOMSAT Receive Process uses the following IPC resources:
a.The configuration shared memory is read during initialization to determine various operational parameters. It contains the DOMSAT-ENABLE flag which is checked after every read call.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DQM Control Process at start-up and shut-down time, respectively. This is handled by the g_sendctrl.c library module.
c. When the shutdown signal (SIGUSR1) is received (from the DQM Control Process), the main processing loop is terminated and this process is gracefully halted.
d. The real-time and non-real-time screen output message queues are used to display various status information. This is handled through various function in the Windows Library.
e. The serial output message queue is used to send quality reports to the DAPS Interface Process.
Source Files
The source files comprising the DQM DOMSAT Receive Process are as follows.
a. q_recv.c contains the initialization, shutdown, main, and main loop functions.
b. q_chkmsg.c contains functions for checking the sequence number and CRC of each incoming DCP message.
c. q_sendrpt.c contains functions for building and sending the quality reports to the DAPS Interface Process.
DQM Real-Time Functions User Interface Process (q_rtuser)
The Real-Time Functions User Interface Process is spawned by the DQM Control Process. It handles the user-interface for the real-time portion of the DQM by making heavy use of the Windows Library to define and update areas on the screen, and to interact with the user via the keyboard.
Data Flow
Figure f-4 is a data flow diagram for the DQM Real-Time Functions User Interface Process.
Processing Description
The DQM Real-Time Functions User Interface Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
o Attach to the specified real-time terminal.
o Define color attributes for user interaction.
o Start the clock in the upper left corner.
o Paint the screen template.
o Set up the scrolling text box in which to display the most recent quality reports.
o Define an overlay window for displaying alarms.
o Send a message to the DQM Control Process containing the various screen tags for real-time update. The Control Process then places these in the configurations area so that other processes can update the screen.
o Create the interactive configuration-change windows.
o Define special keystrokes for alarm-cancel (F10) and to repaint the screen (CTRL-L).
o Send the READY_TO_GO message to the DQM Control Process.
DQM REAL-TIME FUNCTIONS USER INTERFACE PROCESS
DATA FLOW DIAGRAM
b. Main Processing Loop:
o Wait for a keystroke from the user.
o If it is ESCAPE, activate the top-level configuration change window using the Windows Library functions.
o If it is one of the special keystrokes defined above, perform the appropriate functions.
o Otherwise it's an undefined keystroke, beep furiously.
c. Shutdown:
o Detach from the real-time terminal.
o Detach from the configuration shared memory area.
o Send the DYING message to the DROT Control Process.
Data Structures
a. During initialization, this process uses the Windows Library functions to define various 'windows' on the screen to be used later for screen update. For example, one window contains the constantly updating GMT clock. Another window shows the message sequence number of the last good message received. Each window has a unique (integer) 'tag' associated with it. This process places these tags in a structure of type 'struct RT_TAGS', and sends them via the control message queue to the DQM Control Process, where they are placed in the configuration shared memory area. This structure is defined in the file g_ctrl_q.h.
b. This process defines and maintains various structures of type 'WINDOW' and 'WINDOWOBJECT'. These types are defined in the file w_windows.h. This process does not access the contents of these structures directly, but uses the Windows Library functions to do so by passing pointers.
Inputs
The specified real-time terminal is opened for reading from the keyboard. This is handled through the Windows Library w_keyboard.c module.
Outputs
The DQM Real-Time Functions User Interface process does no direct file output. Screen outputs are handled through the screen-output process in the Windows library.
Interprocess Communication
The DROT Real-Time Functions User Interface Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DQM Control Process at start-up and shut-down time, respectively. It is also used to send configuration change requests in direct response to user action (e.g. Enabling/Disabling the DOMSAT link).
c. When the shutdown signal (SIGUSR1) is received (from the DQM control process), the main processing loop is terminated and this process is gracefully halted.
d. The real-time screen output message queue is used to send screen updates to interact with the user. This is handled through various function in the Windows Library.
Source Files
q_rtuser.c contains the initialization, shutdown, main, and main loop functions.
DQM Non-Real-Time Functions User Interface Process (q_oluser)
The Non-Real-Time Functions User Interface Process is spawned by the DQM Control Process. It handles the user-interface for the real-time portion of the DQM by making heavy use of the Windows Library package to define and update areas on the screen, and to interact with the user via the keyboard.
The only non-real-time function in the DQM is the viewing of the current and backup quality report logs. Hence this process is much simpler than its DROT counterpart.
Data Flow
Figure f-5 is a data flow diagram for the DQM Non-Real-Time Functions User Interface Process.
Processing Description
The DQM Non-Real-Time Functions User Interface Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
o Attach to the specified real-time terminal.
o Define color attributes for user interaction.
DQM NON-REAL-TIME FUNCTIONS USER INTERFACE PROCESS
DATA FLOW DIAGRAM
o Start the clock in the upper left corner.
o Paint the screen template.
o Set up the interactive scrolling window in which to display quality reports.
o Define an overlay window for displaying alarms.
o Send a message to the DQM Control Process containing the various screen tags for real-time update. The Control Process then places these in the configurations area so that other processes can update the screen.
o Define special keystrokes for alarm-cancel (F10) and to repaint the screen (CTRL-L).
o Send the READY_TO_GO message to the DQM Control Process.
b. Main Processing:
o Activate the top-level window using the Windows Library functions.
c. Shutdown:
o Detach from the real-time terminal.
o Detach from the configuration shared memory area.
o Send the DYING message to the DROT Control Process.
Data Structures
a. During initialization, this process uses the Windows Library to define various 'windows' on the screen to be used later for screen update. Each window has a unique (integer) 'tag' associated with it. This process places these tags in a structure of type 'struct RT_TAGS', and sends them via the control message queue to the DQM Control Process. This structure is defined in the file g_ctrl_q.h.
b. This process defines and maintains various structures of type 'WINDOW' and 'WINDOWOBJECT'. These types are defined in the file w_windows.h. This process does not access the contents of these structures directly, but uses the Windows Library functions to do so by passing pointers.
Inputs
The DQM Real-Time Functions User Interface process reads from the following input files:
a. The DQM quality report logs. These are two files called dqm_log.a and dqm_log.b. When one log is full, the other is flushed and then written to. Each log holds 10,000 quality reports. The DQM Non-Real-Time Functions Process enables the user to interactively read either file.
b. The specified non-real-time terminal is opened for reading from the keyboard. This is handled through the Windows Library w_keyboard.c module.
Outputs
The DQM Non-Real-Time Functions User Interface process does no direct file output. Screen outputs are handled through the Screen Output Process in the Windows library.
Interprocess Communication
The DROT Non-Real-Time Functions User Interface Process uses the following IPC resources:
a. The configuration shared memory is read during initialization to determine various operational parameters. b. The control message queue is used to send the READY_TO_GO and DYING messages to the DQM Control Process at start-up and shut-down time, respectively.
c. When the shutdown signal (SIGUSR1) is received (from the DQM control process), the main processing loop is terminated and this process is gracefully halted.
d. The non-real-time screen output message queue is used to send screen updates to interact with the user. This is handled through various functions in the Windows Library.
Source Files
q_oluser.c contains the initialization, shutdown, main, and main loop functions.
DQM DAPS Interface Process (q_dapsif)
The DAPS Interface Process is spawned by the DQM Control Process. It handles the serial link to DAPS for the transmission of quality reports. It reads the serial parameters such as device name, baud rate, etc., from the configuration shared memory area to initialize the serial device. It then reads request messages from the serial output message queue. Each message is one of the following types of request:
SER_CNFGCHANGE Serial port configuration change
DQM_PERIODIC Send a periodic report to DAPS.
DQM_CRC_ERR Send a CRC error report to DAPS.
DQM_SEQ_ERR Send a sequence error report to DAPS.
DQM_DOMSAT_ENA Log thefact that the DOMSAT link was enabled.
DQM_DOMSAT_DIS Log the fact that the DOMSAT link was disabled.
SER_SHUTDOWN Clean up and die.
As each report is sent to DAPS it is also logged in the DQM report log. The report log is comprised of two files called dqm_log.a and dqm_log.b. When one file is full, the other is flushed and then written to. Each file holds 10,000 quality reports.
Data Flow
Figure f-6 is a data flow diagram for the DAPS Interface Process.
Processing Description
The DAPS Interface Process performs the following functions:
a. Initialization:
o Attach to the configuration shared memory area.
o Initialize the serial port with the parameters from the configuration file.
o Attach to the serial-output message queue.
o Attach to the real-time screen output message queue for sending status information.
o Send the READY_TO_GO message to the DROT Control Process.
DQM DAPS INTERFACE PROCESS DATA FLOW DIAGRAM
b. Main Processing Loop:
o Get the next requests off of the serial output message queue.
o Process the request.
c. Shutdown:
o Detach from the real-time terminal.
o Close the serial port.
o Send the DYING message to the DQM Control Process.
o Detach from the configuration shared memory area.
Data Structures
a. Requests are received via the serial output message queue in the type 'struct SEROUT_MSG'. This structure is defined in the file g_serial.h.
Inputs
The DAPS Interface Process does no direct file input.
Outputs
The DQM quality report logs. These are two files called dqm_log.a and dqm_log.b. When one log is full, the other is flushed and then written to. Each log holds 10,000 quality reports.
Interprocess Communication
The DAPS Interface Process uses the following IPC resources:
a.The configuration shared memory is read during initialization to determine various operational parameters.
b. The control message queue is used to send the READY_TO_GO and DYING messages to the DQM Control Process at start-up and shut-down time, respectively.
c. The Real-Time Screen Output Message Queue is used to display the last 10 quality reports sent to DAPS.
d. The serial output message queue is read continually during the main processing loop.
Source Files
q_dapsif.c contains the initialization, shutdown, main, and main loop functions.
DOMSAT Enable/Disable Utility
The DOMSAT Enable/Disable Utility for the DQM is identical to the one described for the DROT above in Section 5.7.
QM Shutdown Utility (killdqm)
The Shutdown Utility for the DQM is identical to the one described for the DROT above in Section 5.8.
The following is the DQM configuration file as provided in the installation floppy.
#
# DQM Configuration File
#
#
# X.25 Parameters:
#
XLINE: /dev/icp 56000 DQM
#
# Timout for DOMSAT:
#
DOMSAT_TIMEOUT: 90
#
# Program to download to ICP:
#
ICP_PROGRAM: bin/188x25.exe
#
# Serial Line Parameters:
#
SERIAL_LINE: /dev/tty1a 9600 8 even 1
#
# Real-Time Terminal:
#
RT_TERMINAL: /dev/tty02 ansi \033[2;1;7m\033[7;0;2m 1 1 7
ALARMCOLOR: 4
#
# Off-Line Terminal:
#
OL_TERMINAL: /dev/tty03 ansi \033[2;1;7m\033[7;0;2m 1 1 7
#
# DQM DAPS Report Log File:
#
DQM_LOG: dqm_log 10000
#
# Seconds between periodic DAPS reports:
#
PERIODIC_RPT: 60
FUNCTION REFERENCE
DELIVERED UNDER SEPARATE COVER