Recommended Standard of the Joint Committee on the ATC
Ballot Copy for Joint Adoption by AASHTO, ITE, and NEMA
Joint AASHTO / ITE / NEMA Standards Publication TS X.X - 199X
Application Programming Interface (API)
Standard for the
Advanced Transportation Controller (ATC)
Working Group Draft Version 99.09.14, September 14, 1999
Published by
American Association of State Highway and Transportation Officials (AASHTO)
444 North Capitol St., N.W., Suite 249
Washington, D.C. 20001
Institute of Transportation Engineers (ITE)
525 School St., S.W., Suite 410
Washington, D.C. 20024-2797
National Electrical Manufacturers Association (NEMA)
1300 N. 17th Street, Suite 1847
Rosslyn, Virginia 22209-3801
 Copyright 1997 by the National Electrical Manufacturers Association (NEMA), the American Association of State Highway and
Transportation Officials (AASHTO), and the Institute of Transportation Engineers (ITE). All intellectual property rights, including, but not
limited to, the rights of reproduction in whole or in part in any form, translation into other languages and display are reserved by the copyright
owners under the laws of the United States of America, the Universal Copyright Convention, the Berne Convention, and the International and Pan
American Copyright Conventions. Do not copy without written permission of either NEMA, AASHTO, or ITE.
1
Joint NEMA, AASHTO, and ITE Copyright
and
ATC Application Programming Interface
NOTICE
 Copyright 1997 by the National Electrical Manufacturers Association (NEMA), the American Association of
State Highway and Transportation Officials (AASHTO), and the Institute of Transportation Engineers (ITE). All
intellectual property rights, including, but not limited to, the rights of reproduction, translation and display are
reserved under the laws of the United States of America, the Universal Copyright Convention, the Berne
Convention, and the International and Pan American Copyright Conventions. You may not copy these materials
without written permission from NEMA, AASHTO, or ITE. Use of these materials does not give you any rights of
ownership or claim of copyright in or to these materials.
To the extent and in the limited event these materials are distributed by AASHTO/ITE/NEMA in the form of written
specifications, AASHTO/ITE/NEMA extends the following permissions:
*** Place Holder for Distribution Permissions ***
These materials are delivered “AS IS” without any warranties as to their use or performance.
AASHTO/ITE/NEMA AND THEIR SUPPLIERS DO NOT WARRANT THE PERFORMANCE OR RESULTS
YOU MAY OBTAIN BY USING THESE MATERIALS. AASHTO/ITE/NEMA AND THEIR SUPPLIERS
MAKE NO WARRANTIES, EXPRESS OR IMPLIED, AS TO NONINFRINGEMENT OF THIRD PARTY
RIGHTS, MERCHANTABILITY, OR FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT WILL
AASHTO, ITE OR NEMA OR THEIR SUPPLIERS BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY
CLAIM OR FOR ANY CONSEQUENTIAL, INCIDENTAL OR SPECIAL DAMAGES, INCLUDING ANY
LOST PROFITS OR LOST SAVINGS, ARISING FROM YOUR REPRODUCTION OR USE OF THESE
MATERIALS, EVEN IF AN AASHTO, ITE, OR NEMA REPRESENTATIVE HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. Some states or jurisdictions do not allow the exclusion or limitation of
incidental, consequential or special damages, or the exclusion of implied warranties, so the above limitations may
not apply to you.
Use of these materials does not constitute an endorsement or affiliation by or between AASHTO, ITE, or NEMA
and you, your company, or your products and services.
If you are unwilling to accept the foregoing restrictions, you should immediately return these materials.
*** Place Holder for Distribution Disclaimer ***
2
Table of Contents
1. FOREWARD............................................ 8
2. INTRODUCTION........................................ 9
2.1. Architecture Overview ...................................................................................................... 9
2.1.1. ATC Software Standards Approach............................................................................ 9
2.1.2. Layer 1: “Platform Interface” API ............................................................................ 10
2.1.3. Layer 2: “Application Environment” API ................................................................ 10
2.1.4. Layer 3: “Applications” ............................................................................................ 11
3. LAYER 1 API – Platform Interface................... 12
3.1. DISCRETE I/O DEVICE DRIVER – LAYER 1 API .................................................... 12
3.1.1. Overview ................................................................................................................... 12
3.1.2. Diodev_attach( )........................................................................................................ 13
3.1.3. Diodev_detach( ) ....................................................................................................... 14
3.1.4. Diodev_get_modStatus( ) ......................................................................................... 15
3.1.5. Diodev_get_inputs( ) ................................................................................................ 16
3.1.6. Diodev_get_filterInputs( ) ........................................................................................ 17
3.1.7. Diodev_set_outputs( ) ............................................................................................... 18
3.1.8. Diodev_get_inpTransBuf( ) ...................................................................................... 19
3.1.9. Diodev_get_cabinetID( ) .......................................................................................... 21
3.1.10. Diodev_get_moduleID( ) .......................................................................................... 22
3.1.11. Diodev_cfg_msCounter( ) ........................................................................................ 23
3.1.12. Diodev_cfg_inputs( ) ................................................................................................ 24
3.1.13. Diodev_cfg_inpTracking( ) ...................................................................................... 25
3.1.14. Diodev_cfg_cpxOut( ) .............................................................................................. 26
3.1.15. Diodev_cfg_watchDog( ).......................................................................................... 27
3.1.16. DIODEV.H ............................................................................................................... 28
3.1.17. DIOTYPE.H.............................................................................................................. 30
3.2. SERIAL COMMUNICATIONS PORT DEVICE DRIVER – LAYER 1 API............... 40
3.2.1. Overview ................................................................................................................... 40
3.2.2. EIA232 HARDWARE FLOW CONTROL REQUIREMENTS .............................. 41
3.2.3. Scpdev_open( ) ......................................................................................................... 42
3.2.4. Scpdev_close( ) ......................................................................................................... 43
3.2.5. Scpdev_read( ) .......................................................................................................... 44
3.2.6. Scpdev_read_timed( ) ............................................................................................... 45
3.2.7. Scpdev_read_callback( ) ........................................................................................... 47
3.2.8. Scpdev_write( ) ......................................................................................................... 48
3.2.9. Scpdev_write_timed( ) .............................................................................................. 49
3.2.10. Scpdev_write_callback( ).......................................................................................... 50
3.2.11. Scpdev_flush( ) ......................................................................................................... 51
3.2.12. Scpdev_cancel_calback( ) ......................................................................................... 52
3.2.13. Scpdev_release( ) ...................................................................................................... 53
3.2.14. Scpdev_dataready( ).................................................................................................. 54
3.2.15. Scpdev_get_attrib( ) .................................................................................................. 55
3.2.16. Scpdev_set_attrib( ) .................................................................................................. 56
3.2.17. Scpdev_get_status( ) ................................................................................................. 57
3
3.2.18. Scpdev_set_status( ).................................................................................................. 58
3.2.19. Scpdev_get_control( ) ............................................................................................... 59
3.2.20. Scpdev_set_control( ) ............................................................................................... 60
3.2.21. SCPDEV.H ............................................................................................................... 61
3.3. SYSTEM DEVICE INTERFACE – LAYER 1 API ....................................................... 65
3.3.1. Overview ................................................................................................................... 65
3.3.2. Sysdev_event_init( ) ................................................................................................. 68
3.3.3. Sysdev_event_deinit( ).............................................................................................. 69
3.3.4. Sysdev_event_reg( ).................................................................................................. 70
3.3.5. Sysdev_event_dereg( ) .............................................................................................. 72
3.3.6. Sysdev_event_allocateTag( ) .................................................................................... 73
3.3.7. Sysdev_event_freeTag( ) .......................................................................................... 74
3.3.8. Sysdev_event_get_attrib( ) ....................................................................................... 75
3.3.9. Sysdev_event_set_attrib( ) ........................................................................................ 76
3.3.10. Sysdev_event_start( ) ................................................................................................ 77
3.3.11. Sysdev_event_stop( ) ................................................................................................ 78
3.3.12. Sysdev_event_send( ) ............................................................................................... 79
3.3.13. Sysdev_event_waitfor( ) ........................................................................................... 80
3.3.14. Sysdev_event_cancel( ) ............................................................................................ 81
3.3.15. Sysdev_event_disable( ) ........................................................................................... 82
3.3.16. Sysdev_event_enable( ) ............................................................................................ 83
3.3.17. Sysdev_shmem_create( ) .......................................................................................... 84
3.3.18. Sysdev_shmem_delete( ) .......................................................................................... 85
3.3.19. Sysdev_shmem_open( ) ............................................................................................ 86
3.3.20. Sysdev_shmem_close( )............................................................................................ 87
3.3.21. Sysdev_pipe_create( ) ............................................................................................... 88
3.3.22. Sysdev_pipe_delete( ) ............................................................................................... 89
3.3.23. Sysdev_pipe_open( ) ................................................................................................. 90
3.3.24. Sysdev_pipe_close( ) ................................................................................................ 91
3.3.25. Sysdev_pipe_read( ).................................................................................................. 92
3.3.26. Sysdev_pipe_read_timed( ) ...................................................................................... 93
3.3.27. Sysdev_pipe_write( ) ................................................................................................ 94
3.3.28. Sysdev_pipe_write_timed( ) ..................................................................................... 95
3.3.29. Sysdev_pipe_dataready( ) ......................................................................................... 96
3.3.30. Sysdev_pipe_flush( ) ................................................................................................ 97
3.3.31. Sysdev_pipe_release( ) ............................................................................................. 98
3.3.32. Sysdev_semaphore_create( ) .................................................................................... 99
3.3.33. Sysdev_semaphore_delete( ) .................................................................................. 100
3.3.34. Sysdev_semaphore_open( ) .................................................................................... 101
3.3.35. Sysdev_semaphore_close( ) .................................................................................... 102
3.3.36. Sysdev_semaphore_wait( ) ..................................................................................... 103
3.3.37. Sysdev_semaphore_post( ) ..................................................................................... 104
3.3.38. Sysdev_mutex_create( ) .......................................................................................... 105
3.3.39. Sysdev_mutex_delete( ) .......................................................................................... 106
3.3.40. Sysdev_mutex_open( )............................................................................................ 107
3.3.41. Sysdev_mutex_close( ) ........................................................................................... 108
4
3.3.42. Sysdev_mutex_acquire( )........................................................................................ 109
3.3.43. Sysdev_mutex_release( ) ........................................................................................ 110
3.3.44. Sysdev_get_priority( ) ............................................................................................ 111
3.3.45. Sysdev_set_priority( ) ............................................................................................. 112
3.3.46. Sysdev_get_procID( ) ............................................................................................. 113
3.3.47. Sysdev_exec( ) ........................................................................................................ 114
3.3.48. Sysdev_kill( ) .......................................................................................................... 115
3.3.49. Sysdev_sleep( ) ....................................................................................................... 116
3.3.50. Sysdev_thread_create( ) .......................................................................................... 117
3.3.51. Sysdev_thread_delete( ) .......................................................................................... 118
3.3.52. Sysdev_thread_start( ) ............................................................................................ 119
3.3.53. Sysdev_thread_stop( ) ............................................................................................. 120
3.3.54. Sysdev_thread_sleep( ) ........................................................................................... 121
3.3.55. Sysdev_thread_get_priority( ) ................................................................................ 122
3.3.56. Sysdev_thread_set_priority( ) ................................................................................. 123
3.3.57. Sysdev_get_time( ) ................................................................................................. 124
3.3.58. Sysdev_set_time( ) .................................................................................................. 125
3.3.59. Sysdev_get_sysClock( ) .......................................................................................... 126
3.3.60. Sysdev_get_sysClockResolution( ) ........................................................................ 127
3.3.61. Sysdev_interrupt_service( ) .................................................................................... 128
3.3.62. Sysdev_interrupt_disable( ) .................................................................................... 129
3.3.63. Sysdev_interrupt_enable( ) ..................................................................................... 130
3.3.64. SYSDEV.H ............................................................................................................. 131
3.4. TEXT USER INTERFACE – LAYER 1 API ............................................................... 135
3.4.1. Overview ................................................................................................................. 135
3.4.2. Tuidev_open( ) ........................................................................................................ 136
3.4.3. Tuidev_close( ) ....................................................................................................... 137
3.4.4. Tuidev_read_key( ) ................................................................................................. 138
3.4.5. Tuidev_write_buf( ) ................................................................................................ 139
3.4.6. Tuidev_write_char( ) .............................................................................................. 140
3.4.7. Tuidev_write_str( ) ................................................................................................. 141
3.4.8. Tuidev_put_cursor( ) .............................................................................................. 142
3.4.9. Tuidev_get_cursor( ) ............................................................................................... 143
3.4.10. Tuidev_init_buf( ) ................................................................................................... 144
3.4.11. Tuidev_dataready( ) ................................................................................................ 145
3.4.12. Tuidev_set_attrib( ) ................................................................................................. 146
3.4.13. Tuidev_get_attrib( ) ................................................................................................ 147
3.4.14. Tuidev_get_status( )................................................................................................ 148
3.4.15. Tuidev_comp_char( ) .............................................................................................. 149
3.4.16. TUIDEV.H .............................................................................................................. 150
4. LAYER 2 API – Application Environment............. 152
4.1. DISCRETE I/O DEVICE MANAGER – LAYER 2 API ............................................. 152
4.1.1. Overview ................................................................................................................. 152
4.1.2. Dioman_attach( ) .................................................................................................... 153
4.1.3. Dioman_detach( ).................................................................................................... 154
4.1.4. Dioman_get_attrib( ) ............................................................................................... 155
5
4.1.5. Dioman_set_attrib( ) ............................................................................................... 156
4.1.6. Dioman_reg_inputs( ) ............................................................................................. 157
4.1.7. Dioman_dereg_inputs( ) ......................................................................................... 159
4.1.8. Dioman_reg_outputs( ) ........................................................................................... 160
4.1.9. Dioman_dereg_outputs( ) ....................................................................................... 162
4.1.10. Dioman_get_outputReg( ) ...................................................................................... 163
4.1.11. Dioman_inputs( ) .................................................................................................... 164
4.1.12. Dioman_input( ) ...................................................................................................... 165
4.1.13. Dioman_filterInputs( ) ............................................................................................ 167
4.1.14. Dioman_filterInput( ) .............................................................................................. 168
4.1.15. Dioman_get_outputs( ) ........................................................................................... 169
4.1.16. Dioman_outputs( ) .................................................................................................. 170
4.1.17. Dioman_output( ) .................................................................................................... 171
4.1.18. Dioman_inpTransBuf( ) .......................................................................................... 172
4.1.19. Dioman_inpTrans( ) ................................................................................................ 173
4.1.20. Dioman_modStatus( ) ............................................................................................. 175
4.1.21. Dioman_cabinetID( ) .............................................................................................. 176
4.1.22. Dioman_get_inputs( ) ............................................................................................. 177
4.1.23. Dioman_get_filterInputs( ) ..................................................................................... 179
4.1.24. Dioman_set_outputs( ) ............................................................................................ 181
4.1.25. Dioman_get_inpTransBuf( ) ................................................................................... 183
4.1.26. Dioman_get_modStatus( ) ...................................................................................... 185
4.1.27. Dioman_get_cabinetID( ) ....................................................................................... 187
4.1.28. Dioman_get_moduleID( ) ....................................................................................... 189
4.1.29. Dioman_cfg_msCounter( ) ..................................................................................... 191
4.1.30. Dioman_cfg_inputs( ) ............................................................................................. 192
4.1.31. Dioman_cfg_inpTracking( ) ................................................................................... 193
4.1.32. Dioman_cfg_cpxOut( ) ........................................................................................... 194
4.1.33. Dioman_cfg_watchDog( ) ...................................................................................... 195
4.1.34. DIOMAN.H ............................................................................................................ 196
4.2. SERIAL COMMUNICATIONS PORT MANAGER – LAYER 2 API ....................... 200
4.2.1. Overview ................................................................................................................. 200
4.2.2. Scpman_attach( ) .................................................................................................... 201
4.2.3. Scpman_detach( ).................................................................................................... 202
4.2.4. Scpman_read( ) ....................................................................................................... 203
4.2.5. Scpman_read_timed( ) ............................................................................................ 204
4.2.6. Scpman_read_callback( ) ........................................................................................ 206
4.2.7. Scpman_write( ) ...................................................................................................... 208
4.2.8. Scpman_write_timed( ) ........................................................................................... 210
4.2.9. Scpman_write_callback( ) ...................................................................................... 211
4.2.10. Scpman_flush( ) ...................................................................................................... 212
4.2.11. Scpman_cancel_callback( ) .................................................................................... 213
4.2.12. Scpman_dataready( ) .............................................................................................. 214
4.2.13. Scpman_get_attrib( ) ............................................................................................... 215
4.2.14. Scpman_set_attrib( ) ............................................................................................... 216
4.2.15. Scpman_get_devAttrib( ) ........................................................................................ 217
6
4.2.16. Scpman_set_devAttrib( ) ........................................................................................ 218
4.2.17. Scpman_get_devStatus( )........................................................................................ 219
4.2.18. Scpman_set_devStatus( ) ........................................................................................ 220
4.2.19. Scpman_get_devControl( ) ..................................................................................... 221
4.2.20. Scpman_set_devControl( )...................................................................................... 222
4.2.21. SCPMAN.H ............................................................................................................ 223
4.3. TEXT USER INTERFACE MANAGER – LAYER 2 API .......................................... 225
4.3.1. Overview ................................................................................................................. 225
4.3.2. Tuiman_attach( ) ..................................................................................................... 226
4.3.3. Tuiman_detach( ) .................................................................................................... 227
4.3.4. Tuiman_set_window( ) ........................................................................................... 228
4.3.5. Tuiman_release_control( ) ...................................................................................... 229
4.3.6. Tuiman_gain_control( ) .......................................................................................... 230
4.3.7. Tuiman_read_key( ) ................................................................................................ 231
4.3.8. Tuiman_write_buf( ) ............................................................................................... 232
4.3.9. Tuiman_write_char( ) ............................................................................................. 233
4.3.10. Tuiman_write_str( ) ................................................................................................ 234
4.3.11. Tuiman_put_cursor( ) ............................................................................................. 235
4.3.12. Tuiman_get_cursor( ).............................................................................................. 236
4.3.13. Tuiman_init_buf( ) .................................................................................................. 237
4.3.14. Tuiman_dataready( ) ............................................................................................... 238
4.3.15. Tuiman_set_attrib( )................................................................................................ 239
4.3.16. Tuiman_get_attrib( ) ............................................................................................... 240
4.3.17. Tuiman_get_status( ) .............................................................................................. 241
4.3.18. Tuiman_comp_char( ) ............................................................................................. 242
4.3.19. Tuiman_beep( ) ....................................................................................................... 243
4.3.20. Tuiman_refresh_screen( ) ....................................................................................... 244
4.3.21. Tuiman.h ................................................................................................................. 245
5. ANNEX............................................. 246
5.1. REQUIRED STANDARD “C” HEADERS.................................................................. 246
5.2. ATC GLOBAL TYPE HEADER .................................................................................. 247
7
1.
FOREWARD
The purpose of this document is to define the function calls that are supported by the ATC
Application Programming Interface.
The effort to develop standards for the ATC began with the Federal Highway Administration
gathering together a group of users interested in furthering the development of open architecture
hardware and software to meet the future needs of Intelligent Transportation Systems. The ATC
users group gained the support of the Institute of Transportation Engineers to continue their work
in developing standards for the ATC. The American Association of State Highway and
Transportation Officials (AASHTO) and the National Electrical Manufacturer’s Association
joined with ITE to create a joint effort
In MONTH,YEAR, a formal agreement was reached among NEMA, ITE and AASHTO to
jointly develop, approve and maintain the ATC standards. Under the guidance of a Joint
AASHTO/ITE/NEMA Committee on the ATC, a Working Group was created in order to
develop a standard for the Application Programming Interface. The first official meeting of this
working group was in MONTH,YEAR.
In preparation of this Standards Publication, input of users and other interested parties was
sought and evaluated. Inquiries, comments and proposed or recommended revisions should be
submitted to:
Standards Engineer
Institute of Transportation Engineers
525 School St. SW, Suite 410
Washington, DC 20024-2797
voice:
fax:
email:
202-554-8050
202-863-5486 fax
8
2.
INTRODUCTION
2.1.
Architecture Overview
The following is a visual representation of the ATC Application Programming Interface
architecture. The architecture depicts a two-layer approach for the API.
ATC
Multiple
Applications
- or -
Single
Application
- or -
API Layer 2: Application Environment
API Layer 1: Platform Interface
Compliant ATC platform
(hardware, OS, services, facilities)
Figure 1. API approach for the ATC
2.1.1. ATC Software Standards Approach
The approach taken to develop an Application Programming Interface (API) for the Advanced
Transportation Controller (ATC) employs two layers. Layer 1 of the API describes the platform
interface. Layer 2 of the API describes the application environment interface. Figure 1 provides
a graphical representation of the API approach.
Separating Layers 1 and 2 allows ATC manufacturers to minimize their software efforts. Layer 2
can be provided by third parties if desired. In general, Layer 2 is presented as the primary
application level API while Layer 1 is viewed more as an implementation detail of the Layer 2
interface. These ATC software API definitions and requirements are developed and specified
separately from the controller hardware specifications. Recognizing that a variety of hardware
platforms could exist within a family of Advanced Transportation Controllers, a primary goal in
developing the API was to provide the flexibility to support devices other than the currently
specified Model 2070. Another goal in developing an API standard was to ensure that the API
9
and the application software could be supplied by a variety of parties, including hardware
suppliers, software suppliers, end-user agencies, or any combination of those.
The Application Programming Interface (API) for the ATC is written in terms of the Standard C
programming language as defined by the International Organization for Standards known as
ISO/IEC 9899: Information Processing Systems - Programming Language - C. This API defines
as C header files exclusively at the source code level for user applications. User applications,
written in Standard C, shall be able to link to a conforming API library that are specific to an
ATC platform with a real time operating system (RTOS) environment using its Standard C
compiler. The linked executable is then able to run in that ATC platform, and is NOT required to
be binary compatible with other ATC platforms. (The RTOS shall conform to the Operating
System Abstraction requirements of ATC). However, this API document does not require an
implementation of the API library or that the user applications has to be written in only Standard
C programming language. However, The API is not limited to the Standard C only. If the API is
also defined in terms of other programming languages such as assembly or C++, user
applications shall be able to link to those programming libraries as well.
2.1.2. Layer 1: “Platform Interface” API
Layer 1 of the API architecture is regarded as the Platform Interface. Layer 1 enables basic
platform independence for application software and provides the lowest common denominator to
support common application software across heterogeneous ATC platforms. The Platform
Interface encapsulates platform-dependent services, such as hardware and operating system that
are specific to each ATC platform. Layer 1 represents lowest level reasonable to support a
general class of ATC/ITS applications and assumes a basic set of features/services that are
available on host platforms.
The capability to support this API would be one requirement for an ATC to be compliant with a
national standard, however, this capability alone does not define compliance. Other
requirements need to be defined to identify the features/capabilities needed to support the API
and the intended range of ITS applications (i.e. performance, system services, I/O capabilities,
storage media, etc.)
This standard defines a set ANSI C function interfaces. The Layer 1 compliant API shall be
provided as ANSI C function libraries for linkage with higher level routines.
2.1.3. Layer 2: “Application Environment” API
Layer2 of the API architecture is designated as the Application Environment. Layer 2 runs on
top of Layer 1 – Platform Interface. The implementation of Layer 2 is regarded as being
dependent on Layer 1 interfaces only, making the code directly portable to any ATC platform
providing a compliant Layer 1 – Platform Interface. Layer 2 enables multiple application
support and handles resource sharing among various applications. Essentially, Layer 2 of the
API architecture allows multiple compliant applications from multiple suppliers to run
cooperatively on any ATC platform using a compliant Layer 1 API.
10
The Application Environment provides common general purpose and flexible low-level
application functionality to manage application cooperation, to enhance system performance,
and/or to ease application development. Layer 2 of the API encapsulates the Layer 1 interface.
The Layer 2 API shall be provided as ANSI C function libraries for linkage with higher level
routines.
2.1.4. Layer 3: “Applications”
For the purposes of this standard, one might consider Applications as Layer 3 in the API
architecture. Applications perform specific end-user tasks: intersection control, sign control,
ramp metering, communications, data collection, etc. Single applications may run directly on the
Layer 1 API, although this approach should generally be discouraged since it does not promote
interoperability. Applications designed to run cooperatively will interface strictly with Layer 2
of the API. Applications, themselves, are separate and outside the scope of API standards
development. This approach assumes and accommodates services required to implement a
general class of ITS applications, but no assumptions are made about individual application
architecture.
11
3.
LAYER 1 API – Platform Interface
3.1.
DISCRETE I/O DEVICE DRIVER – LAYER 1 API
3.1.1. Overview
This API has two layers of programming interfaces for user applications to communicate with a
Discrete I/O device on an ATC. Level one of the API defines the functional interface between an
ATC application and DIODEV driver. The device driver and its accompanying source level
interface library is usually manufacturer dependent. Level two of the API defines the functional
interface between an ATC application and the Discrete I/O device manager (DIOMAN). The
DIOMAN provides a subset of high level functions and a single access point to the Discrete I/O
device for all user applications.
12
3.1.2. Diodev_attach( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_attach ( u_int8 deviceID, TDiodev *hDiodev, u_int8 * moduleID
);
Description:
Request the Discrete I/O device driver to attach to the Discrete I/O device for
resource access. The function returns a handle for calling process access.
Parameters:
deviceID is the address of the Discrete I/O device on the target device bus.
hDiodev is a pointer to the handle that the function returns.
moduleID is a pointer to the location where the function returns the Discrete
I/O device identification.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NO_DEVICE – the Discrete I/O device does not exist.
E_ DIODEV_INVALID_ADDRESS – the requested Discrete I/O address is
not valid.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
Library:
Diodev.lib
See Also:
Diodev_close()
Example:
13
3.1.3. Diodev_detach( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_detach ( TDiodev hDiodev );
Description:
Request driver to detach from the Discrete I/O device. Usually called before
the calling process terminates or no longer needs to access resources of the
Discrete I/O device.
Parameters:
hDiodev is the handle of the Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_ALREADY_CLOSED – the Discrete I/O already closed.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
Library:
Diodev.lib
See Also:
Diodev_open()
14
3.1.4. Diodev_get_modStatus( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_get_modStatus ( TDiodev hDiodev, TDio_modStatus
*modstatus, TDio_callback function, u_int32 func_tag);
Description:
Gets the Discrete I/O device status.
Parameters:
hDiodev is the handle of the Discrete I/O device.
modstatus is a pointer to the user TDio_modStatus structure.
function is a pointer to a callback function to be run when data is ready for
user inspection. The routine takes a single u_int32 value and returns void. A
null pointer informs the Discrete I/O device driver not to invoke any callback
function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
driver retrieves the data from the device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
15
3.1.5. Diodev_get_inputs( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_get_inputs ( TDiodev hDiodev, TDio_inputs *inputs,
TDio_callback function, u_int32 func_tag);
Description:
Gets current Discrete I/O device input state of all inputs and notifies the
calling process when data is ready to be inspected.
Parameters:
hDiodev is the handle of the Discrete I/O device.
inputs is a pointer to the TDio_inputs structure.
function is a pointer to a callback function to be run when data is ready for
user inspection. The routine takes a single u_int32 value and returns void. A
null pointer informs the Discrete I/O device driver not to invoke any callback
function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
driver retrieves the data from the device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
See Also:
Diodev_set_outputs(), Diodev_inputs(), Diodev_outputs()
16
3.1.6. Diodev_get_filterInputs( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_get_filterInputs ( TDiodev hDiodev, TDio_filterInputs *fInputs,
TDio_callback function, u_int32 func_tag );
Description:
Gets Discrete I/O device’s filtered inputs and notifies the calling process
when data is ready to be inspected.
Parameters:
hDiodev is the handle of the Discrete I/O device.
fInputs is a pointer to the TDio_filterInputs structure.
function is a pointer to a callback function to be run when data is ready for
user inspection. The routine takes a single u_int32 value and returns void. A
null pointer informs the Discrete I/O device driver not to invoke any callback
function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
driver retrieves the data from the device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
See Also:
Diodev_get_inputs(), Diodev_inputs()
17
3.1.7. Diodev_set_outputs( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_set_outputs ( TDiodev hDiodev, TDio_outputs *outputs,
TDio_callback function, u_int32 func_tag );
Description:
Sets the outputs to the Discrete I/O device and notifies the calling process
when operation is completed.
Parameters:
hDiodev is the handle of the Discrete I/O device.
outputs is a pointer to the TDio_outputs structure.
function is a pointer to a callback function to be run when set outputs
command is completed. The routine takes a single u_int32 value and returns
void. A null pointer informs the Discrete I/O device driver not to invoke any
callback function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
acknowledges the reception of data.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
See Also:
Diodev_outputs(), Diodev_regOutputs(), Diodev_deregOutputs
18
3.1.8. Diodev_get_inpTransBuf( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_get_inpTransBuf ( TDiodev hDiodev, TDio_inpTransBuf
*inptsbuf, TDio_callback function, u_int32 func_tag );
Description:
Gets the complete contents of the input transition buffer and notifies the
calling process when data is ready to be inspected .
Parameters:
hDiodev is the handle of the Discrete I/O device.
inptsbuf is a pointer to the TDio_inpTransBuf structure where processed
transition data is stored. The timestamp information in the structure is the true
4-byte length time stamp of the millisecond counter in the Discrete I/O
device.
function is a pointer to a callback function to be run when data is ready for
user inspection. The routine takes a single u_int32 value and returns void. A
null pointer informs the Discrete I/O device driver not to invoke any callback
function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
driver retrieves the data from the device.
Return Value:
On success, it returns 0. Otherwise, it returns an operating system error has
occurred.
Error codes:
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
19
See Also:
Diodev_cfg_inputs()
20
3.1.9. Diodev_get_cabinetID( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_get_cabinetID ( TDiodev hDiodev, TDio_cabinetID *cabid,
TDio_callback function, u_int32 func_tag );
Description:
Gets the cabinet identification from the Discrete I/O device and notifies the
calling process when data is ready to be inspected.
Parameters:
hDiodev is the handle of the Discrete I/O device.
cabid is a pointer to the TDio_cabinetID structure.
function is a pointer to a callback function to be run when data is ready for
user inspection. The routine takes a single u_int32 value and returns void. A
null pointer informs the Discrete I/O device driver not to invoke any callback
function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
driver retrieves the data from the device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
See Also:
Diodev_get_moduleID()
21
3.1.10. Diodev_get_moduleID( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_get_moduleID ( TDiodev hDiodev, TDio_moduleID *modid,
TDio_callback function, u_int32 func_tag );
Description:
Gets the Discrete I/O device identification and notifies the calling process
when data is ready to be inspected.
Parameters:
hDiodev is the handle of the Discrete I/O device.
modid is a pointer to the TDio_moduleID structure.
function is a pointer to a callback function to be run when data is ready for
user inspection. The routine takes a single u_int32 value and returns void. A
null pointer informs the Discrete I/O device driver not to invoke any callback
function.
func_tag is the tag to be returned to the calling process when its callback
function is invoked. If a null function pointer is passed, a zero value of
func_tag indicates that the calling process is blocked until Discrete I/O device
driver retrieves the data from the device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
See Also:
Diodev_get_cabinetID()
22
3.1.11. Diodev_cfg_msCounter( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_cfg_msCounter ( TDiodev hDiodev, u_int32 milcnt );
Description:
Configures Discrete I/O device’s milliseconds counter to a specified value.
The calling process is blocked until configuration is completed.
Parameters:
hDiodev is the handle of the Discrete I/O device.
milcnt is the value of the millisecond counter.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_CONFIG_ERROR – configuration error has occurred.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
23
3.1.12. Diodev_cfg_inputs( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_cfg_inputs ( TDiodev hDiodev, TDio_cfgInp *cfgInp );
Description:
Configures input filter function of multiple Discrete I/O device inputs
specified in the TDio_cfgInp. The calling process is blocked until
configuration is completed.
Parameters:
hDiodev is the handle of the Discrete I/O device.
cfgInp is a pointer to the TDio_cfgInp structure. The TDio_cfgInp data
structure is described in the DIOTYPE.H header file.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_CONFIG_ERROR – configuration error has occurred.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
See Also:
Diodev_cfg_input()
24
3.1.13. Diodev_cfg_inpTracking( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_cfg_inputTracking ( TDiodev hDiodev, TDio_inpTracking
*cfgInptrk );
Description:
Configures multiple input tracking functions of the Discrete I/O. The calling
process is blocked until configuration is completed.
Parameters:
hDiodev is the handle of the Discrete I/O device.
cfgInptrk is a pointer to the TDio_inpTracking structure.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_CONFIG_ERROR – configuration error has occurred.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
25
3.1.14. Diodev_cfg_cpxOut( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_cfg_cpxOut ( TDiodev hDiodev, TDio_cpxOut *cfgCpxout );
Description:
Configures complex outputs of the Discrete I/O. The calling process is
blocked until configuration is completed.
Parameters:
hDiodev is the handle of the Discrete I/O device.
cfgCpxout is a pointer to the TDio_cpxOut structure.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_CONFIG_ERROR – configuration error has occurred.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
26
3.1.15. Diodev_cfg_watchDog( )
Syntax:
#include “Diodev.h”
#include “Diotype.h”
int Diodev_cfg_watchDog ( TDiodev hDiodev, u_int32 timeout );
Description:
Configures the watch dog timer of the Discrete I/O. The calling process is
blocked until configuration is completed.
Parameters:
hDiodev is the handle of the Discrete I/O device.
timeout is the timeout value for the watchdog timer.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIODEV_CONFIG_ERROR – configuration error has occurred.
E_DIODEV_DEVICE_ERROR – the Discrete I/O device failed.
E_DIODEV_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIODEV_OS_ERROR – an operating system error has occurred.
E_DIODEV_NULL_POINTER – a null pointer is passed to the function.
E_DIODEV_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Diodev.lib
27
3.1.16. DIODEV.H
/**************************************************************************/
#ifndef _DIODEV_H_
#define _DIODEV_H_
#include <types.h>
#include “Diotype.h”
typedef unsigned int TDiodev;
typedef void (*function)(u_int32) TDio_callback;
/**************************************************************************/
/* Diodev Function Prototypes
*/
/**************************************************************************/
int Diodev_attach ( u_int8 addr,
TDiodev *hDiodev,
u_int8 *modID );
int Diodev_detach ( TDiodev hDiodev );
int Diodev_get_modStatus ( TDiodev hDiodev,
TDio_modStatus *modstatus,
TDio_callback function,
u_int32 func_tag);
int Diodev_get_inputs ( TDiodev hDiodev,
TDio_inputs *inputs,
TDio_callback function,
u_int32 func_tag);
int Diodev_get_filterInputs ( TDiodev hDiodev,
TDio_filterInputs *finputs,
TDio_callback function,
u_int32 func_tag );
int Diodev_set_outputs ( Tdiodev hDiodev,
TDio_outputs *outputs,
TDio_callback function,
u_int32 func_tag );
int Diodev_get_inpTransBuf ( TDiodev hDiodev,
TDio_inpTransBuf *inptsbuf,
TDio_callback function,
u_int32 func_tag );
int Diodev_get_cabinetID ( TDiodev hDiodev,
TDio_cabinetID *cabid,
TDio_callback function,
u_int32 func_tag );
int Diodev_get_moduleID ( TDiodev hDiodev,
TDio_moduleID *modid,
TDio_callback function,
u_int32 func_tag );
28
int Diodev_cfg_msCounter ( TDiodev hDiodev,
u_int32 milcnt );
int Diodev_cfg_inputs ( TDiodev hDiodev,
TDio_cfgInp *cfginp );
int Diodev_cfg_inputTracking ( TDiodev hDiodev,
TDio_inpTracking *cfgInptrk );
int Diodev_cfg_cpxOut ( TDiodev hDiodev,
TDio_cpxOut *cfgCpxout );
int Diodev_cfg_watchDog ( TDiodev hDiodev,
u_int32 timeout );
/* DIODEV Error Codes */
typedef enum
{
E_DIODEV_INVALID_ADDRESS= 2000,
E_DIODEV_NO_DEVICE
,
E_DIODEV_INVALID_HANDLE
,
E_DIODEV_DEVICE_ERROR
,
E_DIODEV_ALREADY_CLOSED
,
E_DIODEV_OUTOF_BUFFER
,
E_DIODEV_INVALID_ATTRIBUTE
,
E_DIODEV_CONFIG_ERROR
,
E_DIODEV_OS_ERROR
,
E_DIODEV_NOTSUPPORTED,
E_DIODEV_NULL_POINTER
} _E_DIODEV_ENUM;
#endif
29
3.1.17. DIOTYPE.H
/***************************************************************
***********
* MODULE
: Diotype.h
* VERSION
: 2.1
* DATE
: 5/24/98
* PROGRAMMER: George Chen
* REVIEWER 1:
* REVIEWER 2:
* PORTABILITY: ATC WITH FIELD I/O MODULE
*
* DESCRIPTION:
* This header file defines all the Discrete I/O device data
structures
*
****************************************************************
*********/
#ifndef _DIO_STRUCTURE_TYPES_
#define _DIO_STRUCTURE_TYPES_
#include <types.h>
/***************************************************************
**********/
/* This section defines the Request_Module_Status (status)
structure
*/
typedef struct
{
unsigned int resv
:24;
/* reserve and padding bits
*/
unsigned int hw_rst
:1;
/* P - bit dio_hdwr_rst
*/
unsigned int timeout :1;
/* E - bit comm_timeout
*/
unsigned int key_fail :1;
/* K - bit datakey_fail
*/
unsigned int rx_rol
:1;
/* R - bit rx_errcnt_rol
*/
unsigned int tx_rol
:1;
/* T - bit tx_errcnt_rol
*/
unsigned int mc_irq
:1;
/* M - bit MC_irq_err
*/
unsigned int linesync :1;
/* L - bit LINESYNC_err
*/
unsigned int wdog_rst :1;
/* W - bit dio_wdog_rst
30
*/
} TDio_modStatus_bits;
typedef union
{
u_int32
bits;
TDio_modStatus_bits bit;
} TDio_modStatus_status;
typedef struct
{
TDio_modStatus_status status;
u_int32
timestamp;
} TDio_modStatus;
/***************************************************************
************/
/***************************************************************
************/
/* This section defines the Millisecond Counter (msCounter)
structure
*/
typedef struct
{
u_int32
msClock;
u_int32
status;
} TDio_msCounter;
/***************************************************************
***********/
/***************************************************************
***********/
/* This section defines the Configure Input (cfgInp) structure
*/
#ifndef DIO_CFGINP_MAX
#define DIO_CFGINP_MAX
64
#endif
typedef struct
{
u_int8
ign_inp_flg;
u_int8
inp_num;
u_int8
lead_edge;
u_int8
trail_edge;
} TDio_cfgInp_item;
typedef struct
{
u_int32
num_item;
TDdio_cfgInp_item item[DIO_CFGINP_MAX];
u_int32
status;
31
} TDio_cfgInp;
/***************************************************************
***********/
/***************************************************************
***********/
/* poll signal input function definition
*/
#ifndef DIO_INPUTS_MAX
#ifdef DIO_INPUTS_NORMAL
#define DIO_INPUTS_MAX
64
/* I0 – I63 */
#else
#define DIO_INPUTS_MAX
128
/* I0 - I128 */
#endif
#endif
#define DIO_INPUT_PORTS_MAX
(DIO_INPUTS_MAX/8+((DIO_INPUTS_MAX%8)==0?0:1))
typedef union
{
u_int8
port[DIO_INPUT_PORTS_MAX];
} TDio_input_ports;
typedef struct
{
TDio_input_ports data;
u_int32
timestamp;
} TDio_inputs;
/***************************************************************
**********/
/***************************************************************
**********/
/* This section defines the Poll Filtered Input (filterInputs)
structure */
typedef struct {
TDio_input_ports data;
u_int32
timestamp;
} TDio_filterInputs;
/***************************************************************
**********/
/***************************************************************
**********/
/* This section defines the Poll Input transition buffer
(inpTransBuf)
*/
#ifndef DIO_INPTRANSBUF_MAX
32
#define DIO_INPTRANSBUF_MAX 255
#endif
typedef struct
{
unsigned int
:28;
/* 28 bits
reserve bits
*/
unsigned int entry_rol
:1;
/* C_bit
entry_rol */
unsigned int tsbuf_rol
:1;
/* F_bit
buf_rol
*/
unsigned int resent_blk
:1;
/* E_bit
resent_blk */
unsigned int blk_outof_order :1;
/* G_bit out of
order */
} TDio_inpTransBuf_status_bits;
typedef union
{
u_int32
bits;
TDio_inpTransBuf_status_bits bit;
} TDio_inpTransBuf_status;
typedef struct
{
u_int8 in_state;
u_int8 in_num;
u_int16 padding;
u_int32 timestamp;
} TDio_inpTransBuf_item;
typedef struct {
u_int16
blk_num;
u_int16
num_item;
TDio_inpTransBuf_item
item[DIO_INPTRANSBUF_MAX];
TDio_inpTransBuf_status status;
u_int32
timestamp;
} TDio_inpTransBuf;
/***************************************************************
***********/
/***************************************************************
***********/
/* signal output function definition
*/
#ifndef DIO_OUTPUTS_MAX
#ifdef DIO_OUTPUTS_NORMAL
#define DIO_OUTPUTS_MAX
#else
64
33
/* O0 – O63 */
#define DIO_OUTPUTS_MAX
128
*/
#endif
#endif
#define DIO_OUTPUT_PORTS_MAX
(DIO_OUTPUTS_MAX/8+((DIO_OUTPUTS_MAX%8)==0?0:1))
/* O0 - O128
typedef struct
{
unsigned int
:30;
unsigned int linesync :1;
/* linesync lost
*/
unsigned int error
:1;
/* error setting
outputs */
} TDio_outputs_status_bits;
typedef union
{
u_int32
bits;
TDio_outputs_status_bits bit;
} TDio_outputs_status;
typedef union
{
u_int8 port[DIO_OUTPUT_PORTS_MAX];
} TDio_output_ports;
typedef struct
{
TDio_output_ports
data;
TDio_output_ports
ctrl;
TDio_outputs_status status;
} TDio_outputs;
/***************************************************************
***********/
/***************************************************************
***********/
/* This defines the Configure Input Tracking (inpTracking)
*/
#ifndef DIO_INPTRACKING_MAX
#define DIO_INPTRACKING_MAX 64
#endif
typedef struct
{
unsigned int enable
:1;
unsigned int out_num
:7;
unsigned int invert
:1;
unsigned int in_num
:7;
34
/* E bit enable
*/
/* I bit invert io */
} TDio_inpTracking_item;
typedef struct
{
u_int32
num_item;
TDio_inpTracking_item item[DIO_INPTRACKING_MAX];
u_int32
status;
u_int32
timestamp;
} TDio_inpTracking;
/***************************************************************
***********/
/***************************************************************
***********/
/* This defines the Configure Complex Output (cpxOut) commandresponse
*/
#ifndef DIO_CPXOUT_MAX
#define DIO_CPXOUT_MAX 8
#endif
typedef struct
{
u_int8
out_num;
u_int8
inp_num;
u_int16
prim_duration;
u_int16
secd_duration;
unsigned int reserve
:8;
unsigned int single_pulse
:1;
/* P bit */
unsigned int trigger_delay
:1;
/* W bit */
unsigned int gated_inp
:1;
/* G bit */
unsigned int enable
:1;
/* E bit */
unsigned int out_state
:1;
/* J bit */
unsigned int filtering
:1;
/* F bit */
unsigned int trigger_edge
:1;
/* R bit */
unsigned int linesync
:1;
/* L bit */
} TDio_cpxOut_item;
typedef struct
{
u_int32
num_item;
TDio_cpxOut_item item[DIO_CPXOUT_MAX];
u_int32
status;
u_int32
timestamp;
} TDio_cpxOut;
/***************************************************************
***********/
/***************************************************************
***********/
35
/* This section defines the Config_Watchdog (watchDog) commandresponse
*/
typedef struct
{
u_int32
timeout;
u_int32
status;
} TDio_watchDog;
/***************************************************************
***********/
/***************************************************************
***********/
/* This section defines the Cabinet Identification (cabinetID)
structure */
typedef union
{
u_int8
bytes[128];
struct {
char
version[2];
*/
u_int16 system_num;
*/
u_int16 cabinet_num;
*/
u_int16 channel;
*/
u_int16 address;
*/
u_int16 master;
*/
u_int16 group;
*/
u_int16 route1;
*/
u_int16 route2;
*/
u_int32 latitude;
*/
u_int32 longitude;
*/
u_int8 matrix[16*2];
*/
u_int8 type[10];
*/
/* byte count = 2
/* byte count = 4
/* byte count = 6
/* byte count = 8
/* byte count = 10
/* byte count = 12
/* byte count = 14
/* byte count = 16
/* byte count = 18
/* byte count = 22
/* byte count = 26
/* byte count = 58
/* byte count = 68
36
char
cabinet_name[60];
/* byte count = 128
*/
} key;
} TDio_cabinetID_data;
typedef struct {
TDio_cabinetID_data id;
u_int32
status;
} TDio_cabinetID;
/***************************************************************
***********/
/***************************************************************
***********/
/* This section defines the Discrete I/O device Identification
(moduleID) */
/* structure
typedef struct {
u_int32
id;
u_int32
status;
} TDio_moduleID;
/***************************************************************
***********/
/***************************************************************
***********/
/* This section defines the dio_dev_type that include all
command-response*/
typedef struct
{
TDio_modStatus
modStatus;
TDio_msCounter
msCounter;
TDio_cfgInp
cfgInp;
TDio_inputs
inputs;
TDio_filterInputs
filterInputs;
TDio_inpTransBuf
inpTransBuf;
TDio_outputs
outputs;
TDio_inpTracking
inpTracking;
TDio_cpxOut
cpxOut;
TDio_watchDog
watchDog;
TDio_cabinetID
cabinetID;
TDio_moduleID
moduleID;
} TDio_dev;
/***************************************************************
***********/
37
/***************************************************************
***********/
/* This section defines the TDio_mod type that include all
structures
*/
/* for the dio module. All configuration messages are combined
into an
*/
/* union.
*/
typedef union
{
TDio_msCounter
msCounter;
TDio_cfgInp
cfgInp;
TDio_inpTracking
inpTracking;
TDio_cpxOut
cpxOut;
TDio_watchDog
watchDog;
} TDio_cfg_union;
typedef struct
{
TDio_modStatus
modStatus;
TDio_inputs
inputs;
TDio_filterInputs
filterInputs;
TDio_inpTransBuf
inpTransbuf;
TDio_outputs
outputs;
TDio_cabinetID
cabinetID;
TDio_moduleID
moduleID;
TDio_cfg_union
cfg;
} TDio_mod;
/***************************************************************
***********/
/***************************************************************
***********/
/* This section defines the dio_dev_union_type that include all
command- */
/* response for the dio module
*/
typedef union
{
TDio_modStatus
TDio_msCounter
TDio_cfgInp
TDio_inputs
TDio_filterInputs
TDio_inpTransBuf
TDio_outputs
modStatus;
msCounter;
cfgInp;
inputs;
filterInputs;
inpTransBuf;
outputs;
38
TDio_inpTracking
inpTracking;
TDio_cpxOut
cpxOut;
TDio_watchDog
watchDog;
TDio_cabinetID
cabinetID;
TDio_moduleID
moduleID;
} TDio_union;
/***************************************************************
***********/
#endif
39
3.2.
SERIAL COMMUNICATIONS PORT DEVICE DRIVER – LAYER 1 API
3.2.1. Overview
This API has two layers of programming interfaces for user applications to communicate with a
Serial Communications Port (SCP) device on an ATC. Layer 1 of the API defines the functional
interface between an ATC application and SCP device driver. The device driver and its
accompanying source level interface library is usually manufacturer dependent. Layer 2 of the
API defines the functional interface between an ATC application and the SCP device manager
(SCPMAN). The SCPMAN provides a subset of high level functions and a single access point to
the SCP devices for all user applications. It allows multiple calling processes to share the same
resource in an Advanced Transportation Controller (ATC) and manages at least four serial
communications ports. The SCPMAN permits each calling process to have either shared or
exclusive accesses to the communications resources. The calling process can configure the
communications devices through the SCPMAN. The SCPMAN provides calling process services
such as automatic hardware handshaking handling, read-write function paring and blocked or
non-blocked read or writes functions for each communications resource.
40
3.2.2. EIA232 HARDWARE FLOW CONTROL REQUIREMENTS
The SCP device driver shall operate in five modes described below to accommodate
communications network (EIA232) that requires the proper signaling of hardware handshaking
signals:
1) Manual Flow Control Mode: The SCP device driver transmits and receives data regardless
of what the states are of RTS, CTS, DCD, DTR, DSR, and RI. User programs can control the
states of RTS and DTR, and inquire the states of CTS, DCD, and DSR through the device
driver. The states of CTS, DCD, DSR, and RI are set externally by a DCE.
2) Auto-CTS Flow Control Mode: The SCP device driver transmits data only when CTS is
asserted. The state of CTS is controlled externally by a DCE. The user program can control
the state of RTS. The device driver can transmit and receive data regardless the states of
other signals.
3) Auto-RTS Flow Control Mode: Upon a write command, the SCP device driver asserts RTS
to start data transmission, and de-asserts RTS when data transmission is completed. If the
RTS is asserted, RTS remains on until the RTS is de-asserted. If the RTS is de-asserted
before the transmitting buffer is empty, the device driver holds RTS on until the transmitting
buffer is empty. The device driver can transmit and receive data regardless the states of other
signals.
4) Automatic Flow Control Mode: Upon a write command, the SCP device driver asserts
RTS, waits for CTS, starts data transmission when CTS is asserted, and de-asserts RTS when
data transmission is completed. Parameters related to delays of RTS turn-off after last
character is sent may be needed. The device driver can transit and receive data regardless the
states of other signals.
5) Dynamic Flow Control Mode: The SCP device driver manages transmission and reception
of data automatically through the RTS and CTS signals. The device driver controls the state
of RTS and monitors the state of CTS. The device driver also maintains a transmit buffer and
a receive buffer with fixed sizes. The device driver transmits data only when CTS is asserted.
The device driver asserts RTS when its receiving buffer is filled below certain level (low
watermark), and de-asserts RTS when its receiving buffer is filled above certain level (high
watermark). The device driver can transmit and receive data regardless the states of other
signals.
41
3.2.3. Scpdev_open( )
Syntax:
#include “scpdev.h”
int Scpdev_open ( TScpdev *phScpdev, char *devname, u_int32
read_bufsize, u_int32 write_bufszie );
Description:
Opens a serial port through the Serial Communications Port (SCP) device
driver, which returns a handle to the calling process.
Parameters:
phScpdev is a pointer to the handle that SCP device driver assigns.
devname is a character pointer to the null-terminated serial port device
descriptor name.
read_bufsize is the buffer size for the serial port receive buffer of the SCP
device driver.
write_bufsize is the buffer size for the serial port transmit buffer of the SCP
device driver.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other error codes:
E_SCPDEV_INVALID_DEVNAME – if devname is incorrect.
E_SCPDEV_BUFFER_TOO_LARGE – if the requested buffer size exceeds
the maximum buffer size of the driver.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_close();
Example:
42
3.2.4. Scpdev_close( )
Syntax:
#include “scpdev.h”
int Scpdev_close ( TScpdev hScpdev );
Description:
Closes the Serial Communications Port (SCP) for this calling process.
Parameters:
hScpdev is the handle that SCP device driver assigns the port handle.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened by this function.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_open()
Example:
43
3.2.5. Scpdev_read( )
Syntax:
#include “scpdev.h”
int Scpdev_read ( TScpdev hScpdev, u_int8 *readbuf, u_int32 size, u_int32
*sizeRead );
Description:
Reads up to the number of requested bytes that are available from the serial
port and puts them into the user buffer. This function shall not block the
calling process if the requested bytes are more than available data from the
port. If the number of requested bytes are more than availabe data in the port,
the function shall return the data that are available and set sizeRead to the
actual number that are read.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
readbuf is a pointer to the buffer where the serial data is being stored.
size is the number of bytes to be read from the serial communications port.
sizeRead is a pointer to a location where the driver returns the number of
bytes that are read.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_HARDWARE_ERROR – hardware related errors are
encountered.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read_timed(), Scpdev_write()
Example:
44
3.2.6. Scpdev_read_timed( )
Syntax:
#include “scpdev.h”
int Scpdev_read_timed ( TScpdev hScpdev, u_int8 *readbuf, u_int32 size,
u_int32 *sizeRead, u_int32 timeout );
Description:
Reads a number of requested bytes from the serial port and puts them into the
user buffer within a specified time.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
readbuf is a pointer to the buffer where the serial data is being stored.
size is the number of bytes to be read from the serial communications port.
sizeRead is a pointer to the number of bytes that are read from the serial
communications port.
timeout is the time in milliseconds that the SCP device driver must complete
the read operation. The value may be rounded up to the nearest system tick, if
the operating system’s timer resolution is lower than the value requested. If
timeout is zero, the read operation will not timeout. The function shall block
calling process until either the number bytes specified in size are read or time
specified in timeout has expired.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_READ_QUEUE_FULL – the read queue of the SCP device
driver is full.
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_HARDWARE_ERROR – hardware related errors are
encountered.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
45
See Also:
Scpdev_read(), Scpdev_write().
Example:
46
3.2.7. Scpdev_read_callback( )
Syntax:
#include “scpdev.h”
int Scpdev_read_callback ( TScpdev hScpdev, u_int8 *readbuf, u_int32
size, TScp_callback function, u_int32 func_tag );
Description:
Reads a number of bytes from the serial port and puts them into the user
buffer and invokes the callback function in calling the process space.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
readbuf is a pointer to the buffer where the serial data is being stored.
size is the number of bytes to be read from the serial communications port.
function is a pointer to a callback function to be executed when the number
bytes specified in size are read. The routine takes a single u_int32 value and
returns void.
func_tag is the tag to be returned to the calling process when its callback
function is executed.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_HARDWARE_ERROR – hardware related error.
E_SCPDEV_INVALID_TAG_NUMBER – an invalid tag number is used.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read(), Scpdev_write().
Example:
47
3.2.8. Scpdev_write( )
Syntax:
#include “scpdev.h”
int Scpdev_write ( TScpdev hScpdev, u_int8 *writebuf, u_int32 size);
Description:
Writes a number of bytes to the serial communications port through the Serial
Communications Port (SCP) device driver.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
writebuf is a pointer to the serial data to be written to the serial
communications port.
size is the number of bytes written to the serial communications port.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_HARDWARE_ERROR – hardware related error.
E_SCPDEV_WRITE_BUFFER_FULL – the write size is larger than the
available size of the write buffer of the device driver. User process should
wait until enough device write buffers become available to complete the write
command.
E_SCPDEV_WRITE_BUFFER_TOO_SMALL – the maximum size of the
write buffers of the device driver is smaller than write size of the calling
process. User process should reduce the size of the write command.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read()
Example:
48
3.2.9. Scpdev_write_timed( )
Syntax:
#include “scpdev.h”
int Scpdev_write_timed ( TScpdev hScpdev, u_int8 *writebuf, u_int32 size,
u_int32 sizeWritten, u_int32 timeout);
Description:
Writes a number of bytes to the serial communications port through the Serial
Communications Port (SCP) device driver within a specified time frame. The
write operation shall terminate at the time of expiration.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
writebuf is a pointer to the serial data to be written to the serial
communications port.
size is the number of bytes written to the serial communications port.
sizeWritten is a pointer to the number of bytes that are written to the serial
communications port.
timeout is the time in milliseconds that the SCP device driver must complete
the write operation. The value may be rounded up to the nearest system tick,
if the operating system’s timer resolution is lower than the value requested. If
timeout is zero, the write operation will not timeout.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_HARDWARE_ERROR – hardware related error.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read()
Example:
49
3.2.10. Scpdev_write_callback( )
Syntax:
#include “scpdev.h”
int Scpdev_write_callback ( TScpdev hScpdev, u_int8 *writebuf, u_int32
size, TScp_callback function, u_int32 func_tag );
Description:
Writes a number of bytes to the serial communications port through the Serial
Communications Port (SCP) device driver and invokes the callback function
in the calling process space when the write operation is completed.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
writebuf is a pointer to the serial data to be written to the serial
communications port.
size is the number of bytes written to the serial communications port.
function is a pointer to a callback function to be executed when the number
bytes specified in size are written. The routine takes a single u_int32 value
and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is executed.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E E_SCPDEV_NOT_OPEN – if the device was not opened.
_SCPDEV_HARDWARE_ERROR – hardware related error.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read()
Example:
50
3.2.11. Scpdev_flush( )
Syntax:
#include “scpdev.h”
int Scpdev_flush ( TScpdev hScpdev, int buffer_type );
Description:
Flushes the Serial Communications Port (SCP) device driver’s port buffer.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
buffer_type is the type of buffer to be flushed. A value of
SCPDEV_OUTPUT_BUFFER indicates to flush to output buffer. A value of
SCPDEV_INPUT_BUFFER indicates to flush the input buffer. Both values
can be ORed together to flush the input and output buffers.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
Library:
scpdev.lib
See Also:
Scpdev_release()
Example:
51
3.2.12. Scpdev_cancel_calback( )
Syntax:
#include “scpdev.h”
int Scpdev_cancel_callback ( TScpdev hScpdev );
Description:
Cancels all requested callback functions by the Serial Communications Port
(SCP) device driver to that calling process.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
Library:
scpdev.lib
See Also:
Scpdev_flush()
Example:
52
3.2.13. Scpdev_release( )
Syntax:
#include “scpdev.h”
int Scpdev_release ( TScpdev hScpdev );
Description:
Cancels one pending timed read and one pending timed write functions that
are associated with the Serial Communications Port (SCP) device driver.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
Library:
scpdev.lib
See Also:
Scpdev_flush()
Example:
53
3.2.14. Scpdev_dataready( )
Syntax:
#include “scpdev.h”
int Scpdev_dataready ( TScpdev hScpdev, u_int32 *size );
Description:
Returns the number of bytes of data ready to be read.
Parameters:
hScpdev is the handle that SCP device driver assigns.
size is a pointer to a location where the SCP device driver returns the number
of bytes of data available to be read.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_flush()
Example:
54
3.2.15. Scpdev_get_attrib( )
Syntax:
#include “scpdev.h”
int Scpdev_get_attrib ( TScpdev hScpdev, TScfdev_attrib *attrib );
Description:
Gets attributes of the current serial port device through the Serial
Communications Port (SCP) device driver. This function returns information
to the user buffer for inspection. The descriptor includes information related
to serial port’s baud, bit, handshaking, and other attributes.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
attrib is a pointer to the user TScpdev_attrib structure. The TScpdev_attrib
structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCDEV_OUTOF_BUFFER – the user buffer size is too small.
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_set_attrib()
Example:
55
3.2.16. Scpdev_set_attrib( )
Syntax:
#include “scpdev.h”
int Scpdev_set_attrib ( TScpdev hScpdev, TScpdev_attrib *attrib );
Description:
Sets attributes of the current serial port device through the Serial
Communications Port (SCP) device driver. This function will copy
information from the user buffer to the hScpdev’s attribute table. The
attributes include information related to serial port’s baud rate, bit format,
handshaking, and other attributes.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
attrib is a pointer to the user TScpdev_attrib structure. The TScpdev_attrib
structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_INVALID_ATTRIBUTE – if one or more parameters in the
attribute table pointed to by attrib_ptr have a valid attribute.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_get_attrib()
Example:
56
3.2.17. Scpdev_get_status( )
Syntax:
#include “scpdev.h”
int Scpdev_get_status ( TScpdev hScpdev, TScfdev_status *status );
Description:
Gets status of the current serial port device through the Serial
Communications Port (SCP) device driver. This function returns information
to the user buffer for inspection. The status includes information related to
serial port’s control states and error conditions.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
status is a pointer to the user TScpdev_status structure. The
TScpdev_status structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCDEV_OUTOF_BUFFER – the user buffer size is too small.
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_set_status()
Example:
57
3.2.18. Scpdev_set_status( )
Syntax:
#include “scpdev.h”
int Scpdev_set_status ( TScpdev hScpdev, TScpdev_status *status );
Description:
Sets statuses of the current serial port device through the Serial
Communications Port (SCP) device driver. This function copies information
from the user buffer to the hScpdev status table. The statuses include
information related to serial port’s control states and error conditions.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
status is a pointer to the user TScpdev_status structure. The
TScpdev_status structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_INVALID_ATTRIBUTE – if one or more parameters in the
attribute table pointed to by status_ptr have a valid attribute.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_get_attrib(), Scpdev_get_status().
Example:
58
3.2.19. Scpdev_get_control( )
Syntax:
#include “scpdev.h”
int Scpdev_get_control ( TScpdev hScpdev, TScfdev_control *control );
Description:
Gets control states of the current serial port device through the Serial
Communications Port (SCP) device driver. This function returns information
to the user buffer for inspection. The control states include information
related to serial port’s CTS and DTR.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
control is a pointer to the user TScpdev_control structure. The
TScpdev_control structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCDEV_OUTOF_BUFFER – the user buffer size is too small.
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_set_control()
Example:
59
3.2.20. Scpdev_set_control( )
Syntax:
#include “scpdev.h”
int Scpdev_set_control ( TScpdev hScpdev, TScpdev_control *control );
Description:
Sets control states of the current serial port device through the Serial
Communications Port (SCP) device driver. This function copies information
from the user buffer to the hScpdev control table. The control states include
information related to serial port’s CTS and DTR.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
control is a pointer to the user TScpdev_control structure. The
TScpdev_control structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPDEV_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPDEV_NOT_OPEN – if the device was not opened.
E_SCPDEV_INVALID_CONTROL – if one or more parameters in the
control table pointed to by control_ptr have a valid value.
E_SCPDEV_OS_ERROR – an operating system error has occurred.
E_SCPDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_get_control().
Example:
60
3.2.21. SCPDEV.H
/****************************************************************************
/
/* MODULE : scpdev.h
*/
/* VERSION: 3.0
*/
/* DATE:
06/01/98
*/
/* PROGRAMMER: George Chen
*/
/* PORTABILITY: ATC SYSTEM UNITS
*/
/*
*/
/* DESCRIPTION:
*/
/* This module is the header file for scpdev device driver library for /* the
ATC serial communications ports.
*/
/****************************************************************************
/
#ifndef _SCPDEV_H_
#define _SCPDEV_H_
#ifdef __cplusplus
extern "C" {
#endif
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
typedef unsigned int TScpdev;
/* rtio handle */
typedef void (*function)(u_int32) TScp_callback;
typedef struct
{
u_int8
txXON;
u_int8
txXOFF;
u_int8
rxXON;
u_int8
rxXOFF;
u_int8
dataBits;
u_int8
parity;
u_int8
stopBits;
/* xon char
0 = disable
(default)
$ = xon char and enable
/* xoff char
0 = disable
(default)
$ = xoff char and enable
/* xon char
0 = disable
(default)
$ = xon char and enable
/* xoff char
0 = disable
(default)
$ = xoff char and enable
/* data bits per char
5 = 5 bits per char;
6 = 6 bits per char;
7 = 7 bits per char;
8 = 8 bits per char; (default)
/* parity
0 = none;
(default)
1 = odd;
2 = even
/* stop bits
10 = 1
stop bit;
(default)
15 = 1.5 stop bits;
2 = 2
stop bits
61
*/
*/
*/
*/
*/
*/
*/
u_int32 baudRate;
/* baud rate
1200 = 1200 baud
(default)
value = buad rate
*/
u_int8 swFlowCtrl; /* software handshaking mode
0 = no flow control (default)
1 = flow control on
*/
u_int8 hwFlowCtrl; /* hardware handshaking mode
0 = No flow control (default)
1 = Manual
2 = Auto-CTS
3 = Auto-RTS
4 = Fully automatic
5 = Dynamic
*/
u_int8 rtsoff_delay;/* RTS off delay time in ms for
hardware handshaking mode 3 & 4
(default = 0) */
} TScpdev_attrib, *PTScpdev_attrib;
typedef struct
{
boolean CTS;
boolean DSR;
boolean DCD;
boolean Ring;
boolean overflowError;
boolean framingError;
boolean parityError;
u_int32 overflowErrors;
u_int32 framingErrors;
u_int32 parityErrors;
} TScpdev_status, *PTScpdev_status;
typedef struct
{
boolean RTS;
boolean DTR;
boolean Break;
} TScpdev_control, *PTScpdev_control;
/* ATC API Function Prototypes */
u_int32 Scpdev_open( char *devname,
TScpdev *hScpdev,
int exclusive );
u_int32 Scpdev_close( TScpdev hScpdev );
u_int32 Scpdev_available( TScpdev hScpdev,
u_int32 *size );
u_int32 Scpdev_release( TScpdev hScpdev );
u_int32 Scpdev_flush( TScpdev hScpdev,
int inp_out );
u_int32 Scpdev_read( TScpdev hScpdev,
u_int8 *readbuf,
62
u_int32 size,
u_int32 *readsize,
void *, u_int32 tag );
u_int32 Scpdev_read_timed( TScpdev hScpdev,
u_int8 *readbuf,
u_int32 size,
u_int32 *readsize,
u_int32 msTimeout);
u_int32 Scpdev_read_callback( TScpdev hScpdev,
u_int8 *readbuf,
u_int32 size,
u_int32 *readsize,
TScp_callback function,
u_int32 tag );
u_int32 Scpdev_write( TScpdev hScpdev,
u_int8 *writebuf,
u_int32 size,
u_int32 *writtensize );
u_int32 Scpdev_write_timed( TScpdev hScpdev,
u_int8 *writebuf,
u_int32 size,
u_int32 *writtensize,
u_int32 msTimeout );
u_int32 Scpdev_write_callback( TScpdev hScpdev,
u_int8 *writebuf,
u_int32 size,
u_int32 *writtensize,
TScp_callback function,
u_int32 tag );
u_int32 Scpdev_get_attrib( TScpdev hScpdev,
TScpdev_attrib *attrib );
u_int32 Scpdev_set_attrib( TScpdev hScpdev,
TScpdev_attrib *attrib );
u_int32 Scpdev_get_status( TScpdev hScpdev,
TScpdev_status *status );
u_int32 Scpdev_set_status( TScpdev hScpdev,
TScpdev_status *status );
u_int32 Scpdev_get_control( TScpdev hScpdev,
TScpdev_control *control );
u_int32 Scpdev_set_control( TScpdev hScpdev,
TScpdev_control *control );
//* error codes
#define E_SCPDEV_GENERAL_FAILURE -1
typedef enum _E_SCPDEV_ENUM
{
63
E_SCPDEV_NULL_POINTER=20
,
E_SCPDEV_INVALID_ATTRIBUTE ,
E_SCPDEV_OUT OF_BUFFER
,
E_SCPDEV_READ_QUEUE_FULL
,
E_SCPDEV_HARDWARE_ERROR
,
E_SCPDEV_ALREADY_CLOSED
,
E_SCPDEV_BUFFER_TOO_LARGE ,
E_SCPDEV_WRITE_BUFFER_FULL ,
E_SCPDEV_OS_ERROR
,
E_SCPDEV_INVALID_DEVNAME
,
E_SCPDEV_INVALID_HANDLE
,
E_SCPDEV_WRITE_BUFFER_TOO_SMALL,
E_SCPDEV_INVALID_SIGNAL_NUMBER
} E_SCPDEV_ENUM;
#ifdef __cplusplus
}
#endif
#endif
64
3.3.
SYSTEM DEVICE INTERFACE – LAYER 1 API
3.3.1. Overview
This API has only level one programming interface for user applications to access system
functions of an operating system on an ATC. Level one API defines the functional interface
between an ATC application and system environments that the applications are running. The
system interface and its accompanying source level library are usually manufacturer and
operating system dependent.
The SYSDEV API provides an interface to encapsulate most of system level services of a RTOS.
These services enable inter-process communications (IPC) and other system level functions for
all applications in an ATC. The services include event notification, data sharing,
synchronization, process management, thread management, system time, and hardware interrupt
services.
3.3.1.1.
Event Service
The event service is used to encapsulate software and hardware interrupt services of an operating
system. The event can be either a single-shot event that occurs only once, or a multiple-shot
event that occur in a fixed interval. The notification of an interrupt is signaled through either a
callback function with an associated tag, or a wait command.
The current event service define at least four types of events, tag notification event, calendar
alarm event, timer event, and power-down event. A tag notification event allows the calling
process to receive a tag notification. A calendar alarm event allows the calling process to receive
a notification when a calendar alarm is occurred. A timer event allows the calling process to
receive a notification when a timer is expired. A power-down event allows the calling process to
receive a pending power-down notification. To use this event service, the user process must
register the event in order to be notified.
The tag notification event is the basic event of the other three events. It is similar to a signal
event. The tag used in a tag notification event and all other events must be unique throughout an
ATC system. Tag numbers from 0-512 are reserved and are defined by this API. User programs
that use a tag number in any event notifications must request an unique tag number from the
Sysdev Device driver. The tag number shall be returned to the SYSDEV driver when the tag is
no longer needed.
A calendar alarm event provides absolute event notifications. The event is signaled only when
the scheduled calendar time is reached. For example, in a single-shot event, if a process requests
to be notified at 6:30 on March 14, 1999, the process is signaled on that time and date. In a
multiple-shot event, the process is signaled at 6 o’clock , 30 minutes, 40 seconds, and 500
milliseconds every Monday, if the event attributes are configured to be alarm.dow = 1,
alarm.hour = 6, alarm.minute = 30, alarm.second = 40, alarm.msecond = 500, and all the rest of
alarm structure members = don’t care values.
65
A timer event provides relative event notifications. The event is signaled only when the elapsed
time is reached. For example, if a process sets multiple-shot timer for every 2 hours and 30
minutes, it is signaled when 2 hours and 30 minutes has elapsed even if the system time and date
have been changed during the notification interval.
3.3.1.2.
Data Sharing Service
The shared memory service provides data sharing through the shared memory and named pipe
communications. Shared memory is a common block of memory in the system that allows
multiple processes to access its contents. A named pipe is a first-in, first-out buffer that allows all
multiple processes to communicate data.
3.3.1.3.
Synchronization Service
The data synchronization service provides data, and multiple task execution synchronization in a
multi-tasking operating system through the semaphore and mutex services.
A semaphore is a synchronization object that maintains a count from zero to a maximum value.
The count is decreased by one with each wait command, and is increased by each post command
of a task for the semaphore. If the count reaches zero, any tasks waiting for the semaphore are
blocked until the count is increased to non-zero.
A mutex is a synchronization object that can be owned by only one task at a time. A task owns a
mutex when it completes an acquire command, and disowns a mutex by issuing the release
command. When a mutex is owned, no other tasks can own it until it is disowned. Any tasks that
are trying to acquire the mutex are blocked until the mutex owner releases it.
Note: If more than one task is waiting for a synchronization service, the task with the highest
priority gets to be signaled first and is the first to return from the wait or acquire functions. In
case where the tasks have the same priority, the earliest requesting task returns first.
3.3.1.4.
Process Management Service
The process management service provides management functions of multiple processes in an
operating system.
3.3.1.5.
Thread Management Service
The thread management service provides management functions of multiple threads in a process.
3.3.1.6.
System time Service
The system time allows user programs to inquire and change the ATC system’s date and time
information. The services also provide access to the ATC system’s higher resolution clock if it
exists.
66
3.3.1.7.
Hardware Interrupt Service
The hardware interrupt service provides a consistent means of applications in an APC to attach a
hardware interrupt handler to a device in an ATC system.
67
3.3.2. Sysdev_event_init( )
Syntax:
#include “sysdev.h”
int Sysdev_init_event ( void );
Description:
Initializes the event handler for the calling process. Only one event handle is
created per calling process. The event handler is used for inter-process
communications via callback routines and tags.
Parameters:
None.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other error codes:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_ALREADY_INIT – the calling process already call this
function.
Library:
sysdev.lib
See Also:
Sysdev_event_deinit( );
Example:
68
3.3.3. Sysdev_event_deinit( )
Syntax:
#include “sysdev.h”
int Sysdev_event_deinit ( void );
Description:
De-initializes the event handler for the calling process. All events that occur
for the calling process will be ignored.
Parameters:
None.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_ALREADY_DEINIT – if the device was already de-initialized
by this function.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_event_init( )
Example:
69
3.3.4. Sysdev_event_reg( )
Syntax:
#include “sysdev.h”
int Sysdev_event_reg ( TSysdev *phSysdev, u_int32 type, TSys_callback
function, u_int32 func_tag );
Description:
Registers and installs an event that has a callback function and its associated
tag. The registered event can be a callbackable event or a waitable event, a
one shot event or a multiple shot event.
Parameters:
phSysdev is a pointer to the handle that the system device driver assigns to the
registered event.
type is the type of event that the calling process requests to be registered. A
value of SYSDEV_EVENT_TAG indicates that the registered event is a tag
notification event. A value of SYSDEV_EVENT_ALARM indicates that the
registered event is a calendar alarm event. A value of
SYSDEV_EVENT_TIMER indicates that the registered event is a timer
event. A value of SYSDEV_EVENT_POWERDOWN indicates that the
registered event is a power-down event.
function is a pointer to a callback function to be executed when an event is
signaled by the system. The func_tag is also passed to the callback function.
The routine takes a single u_int32 value and returns void. A null pointer
informs the system device driver not to invoke any callback functions, and the
event is a waitable event. However, the calling process will be blocked if it
calls the Sysdev_event_waitfor( ) function to wait for any event.
func_tag is the tag to be returned to the calling process when its callback
function is executed. A value of zero indicates that the calling process is
requesting a notification without a tag (used for waitable events).
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_HARDWARE_ERROR – hardware related errors are
encountered.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_INVALID_TAG – an invalid tag is used to register an event.
70
E_SYSDEV_EVENT_NOTSUPPORTED – a requested event is not
supported by this particular system.
Library:
sysdev.lib
See Also:
Sysdev_event_dereg( )
Example:
71
3.3.5. Sysdev_event_dereg( )
Syntax:
#include “sysdev.h”
int Sysdev_dereg_event ( TSysdev hSysdev );
Description:
De-registers and removes the callback function from the event handler.
Parameters:
hSysdev is the handle that the system device driver assigns to the event.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_INVALID_HANDLE – an invalid system device handle is used.
E_SYSDEV_HARDWARE_ERROR – hardware related error.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_event_reg( )
Example:
72
3.3.6. Sysdev_event_allocateTag( )
Syntax:
#include “sysdev.h”
int Sysdev_event_allocateTag ( u_int32 *tag );
Description:
Requests to allocate a tag number that is unique to the system.
Parameters:
tag is a pointer to the location that the device driver returns an unique tag
number.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_event_freeTag( )
Example:
73
3.3.7. Sysdev_event_freeTag( )
Syntax:
#include “sysdev.h”
int Sysdev_event_freeTag ( u_int32 tag );
Description:
Requests to free a tag number.
Parameters:
tag is the tag number to be freed.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_event_allocateTag( )
Example:
74
3.3.8. Sysdev_event_get_attrib( )
Syntax:
#include “sysdev.h”
int Sysdev_event_get_attrib ( TSysdev hSysdev, TSysdev_event_attrib
*attrib );
Description:
Gets the current event attributes.
Parameters:
hSysdev is the handle that the System device driver assigns to the event
handler.
attrib is a pointer to the attribute buffer where the device driver returns the
event attributes.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_event_set_attrib( )
Example:
75
3.3.9. Sysdev_event_set_attrib( )
Syntax:
#include “sysdev.h”
int Sysdev_event_set_attrib (TSysdev hSysdev, TSysdev_event_attrib
*attrib );
Description:
Sets the event attributes. It also starts or restarts a timer event. In the case of
re-starting a timer, the new timer interval is in effect when the current timer
event with the old interval is elapsed.
Parameters:
hSysdev is the handle that the System device driver assigns the event.
attrib is a pointer to the attribute buffer that the device driver uses to set the
event attributes.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_event_get_attrib( )
Example:
76
3.3.10. Sysdev_event_start( )
Syntax:
#include “sysdev.h”
int Sysdev_event_start ( TSysdev hSysdev );
Description:
Starts or restarts an event.
Parameters:
hSysdev is the handle that the System device driver assigns the event.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_EVENT_ACTIVE – the event is still active when requested.
Request is ignored.
Library:
sysdev.lib
See Also:
Sysdev_event_stop( )
Example:
77
3.3.11. Sysdev_event_stop( )
Syntax:
#include “sysdev.h”
int Sysdev_event_stop (TSysdev hSysdev );
Description:
Stops an active event. No event notification is sent until the event is restarted.
Parameters:
hSysdev is the handle that the System device driver assigns the event.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_EVENT_NOTACTIVE – the event is not active a null pointer is
passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_event_start( )
Example:
78
3.3.12. Sysdev_event_send( )
Syntax:
#include “sysdev.h”
int Sysdev_event_send ( int proc_id, u_int32 func_tag );
Description:
Sends a function tag or token to another process via the event handler.
Parameters:
proc_id is the active process ID number that the system assigned. If the
proc_id is zero, the tag is sent to all registered processes.
func_tag is the tag or token to be sent to the process with the proc_id.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SYSDEV_INVALID_HANDLE – an invalid system device handle is used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_PROCESS_NOT_EXIST – the process with the proc_id does
not exist.
Library:
sysdev.lib
See Also:
Sysdev_event_waitfor( )
Example:
79
3.3.13. Sysdev_event_waitfor( )
Syntax:
#include “sysdev.h”
int Sysdev_event_waitfor ( TSysdev hSysdev );
Description:
Waits for either a single event associated with the event handle or multiple
events to occur in the calling process. If an event is signaled, the calling
process is unblocked and continues its execution.
Parameters:
hSysdev is the event handle that the calling process is waiting for. If hSysdev
is zero, the calling process waits for an event that is registered to occur. The
registered events include tag notification, calendar alarm, and timer events.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_event_send( )
Example:
80
3.3.14. Sysdev_event_cancel( )
Syntax:
#include “sysdev.h”
int Sysdev_event_cancel ( TSysdev hSysdev );
Description:
Cancels the next occurrence of an active event notification.
Parameters:
hSysdev is the event handle associated with this event.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_event_stop( )
Example:
81
3.3.15. Sysdev_event_disable( )
Syntax:
#include “sysdev.h”
int Sysdev_event_disable ( TSysdev hSysdev );
Description:
Disable all event notifications sent to the calling process. All events are
queued up by the system.
Parameters:
hSysdev is the event handle associated with this event.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_event_enable( )
Example:
82
3.3.16. Sysdev_event_enable( )
Syntax:
#include “sysdev.h”
int Sysdev_event_enable ( TSysdev hSysdev );
Description:
Enable all event notifications to the calling process. All the queued events are
sent to the calling process according to their chronological orders.
Parameters:
hSysdev is the event handle associated with this event.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_event_enable( )
Example:
83
3.3.17. Sysdev_shmem_create( )
Syntax:
#include “sysdev.h”
int Sysdev_shmem_create ( TSysdev *phSysdev, void **pShmem, char
*shmemName, u_int32 size );
Description:
Creates a named shared memory in the system for inter-process
communications. Read and write operations to the shared memory are
allowed.
Parameters:
phSysdev is the handle that the System device driver assigns to the allocated
shared memory.
pShmem is a pointer to the location where the function returns the pointer to
the base of the allocated shear memory. A null pointer is returned if this
function is failed.
shmemName is the name of the shear memory. The shmemName must be
unique system-wide for all shared memories.
size is the size in byte of the shared memory.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_NO_MEMORY – the block size of the requested memory is
larger than any available blocks of free memory.
E_SYSDEV_SHMEM_EXIST – a shared memory with the same name is
existing in the system.
Library:
sysdev.lib
See Also:
Sysdev_shmem_delete( )
Example:
84
3.3.18. Sysdev_shmem_delete( )
Syntax:
#include “sysdev.h”
int Sysdev_shmem_delete ( TSysdev hSysdev );
Description:
Deletes the named shared memory if no other processes still connect to it.
Parameters:
hSysdev is the handle of the shared memory that the System device driver
assigns.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_USER_ATTACHED – failed to delete the named shared
memory because other processes are still connected to it.
Library:
sysdev.lib
See Also:
Sysdev_shmem_create( )
Example:
85
3.3.19. Sysdev_shmem_open( )
Syntax:
#include “sysdev.h”
int Sysdev_shmem_open ( TSysdev *phSysdev, char *shmemName );
Description:
Opens an existing named shared memory for inter-process communications.
Read and write operations to the named shared memory are allowed.
Parameters:
phSysdev is the handle of the shared memory that the System device driver
assigns.
shmemName is the name of the shared memory.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_NOT_EXIST – the named shared memory does not exist.
Library:
sysdev.lib
See Also:
Sysdev_shmem_close( )
Example:
86
3.3.20. Sysdev_shmem_close( )
Syntax:
#include “sysdev.h”
int Sysdev_shmem_close ( TSysdev hSysdev );
Description:
Closes the named shared memory.
Parameters:
hSysdev is the handle of the shared memory that the System device driver
assigns.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_create_shmem( )
Example:
87
3.3.21. Sysdev_pipe_create( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_create ( TSysdev *phSysdev, char *pipeName, u_int32 size
);
Description:
Creates a one-directional named pipe for inter-process communications. Read
and write operations to the named pipe are allowed.
Parameters:
phSysdev is the handle of the pipe that the System device driver assigns to the
pipe.
pipeName is the name of the pipe. The pipeName must be unique systemwide for all pipes.
size is the size in bytes of the named pipe buffer.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_NO_MEMORY – the block size of the requested pipe memory
is larger than any available blocks of free memory.
E_SYSDEV_PIPE_EXIST – a pipe with the same name is existing in the
system.
Library:
sysdev.lib
See Also:
Sysdev_pipe_delete( )
Example:
88
3.3.22. Sysdev_pipe_delete( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_delete ( TSysdev hSysdev );
Description:
Deletes the named pipe if no other processes still connect to it.
Parameters:
hSysdev is the handle of the pipe that the System device driver assigns.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_USER_ATTACHED – fail to delete the named pipe because
other processes are still connected to and using it.
Library:
sysdev.lib
See Also:
Sysdev_pipe_create( )
Example:
89
3.3.23. Sysdev_pipe_open( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_open ( TSysdev *phSysdev, char *pipeName );
Description:
Opens an existing named pipe for inter-process communications. Read and
write operations to the name pipe are allowed.
Parameters:
phSysdev is the handle that the System device driver assigns the pipe.
pipeName is the name of the pipe.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_NOT_EXIST – the named pipe does not exist.
Library:
sysdev.lib
See Also:
Sysdev_pipe_close( )
Example:
90
3.3.24. Sysdev_pipe_close( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_close ( TSysdev hSysdev );
Description:
Closes the named pipe.
Parameters:
hSysdev is the handle that the System device driver assigns to a pipe.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_pipe_open( )
Example:
91
3.3.25. Sysdev_pipe_read( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_read ( TSysdev hSysdev, u_int8 *buf, u_int32 size, u_int32
*sizeRead);
Description:
Reads specified number of bytes from the named pipe and returns the number
of read bytes to the calling process. The function shall not be blocked.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
buf is a pointer to the buffer where the device driver stores read data.
size is the number of bytes that the calling process requests to read from the
pipe.
sizeRead is a pointer to a location where the System device driver returns the
number of read bytes.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_pipe_write( )
Example:
92
3.3.26. Sysdev_pipe_read_timed( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_read_timed ( TSysdev hSysdev, u_int8 *buf, u_int32 size,
u_int32 *sizeRead, u_int32 timeout );
Description:
Reads specified number of bytes from the named pipe and returns the number
of read bytes to the calling process within a specified time frame. The calling
process will be blocked until either the timeout has expired or the size of bytes
has been read.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
buf is a pointer to the buffer that the device driver stores read data.
size is the number of bytes that the calling process requests to read from the
pipe.
sizeRead is a pointer to a location that the device driver returns the number of
read bytes.
timeout is the time in milliseconds that the device driver must complete the
read operation. The value may be rounded up to the nearest system tick, if the
operating system’s timer resolution is lower than the value requested. If
timeout is zero, the read operation will not timeout.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_ABORT – a release command is received by the device driver.
Library:
sysdev.lib
See Also:
Sysdev_pipe_write_timed( )
Example:
93
3.3.27. Sysdev_pipe_write( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_write ( TSysdev hSysdev, u_int8 *buf, u_int32 size );
Description:
Writes data to named pipe.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
buf is a pointer to the buffer contains the data.
size is the number of bytes that the calling process requests to write to the
pipe.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_WRITE_BUFFER_FULL – the write buffer of the named pipe
is smaller than the size of the requested write.
Library:
sysdev.lib
See Also:
Sysdev_pipe_read( )
Example:
94
3.3.28. Sysdev_pipe_write_timed( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_write_timed ( TSysdev hSysdev, u_int8 char *buf, u_int32
size, u_int32 *sizeWritten, u_int32 timeout );
Description:
Writes data to named pipe with the specified time frame.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
buf is a pointer to the buffer contains the data.
size is the number of bytes that the calling process requests to write to the
pipe.
sizeWritten is a pointer to a location that the System device driver returns the
number of written bytes.
timeout is the time in milliseconds that the device driver must complete the
write operation. The value may be rounded up to the nearest system tick, if
the operating system’s timer resolution is lower than the value requested. If
timeout is zero, the write operation will not timeout.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_pipe_read_timed( )
Example:
95
3.3.29. Sysdev_pipe_dataready( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_dataready ( TSysdev hSysdev, u_int32 *size );
Description:
Returns the number of bytes of data ready to be read.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
size is a pointer to a location that the System device driver returns the number
of bytes of data available to be read.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_pipe_flush( )
Example:
96
3.3.30. Sysdev_pipe_flush( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_flush ( TSysdev hSysdev );
Description:
Flush and clear existing data in the pipe. All data is lost after the call.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_pipe_dataready( )
Example:
97
3.3.31. Sysdev_pipe_release( )
Syntax:
#include “sysdev.h”
int Sysdev_pipe_release ( TSysdev hSysdev );
Description:
Release one timed read and one timed write that are pending.
Parameters:
hSysdev is the handle that the System device driver assigns to the pipe.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_flush( )
Example:
98
3.3.32. Sysdev_semaphore_create( )
Syntax:
#include “sysdev.h”
int Sysdev_semaphore_create ( TSysdev *phSysdev, char *semaName,
u_int32 max_count );
Description:
Creates a named semaphore for data and process synchronization.
Parameters:
phSysdev is the handle that the System device driver assigns the semaphore.
semaName is the name of the semaphore. The semaName must be unique for
all system-wide semaphores.
max_count is the maximum counts of the semaphore.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_SEMA_EXIST – a semaphore with the same name is existing in
the system.
Library:
sysdev.lib
See Also:
Sysdev_semaphore_delete( )
Example:
99
3.3.33. Sysdev_semaphore_delete( )
Syntax:
#include “sysdev.h”
int Sysdev_semaphore_delete ( TSysdev hSysdev );
Description:
Deletes the named semaphore if no other processes are connect to it.
Parameters:
hSysdev is the handle that the System device driver assigns.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_PIPE_USER_ATTACHED – failed to delete the name
semaphore because other processes are still connected to it.
Library:
sysdev.lib
See Also:
Sysdev_semaphore_create( )
Example:
100
3.3.34. Sysdev_semaphore_open( )
Syntax:
#include “sysdev.h”
int Sysdev_semaphore_open ( TSysdev *phSysdev, char *semaName );
Description:
Opens an existing named semaphore for data and process synchronization.
Parameters:
phSysdev is the location that the System device driver returns the semaphore
handle.
semaName is the name of the semaphore.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_NOT_EXIST – the named semaphore does not exist.
Library:
sysdev.lib
See Also:
Sysdev_semaphore_close( )
Example:
101
3.3.35. Sysdev_semaphore_close( )
Syntax:
#include “sysdev.h”
int Sysdev_semaphore_close ( TSysdev hSysdev );
Description:
Closes the named semaphore.
Parameters:
hSysdev is the handle that the System device driver assigns to the semaphore.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_semaphore_open( )
Example:
102
3.3.36. Sysdev_semaphore_wait( )
Syntax:
#include “sysdev.h”
int Sysdev_semaphore_wait ( TSysdev hSysdev, u_int32 timeout );
Description:
Waits for the named semaphore to become available. The process is blocked
until either the semaphore is signaled or the function is timed out.
Parameters:
hSysdev is the handle that the System device driver assigns to the semaphore.
timeout is the timeout value in milliseconds that the process waits for the
semaphore to become available. The value may be rounded up to the nearest
system tick, if the operating system’s timer resolution is lower than the value
requested. If timeout is zero, the read operation will not timeout.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_TIMEOUT – timeout when waiting for the semaphore.
Library:
sysdev.lib
See Also:
Sysdev_semaphore_post( )
Example:
103
3.3.37. Sysdev_semaphore_post( )
Syntax:
#include “sysdev.h”
int Sysdev_semaphore_post ( TSysdev hSysdev );
Description:
Posts a count increment to the named semaphore.
Parameters:
hSysdev is the handle that the System device driver assigns to the semaphore.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_semaphore_wait( )
Example:
104
3.3.38. Sysdev_mutex_create( )
Syntax:
#include “sysdev.h”
int Sysdev_mutex_create ( TSysdev *phSysdev, char *mutexName );
Description:
Creates a named mutex for data and process synchronization.
Parameters:
phSysdev is the handle that the System device driver assigns the mutex.
mutexName is the name of the mutex. The mutexName must be unique
system-wide for all mutexes.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_MUTEX_EXIST – a mutex with the same name is existing in
the system.
Library:
sysdev.lib
See Also:
Sysdev_mutex_delete( )
Example:
105
3.3.39. Sysdev_mutex_delete( )
Syntax:
#include “sysdev.h”
int Sysdev_mutex_delete ( TSysdev hSysdev );
Description:
Deletes the named mutex if no other processes still connect to it.
Parameters:
hSysdev is the handle that the System device driver assigns to the mutex.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_ATTACHED – fails to delete the name mutex because other
processes are still connected to it.
Library:
sysdev.lib
See Also:
Sysdev_mutex_create( )
Example:
106
3.3.40. Sysdev_mutex_open( )
Syntax:
#include “sysdev.h”
int Sysdev_mutex_open ( TSysdev *phSysdev, char *mutexName );
Description:
Opens an existing named mutex for data and process synchronization.
Parameters:
phSysdev is the handle that the System device driver assigns the mutex.
mutexName is the name of the mutex.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_NOT_EXIST – the named mutex does not exist.
Library:
sysdev.lib
See Also:
Sysdev_mutex_close( )
Example:
107
3.3.41. Sysdev_mutex_close( )
Syntax:
#include “sysdev.h”
int Sysdev_mutex_close ( TSysdev hSysdev );
Description:
Closes the named mutex.
Parameters:
hSysdev is the handle of the mutex that the System device driver assigns.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_mutex_open( )
Example:
108
3.3.42. Sysdev_mutex_acquire( )
Syntax:
#include “sysdev.h”
int Sysdev_mutex_acquire ( TSysdev hSysdev, u_int32 timeout );
Description:
Acquires the named mutex. If the named mutex is not available, the calling
process is blocked until either the mutex is signaled or the wait times out.
Parameters:
hSysdev is the handle that the System device driver assigns mutex.
timeout is the time in milliseconds that the process waits to acquire the mutex.
The value may be rounded up to the nearest system tick, if the operating
system’s timer resolution is lower than the value requested. If timeout is zero,
the read operation will not timeout.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_TIMEOUT – timeout when acquiring the mutex.
Library:
sysdev.lib
See Also:
Sysdev_mutex_release( )
Example:
109
3.3.43. Sysdev_mutex_release( )
Syntax:
#include “sysdev.h”
int Sysdev_mutex_realese ( TSysdev hSysdev );
Description:
Releases an acquired mutex for other waiting process.
Parameters:
hSysdev is the handle that the System device driver assigns the mutex.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NOT_OWNED – the calling process tries to release a mutex
that it does not own.
Library:
sysdev.lib
See Also:
Sysdev_mutex_acquire( )
Example:
110
3.3.44. Sysdev_get_priority( )
Syntax:
#include “sysdev.h”
int Sysdev_get_priority ( u_int32 proc_id, u_int32 *priority, u_int32
*default_priority, u_int32 *min_priority, u_int32 *max_priority );
Description:
Returns the priority related information of a process to the calling process.
Parameters:
proc_id is the system identification number of a process.
priority is a pointer to a location where the system returns the current priority
of the calling process.
default_priority is a pointer to a location where the device driver returns the
system’s default priority.
min_priority is a pointer to a location where the device driver returns the
lowest (minimum) priority that the calling process can be set to in the system.
max_priority is a pointer to a location where the device driver returns the
highest (maximum) priority that the calling process can be set to in the
system.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_INVALID_PROCESS – an invalid process identification
number is used.
Library:
sysdev.lib
See Also:
Sysdev_set_priority( )
Example:
111
3.3.45. Sysdev_set_priority( )
Syntax:
#include “sysdev.h”
int Sysdev_set_priority ( u_int32 proc_id, u_int32 priority );
Description:
Sets the priority of the process.
Parameters:
proc_id is the system identification number of the process that calling process
wants to set its priority.
priority is the priority level the calling process requested to be operating at. If
the requested priority is higher than the maximum priority level of a system,
the highest priority is assigned to the calling process. If the requested priority
is lower than the minimum priority level of a system, the lowest priority is
assigned to the calling process.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_INVALID_PRIORITY – an invalid priority level is requested.
E_SYSDEV_INVALID_PROCESS – an invalid process identification
number is used.
Library:
sysdev.lib
See Also:
Sysdev_get_priority( )
Example:
112
3.3.46. Sysdev_get_procID( )
Syntax:
#include “sysdev.h”
int Sysdev_get_procID ( char *proc_name, u_int32 *proc_id, u_int32
*array_size );
Description:
Gets all the process identifications of the corresponding proc_name.
Parameters:
proc_name is the name of the active process(es). If proc_name is NULL, it
returns the calling process’s proc_id.
proc_id is a pointer to an array of proc_id(s) in the calling process’s space
that this function fills in all instances for the program module named
proc_name up to the calling process’s array size.
array_size is a pointer to a location that stores the size of the calling process’s
proc_id array. The function returns the number of instances of processes with
the proc_name. If the array_size is smaller than the returning array, the
function returns the number of process identifiction numbers to the proc_id
only. The actual number of process identification numbers is return to the
array_size.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_INVALID_PROCESS – if the proc_name does not exist.
E_SYSDEV_ARRAY_OVERFLOW – if the proc_id array is smaller than
the actual number of process idetification numbers that are returned.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Example:
113
3.3.47. Sysdev_exec( )
Syntax:
#include “sysdev.h”
int Sysdev_exec ( char *prog_name, char **argv, char **envp, u_int32
priority );
Description:
Execute a program from the calling process.
Parameters:
prog_name is the name of the program.
argv is a pointer to the parameter pointer list that the new process is to
receive. The end of argv list is marked by a null pointer.
envp is a pointer to the environment pointer list containing environment
variables that the new process is to receive. A null pointer also marks the end
of the envp list.
priority is the priority level of the function routine. The priority level of one
has the lowest system wide priority. The highest priority level can be obtained
from Sysdev_get_priority() function call. If the requested priority is higher
than the highest priority level of a system, the highest priority is assigned to
the interrupt handler.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_PROCESS_NOT_EXIST – if the proc_name is null or if the
proc_name does not exist.
Library:
sysdev.lib
See Also:
Sysdev_kill( )
Example:
114
3.3.48. Sysdev_kill( )
Syntax:
#include “sysdev.h”
int Sysdev_kill ( u_int32 proc_id );
Description:
Kills and terminates a process.
Parameters:
proc_id is the identification number of the process the calling process intends
to terminate.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
E_SYSDEV_INVALID_PROCESS – the process with the proc_id does not
exist.
Library:
sysdev.lib
See Also:
Sysdev_exec( )
Example:
115
3.3.49. Sysdev_sleep( )
Syntax:
#include “sysdev.h”
int Sysdev_sleep ( u_int32 millisecond );
Description:
Suspends only the calling process for a number of microseconds. All other
concurrent processes continue to run.
Parameters:
millisecond is the milliseconds the process requests to be suspended. The
value may be rounded up to the nearest system tick, if the operating system’s
timer resolution is lower than the value requested. If millisecond is zero, the
process will be suspended indefinitely.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Example:
116
3.3.50. Sysdev_thread_create( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_create ( Tsysdev *phSysdev, void (*function)(void*),
void *pVoid, u_int32 stack, u_int32 priority);
Description:
Creates a concurrent thread in the calling process space.
Parameters:
phSysdev is a pointer to a location that the thread handle is returned.
function is a pointer to a thread function to be executed concurrently with
other threads in the process. The routine takes a single void pointer value and
returns a void.
pVoid is the value of a void pointer passes to the thread.
stack is the requested stack memory in byte for the created thread. If it is zero,
the default size of stack memory is given to the thread.
priority is priority of the created thread. If the requested priority is higher than
the maximum priority level of a system, the highest priority is assigned to the
thread. If the requested priority is lower than the minimum priority level of a
system, the lowest priority is assigned to the thread.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_thread_delete( )
Example:
117
3.3.51. Sysdev_thread_delete( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_delete ( TSysdev hSysdev );
Description:
Deletes the thread and cleans up acquired resources.
Parameters:
hSysdev is the handle that the System device driver assigns to the thread.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_thread_create( )
Example:
118
3.3.52. Sysdev_thread_start( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_start ( TSysdev hSysdev );
Description:
Starts the thread.
Parameters:
hSysdev is the handle that the System device driver assigns to the thread.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_thread_stop( )
Example:
119
3.3.53. Sysdev_thread_stop( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_stop ( TSysdev hSysdev );
Description:
Stops or suspends the thread.
Parameters:
hSysdev is the handle that the System device driver assigns to the thread.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_thread_start( )
Example:
120
3.3.54. Sysdev_thread_sleep( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_sleep ( TSysdev hSysdev, u_int32 millisecond );
Description:
Suspends only the thread for a number of microseconds. All other concurrent
threads continue to run.
Parameters:
hSysdev is the handle that the System device driver assigns to the thread.
millisecond is the milliseconds the thread to be suspended. The value may be
rounded up to the nearest system tick, if the operating system’s timer
resolution is lower than the value requested. If millisecond is zero, the thread
will be suspended indefinitely.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_thread_stop( )
Example:
121
3.3.55. Sysdev_thread_get_priority( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_get_priority ( TSysdev hSysdev, u_int32 *priority,
u_int32 *default_priority, u_int32 *min_priority, u_int32 *max_priority );
Description:
Returns the system’s priority configuration to the calling process.
Parameters:
hSysdev is the handle that the System device driver assigns to the thread.
priority is a pointer to a location where the device driver returns the current
priority of the thread.
default_priority is a pointer to a location where the device driver returns the
system’s default priority for a thread.
min_priority is a pointer to a location where the device driver returns the
lowest (minimum) priority that a thread can be set to in the system.
max_priority is a pointer to a location where the device driver returns the
highest (maximum) priority that a thread can be set to in the system.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_thread_set_priority( )
Example:
122
3.3.56. Sysdev_thread_set_priority( )
Syntax:
#include “sysdev.h”
int Sysdev_thread_set_priority ( TSysdev hSysdev, u_int32 priority );
Description:
Sets the priority of the process.
Parameters:
hSysdev is the handle that the System device driver assigns to the thread.
priority is the priority level the calling process requested to be operating at. If
the requested priority is higher than the maximum priority level of a system,
the highest priority is assigned to the thread. If the requested priority is lower
than the minimum priority level of a system, the lowest priority is assigned to
the thread.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_INVALID_PRIORITY – an invalid priority level is requested.
Library:
sysdev.lib
See Also:
Sysdev_thread_get_priority( )
Example:
123
3.3.57. Sysdev_get_time( )
Syntax:
#include “sysdev.h”
int Sysdev_get_time ( TDateTime *dt );
Description:
Gets the date and time from the system.
Parameters:
dt is a pointer to the structure that the Sysdev driver returns time and date
information.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_set_time( )
Example:
124
3.3.58. Sysdev_set_time( )
Syntax:
#include “sysdev.h”
int Sysdev_set_time ( TDateTime dt );
Description:
Sets the date and time of the system on the second boundary. Time values that
are less than a second are igored.
Parameters:
dt is the structure that holds the time and date values that are passed through
the sysdev driver to set the system’s time and date.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_get_time( )
Example:
125
3.3.59. Sysdev_get_sysClock( )
Syntax:
#include “sysdev.h”
int Sysdev_get_sysClock ( u_int32 *clock );
Description:
Gets the current interval value of the system clock which counts up and rolled
over.
Parameters:
clock is a pointer to the location where the Sysdev driver returns current
interval value of the system clock.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_get_time( )
Example:
126
3.3.60. Sysdev_get_sysClockResolution( )
Syntax:
#include “sysdev.h”
int Sysdev_get_sysClockResolution ( u_int32 *max_value, u_int32
*resolution, u_int32 *reserve );
Description:
Gets the current system clock interval resolution and the maximum interval
value of the system clock.
Parameters:
max_value is a pointer to the location where the Sysdev driver returns
maximum interval value of the system clock that the system can return.
resolution is a pointer to the location where the Sysdev driver returns
resolution of one interval of the system clock in nanoseconds.
reserve is a pointer to a reserved parameter. A NULL value can be passed to
indicate that the calling process do not need the return value.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_get_time( )
Example:
127
3.3.61. Sysdev_interrupt_service( )
Syntax:
#include “sysdev.h”
int Sysdev_interrupt_service ( u_int32 vector, u_int32 level, u_int32
stack_size, void (*function)(void *), void *func_argv, u_int32 priority );
Description:
Attaches an interrupt handling routine to the specified interrupt vector and
level.
Parameters:
vector is the interrupt vector or address that the function will handle interrupt.
level is the interrupt level or priority that the function will respond to the
interrupt.
stack_size is the specific stack size for the interrupt handler (function).
function is a pointer to the interrupt handler that will respond to the interrupt.
The routine takes a void pointer value and returns void. A null pointer
indicates to the device driver to detach the associated interrupt function from
the specified interrupt vector and level.
func_argv is a pointer to the context when its function is executed.
priority is the priority level of the function routine. The priority level of one
has the lowest system wide priority. The highest priority level can be obtained
from Sysdev_get_priority() function call. If the requested priority is higher
than the highest priority level of a system, the highest priority is assigned to
the interrupt handler.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_INVALID_HANDLE – an invalid System device handle is
used.
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Example:
128
3.3.62. Sysdev_interrupt_disable( )
Syntax:
#include “sysdev.h”
int Sysdev_interrupt_disable ( void );
Description:
Disables all interrupt at the processor level.
Parameters:
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
E_SYSDEV_NULL_POINTER – a null pointer is passed to the function.
Library:
sysdev.lib
See Also:
Sysdev_interrupt_enable()
Example:
129
3.3.63. Sysdev_interrupt_enable( )
Syntax:
#include “sysdev.h”
int Sysdev_interrupt_enable ( void );
Description:
Enables all interrupt at the processor level.
Parameters:
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SYSDEV_OS_ERROR – an operating system error has occurred.
Library:
sysdev.lib
See Also:
Sysdev_interrupt_disable()
Example:
130
3.3.64. SYSDEV.H
/*************************************************************
* MODULE :
sysdev.h
* VERSION:
3.0
* DATE: 06/01/98
* PROGRAMMER: George Chen
* PORTABILITY: ATC SYSTEM UNITS
*
* DESCRIPTION:
* This module is the header file for sysdev device driver
* library for the ATC.
*************************************************************/
#ifndef _SYSDEV_H_
#define _SYSDEV_H_
#ifdef __cplusplus
extern "C" {
#endif
#define SYSDEV_WRITE
#define SYSDEV_READ
0x01
0x02
typedef unsigned int TSysdev;
/* rtio handle */
typedef void (*function)(u_int32) TSys_callback;
typedef struct _TDateTime
{
unsigned short year; //* 1 – 65535
unsigned char month; //* 1 – 12
unsigned char day;
//* 1 – 31
unsigned char dow;
//* 1 - 7
unsigned char hour; //* 0 – 23
unsigned char minute;//* 0 – 59
unsigned char second;//* 0 – 59
unsigned short msecond;//* 0 – 999
unsigned char reserve[2];//*
} TDateTime, *PTDateTime;
Gregorian year
month-of-year
day-of-month
day-of-week 7=sunday
hour-of-day
minute-of-hour
second-of-minute
millisecond-of-second
2 byte reserved
typedef union _TEvent_attrib
{
struct {
u_int32 number;
u_int32 dummy[2];
unsigned char reserve[3];
unsigned char one_shot;//* 1=one shot; 0=multiple shot
} tag;
131
struct {
unsigned short year;
//* 1 – 65535 Gregorian year
//* 0 = don’t care
unsigned char month; //* 1 – 12
month-of-year
//* 0x80 = don’t care
unsigned char day;
//* 1 – 31
day-of-month
//* 0x80 = don’t care
unsigned char dow;
//* 1 - 7
day-of-week 7=Sunday
//* 0x80 = don’t care
unsigned char hour; //* 0 – 23
hour-of-day
//* 0x80 = don’t care
unsigned char minute;//* 0 – 59
minute-of-hour
//* 0x80 = don’t care
unsigned char second;//* 0 – 59
second-of-minute
//* 0x80 = don’t care
unsigned short msecond;//*0 – 999
millisecond-of-second
//* 0x8000 = don’t care
unsigned char reserve;//* reserved
unsigned char one_shot;//* 1=one; 0=multiple shot alarm
} alarm;
struct {
u_int32 msecond;
//* 0 – 0xffffffff millisecond counts
u_int32 second;
//* 0 – 0xffffffff second counts
u_int32 minute;
//* 0 – 0xffffffff minute counts
unsigned short hour; //* 0 – 0xffff hour counts
unsigned char reserve;//* reserve
unsigned one_shot;
//* 1=one; 0=multiple shot timer
} timer;
struct {
u_int32 number;
u_int32 dummy[2];
unsigned char reserve[3];
unsigned char one_shot;//* 1=one; 0=multiple shot
} powerdown;
} TEvent_attrib, *PTEvent_attrib;
int Sysdev_semaphore_create(TSysdev *phSysdev,
char *sema_name);
int Sysdev_semaphore_delete(TSysdev hSysdev);
int Sysdev_semaphore_wait(TSysdev hSysdev,
int timeout);
int Sysdev_semaphore_post(TSysdev hSysdev);
int Sysdev_sleep(u_int32 milliSeconds);
132
int Sysdev_pipe_create (TSysdev *phSysdev,
char *pipeName,
u_long size,
char *mode);
int Sysdev_pipe_delete (TSysdev hSysdev);
int Sysdev_pipe_read (TSysdev hSysdev,
unsigned char *buf,
u_long size,
u_long *sizeRead);
int Sysdev_pipe _read_timed(TSysdev hSysdev,
unsigned char *buf,
u_long size,
u_long *sizeRead,
u_long timeout);
int Sysdev_pipe_write (TSysdev hSysdev,
unsigned char *buf,
u_long size,
u_long *sizeWritten);
int Sysdev_pipe_dataready (TSysdev hSysdev,
unsigned long *psize);
//*
//** Extended Sysdev functions
//*
int Sysdev_mutex_create (TSysdev *phSysdev, char *mutex_name);
int Sysdev_mutex_delete (TSysdev hSysdev);
int Sysdev_mutex_acquire (TSysdev hSysdev, int timeout);
int Sysdev_mutex_release (TSysdev hSysdev);
int Sysdev_thread_create (TSysdev *phSysdev,
void (*function)(void *),
void *pVoid,
u_int32 stack,
int priority);
int Sysdev_thread_delete (TSysdev hSysdev);
int Sysdev_thread_start (TSysdev hSysdev);
int Sysdev_thread_stop (TSysdev hSysdev);
//* error codes
#define E_SYSDEV_GENERAL_FAILURE -1
typedef enum _E_SYSDEV_ENUM
133
{
E_SYSDEV_NULL_POINTER=20
,
E_SYSDEV_INVALID_ATTRIBUTE ,
E_SYSDEV_OUT OF_BUFFER
,
E_SYSDEV_READ_QUEUE_FULL
,
E_SYSDEV_HARDWARE_ERROR
,
E_SYSDEV_ALREADY_CLOSED
,
E_SYSDEV_BUFFER_TOO_LARGE ,
E_SYSDEV_WRITE_BUFFER_FULL ,
E_SYSDEV_OS_ERROR
,
E_SYSDEV_INVALID_DEVNAME
,
E_SYSDEV_INVALID_HANDLE
,
E_SYSDEV_WRITE_BUFFER_TOO_SMALL,
E_SYSDEV_INVALID_SIGNAL_NUMBER
} E_SYSDEV_ENUM;
#ifdef __cplusplus
}
#endif
#endif
134
3.4.
TEXT USER INTERFACE – LAYER 1 API
3.4.1. Overview
The Application Programming Interface (API) for the Text User Interface (TUI) is a set of C
functions used to access the Front Panel or Front Terminal of an Advanced Traffic Controller
(ATC). With the API, a program can read and write characters to and from the TUI. It can also
control the cursor position, set character display attributes, sense the auxiliary switch, and
compose user-defined characters.
135
3.4.2. Tuidev_open( )
Syntax:
#include “tuidev.h”
int Tuidev_open( char *dev_name, TTuidev *tuidev, int buf_size);
Description:
Opens and initializes a tui device for read/write operations.
Parameters:
dev_name is a pointer that specifies the device on which the TUI operates.
tuidev is a pointer to a device handle that is returned to be used by all other
function calls. tuidev is NULL if it is already open.
buf_size indicates the buffer size for internal use.
The above TUI constants are defined in tuidev.h.
Return Value:
E_TUI_NO_ERROR – if the tui can be opened successfully.
E_TUI_INVALID_DEV_NAME – if dev_name is incorrect.
E_TUI_OUT_OF_MEM – if the system does not have enough memory for
this operation.
E_TUI_ALREADY_OPEN – if tuidev is already open.
E_TUI_OS_ERROR – if there is an operating system error has occurred.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuidev.h
See Also:
Tuidev_close()
136
3.4.3. Tuidev_close( )
Syntax:
#include “tuidev.h”
int Tuidev_close( TTuidev tuidev);
Description:
Closes the tui device previously opened by Tuidev_open.
Parameters:
tuidev must be a valid device handle provided by Tuidev_open().
Return Value:
E_TUI_NO_ERROR – if the device can be closed successfully.
E_TUI_INVALID_HANDLE – if tuidev is an invalid handle.
E_TUI_NOT_OPEN – if the device was not opened.
The above constants are defined in tuidev.h
See Also:
Tuidev_open()
137
3.4.4. Tuidev_read_key( )
Syntax:
#include “tuidev.h”
int Tuidev_read_key( Ttuiman tuiman, TKey *key, TKeyStat *stat);
Description:
Reads a key from the TUI. key contains a two-byte key code consistent with
the PC BIOS key code. It does not wait until a key is pressed.
Parameters:
tuidev must be a valid device handle.
key is a pointer that contains the key code read from the TUI. If the user is
interested in only the keyboard status, then set key to null upon function entry.
Otherwise, it can hold one of the following:
0, 1, 2 ,3, 4, 6, 7, 8, 9, A, B, C, D, E, F,
TUI_UP,
TUI_DOWN,
TUI_LEFT,
TUI_RIGHT,
TUI_ESC,
TUI_PLUS,
TUI_MINUS,
TUI_YES,
TUI_NO,
TUI_DOT,
TUI_NEXT,
TUI_ENTER,
TUI_NONE
stat is a pointer that contains the keyboard status (i.e. RIGHT-SHIFT, LEFTSHIFT, CTRL). If the user is not interested in the keyboard status, set stat to
null upon function entry.
The above TUI constants are defined in tuidev.h.
Return Value:
E_TUI_NO_ERROR – if character can be read successfully.
E_TUI_INVALID_HANDLE – if tuidev is an invalid handle.
The above constants are defined in tuidev.h
See Also:
Tuidev_write_char(), Tuidev_write_buf(), Tuidev_write_str()
138
3.4.5. Tuidev_write_buf( )
Syntax:
#include “tuidev.h”
int Tuidev_write_buf( Ttuidev tuidev, wchar *buf, int num_bytes);
Description:
Writes num_bytes of unicode characters from a buffer to the TUI. If a
character within buf has been composed by Tuidev_comp_char(), the
composed character or bitmap will be written to the screen.
Parameters:
tuidev must be a valid device handle.
buf is a pointer that contains the data to be written. It does not have to be
null-terminated.
num_bytes of unicode data will be written regardless of whether buf contains
null characters or not.
Return Value:
E_TUI_NO_ERROR – if data can be written successfully.
E_TUI_INVALID_HANDLE – if tuidev is an invalid handle.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_write_str(), Tuidev_write_char(), Tuidev_read_key(),
Tuidev_comp_char()
139
3.4.6. Tuidev_write_char( )
Syntax:
#include “tuidev.h”
int Tuidev_write_char( TTuidev tuidev, wchar ch);
Description:
Writes a unicode character to the TUI. If ch has been composed by
Tuidev_comp_char(), the composed character or bitmap will be written to the
screen.
Parameters:
tuidev must be a valid device handle.
ch is a unicode character to be displayed.
Return Value:
E_TUI_NO_ERROR if the character can be written successfully.
E_TUI_INVALID_HANDLE if tuidev is an invalid handle.
The above constants are defined in tuidev.h.
See Also:
Tuidev_write_buf(), Tuidev_write_str(), Tuidev_read_key(),
Tuidev_comp_char()
140
3.4.7. Tuidev_write_str( )
Syntax:
#include “tuidev.h”
int Tuidev_write_str( TTuidev tuidev, wchar *str);
Description:
Writes a null-terminated unicode string to the TUI. If a character within str
has been composed by Tuidev_comp_char(), the composed character or
bitmap will be written to the screen.
Parameters:
tuidev must be a valid device handle.
str is a pointer to a null-terminated unicode string to be written.
Return Value:
E_TUI_NO_ERROR – if the string can be written successfully.
E_TUI_INVALID_HANDLE – if tuidev is an invalid handle.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_write_buf(), Tuidev_write_char(), Tuidev_read_key(),
Tuidev_comp_char()
141
3.4.8. Tuidev_put_cursor( )
Syntax:
#include “tuidev.h”
int Tuidev_put_cursor(TTuidev tuidev, int row, int col);
Description:
Put cursor within the Tui buffer with (1,1) as the upper-left-most position.
Parameters:
tuidev must be a valid device handle.
row indicates the row number.
col indicates the column number.
Return Value:
E_TUI_NO_ERROR – if cursor can be successfully placed at the requested
position.
E_TUI_INVALID_HANDLE – if tuidev is an invalid handle.
E_TUI_OUT_OF_RANGE – if row or col are out of range.
The above constants are defined in tuidev.h.
See Also:
Tuidev_get_cursor()
142
3.4.9. Tuidev_get_cursor( )
Syntax:
#include “tuidev.h”
int Tuidev_get_cursor(TTuidev tuidev, int *row, int *col);
Description:
Get cursor position within the user’s own Tui buffer using (1, 1) as the upperleft-most position
Parameters:
tuidev must be a valid device handle.
row is a pointer to the row number.
col is a pointer to the column number.
Return Value:
E_TUI_NO_ERROR – if cursor position can be returned successfully in row
and col.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_put_cursor()
143
3.4.10. Tuidev_init_buf( )
Syntax:
#include “tuidev.h”
int Tuidev_init_buf( TTuidev tuidev, wchar ch);
Description:
Initializes the TUI by setting the cursor to (1,1) at the upper-left-most position
and filling the entire screen with ch. Set ch to a SPACE (0x20) character for
clearing the buffer.
Parameters:
tuidev must be a valid device handle.
ch is used as the initialization character.
Return Value:
E_TUI_NO_ERROR – if the TUI buffer can be initialized successfully.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
The above constants are defined in tuidev.h.
See Also:
Tuidev_write_buf(), Tuidev_write_str(), Tuidev_write_char()
144
3.4.11. Tuidev_dataready( )
Syntax:
#include “tuidev.h”
int Tuidev_dataready(TTuidev tuidev, int *key_count);
Description:
Checks to see if the TUI has data.
Parameters:
tuidev must be a valid device handle.
key_count is a pointer that returns the number of keys ready for processing.
Zero indicates no keys in the buffer. This buffer shall hold at least 16 keys.
Return Value:
E_TUI_NO_ERROR – if function can be executed successfully.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_read_key()
145
3.4.12. Tuidev_set_attrib( )
Syntax:
#include “tuidev.h”
int Tuidev_set_attrib(TTuidev tuidev, int attrib, int state);
Description:
Sets the attribute of the TUI buffer to the specified state.
Parameters:
tuidev must be a valid device handle.
attrib can be one of the following:
TUI_AUTO_WRAP
TUI_AUTO_SCROLL
TUI_AUTO_REPEAT
TUI_CURSOR_DISP
TUI_BACKLIGHT
TUI_BLINK_CHAR
TUI_REVERSE_VIDEO
TUI_ITALIC
TUI_UNDERLINED
TUI_BOLD
TUI_NORMAL
state specifies the desired state. It can be either TUI_ON or TUI_OFF.
The above constants are defined in tuidev.h.
Return Value:
E_TUI_NO_ERROR – if mode can be set successfully.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
E_TUI_INVALID_ATTRIB – if attrib is not one of attributes listed above.
E_TUI_INVALID_STATE – if state is not either TUI_ON or TUI_OFF.
The above constants are defined in tuidev.h.
See Also:
Tuidev_get_attrib()
146
3.4.13. Tuidev_get_attrib( )
Syntax:
#include “tuidev.h”
int Tuidev_get_attrib(TTuidev tuidev, int attrib, int *state);
Description:
Gets the current state of the specified attribute of the TUI buffer.
Parameters:
tuidev must be a valid device handle.
attrib can be one of the following:
TUI_AUTO_WRAP
TUI_AUTO_SCROLL
TUI_AUTO_REPEAT
TUI_CURSOR_DISPLAY
TUI_BACKLIGHT
TUI_BLINK_CHAR
TUI_REVERSE_VIDEO
TUI_ITALIC
TUI_UNDERLINED
TUI_BOLD
state is a pointer to TUI_ON, TUI_OFF, or TUI_NOT_IMPLEMENTED.
The above constants are defined in tuidev.h.
Return Value:
E_TUI_NO_ERROR – if mode can be set successfully.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
E_TUI_INVALID_ATTRIB – if attrib is not one listed above.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_set_attrib()
147
3.4.14. Tuidev_get_status( )
Syntax:
#include “tuidev.h”
int Tuidev_get_status(TTuidev tuidev, int status, int *state);
Description:
Gets the status of the TUI.
Parameters:
tuidev must be a valid device handle.
status can be one of the following:
TUI_AUX_SWITCH
On function return, state contains one of the following:
TUI_ON if the desired status is on.
TUI_OFF if the desired status is off.
TUI_NULL if the desired status is not implemented in the TUI.
Return Value:
E_TUI_NO_ERROR – if status can be returned successfully.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_get_cursor()
148
3.4.15. Tuidev_comp_char( )
Syntax:
#include “tuidev.h”
int Tuidev_comp_char(TTuidev tuidev, wchar ch_id, unsigned char
*matrix, int num_bytes);
Description:
Composes special characters with a pixel matrix of 8 bits by num_bytes.
These bytes are arranged from left to right, with the least significant bit on the
bottom. If a composition already exists for the specified ch_id, the new
composition will preside.
Parameters:
tuidev must be a valid device handle.
ch_id is the unicode specified by the user and can also replace a standard
unicode character. ch_id of zero is not allowed.
matrix is a pointer that contains the num_bytes of bitmap of the composed
character. For example, a 5-byte matrix of {0xFE, 0x90, 0x90, 0x80, 0x80}
represents the letter ‘F’.
Return Value:
E_TUI_NO_ERROR – if status can be returned successfully.
E_TUI_INVALID_HANDLE – if tuidev is invalid.
E_TUI_INVALID_ID – if ch_id is zero.
E_TUI_COMP_CHAR_MAX – if the maximum number of composed
characters is reached.
E_TUI_NULL_POINTER – if a null pointer is passed to the function.
The above constants are defined in tuidev.h.
See Also:
Tuidev_write_char()
149
3.4.16. TUIDEV.H
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
E_TUI_NO_ERROR 0
E_TUI_OS_ERROR 1
E_TUI_NULL_POINTER
2
E_TUI_OUT_OF_MEM
3
E_TUI_OUT_OF_RANGE
4
E_TUI_ALREADY_OPEN
5
E_TUI_ALREADY_CLOSED 6
E_TUI_INVALID_DEV_NAME
E_TUI_INVALID_HANDLE 8
E_TUI_INVALID_ID
9
E_TUI_INVALID_ATTRIB 10
E_TUI_INVALID_STATE
11
7
typedef unsigned int TTuidev;
typedef u_int16 TKey;
typedef u_int16 TKeyStat;
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
TUI_COMP_CHAR_MAX
8
TUI_NONE
0x0000
TUI_UP
0x4800
TUI_DOWN 0x5100
TUI_LEFT 0x4B00
TUI_RIGHT 0x4D00
TUI_NEXT
0x5100
TUI_DOT
'*'
TUI_PLUS
'+'
TUI_MINUS
'-'
TUI_YES
0x1500
TUI_NO
0x3100
TUI_ESC
0x001B
TUI_ENTER
0x000D
#define
#define
#define
#define
#define
#define
#define
#define
TUI_MASK_RSHIFT 0x01
TUI_MASK_LSHIFT 0x02
TUI_MASK CTRL
0x04
TUI_MASK_ALT
0x08
TUI_MASK_SCROLL_LOCK
TUI_MASK_NUM_LOCK
TUI_MASK_CAPS_LOCK
TUI_MASK_INSERT 0x80
#define TUI_ON
#define TUI_OFF
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
0x10
0x20
0x40
1
0
TUI_AUTO_WRAP
1
TUI_AUTO_SCROLL 2
TUI_AUTO_REPEAT 3
TUI_CURSOR_DISP 4
TUI_BACKLIGHT
5
TUI_BLINK_CHAR 6
TUI_REVERSE_VIDEO
TUI_ITALIC
8
TUI_UNDERLINED 9
TUI_BOLD 10
7
150
#define TUI_AUX_SWITCH
11
151
4.
LAYER 2 API – Application Environment
4.1.
DISCRETE I/O DEVICE MANAGER – LAYER 2 API
4.1.1. Overview
This API has two layers of programming interfaces for user applications to communicate with a
Discrete I/O device on an ATC. Level one of the API defines the functional interface between an
ATC application and DIO device driver. The device driver and its accompanying source level
interface library is usually manufacturer dependent. Level two of the API defines the functional
interface between an ATC application and the Discrete I/O device manager. The DIO device
manager provides a subset of high level functions and a single access point to the Discrete I/O
device for all user applications.
152
4.1.2. Dioman_attach( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_attach ( u_int8 addr, TDioman *hDioman, u_int8 * moduleID );
Description:
Attaches the calling process to a valid Discrete I/O device on the target device
bus through the Discrete I/O device manager. Then it registers the calling
process to access the Discrete I/O resources and returns a handle for
subsequent access. Commands and requests made by the calling processes
will be directed to the attached Discrete I/O device.
Parameters:
addr is the address of the Discrete I/O device on the target device bus.
hDioman is a pointer to the handle that the Discrete I/O device manager
returns to the calling process.
moduleID is a pointer to the location where the function returns the Discrete
I/O device identification.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_ADDRESS – an invalid Discrete I/O device address
is used, or the Discrete I/O device is not present.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the Discrete I/O device.
E_DIOMAN_NOT_EXIST – the Discrete I/O device manager is not active.
E_DIOMAN_SLOT_FULL – no more attachable slot are available to the
calling process because too many calling processes have been linked with the
DIO manager.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
Dioman.lib
See Also:
Dioman_detach()
Example:
153
4.1.3. Dioman_detach( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_detach ( TDioman hDioman );
Description:
Detaches the calling process from the current Discrete I/O device on the
target device bus through the Discrete I/O device manager and de-registers
the calling process.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
Dioman.lib
See Also:
Dioman_attach()
Example:
154
4.1.4. Dioman_get_attrib( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_attrib ( TDioman hDioman, TDioman_attrib *fm_opts,
u_int32 *size );
Description:
Gets status of the current Discrete I/O device manager’s attribute table. This
function will return information to the user buffer for inspection. The
TDioman_attrib structure is described in the DIOMAN.H header file.
Parameters:
fm_opts is a pointer to the user TDioman_attrib structure.
size is a pointer to the location where the size of the user buffer is stored. The
function returns the actual size of manager’s attribute table. If the size of user
buffer is smaller than the driver’s attribute table, the function returns an error
and the actual size of the attribute table.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_OUTOF_BUFFER – the user buffer size is too small.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_INVALID_ATTRIBUTE – an invalid attribute is used in the
Discrete I/O device manager’s attribute table. No attribute is set.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_set_opts()
Example:
155
4.1.5. Dioman_set_attrib( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_set_attrib ( TDioman hDioman, TDioman_attrib *fm_opts,
u_int32 size );
Description:
Sets status of the current Discrete I/O device manager’s attribute table. This
function will copy information from the user buffer to the Discrete I/O device
manager’s attribute table. The TDioman_attrib structure is described in the
DIOMAN.H header file.
Parameters:
fm_opts is a pointer to the user TDioman_attrib structure.
size is the size of the DIO manager’s attribute table.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_ATTRIBUTE – an invalid attribute is used in the
Discrete I/O device manager’s attribute table. No attribute is set.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_opts()
Example:
156
4.1.6. Dioman_reg_inputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_reg_inputs ( TDioman hDioman, u_int8 *inp_data,
TDio_callback function, u_int32 func_tag );
Description:
Registers all inputs that the calling process requested for monitoring to the
Discrete I/O device manager’s monitor table. The Discrete I/O device
manager will invoke the callback function in the user’s process space and
time-slice when one or more monitoring input states change. The same calling
process can register multiple inputs and callback functions.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inp_data is a pointer to the user input registration buffer that the calling
process requests for monitoring. An ON bit in the inp_data buffer indicates
that the corresponding input is to be monitored. The size of the inp_data
buffer is defined by the type of Discrete I/O device.
function is a pointer to a callback function to be run when the any one of the
registered input state changes. The routine takes a single u_int32 value and
returns void.
func_tag is the tag to be returned to the calling process when its call-back
function is executed.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
157
E_DIOMAN_INVALID_TAG – an invalid tag is used for tag notification.
The tag is reserved for system functions.
Library:
Dioman.lib
See Also:
Dioman_inputs(), Dioman_get_inputs(), Dioman_dereg_inputs()
Example:
158
4.1.7. Dioman_dereg_inputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_dereg_inputs ( TDioman hDioman, u_int8 *inp_data );
Description:
De-registers the input number from the Discrete I/O device manager’s
monitoring input table.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inp_data is a pointer to the user input registration buffer that the calling
process requests for monitoring. An ON bit in the inp_data buffer indicates
that monitor of that input bit is to be removed. The size of the inp_data buffer
is defined by the type of Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_reg_inputs(), Dioman_inputs(), Dioman_get_inputs()
Example:
159
4.1.8. Dioman_reg_outputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_reg_outputs ( TDioman hDioman, u_int8 *out_data );
Description:
Registers all the output bits in the out_data buffer for control by the calling
process to the Discrete I/O device manager’s output table on a first-comefirst-serve basis. All calling processes must issue this request to obtain
exclusive control of the requested output. Once the registration of the output
control is successful, the calling process will have exclusive control of that
output state. A subsequent request appends the previous registration by that
process. If one or more requested outputs are taken by another process, no
outputs are registered and the function returns the taken outputs.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
out_data is a pointer to the output registration buffer that the calling process
requests for exclusive control. An ON bit in the out_data buffer indicates the
request of that output bit. If an E_DIOMAN_OUTPUT_TAKEN error is
returned, the manager returns all the taken output bits to the user buffer, and
an ON bit in the returned out_data buffer indicates that corresponding output
bit is not allowed. The size of the out_data buffer is defined by the type of
Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_OUTPUT_TAKEN – control of one or all output numbers
requested by calling process is not allowed because another process has taken
control of requested outputs.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
160
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_dereg_outputs(), Dioman_outputs(), Dioman_set_outputs()
Example:
161
4.1.9. Dioman_dereg_outputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_dereg_outputs ( TDioman hDioman, u_int8 *out_data );
Description:
De-registers control of all the output numbers in the out_data buffer from the
Discrete I/O device manager’s output mask control. User process still has
control over outputs that are previously registered, but not de-registered by
this function call.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
out_data is a pointer to user output registration buffer that the calling process
requests to release control. An ON bit in the out_data buffer removes the
control of that output bit. The size of the out_data buffer is defined by the
type of Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
E_DIOMAN_OUTPUT_NOTREGISTERED - the calling process did not
register control of one or more outputs.
Library:
Dioman.lib
See Also:
Dioman_reg_outputs(), Dioman_outputs(), Dioman_set_outputs()
Example:
162
4.1.10. Dioman_get_outputReg( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_outputReg ( TDioman hDioman, u_int8 *out_data );
Description:
Gets all outputs that are currently registered in the Discrete I/O device
manager’s output mask control table.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
out_data is a pointer to user buffer that the function returns the current
registered outputs. An ON bit in the out_data buffer indicates the output has
been registered. The size of the out_data buffer is defined by the type of
Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_reg_outputs(), Dioman_outputs(), Dioman_set_outputs()
Example:
163
4.1.11. Dioman_inputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_inputs ( TDioman hDioman, u_int8 *data_ptr u_int32
*timestamp );
Description:
Gets the current content of the Discrete I/O device manager’s input buffer.
The input buffers hold the input states of the Discrete I/O device in the
previous polling interval.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
data_ptr is a pointer to the user data buffer. The size of the data_ptr buffer is
defined by the type of Discrete I/O device.
timestamp is a pointer to the time stamp value of the Discrete I/O device’s
millisecond counter associated with the requested input. It is the time stamp
of the last poll by the Discrete I/O device manager.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_inputs(), Dioman_reg_inputs(), Dioman_dereg_inputs()
Example:
164
4.1.12. Dioman_input( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_input ( TDioman hDioman, u_int8 inp_num, u_int8 *inp_state,
u_int32 *timestamp);
Description:
Gets the current state of an input number from the Discrete I/O device
manager’s buffer. The input buffers hold the input states of the Discrete I/O
device polled in the previous polling interval.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inp_num is the requested input number for the input state.
inp_state is a pointer to the user buffer that returns the ON or OFF state of the
requested input.
timestamp is a pointer to the time stamp value of the Discrete I/O device’s
millisecond counter associated with the requested input. It is the time stamp
of the last poll by the Discrete I/O device manager.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
E_DIOMAN_INVALID_INPUT – the input number is not valid for this
Discrete I/O device.
Library:
Dioman.lib
See Also:
Dioman_get_inputs(), Dioman_reg_inputs(), Dioman_dereg_inputs()
165
Example:
166
4.1.13. Dioman_filterInputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_filterInputs ( TDioman hDioman, u_int8 *data_ptr );
Description:
Gets the current content of the Discrete I/O device manager’s filtered input
buffer. The filtered input buffers hold the input states of the Discrete I/O
device polled in the previous polling interval.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
data_ptr is a pointer to the user data buffer. The size of the data_ptr buffer is
defined by the type of Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_filterInputs(), Dioman_reg_inputs(), Dioman_dereg_inputs()
Example:
167
4.1.14. Dioman_filterInput( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_filterInput ( TDioman hDioman, u_int8 inp_num, u_int8
*inp_state, u_int32 *timestamp);
Description:
Gets the current state of a filtered input from the Discrete I/O device
manager’s filtered input buffer. The input buffers hold the filtered input states
of the Discrete I/O device polled in the previous polling interval.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inp_num is the requested input number for the input state.
inp_state is a pointer to the user buffer that returns the ON or OFF state of the
requested filtered input.
timestamp is a pointer to the time stamp value of the Discrete I/O device’s
millisecond counter associated with the requested input. It is the time stamp
of the last poll by the Discrete I/O device manager.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_filterInputs(), Dioman_reg_inputs(), Dioman_dereg_inputs()
Example:
168
4.1.15. Dioman_get_outputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_outputs ( TDioman hDioman, u_int8 *data_ptr, u_int8
*ctrl_ptr );
Description:
Gets the current content of the Discrete I/O device manager’s output buffer.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
data_ptr is a pointer to the user’s output data buffer. The size of the buffer is
defined by the type of Discrete I/O device.
ctrl_ptr is a pointer to the user’s output control function buffer. The size of
the buffer is defined by the type of Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_inputs(), Dioman_get_inputs(), Dioman_set_outputs()
Example:
169
4.1.16. Dioman_outputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_outputs ( TDioman hDioman, u_int8 *data_ptr, u_int8
*ctrl_ptr );
Description:
Sets the content of the Discrete I/O device manager’s output buffer. The new
output state will be set in the next Discrete I/O device manager’s set output
interval. The manager masks off all non-registered output bits of the calling
process.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
data_ptr is a pointer to the user’s output data buffer. The size of the buffer is
defined by the type of Discrete I/O device.
ctrl_ptr is a pointer to the user’s output control function buffer. The size of
the buffer is defined by the type of Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_inputs(), Dioman_get_inputs(), Dioman_set_outputs()
Example:
170
4.1.17. Dioman_output( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_output ( TDioman hDioman, u_int8 out_num, u_int8 out_state,
u_int8 ctrl_state );
Description:
Set the specified output state of the Discrete I/O device manager’s output
buffer. The new output states will be set in the next Set Outputs command of
Discrete I/O device manager.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
out_num is the requested output number.
out_state is the requested output state.
ctrl_state is the requested output control state.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_OUTPUT_NOTREGISTERED - the calling process did not
register control of this output.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_inputs(), Dioman_get_inputs(), Dioman_set_outputs()
Example:
171
4.1.18. Dioman_inpTransBuf( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_inpTransBuf ( TDioman hDioman, TDio_inpTransBuf
*inptsbuf );
Description:
Gets a completed record of the processed input transition buffer information
from the Discrete I/O device manager’s buffer.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inptsbuf is a pointer to the user TDio_inpTransBuf structure where
processed transition data is stored. The timestamp information in the structure
is the value of the millisecond counter in the Discrete I/O device.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_inpTransBuf()
Example:
172
4.1.19. Dioman_inpTrans( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_inpTrans ( TDioman hDioman, u_int8 inp_num, u_int8
block_num, TDio_inpTransBuf_item *inptsbuf_item, u_int16 *num_item,
TDio_inpTransBuf_status *status);
Description:
Gets the requested input transition information from Discrete I/O device
manager’s buffer. All input transitions associated with that input and block
are returned to the calling process.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inp_num is the requested input number for the input transition.
block_num is the input transition block that the calling process requests.
inptsbuf_item is a pointer to the first of user’s TDio_inptsbuf_item buffers
where processed transition data is returned. If the user buffer is less than the
input transitions that the Discrete I/O device manager recorded, the user
buffer is filled, and an error is returned. The timestamp information in the
structure is the value of the millisecond counter in the Field I /O module.
num_item is a pointer to the location where the number of
TDio_inpTransBuf_item(s) are passed. The calling process passes the
number of TDio_inpTransBuf_item(s) indicating the size of its buffer. The
Discrete I/O device manager passes back the number of
TDio_inpTransBuf_item(s) associated with the requested input number. A
zero value of num_item indicates no more transition data is available.
status is a pointer to the location where the current status of the input
transition buffer of the Discrete I/O device. The TDio_inpTransBuf_status
information is described in the DIOTYPE.H header file.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_NO_TRANS_BLOCK – the requested input transition block is
not available from the manager’s buffer.
173
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_inpTrans(), Dioman_getInpTransBuf()
Example:
174
4.1.20. Dioman_modStatus( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_modStatus ( TDioman hDioman, TDio_modStatus_status
*modstatus, u_int32 *timestamp );
Description:
Gets Discrete I/O device status from Discrete I/O device manager’s buffer.
Information is stored from the previous poll by the Discrete I/O device
manager.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
modstatus is a pointer to the Discrete I/O device status byte. The Discrete I/O
device manager re-sets the status byte of the Discrete I/O device status and
returns the updated module status in the TDio_modStatus_status structure.
timestamp is a pointer to the location where the time stamp value of the
Discrete I/O device’s millisecond counter is passed.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_modStatus()
Example:
175
4.1.21. Dioman_cabinetID( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_cabinetID ( TDioman hDioman, TDio_cabinetID_data *cabid
);
Description:
Gets the cabinet identification from the Discrete I/O device manager’s buffer.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
cabid is a pointer to the TDio_cabinetID_data union that the cabinet
identification is returned.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_DATAKEY_NOTPRESENT – the cabinet identification
returned is not valid because the cabinet key is not present.
E_DIOMAN_DATAKEY_ERROR – the cabinet identification returned is not
valid because of a cabinet key error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_get_cabinetID()
Example:
176
4.1.22. Dioman_get_inputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_inputs ( TDioman hDioman, TDio_inputs *inputs,
TDio_callback function, u_int32 func_tag );
Description:
Gets current Discrete I/O device input state of all inputs and notifies the
calling process when data is ready to be inspected.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inputs is a pointer to the TDio_inputs structure.
function is a pointer to a callback function to be executed when data is ready
for user inspection. The routine takes a single u_int32 value and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the calling process is blocked until Discrete I/O device manager retrieves
all data from the Discrete I/O device. A value of negative one for func_tag
indicates that data in the buffer Discrete I/O device manager’s buffer is
returned.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
177
Library:
Dioman.lib
See Also:
Dioman_set_outputs(), Dioman_inputs(), Dioman_outputs()
Example:
178
4.1.23. Dioman_get_filterInputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_filterInputs ( TDioman hDioman, TDio_filterInputs
*finputs, TDio_callback function, u_int32 func_tag );
Description:
Gets Discrete I/O device’s filtered inputs and notifies the calling process
when data is ready to be inspected.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
finputs is a pointer to the TDio_filterInputs structure.
function is a pointer to a callback function to be executed when data is ready
for user inspection. The routine takes a single u_int32 value and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the calling process is blocked until Discrete I/O device manager retrieves
all data from the Discrete I/O device. A value of negative one for func_tag
indicates that data in the buffer Discrete I/O device manager’s buffer is
returned.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
179
Library:
Dioman.lib
See Also:
Dioman_get_inputs(), Dioman_inputs()
Example:
180
4.1.24. Dioman_set_outputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_set_outputs ( TDioman hDioman, TDio_outputs *outputs,
TDio_callback function, u_int32 func_tag );
Description:
Sets the outputs to the Discrete I/O device and notifies the calling process
when operation is completed. The Discrete I/O device manager masks out all
non-registered outputs and combines the registered outputs with other outputs.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
outputs is a pointer to the TDio_outputs structure.
function is a pointer to a callback function to be executed when set outputs
command is completed. The routine takes a single u_int32 value and returns
void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the Discrete I/O device manager immediately send the data to the
Discrete I/O device, and no completion notification is needed. If a value of
negative one for func_tag is passed, this function only changes the data in the
buffer Discrete I/O device manager’s buffer, and the new data is sent to the
Discrete I/O device in the next periodic set command of Discrete I/O device
manager.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
181
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
E_DIOMAN_OUTPUT_NOTREGISTERED - the calling process did not
register control of one or more outputs.
Library:
Dioman.lib
See Also:
Dioman_outputs(), Dioman_reg_outputs(), Dioman_dereg_outputs
Example:
182
4.1.25. Dioman_get_inpTransBuf( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_inpTransBuf ( TDioman hDioman, TDio_inpTransBuf
*inptsbuf, TDio_callback function, u_int32 func_tag );
Description:
Gets the complete contents of the input transition buffer from the Discrete I/O
device and notifies the calling process when data is ready to be inspected. The
information in the structure has been processed by Discrete I/O device
manager.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
inptsbuf is a pointer to the TDio_inpTransBuf structure where processed
transition data is stored. The timestamp information in the structure is the true
4-byte length time stamp of the millisecond counter in the Discrete I/O
device.
function is a pointer to a callback function to be executed when data is ready
for user inspection. The routine takes a single u_int32 value and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the calling process is blocked until Discrete I/O device manager retrieves
all data from the Discrete I/O device. A value of negative one for func_tag
indicates that data in the buffer Discrete I/O device manager’s buffer is
returned.
Return Value:
On success, it returns 0. Otherwise, it returns an operating system error has
occurred.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
183
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_inpTransBuf()
Example:
184
4.1.26. Dioman_get_modStatus( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_modStatus ( TDioman hDioman, TDio_modStatus
*modstatus, TDio_callback function, u_int32 func_tag );
Description:
Gets Discrete I/O device status from the Discrete I/O device.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
modstatus is a pointer to the TDio_modStatus structure.
function is a pointer to a callback function to be executed when data is ready
for user inspection. The routine takes a single u_int32 value and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the calling process is blocked until Discrete I/O device manager retrieves
all data from the Discrete I/O device. A value of negative one for func_tag
indicates that data in the buffer Discrete I/O device manager’s buffer is
returned.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
185
Library:
Dioman.lib
See Also:
Example:
186
4.1.27. Dioman_get_cabinetID( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_cabinetID ( TDioman hDioman, TDio_cabinetID *cabid,
TDio_callback function, u_int32 func_tag );
Description:
Gets the cabinet identification from the Discrete I/O device and notifies the
calling process when data is ready to be inspected.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
cabid is a pointer to the TDio_cabinetID structure.
function is a pointer to a callback function to be executed when data is ready
for user inspection. The routine takes a single u_int32 value and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the calling process is blocked until Discrete I/O device manager retrieves
all data from the Discrete I/O device. A value of negative one for func_tag
indicates that data in the buffer Discrete I/O device manager’s buffer is
returned.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
187
Library:
Dioman.lib
See Also:
Dioman_get_moduleID()
Example:
188
4.1.28. Dioman_get_moduleID( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_get_moduleID ( TDioman hDioman, u_int32 *modid,
TDio_callback function, u_int32 func_tag );
Description:
Gets the Discrete I/O device identification and notifies the calling process
when data is ready to be inspected.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
modid is a pointer to the TDio_moduleID structure.
function is a pointer to a callback function to be executed when data is ready
for user inspection. The routine takes a single u_int32 value and returns void.
func_tag is the tag to be returned to the calling process when its callback
function is invoked.
Note: If a null function pointer is passed, a zero value of func_tag indicates
that the calling process is blocked until Discrete I/O device manager retrieves
all data from the Discrete I/O device. A value of negative one for func_tag
indicates that data in the buffer Discrete I/O device manager’s buffer is
returned.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
189
Library:
Dioman.lib
See Also:
Dioman_get_cabinetID()
Example:
190
4.1.29. Dioman_cfg_msCounter( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_cfg_msCounter ( TDioman hDioman, u_int32 milcnt );
Description:
Configures Discrete I/O device’s milliseconds counter to the user-specified
value. The calling process is blocked until configuration is completed.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
milcnt is the value of the millisecond counter.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_CONFIG_ERROR – configuration failed.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED – the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Example:
191
4.1.30. Dioman_cfg_inputs( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_cfg_inputs ( TDioman hDioman, TDio_cfgInp *cfgInp );
Description:
Configures input filter function of multiple Discrete I/O device inputs
specified in the TDio_cfgInp structure. No registration of input request is
done with this function call. The calling process is blocked until configuration
is completed.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
cfgInp is a pointer to the TDio_cfgInp structure. The TDio_cfgInp data
structure is described in the DIOTYPE.H header file.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_CONFIG_ERROR – configuration failed.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Dioman_cfg_input()
Example:
192
4.1.31. Dioman_cfg_inpTracking( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_cfg_inputTracking ( TDioman hDioman, TDio_inpTracking
*cfgInptrk );
Description:
Configures multiple input tracking functions of the Discrete I/O device. The
calling process is blocked until configuration is completed.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
cfgInptrk is a pointer to the TDio_inpTracking structure.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes;
E_DIOMAN_CONFIG_ERROR – configuration failed.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
E_DIOMAN_OUTPUT_NOTREGISTERED - the calling process did not
register control of one or more outputs.
Library:
Dioman.lib
See Also:
Example:
193
4.1.32. Dioman_cfg_cpxOut( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_cfg_cpxOut ( TDioman hDioman, TDio_cpxOut *cfgCpxout );
Description:
Configures complex outputs of the Discrete I/O device. The calling process is
blocked until configuration is completed.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
cfgCpxout is a pointer to the TDio_cpxOut structure.
Return Value:
On success, it returns a zero; otherwise it returns an error.
E_DIOMAN_CONFIG_ERROR – configuration failed.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
E_DIOMAN_OUTPUT_NOTREGISTERED - the calling process did not
register control of one or more outputs.
Library:
Dioman.lib
See Also:
Example:
194
4.1.33. Dioman_cfg_watchDog( )
Syntax:
#include “Dioman.h”
#include “Diotype.h”
int Dioman_cfg_watchDog ( TDioman hDioman, u_int32 timeout );
Description:
Configures the watch dog timer of the Discrete I/O device.
Parameters:
hDioman is the handle to the attached Discrete I/O device on the target device
bus.
timeout is the timeout value of the Discrete I/O device watch dog.
Return Value:
On success, it returns a zero; otherwise it returns an error.
Error codes:
E_DIOMAN_CONFIG_ERROR – configuration of watchdog timeout timer
failed.
E_DIOMAN_INVALID_HANDLE – an invalid Discrete I/O device handle is
used.
E_DIOMAN_DEVICE_FAILED – the Discrete I/O device manager
encounters a general device failure of the attached Discrete I/O device with
this hDioman.
E_DIOMAN_OS_ERROR – an operating system error has occurred.
E_DIOMAN_STATUS – an error flag or error flags are returned in the status
value of the return structure.
E_DIOMAN_NULL_POINTER – a null pointer is passed to the function.
E_DIOMAN_NOTSUPPORTED - the target device does not support this
feature. No valid data is returned by this function.
Library:
Dioman.lib
See Also:
Example:
195
4.1.34. DIOMAN.H
/***************************************************************************
* MODULE
: Dioman.h
* VERSION
: 1.2
* DATE
: 12/01/95
* PROGRAMMER: George Chen
* REVIEWER 1:
* REVIEWER 2:
* PORTABILITY:
*
* DESCRIPTION:
* This module is responsible for managing the discrete I/O port.
*
*
**************************************************************************/
#ifndef _DIOMAN_H_
#define _DIOMAN_H_
#include “Diotype.h”
typedef unsigned int TDioman;
/* DIOMAN data module options for
typedef struct {
int
reserve
:26;
int
master
:1;
int
sync_io
:1;
int
packet
:1;
int
duplex_mode:1;
int
sort_intsbuf:1;
int
signull_blk:1;
int
sig_intvl;
int
sta_intvl;
int
tsbuf_intvl;
(1/sec)*/
} TDioman_attrib;
DIO manager operations */
/* reserve bits */
/* master mode (default) */
/* synchronized write and read for path */
/*
/*
/*
/*
/*
/*
0=HalfFullDuplex(def); 1=Full Duplex */
0=no sort(def), 1=sort inpTransBuf */
0=no block(def), 1=signull block */
dio I/O poll interval (10/sec) */
dio modstatus poll interval (1/sec) */
transition buffer poll interval
/***************************************************************************
* Dioman Function Prototypes
**************************************************************************/
int Dioman_attach ( u_int8 addr,
TDioman *hDioman,
u_int8 * moduleID );
int Dioman_detach ( TDioman hDioman );
int Dioman_get_attrib ( TDioman hDioman,
TDioman_attrib *fm_opts,
u_int32 *size );
int Dioman_set_attrib ( TDioman hDioman,
TDioman_attrib *fm_opts,
u_int32 size );
196
int Dioman_reg_inputs ( TDioman hDioman,
u_int8 *inp_data,
TDio_callback function,
u_int32 func_tag );
int Dioman_dereg_inputs ( TDioman hDioman,
u_int8 *inp_data );
int Dioman_reg_outputs ( TDioman hDioman,
u_int8 *out_data );
int Dioman_dereg_outputs ( TDioman hDioman,
u_int8 *out_data );
int Dioman_get_outputReg ( TDioman hDioman,
u_int8 *out_data );
int Dioman_inputs ( TDioman hDioman,
u_int8 *data_ptr );
int Dioman_input ( TDioman hDioman,
u_int8 inp_num,
u_int8 *inp_state,
u_int32 *timestamp);
int Dioman_filterInputs ( TDioman hDioman,
u_int8 *data_ptr );
int Dioman_filterInput ( TDioman hDioman,
u_int8 inp_num,
u_int8 *inp_state,
u_int32 *timestamp);
int Dioman_outputs ( TDioman hDioman,
u_int8 *data_ptr,
u_int8 *ctrl_ptr );
int Dioman_output ( TDioman hDioman,
u_int8 out_num,
u_int8 out_state,
u_int8 ctrl_state );
int Dioman_inpTransBuf ( TDioman hDioman,
TDio_inpTransBuf_rsp *inptsbuf );
int Dioman_inpTrans ( TDioman hDioman,
u_int8 inp_num,
TInpTransBuf_item *inptsbuf_item,
u_int16 *num_item,
u_int8 *block_num,
TInpTransBuf_status_bits *status);
int Dioman_modStatus ( TDioman hDioman,
TModStatus_status_bits *modstatus,
u_int32 *timestamp );
int Dioman_cabinetID ( TDioman hDioman,
197
TCabinetID_data *cabid );
int Dioman_moduleID ( TDioman hDioman,
u_int8 *modid );
int Dioman_get_modStatus ( TDioman hDioman,
TDio_modStatus *modstatus,
TDio_callback function,
u_int32 func_tag );
int Dioman_get_inputs ( TDioman hDioman,
TDio_inputs *inputs,
TDio_callback function,
u_int32 func_tag );
int Dioman_get_filterInputs ( TDioman hDioman,
TDio_filterInputs *finputs,
TDio_callback function,
u_int32 func_tag );
int Dioman_set_outputs ( TDioman hDioman,
TDio_outputs *outputs,
TDio_callback function,
u_int32 func_tag );
int Dioman_get_inpTransBuf ( TDioman hDioman,
TDio_inpTransBuf *inptsbuf,
TDio_callback function,
u_int32 func_tag );
int Dioman_get_cabinetID ( TDioman hDioman,
TDio_cabinetID *cabid,
TDio_callback function,
u_int32 func_tag );
int Dioman_get_moduleID ( TDioman hDioman,
TDio_moduleID *modid,
TDio_callback function,
u_int32 func_tag );
int Dioman_cfg_msCounter ( TDioman hDioman,
u_int32 milcnt );
int Dioman_cfg_inputs ( TDioman hDioman,
TDio_cfgInp *cfginp );
int Dioman_cfg_inputTracking ( TDio hDioman,
TDio_inpTracking *cfgInptrk );
int Dioman_cfg_cpxOut ( TDioman hDioman,
TDio_cpxOut *cfgCpxout );
int Dioman_cfg_watchDog ( TDioman hDioman,
u_int32 timeout );
/* DIOMAN Error Codes */
typedef enum
198
{
E_DIOMAN_INVALID_ADDRESS=2100
E_DIOMAN_INVALID_ATTRIBUTE
E_DIOMAN_INVALID_HANDLE
E_DIOMAN_DEVICE_FAILED
E_DIOMAN_NOT_EXIST
E_DIOMAN_OUTPUT_TAKEN
E_DIOMAN_NO_TRANS_BLOCK
E_DIOMAN_DATAKEY_NOTPRESENT
E_DIOMAN_DATAKEY_ERROR
E_DIOMAN_SLOT_FULL
E_DIOMAN_OUTOF_BUFFER
E_DIOMAN_OS_ERROR
E_DIOMAN_NOTSUPPORTED
E_DIOMAN_NOTREGISTERED
E_DIOMAN_CONFIG_ERROR
E_DIOMAN_NULL_POINTER
} _E_DIOMAN_ENUM;
#endif
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
199
4.2.
SERIAL COMMUNICATIONS PORT MANAGER – LAYER 2 API
4.2.1. Overview
This API has two layers of programming interfaces for user applications to communicate with a
Serial Communications Port device on an ATC. Level one of the API defines the functional
interface between an ATC application and SCP device driver. The device driver and its
accompanying source level interface library are usually manufacturer dependent. Layer 2 two of
the API defines the functional interface between an ATC application and the SCP device
manager. The SCP device manager provides a subset of high level functions and a single access
point to the SCP devices for all user applications. It allows multiple calling processes to share the
same resource in an Advanced Transportation Controller (ATC) and manages at least four serial
communications ports. The SCP device manager permits each calling process to have either
shared or exclusive accesses to the communications resources. The calling process can configure
the communications devices through the SCP manger. The SCP device manager provides calling
process services such as automatic hardware handshaking handling, read-write function paring
and blocked or non-blocked read or writes functions for each communications resource.
200
4.2.2. Scpman_attach( )
Syntax:
#include “scpman.h”
int Scpman_attach ( char *devname, TScpman *hScpman, int exclusive );
Description:
Attaches to a serial port through the Serial Communications Port (SCP)
manager, which returns a Scpman handle to the calling process.
Parameters:
devname is the character pointer to the null-terminated serial port device
name.
hScpman is a pointer to the Scpman handle that SCP device manager assigns
the port.
exclusive is the value indicating whether exclusive control of the serial port is
desired. A value of zero indicates that a non-exclusive control is requested,
and a value of one indicates that an exclusive control is requested.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other error codes:
E_SCPMAN_NOT_EXIST – the SCP device manager is not active.
E_SCPMAN_INVALID_DEVNAME – if devname is incorrect
E_SCPMAN_EXCLUSIVE_FAIL – the calling process can not gain
exclusive control of the serial port. Other calling process(s) have shared
control of the serial port.
E_SCPMAN_EXCLUSIVE_OCCUPIED – one process has gained exclusive
control of the serial port. No other process can control this serial port.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_detach()
Example:
201
4.2.3. Scpman_detach( )
Syntax:
#include “scpman.h”
int Scpman_detach ( TScpman hScpman );
Description:
Detaches from the Serial Communications Port (SCP). The SCP device
manager reduces the link count by one. If the link count is equal to zero, the
SCP device manager will flush and close the serial communications port.
Parameters:
hScpman is the handle that SCP device manager assigns the port handle
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_ALREADY_CLOSED – if the device was already closed by
this function.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_attach()
Example:
202
4.2.4. Scpman_read( )
Syntax:
#include “scpman.h”
int Scpman_read ( TScpman hScpman, u_int8 *readbuf, u_int32 size,
u_int32 *sizeRead );
Description:
Reads a number of bytes from the serial port through the Serial
Communications Port (SCP) manager to the user buffer.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
readbuf is a pointer to the buffer that serial data is being stored.
size is the number of bytes to be read from the serial communications port.
sizeRead is a pointer to a location where the manager returns the number of
bytes that are read.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_READ_QUEUE_FULL the read queue of the SCP device
manager is full.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_HARDWARE_ERROR – hardware related error.
E_SCPMAN_INVALID_TAG_NUMBER – an invalid signal number is
used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_read_timed(), Scpman_write().
Example:
203
4.2.5. Scpman_read_timed( )
Syntax:
#include “scpman.h”
int Scpman_read_timed ( TScpman hScpman, u_int8 *readbuf, u_int32 size,
u_int32 *sizeRead, u_int32 timeout );
Description:
Reads a number of bytes from the serial port through the Serial
Communications Port (SCP) manager to the user buffer within a specified
time.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
readbuf is a pointer to the buffer that serial data is being stored.
size is the number of bytes to be read from the serial communications port.
sizeRead is a pointer to the number of bytes to be read from the serial
communications port. The SCP device manager will not notify calling process
until all data requested has arrived or time has expired. The number of bytes
read before time has expired is returned.
timeout is the timeout value in milliseconds that the SCP device driver must
complete the read operation. The value may be rounded up to the nearest
system tick, if the operating system’s timer resolution is lower than the value
requested. If timeout is zero, the read operation will not timeout. The function
shall block calling process until either the number bytes specified in size are
read or time specified in timeout has expired.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_READ_QUEUE_FULL – the read queue of the SCP device
manager is full.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_HARDWARE_ERROR – hardware related error.
E_SCPMAN_INVALID_SIGNAL_NUMBER – an invalid signal number is
used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
204
Library:
scpman.lib
See Also:
Scpman_read(), Scpman_write()
Example:
205
4.2.6. Scpman_read_callback( )
Syntax:
#include “scpman.h”
int Scpman_read_callback ( TScpman hScpman, u_int8 *readbuf, u_int32
size, TScp_callback function,, u_int32 func_tag );
Description:
Reads a number of bytes from the serial port through the Serial
Communications Port (SCP) manager to the user buffer and invoke the
callback function in calling process space when the read function is
completed.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
readbuf is a pointer to the buffer that serial data is being stored.
size is the number of bytes to be read from the serial communications port.
The SCP device manager will not notify calling process until all data
requested has arrived.
function is a pointer to a callback function to be executed when the number
bytes specified in size are read. The routine takes a single u_int32 value and
returns void. A null pointer informs the SCP device driver not to invoke any
callback function.
func_tag is the tag to be returned to the calling process when its callback
function is executed.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_READ_QUEUE_FULL – the read queue of the SCP device
manager is full.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_HARDWARE_ERROR – hardware related error.
E_SCPMAN_INVALID_SIGNAL_NUMBER – an invalid signal number is
used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
206
Library:
scpman.lib
See Also:
Scpman_read(), Scpman_write()
Example:
207
4.2.7. Scpman_write( )
Syntax:
#include “scpman.h”
int Scpman_write ( TScpman hScpman, u_int8 *writebuf, u_int32 size);
Description:
Writes a number of bytes to the serial communications port through the Serial
Communications Port (SCP) manager. If hardware handshaking function is
enabled through Scpman_set_manAttrib(), the SCP device manager will
handle the hardware handshaking function for the calling process.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
writebuf is a pointer to the serial data to be written to the serial
communications port.
size is the number of bytes written to the serial communications port.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_WRITE_QUEUE_FULL – the write queue of the SCP device
manager is full.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_WRITE_BUFFER_FULL – the write size is larger that the
available of write buffer of the device driver. User process should wait until
enough device write buffers become available to complete the write
command.
E_SCPMAN_WRITE_BUFFER_TOO_SMALL – the maximum size of the
write buffers of the device driver is smaller than write size of the calling
process. User process should reduce the size of the write command.
E_SCPMAN_HARDWARE_ERROR – hardware related error.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_read()
208
Example:
209
4.2.8. Scpman_write_timed( )
Syntax:
#include “scpdev.h”
int Scpman_write_timed ( TScpdev hScpdev, u_int8 *writebuf, u_int32 size,
u_int32 sizeWritten, u_int32 timeout);
Description:
Writes a number of bytes to the serial communications port through the Serial
Communications Port (SCP) manager within a specified time frame. The
write operation shall terminate at the time of expiration.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
writebuf is a pointer to the serial data to be written to the serial
communications port.
size is the number of bytes written to the serial communications port.
sizeWritten is a pointer to the number of bytes that are written to the serial
communications port.
timeout is the timeout value in milliseconds that the SCP device manager
must complete the write operation. The value may be rounded up to the
nearest system tick, if the operating system’s timer resolution is lower than
the value requested. If timeout is zero, the write operation will not timeout.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_HARDWARE_ERROR – hardware related error.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read()
Example:
210
4.2.9. Scpman_write_callback( )
Syntax:
#include “scpdev.h”
int Scpdev_write_callback ( TScpdev hScpdev, u_int8 *writebuf, u_int32
size, TScp_callback function, u_int32 func_tag );
Description:
Writes a number of bytes to the serial communications port through the Serial
Communications Port (SCP) manager and invokes the callback function in the
calling process space when the write operation is completed.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
writebuf is a pointer to the serial data to be written to the serial
communications port.
size is the number of bytes written to the serial communications port. The
SCP device manager will not notify calling process until all data requested
has written.
function is a pointer to a callback function to be executed when the number
bytes specified in size are written. The routine takes a single u_int32 value
and returns void. A null pointer informs the SCP device driver not to invoke
any callback function.
func_tag is the tag to be returned to the calling process when its callback
function is executed.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_HARDWARE_ERROR – hardware related error.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpdev.lib
See Also:
Scpdev_read()
Example:
211
4.2.10. Scpman_flush( )
Syntax:
#include “scpman.h”
int Scpman_flush ( TScpman hScpman, int buffer_type );
Description:
Flushes Serial Communications Port (SCP) manager’s port buffer and the
serial communications port.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
buffer_type is the type of buffers to be flushed. A value of
SCPMAN_OUTPUT_BUFFER indicates to flush to output buffer. A value of
SCPMAN_INPUT_BUFFER indicates to flush the input buffer. Both values
can be ORed together to flush the input and output buffers.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_available()
Example:
212
4.2.11. Scpman_cancel_callback( )
Syntax:
#include “scpman.h”
int Scpman_cancel_callback ( TScpman hScpman );
Description:
Cancels one pending read and one pending write callback functions requested
by the calling process.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
Library:
scpman.lib
See Also:
Scpman_flush()
Example:
213
4.2.12. Scpman_dataready( )
Syntax:
#include “scpman.h”
int Scpman_dataready ( TScpman hScpman, u_int32 *size );
Description:
Returns the number of bytes of data ready to be read.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
size is a pointer to a location that the SCP device driver returns the number of
bytes of data available to be read.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Other errors:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_flush()
Example:
214
4.2.13. Scpman_get_attrib( )
Syntax:
#include “scpman.h”
int Scpman_get_attrib ( TScpman hScpman, TScpman_attrib *attrib );
Description:
Gets the hScpman option table from Serial Communications Port (SCP)
manager’s attribute tables. This function will return information to the user
buffer for inspection.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
attrib is a pointer to the user TScpman_attrib table structure. The
TScpman_attrib structure is described in the SCFMAN.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCMAN_OUTOF_BUFFER – the user buffer size is too small.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_set_attrib()
Example:
215
4.2.14. Scpman_set_attrib( )
Syntax:
#include “scpman.h”
int Scpman_set_attrib ( TScpman hScpman, TScpman_attrib *attrib );
Description:
Sets status of the current Serial Communications Port (SCP) manager’s
attribute table. This function will copy information from the user buffer to
SCP device manager’s option table.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
attrib is a pointer to the user TScpman_attrib structure. The
TScpman_attrib structure is described in the SCFMAN.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes;
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_INVALID_ATTRIBUTE – if one or more parameters in the
attribute table pointed to by attrib have a valid attribute.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_get_attrib()
Example:
216
4.2.15. Scpman_get_devAttrib( )
Syntax:
#include “scpman.h”
#include “scpdev.h”
int Scpman_get_devAttrib ( TScpman hScpman, TScpdev_attrib *attrib );
Description:
Gets status of the current serial port device through the Serial
Communications Port (SCP) manager. This function will return information
to the user buffer for inspection. The descriptor includes information related
to the serial port’s baud, bit, handshaking, and other attributes.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
attrib is a pointer to the user TScpdev_attrib structure. The TScpdev_attrib
structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCMAN_OUTOF_BUFFER – the user buffer size is too small.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_set_devAttrib()
Example:
217
4.2.16. Scpman_set_devAttrib( )
Syntax:
#include “scpman.h”
#include “scpdev.h”
int Scpman_set_devAttrib ( TScpman hScpman, TScpdev_attrib *attrib );
Description:
Sets status of the current serial port device through the Serial
Communications Port (SCP) manager. This function will copy information
from the user buffer to the hScpman descriptor. The descriptor includes
information related to the serial port’s baud rate, bit format, handshaking, and
other attributes.
Parameters:
hScpman is the handle that SCP device manager assigns the port.
attrib is a pointer to the user TScpdev_attrib structure. The TScpdev_attrib
structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_INVALID_ATTRIBUTE – if one or more parameter(s) in the
attribute table pointed by attrib have a valid attribute.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_get_devAttrib()
Example:
218
4.2.17. Scpman_get_devStatus( )
Syntax:
#include “scpdev.h”
#include “scpdev.h”
int Scpman_get_devStatus ( TScpman hScpman, TScfdev_status
*status_ptr );
Description:
Gets status of the current serial port device through the Serial
Communications Port (SCP) device driver. This function returns information
to the user buffer for inspection. The status includes information related to the
serial port’s control states, and error conditions.
Parameters:
hScpman is the handle that SCP device manager assigns for the port.
status_ptr is a pointer to the user TScpdev_status structure. The
TScpdev_status structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCMAN_OUTOF_BUFFER – the user buffer size is too small.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device manager handle
is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_set_devStatus()
Example:
219
4.2.18. Scpman_set_devStatus( )
Syntax:
#include “scpman.h”
#include “scpdev.h”
int Scpman_set_devStatus ( TScpman hScpman, TScpdev_status
*status_ptr );
Description:
Sets statuses of the current serial port device through the Serial
Communications Port (SCP) device driver. This function copies information
from the user buffer to the hScpdev status table. The statuses include
information related to the serial port’s control states and error conditions.
Parameters:
hScpdev is the handle that SCP device manager assigns for the port.
status_ptr is a pointer to the user TScpdev_status structure. The
TScpdev_status structure is described in the SCFDEV.H header file.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_INVALID_ATTRIBUTE – if one or more parameters in the
attribute table pointed to by status_ptr have a valid attribute.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_get_devStatus().
Example:
220
4.2.19. Scpman_get_devControl( )
Syntax:
#include “scpman.h”
#include “scpdev.h”
int Scpman_get_devControl ( TScpdev hScpdev, TScpdev_control *control
);
Description:
Gets the control states of the current serial port device through the Serial
Communications Port (SCP) device driver. This function returns information
to the user buffer for inspection. The control states include information
related to serial port’s CTS and DTR. The TScpdev_control structure is
described in the SCFDEV.H header file.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
control is a pointer to the user TScpdev_control structure.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SPCMAN_OUTOF_BUFFER – the user buffer size is too small.
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_set_devControl()
Example:
221
4.2.20. Scpman_set_devControl( )
Syntax:
#include “scpman.h”
#include “scpdev.h”
int Scpman_set_devControl ( TScpdev hScpdev, TScpdev_control *control
);
Description:
Sets the control states of the current serial port device through the Serial
Communications Port (SCP) device driver. This function copies information
from the user buffer to the hScpdev control table. The control states include
information related to serial port’s CTS and DTR. The TScpdev_control
structure is described in the SCFDEV.H header file.
Parameters:
hScpdev is the handle that SCP device driver assigns the port.
control is a pointer to the user TScpdev_control structure.
Return Value:
On success, it returns a zero; otherwise, it returns an error.
Error codes:
E_SCPMAN_INVALID_HANDLE – an invalid SCP device handle is used.
E_SCPMAN_INVALID_CONTROL – if one or more parameters in the
control table pointed to by control_ptr have a valid value.
E_SCPMAN_OS_ERROR – an operating system error has occurred.
E_SCPMAN_NULL_POINTER – a null pointer is passed to the function.
Library:
scpman.lib
See Also:
Scpman_get_devControl().
Example:
222
4.2.21. SCPMAN.H
/****************************************************************************
/
/* MODULE : scpman.h
*/
/* VERSION: 3.0
*/
/* DATE:
12/01/95
*/
/* PROGRAMMER: George Chen
*/
/* REVIEWER 1:
*/
/* REVIEWER 2:
*/
/* PORTABILITY: ATC SYSTEM UNITS
*/
/*
*/
/* DESCRIPTION:
*/
/* This module is the header file for scpman.c that is responsible for
*/
/* managing all the ATC serial communications ports.
*/
/****************************************************************************
/
#ifndef _SCPMAN_H_
#define _SCPMAN_H_
#ifdef __cplusplus
extern "C" {
#endif
#include “scpdev.h”;
typedef unsigned int TScpman;
typedef struct {
int
reserve:26;
int hwhshake:1;
int
rdhshake:1;
int
sync_io:1;
*/
int master:1;
int write_queue_block:1;
int read_queue_block:1;
u_int16
enRTS_dly;
*/
u_int16
dsRTS_dly;
*/
} TScpman_manOpts;
/* Scp handle */
/* hardware handshaking function enable */
/* read handshaking function enable */
/* synchronized write and read for hScpman
/* active control of scp
/* ON = block(default);
/* ON = block(default);
/* enable RTS line
hScpman */
*/
*/
delay factor in ticks
/* disable RTS delay in 1/10th ticks/char
/* Function Prototypes */
u_int32 Scpman_link( void );
u_int32 Scpman_unlink( void );
u_int32 Scpman_open( char *devname, Tscpman *hScpman, int *exclusive );
u_int32 Scpman_close( TScpmanhScpman);
u_int32 Scpman_read( TScpman hScpman, u_int8 *readbuf, u_int32 size,
u_int16 signal );
u_int32 Scpman_read_timed( TScpman hScpman, u_int8 *readbuf, u_int32 size,
u_int32 timeout, u_int16 signal, u_int16
timeout_signal );
u_int32 Scpman_write( TScpman hScpman, u_int8 *writebuf, u_int32 size );
u_int32 Scpman_flush( TScpman hScpman );
223
u_int32 Scpman_release( TScpman hScpman );
u_int32 Scpman_get_manAttrib( TScpman hScpman, TScpman_manAttrib *attrib,
u_int32 *size );
u_int32 Scpman_set_manAttrib( TScpman hScpman, TScpman_manAttrib *attrib,
u_int32 size );
u_int32 Scpman_get_devAttrib( TScpman hScpman, TScpdev_devAttrib *attrib,
u_int32 *size );
u_int32 Scpman_set_devAttrib( TScpman hScpman, TScpdev_devAttrib *attrib,
u_int23 size );
int Scpman_get_devStatus ( TScpman hScpman, TScfdev_status *status_ptr,
u_int32 *size );
int Scpman_set_devStatus ( TScpman hScpman, TScpdev_status *status_ptr,
u_int32 size );
int Scpman_get_devControl ( TScpman hScpman, TScfdev_control *control_ptr,
u_int32 *size );
int Scpman_set_devControl ( TScpman hScpman, TScpdev_control *control_ptr,
u_int32 size );
/* SCPMAN specific error codes */
typedef enum _E_SCPMAN_ENUM
{
E_SCPMAN_NULL_POINTER=1
,
E_SCPMAN_INVALID_HANDLE
,
E_SCPMAN_NOT_EXIST
,
E_SCPMAN_EXCLUSIVE_FAILED ,
E_SCPMAN_EXCLUSVE_OCCUPIED ,
E_SCPMAN_INVALID_DEVICENAME,
E_SCPMAN_ALREADY_CLOSE
,
E_SCPMAN_READ_QUEUE_FULL
,
E_SCPMAN_WRITE_QUEUE_FULL ,
E_SCPMAN_WRITE_BUFFER_FULL ,
E_SCPMAN_WRITE_BUFFER_TOO_SMALL,
E_SCPMAN_INVALID_SIGNAL_NUMBER ,
E_SCPMAN_OS_ERROR
,
E_SCPMAN_HARDWARE_ERROR
,
E_SCPMAN_OUTOF_BUFFER
,
E_SCPMAN_INVALID_ATTRIBUTE ,
E_SCPMAN_INVALID_CONTROL
,
E_SCPMAN_NULL_POINTER
} E_SCPMAN_ENUM;
#ifdef __cplusplus
}
#endif
#endif /* _SCPMAN_H_ */
224
4.3.
TEXT USER INTERFACE MANAGER – LAYER 2 API
4.3.1. Overview
The Application Programming Interface (API) for the Text User Interface Manager (TUIMAN)
is a set of C functions used to access the Front Panel or Front Terminal of an Advanced Traffic
Controller (ATC) through TUIMAN. TUIMAN is an independent process that controls and
manages the Text User Interface (TUI) Module. Upon starting, TUIMAN claims exclusive
access of the TUI and displays a main menu with no menu items on the screen. It is then ready
to share the TUI with other programs, provided that those programs get the appropriate access by
linking to it through this API.
When a user program links to TUIMAN, the appropriate menu item will be displayed on the TUI
Main Menu to indicate that the user program is now sharing the TUI. TUIMAN can share access
of the TUI with up to 16 other programs. Each of these programs has it’s own output buffer,
input buffer, composed character set, and attributes. Only one of them can have focus of the TUI
at any instance. When the focused program writes data to its own output buffer, the data will be
displayed on the TUI by TUIMAN. When a user presses a key on the TUI, this key will be
processed by TUIMAN and sent to the focused program.
A non-focused program can write data to its own output buffer at any time. This data will not be
displayed until the non-focused program has control of the TUI.
225
4.3.2. Tuiman_attach( )
Syntax:
#include “tuiman.h”
int Tuiman_attach( char *dev_name, TKey menu_key, wchar
*menu_item_name, void (*Callback_func)(), TTuiman
*tuiman);
Description:
Attaches to TUIMAN to access the TUI.
Parameters:
dev_name specifies the device on which the TUI operates.
menu_key specifies the key used to access the program linked to TUIMAN.
menu_item_name specifies a meaningful name for the requested buffer.
Characters beyond the expected range will be truncated to fit on the screen.
Callback_func, if not null, will be executed when its buffer receives data.
tuiman is a handle returned by TUIMAN for all other function calls. It points
to NULL if an error occurs.
Return Value:
E_TUI_NO_ERROR if a valid link can be established successfully.
E_TUI_ILLEGAL_MENU_KEY - if menu_key is not in the range of [0..9,
A..F].
E_TUI_MENU_KEY_TAKEN - if menu_key has been taken by another user
program.
E_TUI_MAN_NOT_LOADED - if TUIMAN is not running.
E_TUI_ALL_BUFS_TAKEN - if all managed buffers are taken by other
tasks.
E_TUI_ALREADY_ATTACHED - if tuiman has been detached already.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_detach(), Tuiman_release_control()
226
4.3.3. Tuiman_detach( )
Syntax:
#include “tuiman.h”
int Tuiman_detach( TTuiman tuiman);
Description:
Detaches to TUIMAN and releases control of the shared TUI buffer. This
function is usually called before the user program terminates.
TUIMAN de-allocates this buffer and may reallocate it to other programs.
Parameters:
tuiman must be a handle created by Tuiman_attach().
Return Value:
E_TUI_NO_ERROR - if tuiman can be detached successfully.
E_TUI_ALREADY_DETACHED - if tuiman has been detached already.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
Tuiman_attach(), Tuiman_release_control()
227
4.3.4. Tuiman_set_window( )
Syntax:
#include “tuiman.h”
int Tuiman_set_window( TTuiman tuiman, int start_row, int start_col, int
height, int width);
Description:
Sets the origin and size of the TUI virtual screen. Any characters out of the
range of the physical screen will not be displayed.
Parameters:
tuiman must be a handle created by Tuiman_attach().
start_row and start_col indicates the row and column coordinates of the
physical screen which marks the origin of the virtual screen. The origin of
the virtual screen is always (1,1).
height specifies the desired height of the virtual screen in characters.
width specifies the desired width of the virtual screen in characters.
Return Value:
E_TUI_NO_ERROR - if control can be returned to TUIMAN successfully.
E_TUI_NOT_ACTIVE - if tuiman is not active and therefore does not have
control of the TUI.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
228
4.3.5. Tuiman_release_control( )
Syntax:
#include “tuiman.h”
int Tuiman_release_control( TTuiman tuiman);
Description:
Releases control of the TUI and returns control to TUIMAN. This function
should be used if the user wants to return to the TUI Main Menu without
exiting the program.
Parameters:
tuiman must be a handle created by Tuiman_attach().
Return Value:
E_TUI_NO_ERROR - if control can be returned to TUIMAN successfully.
E_TUI_NOT_ACTIVE - if tuiman is not active and therefore does not have
control of the TUI.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
Tuiman_attach(), Tuiman_detach()
229
4.3.6. Tuiman_gain_control( )
Syntax:
#include “tuiman.h”
int Tuiman_gain_control( TTuiman tuiman);
Description:
Gains control or focus of the TUI. This function is mainly designed for
TUIMAN to regain control if a user program crashes when it has control of
the TUI. When a user program runs normally, it will be notified if the TUI
focus is lost.
Parameters:
tuiman must be a handle created by Tuiman_attach().
Return Value:
E_TUI_NO_ERROR - if control can be taken.
E_TUI_IS_ACTIVE - if tuiman is already active and has control.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
Tuiman_attach(), Tuiman_detach(), Tuiman_release_control()
230
4.3.7. Tuiman_read_key( )
Syntax:
#include “tuiman.h”
int Tuiman_read_key( TTuiman tuiman, TKey *key, TKeyStat *stat);
Description:
Reads a key from TUIMAN. key is a two-byte key code consistent with the
PC BIOS key code. It does not wait until a key is pressed.
Parameters:
tuiman must be a handle created by Tuiman_attach().
key is a pointer to TKey structure that contains the key code read from the
TUIMAN. If the user is interested in only the keyboard status, then set key to
null upon function entry. Otherwise, it can hold one of the following:
0, 1, 2 ,3, 4, 6, 7, 8, 9, A, B, C, D, E, F,
TUI_UP,
TUI_DOWN,
TUI_LEFT,
TUI_RIGHT,
TUI_ESC,
TUI_PLUS,
TUI_MINUS,
TUI_YES,
TUI_NO,
TUI_DOT,
TUI_NEXT,
TUI_ENTER,
TUI_NONE
stat contains the keyboard status (i.e.RIGHT-SHIFT, LEFT-SHIFT, CTRL).
If the user is not interested in the keyboard status, set stat to null upon
function entry.
The above constants are defined in tuiman.h.
Return Value:
E_TUI_NO_ERROR - if character can be read successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h
See Also:
Tuiman_write_char(), Tuiman_write_buf(), Tuiman_write_str()
231
4.3.8. Tuiman_write_buf( )
Syntax:
#include “tuiman.h”
int Tuiman_write_buf( TTuiman tuiman, wchar *buf, int num_bytes);
Description:
Writes num_bytes of unicode characters from a buffer to TUIMAN. If TUI is
active, the data will appear on the TUI starting at the cursor position. If a
character within buf has been composed by Tuiman_comp_char(), the
composed character or bitmap will be written to the screen.
Parameters:
tuiman must be a handle created by Tuiman_attach().
buf is a pointer that contains the data to be written. It does not have to be
null-terminated. num_bytes will be written regardless of whether buf contains
null characters.
num_bytes indicates the number of bytes to be written.
Return Value:
E_TUI_NO_ERROR - if data can be written successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_write_str(), Tuiman_write_char(), Tuiman_read_key()
232
4.3.9. Tuiman_write_char( )
Syntax:
#include “tuiman.h”
int Tuiman_write_char( TTuiman tuiman, wchar ch);
Description:
Writes a unicode character to TUIMAN. If TUI is active, the character will
appear on the TUI starting at the cursor position. If ch has been composed by
Tuiman_comp_char(), the composed character or bitmap will be written to the
screen.
Parameters:
tuiman must be a handle created by Tuiman_attach().
ch is the character to be displayed.
Return Value:
E_TUI_NO_ERROR - if the character can be written successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
Tuiman_write_buf(), Tuiman_write_str(), Tuiman_read_key()
233
4.3.10. Tuiman_write_str( )
Syntax:
#include “tuiman.h”
int Tuiman_write_str( TTuiman tuiman, wchar *str);
Description:
Writes a null-terminated unicode string to TUIMAN. If TUI is active, the
string will appear on the TUI starting at the cursor position. If a character
within str has been composed by Tuiman_comp_char(), the composed
character or bitmap will be written to the screen.
Parameters:
tuiman must be a handle created by Tuiman_attach().
str is a null-terminated unicode string to be written.
Return Value:
E_TUI_NO_ERROR - if the string can be written successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_write_buf(), Tuiman_write_char(), Tuiman_read_key()
234
4.3.11. Tuiman_put_cursor( )
Syntax:
#include “tuiman.h”
int Tuiman_put_cursor( TTuiman tuiman, int row, int col);
Description:
Put cursor within the TUI buffer with (1,1) as the upper-left-most position.
Parameters:
tuiman must be a handle created by Tuiman_attach().
row indicates the row number.
col indicates the column number.
Return Value:
E_TUI_NO_ERROR - if cursor can be successfully placed at the requested
position.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_OUT_OF_RANGE - if row or col are out of range.
The above constants are defined in tuiman.h.
See Also:
Tuiman_get_cursor()
235
4.3.12. Tuiman_get_cursor( )
Syntax:
#include “tuiman.h”
int Tuiman_get_cursor( TTuiman tuiman, int *row, int *col);
Description:
Get cursor position within the user’s own TUI buffer using (1, 1) as the upperleft-most position
Parameters:
tuiman must be a handle created by Tuiman_attach().
row is the address for storing the row number.
col is the address for storing column number.
Return Value:
E_TUI_NO_ERROR - if cursor position can be returned successfully in row
and col.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_put_cursor()
236
4.3.13. Tuiman_init_buf( )
Syntax:
#include “tuiman.h”
int Tuiman_init_buf( TTuiman tuiman, wchar ch);
Description:
Initializes the TUI buffer by setting the cursor to (1,1) at the upper-left-most
position and filling the entire buffer with ch. Set ch to a SPACE character for
clearing the buffer.
Parameters:
tuiman must be a handle created by Tuiman_attach().
ch is used as the initialization character in unicode.
Return Value:
E_TUI_NO_ERROR - if the TUI buffer can be initialized successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
Tuiman_write_buf(), Tuiman_write_str(), Tuiman_write_char()
237
4.3.14. Tuiman_dataready( )
Syntax:
#include “tuiman.h”
int Tuiman_dataready( TTuiman tuiman, int *key_count);
Description:
Checks to see if TUIMAN has data for this buffer.
Parameters:
tuiman must be a handle created by Tuiman_attach().
key_count returns the number of keys ready for processing. Zero indicates no
keys in the buffer. This buffer shall hold at least 16 keys.
Return Value:
E_TUI_NO_ERROR - if function can be executed successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_DATA_LOST - if the buffer has overflowed.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_read_key()
238
4.3.15. Tuiman_set_attrib( )
Syntax:
#include “tuiman.h”
int Tuiman_set_attrib( TTuiman tuiman, int attrib, int state);
Description:
Sets the attribute of the TUI buffer to the specified state.
Parameters:
tuiman must be a handle created by Tuiman_attach().
attrib can be one of the following:
TUI_AUTO_WRAP
TUI_AUTO_SCROLL
TUI_AUTO_REPEAT
TUI_CURSOR_DISP
TUI_BACKLIGHT
TUI_BLINK_CHAR
TUI_REVERSE_VIDEO
TUI_ITALIC
TUI_UNDERLINED
TUI_BOLD
TUI_NORMAL
state specifies the desired state. It can be either TUI_ON or TUI_OFF.
The above constants are defined in tuiman.h.
Return Value:
E_TUI_NO_ERROR - if mode can be set successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_INVALID_ATTRIB - if attrib is not one of attributes listed above.
E_TUI_INVALID_STATE - if state is not either TUI_ON or TUI_OFF.
The above constants are defined in tuiman.h.
See Also:
Tuiman_get_attrib()
239
4.3.16. Tuiman_get_attrib( )
Syntax:
#include “tuiman.h”
int Tuiman_get_attrib( TTuiman tuiman, int attrib, int *state);
Description:
Gets the current state of the specified attribute of the TUI buffer.
Parameters:
tuiman must be a handle created by Tuiman_attach().
attrib can be one of the following:
TUI_AUTO_WRAP
TUI_AUTO_SCROLL
TUI_AUTO_REPEAT
TUI_CURSOR_DISPLAY
TUI_BACKLIGHT
TUI_BLINK_CHAR
TUI_REVERSE_VIDEO
TUI_ITALIC
TUI_UNDERLINED
TUI_BOLD
state is a pointer to TUI_ON, TUI_OFF, or TUI_NOT_IMPLEMENTED.
The above constants are defined in tuiman.h.
Return Value:
E_TUI_NO_ERROR - if mode can be set successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_INVALID_ATTRIB - if attrib is not one listed above.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_set_attrib()
240
4.3.17. Tuiman_get_status( )
Syntax:
#include “tuiman.h”
int Tuiman_get_status( TTuiman tuiman, int *status, int *state);
Description:
Gets the status of the TUI.
Parameters:
tuiman must be a handle created by Tuiman_attach().
status can be one of the following:
TUI_AUX_SWITCH
On function return, state contains one of the following:
TUI_ON if the desired status is on.
TUI_OFF if the desired status if off.
TUI_NULL if the desired status is not implemented in the TUI.
The above constants are defined in tuiman.h.
Return Value:
E_TUI_NO_ERROR - if status can be returned successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_INVALID_STAT_ID - if status ID is not valid.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_get_cursor
241
4.3.18. Tuiman_comp_char( )
Syntax:
#include “tuiman.h”
int Tuiman_comp_char( TTuiman tuiman, wchar ch_id, unsigned char
*matrix, int num_bytes);
Description:
Composes special characters with a pixel matrix of 8 bits by num_bytes.
These bytes are arranged from left to right, with the least significant bit on the
bottom. If a composition already exists for the specified ch_id, the new
composition will preside.
Parameters:
tuiman must be a handle created by Tuiman_attach().
ch_id is the unicode specified by the user and can also replace a standard
unicode character. ch_id of zero is not allowed.
matrix contains the num_bytes of bitmap of the composed character. For
example, a 5-byte matrix of {0xFE, 0x90, 0x90, 0x80, 0x80} represents the
letter ‘F’.
Return Value:
E_TUI_NO_ERROR - if status can be returned successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
E_TUI_INVALID_ID - if ch_id is zero.
E_TUI_COMP_CHAR_MAX - if the maximum number of composed
characters is reached.
E_TUI_NULL_POINTER - if a null pointer is passed to the function.
The above constants are defined in tuiman.h.
See Also:
Tuiman_write_char
242
4.3.19. Tuiman_beep( )
Syntax:
#include “tuiman.h”
int Tuiman_beep( TTuiman tuiman, int freq, int duration);
Description:
Beeps to draw attention even if the user program does not have active control
of the TUI.
Parameters:
tuiman must be a handle created by Tuiman_attach().
freq is the frequency of the beep.
duration is the duration of the sound wave.
Return Value:
E_TUI_NO_ERROR - if status can be returned successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
243
4.3.20. Tuiman_refresh_screen( )
Syntax:
#include “tuiman.h”
int Tuiman_refresh_screen( TTuiman tuiman);
Description:
Request TUIMAN to rewrite all characters in the buffer of the focused
program.
Parameters:
tuiman must be a handle created by Tuiman_attach().
Return Value:
E_TUI_NO_ERROR - if status can be returned successfully.
E_TUI_INVALID_HANDLE - if tuiman is invalid.
The above constants are defined in tuiman.h.
See Also:
244
4.3.21. Tuiman.h
#include “tuidev.h”
#define
#define
#define
#define
#define
#define
#define
#define
#define
E_TUI_ILLEGAL_MENU_KEY
E_TUI_MENU_KEY_TAKEN 102
E_TUI_MAN_NOT_LOADED 103
E_TUI_ALL_BUFS_TAKEN 104
E_TUI_ALREADY_ATTACHED
E_TUI_ALREADY_DETACHED
E_TUI_NOT_ACTIVE
107
E_TUI_IS_ACTIVE 108
E_TUI_NULL_POINTER
101
105
106
109
245
5.
ANNEX
5.1.
REQUIRED STANDARD “C” HEADERS
<CTYPE.H>
<ERROR.H>
<FLOAT.H>
<LIMITS.H>
<LOCAL.H>
<MATH.H>
<SETJMP.H>
<STDARG.H>
<STDDEF.H>
<STDIO.H>
<STDLIB.H>
<STRING.H>
<TIME.H>
246
5.2.
ATC GLOBAL TYPE HEADER
/*************************************************************
* MODULE :
atctype.h
* VERSION:
3.0
* PORTABILITY: ATC SYSTEM UNITS
*
* DESCRIPTION:
* This module is the header file for all ATC API libraries.
*************************************************************/
#ifndef _ATCTYPE_H_
#define _ATCTYPE_H_
#ifdef __cplusplus
extern "C" {
#endif
/* ATC API Function Prototypes */
typedef int error_code;
typedef unsigned char u_int8;
typedef unsigned short u_int16;
typedef unsigned long u_int32;
typedef int boolean;
#ifdef __cplusplus
}
#endif
#endif
247