Third Edition (August 1996)
Chapter 1. General Product Description
Chapter 3. Programming Services (RICPS)
Chapter 4. Asynchronous Communications Support
Chapter 5. Synchronous Communications Support
Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in revisions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
It is possible that this publication may contain references to, or information about, IBM products (machines or programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
Note to U.S. Government Users -
Documentation Related to Restricted Rights -
Use, duplication or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates.
Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply that only IBM's program or other product may be used.
The following terms, DENOTED BY AN ASTERISK (*), used in this publication, are trademarks or service marks of IBM Corporation in the United States and/or other countries:
IBM International Business Machines OS/2 Operating System/2 PS/2 Personal System/2 C/2 C Language/2 Macro Assembler/2The following terms, DENOTED BY A DOUBLE ASTERISK (**), used in this publication, are trademarks of other companies as follows:
Zilog Zilog Inc. Signetics Signetics Corporation
This publication provides technical information on installing and using the Realtime Interface Co-Processor Extended Services (RICES) Version 1.03, a package of program services that support the Realtime Interface Co-Processor family of adapters. The Realtime Interface Co-Processor family of adapters includes:
Note:
The general term "co-processor adapter(s)" is used to designate any adapter in the Realtime Interface Co-Processor family. Specific names, as given above, will be used to indicate specific Realtime Interface Co-Processor adapters.The name "IBM X.25 Interface Co-Processor/2" identifies a specific feature card and does not imply that the IBM Realtime Interface Co-Processor Extended Services provides X.25 support.
The objectives of this publication are to:
Note:
Additional information can be found in the publications listed in "Related Publications" and "Reference Publications".
The information in this publication is both introductory and for reference use. It is intended for software designers, system programmers, engineers, and anyone with a programming knowledge who wishes to understand the use of the RICES. It is also intended for application end users involved in application installation and operation.
The reader of this book should be familiar with the system unit and the co-processor adapter in use, the Realtime Control Microcode and the intended applications, and should understand the differences in hardware capabilities. Terminology is not explained herein except for terms that may be specially implemented.
The information contained in this publication contains general information as well as discusses programming services, it also describes the asynchronous and synchronous communications support.
Chapter 1, "General Product Description"
This chapter gives a brief general description of the Realtime Interface Co-Processor Extended Services (RICES).
Chapter 2, "Getting Started"
This chapter explains how to install, start-up, and load the RICES software.
Chapter 3, "Programming Services"
This chapter discusses the Realtime Interface Co-Processor Programming Services (RICPS). It discusses the different categories of RICPS and gives a description of each service. The services are grouped according to their service types:
Chapter 4, "Asynchronous Communications Support"
This chapter describes the Realtime Interface Co-Processor Asynchronous Communications Support. It contains RICCS C Support and descriptions of the interface to the RICCS driver task. These detailed function descriptions include assembler interface, C-call format, control block format, parameter descriptions, and return codes. Chapter 4 also provides a summary of RICCS return codes, information return codes, programming tips and techniques, and a summary of the Assembler Include file.
Chapter 5, "Synchronous Communications Support"
This chapter describes the Realtime Interface Co-Processor Synchronous Communications Support (RICCS). It contains RICCS C Support and descriptions of the interface to the RICCS driver tasks. These detailed function descriptions include assembler interface, C-call format, control block format, parameter descriptions, and return codes. Chapter 5 also provides a summary of RICCS return codes, information return codes, programming tips and techniques and a summary of the Assembler include file.
Related books in the Realtime Interface Co-Processor library include:
This guide provides instructions for installing the IBM Realtime Interface Co-Processor and IBM Realtime Interface Co-Processor Multiport and describes the features of each. It also describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and others who needs to understand the use and operation of the co-processor adapter.
This guide provides instructions for installing the hardware necessary to use the IBM Realtime Interface Co-Processor Multiport/2 and describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and others who needs to understand the use and operation of the co-processor adapter.
This guide provides instructions for installing the hardware necessary to use the IBM X.25 Interface Co-Processor/2 and describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and others who needs to understand the use and operation of this co-processor adapter.
This manual provides tips and techniques aimed at increasing the productivity of the programmer(s) developing software for the IBM X.25 Interface Co-Processor/2.
This guide provides instructions for installing the IBM Realtime Interface Co-Processor Portmaster Adapter/A, describes the product features, and provides problem determination procedures.
This manual provides both introductory and reference information, and is intended for hardware designers who need to understand the design and operating characteristics of this co-processor adapter. (See also the IBM Realtime Interface Co-Processor Firmware Technical Reference.)
This manual is used in conjunction with either the RS-232-C Interface Board Hardware Maintenance Library or the RS-422-A Interface Board Hardware Maintenance Library. This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are also provided.
This kit, or the RS-422-A Interface Board Hardware Maintenance Library, is required for maintenance of IBM Realtime Interface Co-Processor Portmaster Adapter/A or IBM Realtime Interface Co-Processor Multiport Adapter, Model 2. This kit contains a card wrap connector, cable wrap connector(s), and instructions and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2: Hardware Maintenance Library.
This kit, or the RS-232-C Interface Board Hardware Maintenance library, is required for maintenance of IBM Realtime Interface Co-Processor Portmaster Adapter/A or IBM Realtime Interface Co-Processor Multiport Adapter, Model 2. This kit contains a card wrap connector, cable wrap connector(s), and instructions and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2: Hardware Maintenance Library.
This guide provides instructions for installing the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, describes the product features, and provides problem determination procedures.
This manual provides both introductory and reference information, and is intended for hardware designers who need to understand the design and operating characteristics of this co-processor adapter. (See also the IBM Realtime Interface Co-Processor Firmware Technical Reference.)
This manual is used in conjunction with either the RS-232-C Interface Board Hardware Maintenance Library or the RS-422-A Interface Board Hardware Maintenance Library. This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are also provided.
This kit, or the RS-422-A Interface Board Hardware Maintenance Library, is required for maintenance of IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 or IBM Realtime Interface Co-Processor Portmaster Adapter/A. This kit contains a card wrap connector, cable wrap connector(s), and instructions and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2: Hardware Maintenance Library.
This kit, or the RS-232-C Interface Board Hardware Maintenance library, is required for maintenance of IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 or IBM Realtime Interface Co-Processor Portmaster Adapter/A. This kit contains a card wrap connector, cable wrap connector(s), and instructions and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2: Hardware Maintenance Library.
This guide provides information on using the C Language Support product, a productivity aid that allows programmers to develop code for the co-processor adapter in the C-programming language. It explains the C-interface routines and the method of compiling and linking C-tasks for the co-processor adapter and provides information on writing system unit programs in C Language for use when interacting with the co-processor adapter.
This guide provides information necessary to interface with the co-processor adapter through Disk Operating System (DOS). The guide describes the functions, capabilities and installation of the Realtime Interface Co-Processor DOS Support software.
This guide provides information necessary to interface with the co-processor adapter through Operating System/2* (OS/2*). The guide describes the functions, capabilities and installation of the Realtime Interface Co-Processor OS/2* Support software.
Describes the software of the Realtime Interface Co-Processor Developer's Kit. This software includes:
This manual provides detailed information on the programmer interfaces to the Realtime Control Microcode and is intended for hardware and software designers who need to understand the design and operating characteristics of the control microcode for all IBM Realtime Interface Co-Processor adapters.
One or more of the following publications might be needed for reference when using this publication:
The IBM Realtime Interface Co-Processor Extended Services (RICES) is a productivity aid that provides the system developer with a variety of services to ease the writing of systems applications for the IBM Realtime Interface Co-Processor family of adapters. The RICES product includes numerous task, event, resource, and communications services that allow the system developer to concentrate on the application instead of the system.
The RICES product consists of two major modules that can be used together or independently of each other:
The Realtime Interface Co-Processor Programming Services (RICPS), a task that runs under the control of the Realtime Control Microcode (RCM), provides a variety of services to user-written application tasks. These services ease the job of the system developer by reducing the effort involved in application development.
The services provided by RICPS address typical programming needs. Greater application program standardization can be achieved through the use of RICPS because the various programming needs can be met via common methods. A C-language interface and an Assembler language interface are provided.
RICPS includes services that affect task priorities and their scheduling, enhance inter-task communications capabilities, provide event management, and allow naming of resources and tasks. In addition, RICPS provides services that allow non-specific references for allocating certain resources. Chapter 3 describes the Realtime Interface Co-Processor Programming Services in detail.
The Realtime Interface Co-Processor Communications Support (RICCS) provides a function level interface, using either the C or Assembler programming language, to utilize the asynchronous and synchronous communications facilities of the IBM Realtime Interface Co-Processor family of adapters. RICCS shelters applications from the communications hardware, allowing the implementation of special protocols and networking considerations without being hardware dependent. RICCS allows applications to define all necessary communications parameters and provides powerful read and write functions.
The many features of this facility include:
Version 1.03 of RICCS contains the following enhancements:
The following sections describe the structure used for the RICCS software product. The term "structure", as used in this document, refers to the number of driver tasks provided, and the scope of each driver task.
Three separate driver tasks are provided with RICCS Version 1.03:
+========================================================+=============+ | Driver Task | File Name | +========================================================+=============+ | Asynchronous driver (Zilog** and Signetics**) | RICCS.COM | +--------------------------------------------------------+-------------+ | Bit synchronous driver (Zilog**) | RICCSSZ.EXE | +--------------------------------------------------------+-------------+ | Bit synchronous driver (Signetics**) | RICCSSS.EXE | +--------------------------------------------------------+-------------+
The asynchronous and synchronous Signetics drivers provide support for the Selectable Interface Board/A. When using the Selectable Interface Board/A, the drivers by default will configure the ports for RS-232-C. However, the RCS_DEFEI command or the RCS_S_DEFEI command must be used to configure the Selectable Interface Board/A for other interface combinations. Compatibility at the user task level is maintained.
All drivers allow the posting of another task when a no-wait read or a no-wait write completes. The POSTTASKNUM parameter in the RCS_READ, RCS_S_READ, RCS_WRITE, and RCS_S_WRITE commands must be used to inform the drivers which task should be posted upon a no-wait read or a no-wait write completion.
The following are minimum hardware and software requirements for the IBM Realtime Interface Co-Processor Extended Services:
Note:
The name "IBM X.25 Interface Co-Processor/2" identifies a specific feature card and does not imply that the IBM Realtime Interface Co-Processor Extended Services provides X.25 support.
The following diskettes are needed for software installation:
Note:
Realtime Interface Co-Processor Programming Services (RICPS) requires approximately 12KB of co-processor adapter storage. Realtime Interface Co-Processor Communications Support (RICCS) requires approximately 28KB of co-processor adapter storage per driver.
The IBM Realtime Interface Co-Processor Extended Services (RICES) Programs diskette contains two information files and twelve program files. The program files are divided into two modules:
The information files are:
The program files are:
The IBM Realtime Interface Co-Processor Extended Services Sample Programs contains 3 information files and 26 sample program files. These sample program files support the Realtime Interface Co-Processor Programming Services (RICPS) and the Realtime Interface Co-Processor Communications Support (RICCS).
The information files are:
The program files are:
Use the following procedure to start up the RICES software. Be sure to use the instructions that apply to your operating system environment.
ICAINTH
ICALOAD c# ICAAIM.COM 0For the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, enter:
ICALOAD c# ICARCM.COM 0where:
c# = the co-processor adapter number
ICALDRIC c# ICAAIM.COM 0For the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, enter:
ICALDRIC c# ICARCM.COM 0where:
c# = the co-processor adapter number
Once the Interrupt Handler or Device Driver and the Realtime Control Microcode are loaded, you can load IBM Realtime Interface Co-Processor Extended Services to run under this control program.
Note:
IBM Realtime Interface Co-Processor Extended Services consists of the following tasks:The RICPS and RICCS tasks are independent of each other and may be loaded separately or at the same time.
- Realtime Interface Co-Processor Programming Services (RICPS.COM and RICPSE.COM).
- Realtime Interface Co-Processor Communications Support (RICCS.COM, RICCSSZ.EXE, and RICCSSS.EXE).
Further information on the functionality provided by RICPS may be found in Chapter 3, "Programming Services", in Chapter 4, "Asynchronous Communications Support" and in Chapter 5, "Synchronous Communication Support".
This step is optional. To verify the installation and loading of the IBM Realtime Interface Co-Processor Extended Services software, you may run the sample programs on the IBM Realtime Interface Co-Processor Extended Services Sample Programs. For information on running the sample programs, enter the command:
> TYPE SAMPLE.TXT
Realtime Interface Co-Processor Programming Services (RICPS) must be loaded on the co-processor before use. Any valid task number may be used.
ICALOAD c# RICPS.COM t#For the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, enter:
ICALOAD c# RICPSE.COM t#where:
c# = the co-processor adapter number t# = the RICPS task number
ICALDRIC c# RICPS.COM t#For the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, enter:
ICALDRIC c# RICPSE.COM t#where:
c# = the co-processor adapter number t# = the RICPS task number
The possible initialization errors are:
+=========+=========+=============================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+=============================+ | 01h | 02h | Insufficient storage | +---------+---------+-----------------------------+ | 01h | 03h | No software timer available | +---------+---------+-----------------------------+ | 01h | 04h | Invalid RCM level | +---------+---------+-----------------------------+ | 01h | 06h | RICPS initialization error | +---------+---------+-----------------------------+ | 01h | 0Ch | RICPS already loaded | +---------+---------+-----------------------------+
Realtime Interface Co-Processor Communications Support (RICCS) must be loaded to the co-processor adapter before use. Any valid task number may be used.
ICALOAD c# RICCS.COM t#To load the RICCS bit synchronous Zilog** task to the IBM Realtime Interface Co-Processor, the IBM Realtime Interface Co-Processor Multiport, the Realtime Interface Co-Processor Multiport/2, and the IBM X.25 Interface Co-Processor/2, enter:
ICALOAD c# RICCSSZ.EXE t#To load the RICCS bit synchronous Signetics** task to the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, enter:
ICALOAD c# RICCSSS.EXE t#where:
c# = the co-processor adapter number t# = the RICCS task number
ICALDRIC c# RICCS.COM t#To load the RICCS bit synchronous Zilog** task to the IBM Realtime Interface Co-Processor, the IBM Realtime Interface Co-Processor Multiport, the IBM Realtime Interface Co-Processor Multiport/2, and the IBM X.25 Interface Co-Processor/2, enter the following command:
ICALDRIC c# RICCSSZ.EXE t#To load the RICCS bit synchronous Signetics** task to the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, enter:
ICALDRIC c# RICCSSS.EXE t#where:
c# = the co-processor adapter number t# = the RICCS task number
The possible initialization errors are:
+=========+======================+ | Byte 0 | Meaning | +=========+======================+ | 01h | Initialization | | | complete error | +---------+----------------------+ | 02h | No valid ports | +---------+----------------------+ | 21h | Allocation error | +---------+----------------------+
Realtime Interface Co-Processor Programming Services (RICPS) runs under the control of the Realtime Control Microcode Version 1.5 or higher and provides a variety of software services to user-written applications also running under the control of the Realtime Control Microcode.
Note:
The Realtime Control Microcode is the random-access memory (RAM) loadable supervising microcode for the Realtime Interface Co-Processor family of adapters. The Realtime Control Microcode Version 1.5 or higher is a prerequisite of the Realtime Interface Co-Processor Extended Services.
To load RICPS, refer to "Loading RICPS". Once loaded, RICPS initializes variables and allocates resources and memory for its own use. Other tasks may issue requests to RICPS services through software interrupt vector 5Eh when RICPS is successfully loaded and started.
The services included in RICPS are similar to Realtime Control Microcode Service Interrupts (SVIs) because they do not cause a Dispatch Cycle to occur. To cause a Dispatch Cycle, a task may call the ASAP Supervisor Call immediately following an RICPS call.
The following list contains the services provided by RICPS. These services, grouped into categories, are described in detail in this chapter.
RICPS Services
The C Call Format for the Supervisor Calls affected by the RICPS services requires the Realtime Interface Co-Processor C Support. The C Call Format routines are provided in the RICPS.LIB library. A declarations file, RICPS.H, is also included. C language tasks that use the RICPS services should include RICPS.H and link with RICPS.LIB in addition to the other libraries specified in the Realtime Interface Co-Processor C Support documentation. The RICPS library and include file are on the RICES Programs diskette.
This section describes each of the categories of RICPS services. The individual services are described in detail later in this chapter.
RICPS must be loaded before any other service described in this chapter can be performed. The presence of RICPS should be checked before calling any other service described in this chapter. If any RICPS service is issued without the prior presence of RICPS, an error is returned.
A task may request that it be posted when one event, a combination of events, or multiple events occur. (Refer to Realtime Interface Co-Processor Software Technical Reference Volumes 2 and 3 and the Realtime Interface Co-Processor Firmware Technical Reference for a discussion of Post and posting a task.)
Event management permits 16 user-defined events and supports the posting, querying, and resetting of the events. This is accomplished by two 16-bit fields. One is the user-specified event flag value that the task waits on, and the other is the task's event flag, which represents the events that have already taken place. The event flag value is the binary representation of the argument passed when issuing an EventWait. Each event corresponds to a bit in the 16-bit field; however, EventPost can signal that multiple events have occurred. A task cannot issue an EventWait on behalf of another task; a task can only issue an EventWait for itself.
A unique post code (0055h) indicates an event post. The following shows the possible codes assigned to a task waiting for an event:
This service allows a task to wait with a variable length timeout. The waiting period ranges from 0 milliseconds (no wait) to 327.670 seconds with five-millisecond increments; however, tasks still optionally can wait indefinitely. The timeouts are minimum values, not exact values. A task requiring exact timing should use a hardware timer. (Hardware timers are described in Realtime Interface Co-Processor Hardware Technical Reference Volume 2, in the IBM Realtime Interface Co-Processor Portmaster Adapter/A Hardware Technical Reference, and in the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Technical Reference).
Tasks waiting with a timeout can be posted by either the occurrence of the timeout, the posting of the task by a Post Supervisor Call or the posting of the task by a Post Service Interrupt. When the task is posted by a Post Supervisor Call or a Post Service Interrupt, the timeout is cancelled. If a timeout occurs, the task is posted with a unique timeout post code (0054h), indicating the Post was the result of a timeout.
RICPS provides two user queue resource types: LIFO (Last In First Out) and Priority queues. FIFO (First In First Out) queues are provided by the Realtime Control Microcode. (User Queues and their resource block structure are described in Realtime Interface Co-Processor Software Technical Reference Volume 2, and the Realtime Interface Co-Processor Firmware Technical Reference). The block descriptor field of the user queue resource block identifies the queue type. The block descriptor is 20h for a LIFO queue and 21h for a Priority queue. Priority in a priority queue ranges from 0 (high priority) to 255 (low priority).
There is no restriction except for available storage on the number of queue elements a user can have, the maximum size of each queue element, or the contents of each queue element, except the first four bytes. Each queue element must be at least four bytes in length to hold a pointer to the next element in the queue.
The following table shows the format of a user LIFO queue element:
+=========+============+==============+============+ | Byte | Definition | Description | Comments | +=========+============+==============+============+ | 00h-03h | NEXT | Pointer to | Completed | | | | next queue | by RICPS | | | | element | | +---------+------------+--------------+------------+ | >03h | DATA | User-defined | | | | | data | | +---------+------------+--------------+------------+For priority queues, an additional byte is required to specify the priority of the element. The following table illustrates the format of a user Priority queue element.
+=========+============+==============+============+ | Byte | Definition | Description | Comments | +=========+============+==============+============+ | 00h-03h | NEXT | Pointer to | Completed | | | | next queue | by RICPS | | | | element | | +---------+------------+--------------+------------+ | 04h | ELEMENT | Priority | 0 to 255; | | | PRIORITy | of queue | set by | | | | element | user task | +---------+------------+--------------+------------+ | >04h | DATA | User-defined | | | | | data | | +---------+------------+--------------+------------+The ALLOC Supervisor Call the RETURN Supervisor Call and the ADDQUEUE, RECQUEUE, and REMQUEUE Service Interrupts (described in Realtime Interface Co-Processor Software Technical Reference Volume 3 and the Realtime Interface Co-Processor Firmware Technical Reference) are services supporting LIFO and Priority queues.
Named resources and named tasks facilitate system wide access to shared resources and tasks. A name is treated as a system resource.
When using RICPS all resource types may be named except for a name resource. When using IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 and IBM Realtime Interface Co-Processor Portmaster Adapter/A all resource types may be named except for a named resource and an extended service hooks resource.
The resource types not described in this publication are described in Realtime Interface Co-Processor Software Technical Reference Volume 2, the IBM Realtime Interface Co-Processor Portmaster Adapter/A Hardware Technical Reference, the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Technical Reference and the Realtime Interface Co-Processor Firmware Technical Reference).
Resource and task names can be up to 255 bytes long. No conventions for names are specified; any characters can be used. Names are treated as resources and are allocated and deallocated via the ALLOC and RETURN Supervisor Calls
Tasks or resources can have multiple names. A task may allocate names for any resource in the system; however, names allocated for a specific resource type must be unique to that resource type.
When a task stops, all allocated names it owns are returned even if another task still owns and uses the physical resources. Returning the Name Resource Block also removes names from the system.
A Name Resource Block is required to support named resources and named tasks. The following table illustrates the format of the Name Resource Block:
+======+============+=====================+=============+========+ | Byte | Definition | Descriptions | Comment | Set By | +======+============+=====================+=============+========+ | 00h | NEXT | Pointer to next | | RICPS | | 01h | | resource block | | | +------+------------+---------------------+-------------+--------+ | 02h | PREV | Pointer to previous | | RICPS | | 03h | | resource block | | | +------+------------+---------------------+-------------+--------+ | 04h | 24h | Block descriptor | Must by 24h | APPL | +------+------------+---------------------+-------------+--------+ | 05h | DEVTYPE | Device type | Device type | APPL | | | | | to be named | | +------+------------+---------------------+-------------+--------+ | 06h | TASKNUM | Owner task number | | APPL | +------+------------+---------------------+-------------+--------+ | 07h | RESERVED | Reserved | Must be 0 | APPL | +------+------------+---------------------+-------------+--------+ | 08h- | DEVNUM | Device number, | Limits | APPL | | 0Bh | See Note 1 | storage segment, | dependent | | | | below | semaphore handle or | on device | | | | | expanded memory | type | | | | | (EMM) handle. | | | | | | See Note 2 below. | | | +------+------------+---------------------+-------------+--------+ | 0Ch- | NAMETEXT | Device name chain | | RICPS | | 0Fh | | next pointer | | | +------+------------+---------------------+-------------+--------+ | 10h- | NAMEPREV | Device name chain | | RICPS | | 13h | | previous | | | +------+------------+---------------------+-------------+--------+ | 14h- | NAMEPTR | Device name field | Offset of | APPL | | 15h | | offset | name within | | | | | | task header | | | | | | segment | | +------+------------+---------------------+-------------+--------+ | 16h | NAMELENGTH | Device name length | NAMELENGTH | APPL | | | | | 1-255 | | +------+------------+---------------------+-------------+--------+Note:
1. The device number (DEVNUM) parameter is four bytes. For all resources except for semaphores, Storage Blocks, and expanded memory handles, byte 08h is the device number, and the last three bytes of this field are not used. For Storage Block, bytes 08h-09h are the storage block segment and bytes 0Ah-0Bh are not used. For semaphores, 08h-0Bh contain the semaphore handle. For expanded memory handles, bytes 08h-09h are the expanded memory handle.See the particular resource block for the device type selected in byte 05h to determine the valid entries for DEVNUM. This information is contained in the Realtime Interface Co-Processor Software Technical Reference Volume 2 and in the Realtime Interface Co-Processor Firmware Technical Reference Volume 3.
Note:
2. EMM applies to IBM Realtime Interface Co-Processor Portmaster Adapter/A only.
The user can request the allocation of any available resource of the specified resource type (Software Timers, DMA Channels, User Queues, Hardware Timers, and Semaphores).
The ALLOC Supervisor Call accepts a value of FFh as the device number (byte 5 of the resource block) for allocation requests of Software Timers, DMA Channels, User Queues, Hardware Timers, and Semaphores. Specifying a FFh allocates the next available resource of the requested type. Upon receipt of the resource, byte 5 of the resource block is overridden and returns the allocated resources' actual device number. There is no conflict between the request of a named resource and the specification of a non-specific device number.
When tasks are loaded or built, the user must specify the task number as a parameter of the load or build. Task numbers should be assigned upon availability to prevent the request of an unavailable task number. RICPS allows tasks to be loaded and built using non-specific task numbers. For more information on loading tasks using non-specific task numbers, see the Request Task Load Realtime Control Microcode system unit commands. For more information on building tasks using non-specific task numbers, see the Build Supervisor Call.
With the RICPS Post Code Management services, a task requests that post codes be queued in a task-specified area of task-specified length, to save Post Codes.
A semaphore is a signal mechanism used to control access to resources and to synchronize the execution of multiple tasks. When used to control access to a resource, the initial numeric value of the semaphore (count) corresponds to the number of units available of the resource protected by the semaphore.
To allocate a unit of resource, a task requests the semaphore, causing the semaphore count to decrease by one. If the result is greater than or equal to zero, the task continues; if the result is less than zero, RICPS places the task in a wait queue for the semaphore. When a task no longer needs a resource, it releases the semaphore, causing the semaphore count to increase by one and RICPS to post the highest priority task waiting on the semaphore. If two or more tasks have the same priority level, the first task placed in the wait queue is the first task posted.
When the resource is shared data, the semaphore is initialized to 1 and used as described above to ensure that only one task at a time has access to the shared data.
System and RAM semaphores are supported. System semaphores are treated like regular RICPS resources. System semaphores:
RAM semaphores:
A Semaphore Resource Block is required to support system semaphores. The format of the Semaphore Resource Block is:
+======+============+=====================+=============+========+ | Byte | Definition | Descriptions | Comment | Set By | +======+============+=====================+=============+========+ | 00h- | NEXT | Pointer to next | | RICPS | | 01h | | resource block | | | +------+------------+---------------------+-------------+--------+ | 02h- | PREV | Pointer to previous | | RICPS | | 03h | | resource block | | | +------+------------+---------------------+-------------+--------+ | 04h | 22h | Block descriptor | Must be 22h | APPL | +------+------------+---------------------+-------------+--------+ | 05h | SEMANUM | Semaphore number | Must be FFh | APPL | +------+------------+---------------------+-------------+--------+ | 06h | TASKNUM | Task number |Owner of this| APPL | | | | | resource | | | | | | block | | +------+------------+---------------------+-------------+--------+ | 07h | RESERVED | Reserved | Must be 0 | APPL | +------+------------+---------------------+-------------+--------+ | 08h- | SEMHANDLE | Semaphore Handle |RICPS returns| RICPS | | oBh | | Handle | semaphore | | | | | | handle here | | +------+------------+---------------------+-------------+--------+
The Task Priority Control service allows tasks to vary their priority dynamically and to change the priority of another task. This service should be used with care, because a low priority task receives a dispatch cycle only if no higher priority task is awaiting execution. (For a discussion of task priorities, refer to the section on priority queue scheduling in Realtime Interface Co-Processor Software Technical Reference Volume 2 and the Realtime Interface Co-Processor Firmware Technical Reference Volume 3.)
RICPS provides a command to modify the time interval for timeslicing. The default interval is 10 milliseconds. The timeslice interval can vary from a minimum of 5 milliseconds (one count) to a maximum of 5 minutes and 28 seconds (65,535 counts).
Mailbox provides a queueing/messaging facility enhancement to the queue services provided by Realtime Control Microcode and provides optional notification to the receiving task of receipt of a message. Mailbox provides a shared pool of storage from which tasks can allocate message buffers with the MBXAllocMsg function. By convention, message buffer ownership follows the buffer through MBXSend. When the buffer is sent, ownership of the buffer transfers to the owner of that mailbox. After receiving the buffer, that task is free to use it again or to return it to the shared storage pool using MBXFreeMsg.
The Mailbox shared storage pool is configured to a default of 64KB on the first call to MBXRegister or MBXAllocMsg if it is not specifically configured otherwise. The size of the pool can be configured using Configure Mailbox Message Pool command from the system unit or using the MBXConfigMsgPool service.
All mailboxes are known by symbolic names. Given a mailbox name, a task can call MBXAdrs to obtain an address for a mailbox. Given a mailbox address, a task can obtain the mailbox name using the MBXName function. A task must call MBXRegister before opening a mailbox via the MBXOpen function. Once a task calls MBXOpen, any task can resolve the mailbox's address using MBXAdrs and send messages to it using MBXSend. A task that does not own any mailboxes need not use the MBXRegister, MBXDeregister, MBXOpen, and MBXClose functions. It can still use MBXAdrs to resolve another task's mailbox address and then allocate message buffers via MBXAllocMsg and send them to the task via MBXSend. Mailbox imposes no message length restrictions, and passes no buffer lengths to any Mailbox functions. If the user needs length information, it can be included within the message.
The receive notification option of the MBXOpen call is an important feature of the Mailbox services. When a message arrives in a mailbox, the task has the option of receiving a post, an event post, a call through an asynchronous service routine, or any combination of these services. The task can also elect not to use the receive notification option and, instead, poll the mailbox with the MBXReceive service. In addition, the user may choose not to employ any physical queueing of messages, but instead provide a service routine to handle each element as it is sent. This feature could be used to allow a "front end mail processor" that looks at the incoming message and then decides in which physical mailbox to place the message element.
System unit application programs may issue commands to the co-processor adapter requesting various modes of control and services. These commands can be requested by application programs that execute in the system unit. Realtime Control Microcode, supports some commands and the Realtime Interface Co-Processor Programming Services (RICPS) supports other commands. Once the Realtime Control Microcode and RICPS are loaded and started, all commands are serviced by the Realtime Control Microcode or RICPS until a reset of the co-processor adapter occurs.
Issuing commands to the Realtime Control Microcode or RICPS is made much easier by use of the following packages:
When a command request is made to the Realtime Control Microcode or RICPS tasks, the command cannot be performed until the following conditions are met:
If either condition is not met, the command is rejected immediately. The error and Secondary Status available bits in the primary status byte for Realtime Control Microcode or RICPS are set to 1, the Secondary Status field is set to the appropriate error code value, and the value FEh is written to the PC Select Byte of the Interface Block to indicate that an error has occurred.
If both conditions are met, FFh is written in the PC Select Byte and the command is processed. If any errors are detected, the error status code is passed back to the calling program via the Secondary Status field.
When the system unit program sends a command request to a co-processor adapter task that is running under the Realtime Control Microcode or RICPS, the Realtime Control Microcode or RICPS checks to see if the task is busy. If the task is busy, the command is rejected as described previously. If the task is not busy, the called task must perform any further handling. If needed, the task must set up its own Secondary Status Field, set the error bit in its Primary Status Byte in the Interface Block, and interrupt the system unit.
This section contains descriptions of the Realtime Control Microcode commands enhanced by RICPS:
+==========+==========+=================+ | Command | Name | Function | | Byte | | | | Number | | | +==========+==========+=================+ | 01h | Request | Requests a task | | | Task | load | | | Load | | +----------+----------+-----------------+ | 03h | Request | Requests a task | | | Task | load with | | | Load | boundary | | | with | definition | | | boundary | | +----------+----------+-----------------+ | 0Ch | Request | Requests a task | | | Task | load in low | | | Load low | memory with | | | | boundary | | | | definition | +----------+----------+-----------------+ | 20h | Get | Gets the task | | | RICPS's | number of RICPS | | | Task | | | | number | | +----------+----------+-----------------+These commands are issued to the Realtime Control Microcode task 0. The commands are arranged in the order of their command byte value.
The command may be given FFh as a task number when a specific task number is unimportant. If no error occurs and FFh is the requested task number, the number assigned by RICPS is returned in the Realtime Control Microcode input buffer. After the command completes, the Realtime Control Microcode interrupts the system unit.
For a detailed description of the Request Task Load function, refer to Realtime Interface Co-Processor Software Technical Reference Volume 1 and the Realtime Interface Co-Processor Firmware Technical Reference.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 01h
Entry Parameters
(Realtime Control Microcode output buffer.)
Byte 00h = Task number (may be FFh).
Bytes 01h and 02h = Low-order word of the task size.
Bytes 03h and 04h = High-order word of the task size.
Exit Parameters
(Realtime Control Microcode input buffer)
Bytes 00h and 01h = Segment value of where the task is to be loaded
in the co-processor adapter's storage.
Byte 02h = Assigned task number (if FFh was specified).
Errors
+=========+=========+===================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+===================+ | 02h | 02h | Insufficient | | | | storage | +---------+---------+-------------------+ | 02h | 05h | Invalid task | | | | number | +---------+---------+-------------------+ | 02h | 06h | Task already | | | | loaded | +---------+---------+-------------------+ | 02h | 0Eh | Task number not | | | | available | +---------+---------+-------------------+
The command may be given FFh as a task number when a specific task number is unimportant. If no error occurs and FFh is the requested task number, the number assigned by RICPS is returned in the Realtime Control Microcode input buffer. After the command completes, the Realtime Control Microcode interrupts the system unit.
For a detailed description of the Request Task Load With Boundary function, refer to Realtime Interface Co-Processor Software Technical Reference Volume 1 and the Realtime Interface Co-Processor Firmware Technical Reference.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 03h
Entry Parameters
(Realtime Control Microcode output buffer)
Byte 00h = Task number (may be FFh).
Bytes 01h and 02h = Low-order word of the task size.
Bytes 03h and 04h = High-order word of the task size.
Bytes 05h and 06h = Paragraph boundary requested for a task.
Exit Parameters
(Realtime Control Microcode input buffer)
Bytes 00h and 01h = Segment value of where the task is to be loaded
in the co-processor adapter's storage.
Byte 02h = Assigned task number (if FFh was specified).
Errors
+=========+=========+===================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+===================+ | 02h | 02h | Insufficient | | | | storage | +---------+---------+-------------------+ | 02h | 05h | Invalid task | | | | number | +---------+---------+-------------------+ | 02h | 06h | Task already | | | | loaded | +---------+---------+-------------------+ | 02h | 0Eh | Task number not | | | | available | +---------+---------+-------------------+
The command may be given FFh as a task number when a specific task number is unimportant. If no error occurs and FFh is the requested task number, the number assigned by Realtime Control Microcode is returned in the Realtime Control Microcode input buffer. After the command completes, Realtime Control Microcode interrupts the system unit.
For a detailed description of the Request Task Load Low function, refer to Realtime Interface Co-Processor Technical Reference Volume 1 and the Realtime Interface Co-Processor Firmware Technical Reference.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 0Ch
Entry Parameters
(Realtime Control Microcode output buffer)
Byte 00h = Task number (may be FFh).
Bytes 01h and 02h = Low-order word of the task size.
Bytes 03h and 04h = High-order word of the task size.
Bytes 05h and 06h = Paragraph boundary requested for a task.
Exit Parameters
(Realtime Control Microcode input buffer)
Bytes 00h and 01h = Segment value of where the task is to be loaded
in the co-processor adapter's storage.
Byte 02h = Assigned task number (if FFh was specified).
Errors
+=========+=========+===================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+===================+ | 02h | 02h | Insufficient | | | | storage | +---------+---------+-------------------+ | 02h | 05h | Invalid task | | | | number | +---------+---------+-------------------+ | 02h | 06h | Task already | | | | loaded | +---------+---------+-------------------+ | 02h | 0Eh | Task number not | | | | available | +---------+---------+-------------------+
This command, issued through the Realtime Control Microcode command path, allows a system unit application to determine the task number associated with the RICPS. The RICPS task number is required when the user issues commands to RICPS from the system unit. An error return indicates that RICPS has not been loaded. After the command completes, the Realtime Control Microcode interrupts the system unit and returns RICPS's task number in the Realtime Control Microcode input buffer.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 20h
Entry Parameters
None.
Exit Parameters
(Realtime Control Microcode input buffer)
Bytes 00h = RICPS's task number.
Errors
+=========+=========+===================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+===================+ | 02h | 01h | RICPS not loaded | +---------+---------+-------------------+
This section contains descriptions of the RICPS system unit commands included in RICPS:
+==========+=============+=================+ | Command | Name | Function | | Byte | | | | number | | | +==========+=============+=================+ | 02h | Set | Defines a | | | Timeslice | Timeslice | | | Interval | interval | +----------+-------------+-----------------+ | 03h | ResolveName | Reconciles a | | | | resource or | | | | task name | +----------+-------------+-----------------+ | 04h | Enable | Enables system | | | system | semaphores | | | semaphores | | +----------+-------------+-----------------+ | 06h | Configure | Configures the | | | mailbox | Mailbox Message | | | message | Pool | | | pool | | +----------+-------------+-----------------+These commands are issued to RICPS's task number (determined by issuing the "Get RICPS's Task Number" system unit command). The commands are arranged in the order of their command byte values.
This command defines the interval that any task may run before timeslicing forces a dispatch cycle. If an interval of 0 is requested, the interval is not changed and the current interval is returned. The timeslice interval can vary from a minimum of 5 milliseconds (1 count) to a maximum of 5 minutes and 28 seconds (65,535 counts). RICPS issues an interrupt to the system unit when the command completes.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 02h
Entry Parameters
(RICPS output buffer)
Bytes 00h and 01h = Timeslice interval in counts
(1 count = 5 milliseconds).
Exit Parameters
(RICPS input buffer)
Bytes 00h and 01h = Previous timeslice interval in counts.
Errors
None.
This command allows a system unit application to reconcile a known task or resource name with the corresponding task or resource number. If a task or resource is not named, the name is not found and an error is returned. RICPS issues an interrupt to the system unit when the command completes.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 03h
Entry Parameters
(RICPS output buffer)
Byte 00h = Device Type:
00h Task
01h User Interrupt Vector
02h Storage Block
03h SCC/CIO Port
04h DMA Channel
05h FIFO Queue
06h Hardware Timer
07h Software Timer
08h RS-232-C Port
09h SCC Port
0Ah CIO Port
0Bh RS-422-A Port
20h LIFO Queue
21h Priority Queue
22h Semaphore
Byte 01h = Name Length (Name Length from 1 through 255).
Bytes 02h - (Name Length + 2h) = User-specified Name.
(RICPSE output buffer)
Byte 00h = Device type:
00h Task
01h User Interrupt Vector
02h Storage Block
04h DMA Channel
05h FIFO Queue
06h Hardware Timer
07h Software Timer
09h SCC Port
0Ah CIO Port
0Ch Communications Port
0Dh Expanded Memory
20h LIFO Queue
21h Priority Queue
22h Semaphore
Byte 01h = Name Length (Name Length from 1 through 255).
Bytes 02h - (Name Length + 2h) = User-specified Name.
Exit Parameters
(RICPS input buffer)
Byte 00h = Task number or resource number, if device type is not
Semaphore, or Storage Block.
Bytes 00h and 01h = Storage Block Segment, if device type is
Storage Block.
Bytes 00h-03h = Semaphore handle, if device type is Semaphore.
(RICPSE input buffer)
Byte 00h = Task number or resource number, if device type is not
Semaphore, Storage Block, or Expanded Memory.
Bytes 00h and 01h = Storage Block Segment, if device type is
Storage Block.
Bytes 00h-03h = Semaphore handle, if device type is Semaphore.
Bytes 00h-01h = Expanded Memory handle, if the type is Expanded Memory.
Errors
(RICPS secondary status buffer)
+=========+=========+===================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+===================+ | 02h | 03h | Invalid command | | | | data (Name length | | | | = 0, or invalid | | | | device type | | | | specified) | +---------+---------+-------------------+ | 02h | 0Fh | Name not found | +---------+---------+-------------------+
Initially, system semaphores are disabled. To enable system semaphores, issue this command with the maximum number of system semaphores needed. RICPS interrupts the system unit at the completion of this command.
Note:
To change the maximum number of system semaphores, reset the co-processor adapter and reissue this command with the new maximum number of system semaphores.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 04h
Entry Parameters
(RICPS output buffer)
Byte 00h = Requested maximum number of semaphores (1 through 255).
Exit Parameters
None.
Errors
+=========+=========+====================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+====================+ | 02h | 02h | Insufficient | | | | storage for system | | | | semaphores | +---------+---------+--------------------+ | 02h | 03h | Invalid command | | | | data (Requested | | | | maximum number of | | | | semaphores = 0) | +---------+---------+--------------------+ | 02h | 09h | System semaphores | | | | already enabled | +---------+---------+--------------------+
The Configure Mailbox Message Pool command sets the size of the Mailbox shared storage pool. RICPS issues an interrupt to the system unit when the command completes.
ASSEMBLER INTERFACE
INVOCATION: Command Byte 06h
Entry Parameters
(RICPS output buffer)
Bytes 00h and 01h = Size of storage pool in paragraphs.
(A 0 disables the use of shared message pool
and mailbox services.)
Exit Parameters
None.
Errors
+=========+=========+===================+ | Byte 0 | Byte 1 | Meaning | +=========+=========+===================+ | 02h | 02h | Insufficient | | | | storage for | | | | message pool | +---------+---------+-------------------+ | 02h | 09h | Message pool | | | | already allocated | +---------+---------+-------------------+
Tasks that call the Realtime Control Microcode STAYRES Supervisor Call (SVC) while using RICPS are under the following restrictions, which are in addition to any restrictions imposed by the STAYRES SVC:
Refer to the Realtime Interface Co-Processor Software Technical Reference Volume 3 and the Realtime Interface Co-Processor Firmware Technical Reference for the description of the STAYRES Supervisor Call. For a discussion of a task control block, refer to the Realtime Interface Co-Processor Software Technical Reference Volume 2 and the Realtime Interface Co-Processor Firmware Technical Reference.
The following Supervisor Calls (SVCs) are requested through the Realtime Interface Co-Processor Programming Services to perform functions for application tasks executing on the co-processor adapter. Supervisor Calls may be called from a task's mainline code and from software interrupt handlers. Supervisor Calls may not be accessed from hardware interrupt handlers
A Supervisor Call is invoked via a call to Interrupt Vector INT 56h with the requested Supervisor Call number in register AH. Register AH and other registers are used to pass parameters to the Supervisor Call handler that performs the requested function. All user registers (except register AL upon error detection) are preserved unless specified by the particular Supervisor Call.
When a task executes a Supervisor Call and an error is detected by the Realtime Interface Co-Processor Programming Services, the Carry Flag is set on and register AL is set to an error code. The Realtime Interface Co-Processor Programming Services returns to the requesting task as soon as the first error condition is found. Other error conditions may exist; therefore, the Supervisor Call parameters should be checked before the Supervisor Call is executed again.
This section contains descriptions of the Supervisor Calls supported by RICPS:
+===========+========+========+================================+ | Interrupt | AH Reg | Name | Function | | Number | | | | +===========+========+========+================================+ | 56h | 39h | Build | Simulates a task load from the | | | | | system unit | +-----------+--------+--------+--------------------------------+ | 56h | 46h | Alloc | Allocates a co-processor | | | | | adapter resource (a name, a | | | | | system semaphore, or a specific| | | | | or non-specific resource) | +-----------+--------+--------+--------------------------------+ | 56h | 47h | Return | Returns a co-processor adapter | | | | | resource | +-----------+--------+--------+--------------------------------+The Supervisor Calls are arranged in the order of their AH values.
Note:
The C Call Format support for these Supervisor Calls is not included with this product. To program to this interface for these Supervisor Calls, the IBM Realtime Interface Co-Processor C Support is required.
The Build Supervisor Call simulates a task load from the system unit. It accepts a value of FFh as a task number. If no error exists and the requested task number is FFh, the assigned task number is returned as an exit parameter.
For a detailed description of the Build function, refer to Realtime Interface Co-Processor Software Technical Reference Volume 1 and the Realtime Interface Co-Processor Firmware Technical Reference.
ASSEMBLER INTERFACE
INVOCATION: INT 56h
Entry Parameters
AH = 39h.
AL = Task number to build (may be FFh).
ES = Segment of the task header.
DX = Offset of the task header.
BX = 0 if child task being built or offset of Storage Resource
Block if peer task being built.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
AH = Unchanged if requested task number is not FFh;
assigned task number if requested task number is FFh.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 13h | Invalid data | +---------+-------------------+ | 14h | Invalid task | | | number | +---------+-------------------+ | 20h | Task number not | | | available | +---------+-------------------+C CALL FORMAT
int SVCBuild(Task, TaskStor, Thead)
unsigned char Task; /* Task number of the task */
/* to build */
struct srbstruct *TaskStor; /* Pointer to storage */
/* request block */
struct thstruct far *Thead; /* Pointer to task header */
Entry Parameters
Task is the task number of the task to build. A value of 0xFF indicates that the task number does not have to be a specific number, and the next available task number is used.
TaskStor is a pointer to the storage request block given to the built task. If this parameter is NULL, the task is built in the building task's storage.
Thead is a pointer to the task header for the task that is being built.
Exit Parameters
If 0xFF was specified as the task number, the assigned task number replaces the 0XFF in the built task's task header.
Example Call
#include "icadeclt.h"
#include "ricps.h"
typedef unsigned char uchar;
typedef unsigned int unsigned int;
int ReturnCode; /* Return code */
uchar TaskNumber; /* Task number */
/* struct srbstruct and struct thstruct are declared in icadeclt.h. */
/* The file icadeclt.h is included with the IBM Realtime Interface */
/* Co-Processor C Language Support. */
struct srbstruct StorageRequestBlock =
{
0, 0, /* Next and Previous pointers */
2, /* Storage request block descriptor */
1, /* Search high (1) or low (0) storage*/
0, /* Task number */
0, /* Reserved, must be 0 */
1, /* Requested storage boundary */
2 /* Requested size, in paragraphs */
};
/* Pointer to child task header */
struct thstruct far *TaskHeaderPtr;
/* Allocate storage a task header for a child task */
/* ... Get TaskNum ... */
/* Fill in storage request block */
/* Task number */
StorageRequestBlock.TSKNUM = TaskNumber;
/* Allocate storage for task header */
/* of the child task */
ReturnCode = svcalloc((uchar *) &StorageRequestBlock);
/* ... Check return code ... */
/* Initialize the task header for a child task */
/* TaskHeaderPtr = far pointer to */
/* storage block */
*(((unsigned int *) &TaskHeaderPtr) + 1) = StorageRequestBlock.SRSEG;
*((unsigned int *) &TaskHeaderPtr) = 0;
/* Set up task header, overlaying */
/* the structure over the start */
/* of the memory block */
TaskHeaderPtr->LMODL = 0x20; /* Requested size is 2 paragraphs */
/* (32 bytes) */
TaskHeaderPtr->TASK = 0xFF; /* Task number (non-specific) */
TaskHeaderPtr->ZERO1 = 0; /* Must be 0 */
TaskHeaderPtr->TSKID = 0XACE; /* User-defined task id */
TaskHeaderPtr->PRIRTY = 5; /* Task Priority */
TaskHeaderPtr->ZERO2 = 0; /* Must be 0 */
TaskHeaderPtr->DSEG = StorageRequestBlock.SRSEG; /* Data segment */
TaskHeaderPtr->SSEG = StorageRequestBlock.SRSEG; /* Stack segment */
TaskHeaderPtr->SPTR = 0x20; /* Stack pointer */
TaskHeaderPtr->RBPTR = 0; /* Request block pointer */
/* ... Fill in CMDPTR and INITPTR to appropriate */
/* interrupt handler ... */
/* Build the child task using a non-specific task number */
/* Build child task */
ReturnCode = svcbuild(0xFF, (unsigned int) 0, TaskHeaderPtr);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0013h Invalid data.
0014h Invalid task number.
0020h Task number not available.
The Alloc Supervisor Call may be used to allocate the following resources:
The ALLOC Supervisor Call accepts a value of FFh as the device number (byte 5 of the resource block) for allocation requests of Software Timers, DMA Channels, User Queues, Hardware Timers, and Semaphores. Specifying a FFh allocates the next available resource of the requested type.
ASSEMBLER INTERFACE
INVOCATION: INT 56h
Entry Parameters
AH = 46h
ES = Segment of resource block
DX = Offset of resource block
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 08h | Insufficient | | | storage | +---------+-------------------+ | 13h | Invalid data | +---------+-------------------+ | 15h | Invalid timer | | | number | +---------+-------------------+ | 16h | Invalid queue | | | number | +---------+-------------------+ | 18h | Duplicate name | +---------+-------------------+ | 19h | Device number not | | | available | +---------+-------------------+ | 21h | Invalid semaphore | +---------+-------------------+C CALL FORMAT
int svcalloc(Offset) char *Offset; /* Offset of resource block */Entry Parameters
Offset is the offset of a resource block used to allocate a resource.
Exit Parameters
None.
Example Call
#include "icadeclt.h"
#include "ricps.h"
/* The file icadeclt.h is included with the IBM Realtime Interface */
/* Co-Processor C Language Support. */
int ReturnCode; /* Return code */
/* struct SEMRB is declared in ricps.h */
struct SEMRB SemaphoreRequestBlock =
{
0, 0, /* Next and Previous pointers */
0x22, /* Semaphore request block descriptor*/
0xFF, /* Semaphore number (non-specific) */
0, /* Task number */
0, /* Reserved, must be 0 */
0 /* Semaphore handle returned here */
};
/* Allocate a non-specific system */
/* semaphore */
ReturnCode = svcalloc((char *) &SemaphoreRequestBlock);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0008h Insufficient storage.
0013h Invalid data.
0015h Invalid timer number.
0016h Invalid queue number.
0018h Duplicate name.
0019h Device number not available.
0021h Invalid semaphore.
The Return Supervisor Call returns a resource of the following types:
Any tasks waiting on a system semaphore that is returned will be invoked with an error.
ASSEMBLER INTERFACE
INVOCATION: INT 56h
Entry Parameters
AH = 47h.
ES = Segment of resource block.
DX = Offset of resource block.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 13h | Invalid data | +---------+-------------------+ | 15h | Invalid timer | | | number | +---------+-------------------+ | 16h | Invalid queue | | | number | +---------+-------------------+ | 17h | Name not found | +---------+-------------------+ | 21h | Invalid semaphore | +---------+-------------------+C CALL FORMAT
int SVCDeall(Offset) char *Offset; /* Offset of resource block */Entry Parameters
Offset is the offset of a resource block used to return a resource.
Exit Parameters
None.
Example Call
#include "icadeclt.h"
#include "ricps.h"
/* The file icadeclt.h is included with the IBM Realtime Interface */
/* Co-Processor C Language Support. */
int ReturnCode; /* Return code */
/* struct SEMRB is declared in ricps.h */
struct SEMRB SemaphoreRequestBlock =
{
0, 0, /* Next and Previous pointers */
0x22, /* Semaphore request block descriptor*/
0xFF, /* Semaphore number (non-specific) */
0, /* Task number */
0, /* Reserved, must be 0 */
0 /* Semaphore handle returned here */
};
/* Allocate a non-specific system */
/* semaphore */
ReturnCode = svcalloc((uchar *) &SemaphoreRequestBlock);
/* ... Use the semaphore ... */
/* Return the semaphore */
ReturnCode = svcdeall((char *) &SemaphoreRequestBlock);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0013h Invalid data.
0015h Invalid timer number.
0016h Invalid queue number.
0017h Name not found.
0021h Invalid semaphore.
The following Service Interrupts (SVIs) can be accessed through the Realtime Interface Co-Processor Programming Services to perform various task services and are available to application tasks executing on the co-processor adapter.
An RICPS Service Interrupt is invoked via a call to Interrupt Vector INT 5Eh with the requested Service Interrupt number in register AH. Register AH and other registers pass parameters in the Service Interrupt handler that invoke the appropriate module to perform the requested function. All user registers (except register AL upon error detection) are preserved unless specified by the particular Service Interrupt. Service Interrupts may be called from a task's mainline code and from software interrupt handlers. Some Service Interrupts can be called from hardware interrupt handlers.
When a task executes a Service Interrupt and an error is detected by the Realtime Interface Co-Processor Programming Services, the Carry Flag is set on and register AL is set to an error code. The Realtime Interface Co-Processor Programming Services returns to the requesting task as soon as the first error condition is found. Other error conditions could exist; therefore, the Service Interrupt parameters should be checked before the Service Interrupt is executed again. This section contains descriptions of the Service Interrupts included in RICPS:
+===========+=====+==================+=======================================+ | Interrupt | AH | Name | Function | | number | Reg | | | +===========+=====+==================+=======================================+ | 5Eh | 00h | RICPSPresence | Determines the presence of RICPS | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 01h | EventEnable | Enables event management | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 02h | EventDisable | Disables event management | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 03h | EventPost | Posts an event | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 04h | EventReset | Resets an event | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 05h | EventWait | Specifies an event to wait on | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 06h | WaitTimeout | Specifies a wait pending a timeout | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 07h | ChangePriority | Changes a task's priority | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 08h | PostCodeQEnable | Enables post code queuing | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 09h | PostCodeQDisable | Disables post code queuing | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 0Ah | PostCodeQuery | Queries the post code queue | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 0Bh | PostCodeGet | Gets the oldest post code | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 0Ch | PostCodeClear | Clears the post code queue | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 0Dh | ResolveName | Reconciles a resource or task name | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 0Eh | SemRequest | Requests a semaphore | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 0Fh | SemRelease | Releases a semaphore | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 10h | SemTest | Tests a semaphore | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 11h | SemInit | Initializes a semaphore's count | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 12h | SemClose | Closes a semaphore | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 13h | MBXRegister | Registers the use of mailboxes | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 14h | MBXDeregister | Deregisters the use of mailboxes | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 15h | MBXOpen | Opens a mailbox | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 16h | MBXClose | Closes a mailbox | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 17h | MBXSend | Sends a message to a mailbox | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 18h | MBXReceive | Receives a message | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 19h | MBXCount | Counts a mailbox's messages | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 1Ah | MBXAdrs | Gets a mailbox's address | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 1Bh | MBXName | Gets a mailbox's name | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 1Ch | MBXAllocMsg | Allocates a message buffer | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 1Dh | MBXFreeMsg | Returns a message buffer | +-----------+-----+------------------+---------------------------------------+ | 5Eh | 1Eh | MBXConfigMsgPool | Configures the message pool | +-----------+-----+------------------+---------------------------------------+The commands are arranged in the order of their AH register values.
This service allows tasks running on the co-processor to determine whether RICPS is loaded.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 00h.
Exit Parameters
Carry Flag = 1 if RICPS has not been installed.
0 if RICPS is installed and running.
AX = Unchanged if RICPS is installed and running.
undefined if RICPS has not been installed.
Errors
None.
C CALL FORMAT
int far RICPSPresence (void)Entry Parameters
None.
Exit Parameters
None.
Example Call
#include "ricps.h"
if (RICPSPresence())
{
/* ... RICPS is installed ... */
}
else
{
/* ... RICPS is not installed ... */
}
RETURN CODES
0000h RICPS not installed.
0001h RICPS installed.
This service enables event management for a task. Events may be posted to the task after event management is enabled. A task may enable event management for itself or for any other task.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 01h.
AL = Task number.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 14h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
int far EventEnable (Task) unsigned char Task; /* Task # */Entry Parameters
Task is the task number of the task for which event management is enabled.
Exit Parameters
None.
Example Call
#include "ricps.h" int ReturnCode; /* Return code */ unsigned char TaskNumber; /* Task number */ /* ... Fill in TaskNumber ... */ ReturnCode = EventEnable(TaskNumber); /* Enable event management */RETURN CODES
0000h Normal completion; no errors.
0014h Invalid task number.
This service disables event management for a task. A task may disable event management for itself or for any other task.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 02h.
AL = Task number.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 14h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
int far EventDisable (Task) unsigned char Task; /* Task # */Entry Parameters
Task is the task number of the task for which event management is disabled.
Exit Parameters
None.
Example Call
#include "ricps.h" int ReturnCode; /* Return code */ unsigned char TaskNumber; /* Task number */ /* ... Fill in TaskNumber ... */ ReturnCode = EventDisable(TaskNumber); /* Disable event management */RETURN CODES
0000h Normal completion; no errors.
0014h Invalid task number.
This service posts an event to a task. It logically ORs the specified event(s) to the specified task's event flag. If this event completes the waiting task's event, the waiting task is posted with a post code value of 0055h. If the task is not waiting on an event, the task's event flag is updated. Posting an event value of 0 is equivalent to querying the event flag. A task may post an event to another task without enabling event management for itself.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 03h.
AL = Task number to post.
CX = Event value to be ORed with specified task's event flag.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
CX = Resulting value of task's event flag after this post.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 14h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
int far EventPost (Task, Event, EventFlag) unsigned char Task; /* Task # */ unsigned int Event; /* Event value to post. */ unsigned int far *EventFlag /* Event flag returned here */Entry Parameters
Task is the task number of the task to post.
Event is the event value to logically OR with the specified task's event flag.
Exit Parameters
EventFlag is a pointer to the value of the task's event flag after this post.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
unsigned int far *EventFlag; /* Pointer to event flag */
/* ... Fill in TaskNumber ... */
/* Post event 0x0003 */
ReturnCode = EventPost(TaskNumber, 0x0003, EventFlag);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0014h Invalid task number.
This service resets all or part of the specified task's event flag. The value provided is logically ANDed with the specified task's event flag.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 04h.
AL = Task number.
CX = Event clear mask to be ANDed with event flag (0 clears the flag).
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
CX = Resulting value of task's event flag after this post.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 14h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
int far EventReset (Task, EventMask, EventFlag)
unsigned char Task; /* Task # */
unsigned int EventMask; /* Clear mask to be ANDed with */
/* the event flag */
unsigned int far *EventFlag /* Event flag returned here */
Entry Parameters
Task is the task number of the task's event flag that is to be reset.
EventMask is the value that is ANDed with the event flag of the specified task. This clears particular events. A 0 value clears the entire event flag. A value of 0xFFFF does not clear any event.
Exit Parameters
EventFlag is a pointer to the value of the task's event flag after the events are cleared.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
unsigned int far *EventFlag; /* Pointer to event flag */
/* ... Fill in TaskNumber ... */
/* Reset ALL events */
ReturnCode = EventReset(TaskNumber, 0x0000, EventFlag);
RETURN CODES
0000h Normal completion; no errors.
0014h Invalid task number.
This service waits a task for an event flag value and may not be called from a hardware interrupt handler. If the user-specified events are not satisfied by the event flag, the task is put in an idle or wait state. A timeout may be specified on the EventWait call. The timeout ranges from 0 milliseconds (no wait) to 327.670 seconds in 5 milliseconds increments. A task can choose to wait indefinitely. The timeouts are minimum values, not exact values. A timeout value of -1 indicates to wait indefinitely with no timeout.
Tasks waiting on an event may be posted by either the Post Supervisor Call, Post Service Interrupt, a Timeout Post (post code = 0054h), or an Event Post (post code = 0055h).
Using the event clear mask, a task may clear all or part of its event flag when the task is posted as a result of the requested total event. An event clear mask of FFFFh leaves the event flag unaltered by the event post and the task is responsible for clearing the event flag, if preferred, by using the EventReset service. The EventWait service may not be called from a hardware interrupt handler, and only the task itself may issue the request on its own behalf.
Before a task attempts an EventWait, the task's posted flag must be 0 or the EventWait request is a "no-operation." To facilitate the updating of a task's posted flag in its task control block (TCB), a clear parameter is provided with the C Call Format. (Refer to Realtime Interface Co-Processor Software Technical Reference Volume 2 and the Realtime Interface Co-Processor Firmware Technical Reference for a discussion of a task control block and posted flag.)
The Clear parameter allows a task to optionally clear its posted flag when the task is posted. A non-zero value for Clear causes RICPS to clear the task's posted flag in its task control block when the task is posted. If Clear is 0, the task control block posted flag is left unchanged.
If the events are completed when EventWait is processed, the task is immediately posted with the Event Post code value of 0055h. If the event is not completed, a 0 timeout value causes the task to be posted with a Timeout Post code value of 0054h. Specifying a 0 timeout value causes the task to be immediately posted with a Timeout Post code value of 0054h if the event is not completed when the EventWait is processed.
If a task waits on all events, completion of the EventWait command occurs when all the events specified in the event flag value (passed on the call to EventWait) are set in the task's event flag, or a timeout occurs.
If a task waits on any event, completion of the EventWait command occurs when any bit specified set in the event flag value is also set in the task's event flag, or a timeout occurs.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 05h.
DX = Event flag value.
AL = ALL or ANY flag indicating prerequisite for total event.
00h if ANY events in the event value constitute a total event.
01h if ALL events in the event value are required for a total event.
CX = Event clear mask to be ANDed with event flag on event post.
BX = 0000h for no wait.
0001h to FFFEh for maximum timeout count to wait for events to occur.
FFFFh for wait indefinitely for events to occur.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
+=========+===================+
| AL Code | Meaning |
+=========+===================+
| 05h | Access denied |
+---------+-------------------+
| 13h | Invalid data |
+---------+-------------------+
C CALL FORMAT
int far EventWait (Event, AnyAll, EventMask, Timeout, Clear)
unsigned int Event; /* Event value */
unsigned char AnyAll; /* Total event definition */
/* 0 = ANY events in Event */
/* 1 = ALL events in Event */
unsigned int EventMask; /* Event clear mask to be ANDed */
/* with event flag on event post*/
unsigned int Timeout; /* Wait timeout */
/* 0x0000 no wait */
/* 0xFFFF wait indefinitely */
/* 0xnnnn timeout count */
int Clear; /* Clear posted flag */
Entry Parameters
Event specifies the event(s) to wait on. Each bit corresponds to one event.
AnyAll specifies whether to wait on all events, AnyAll = 1, or to wait on any event, AnyAll = 0.
EventMask is the value that is ANDed with the event flag when a post occurs. This is used to clear particular events. A 0 value clears the entire event flag. A value of 0xFFFF does not clear any event.
Timeout specifies the time, in 5-millisecond increments, to wait before ending the EventWait. 0x0000 means do not wait. 0xFFFF means to wait indefinitely for the event(s) to be satisfied.
Clear is used to clear the posted flag upon completion of the command. A value of 1 means clear the posted flag and 0 means do not clear the posted flag.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
/* ... Enable event management ... */
/* Wait on event value = 0xFFFF, ANY */
/* event, clear mask = 0xFFFF, */
/* timeout = 0, clear posted flag */
ReturnCode = EventWait(0xFFFF, 0x00, 0xFFFF, 0, 1);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0013h Invalid data.
This service may not be called from a hardware interrupt handler. This service allows a task to wait pending a timeout. The timeout is a minimum timeout and is expressed as the count of five-millisecond multiples desired. A timeout value of -1 indicates to wait indefinitely.
Before a task attempts a WaitTimeout, the task's posted flag must be 0 or the WaitTimeout request is a "no-operation." To facilitate the updating of a task's posted flag in its task control block (TCB), a Clear parameter is provided with the C Call Format. (Refer to the Realtime Interface Co-Processor Firmware Technical Reference and the Realtime Interface Co-Processor Software Technical Reference Volume 2 for a discussion of a task control block and posted flag.)
The Clear parameter allows a task to optionally clear its posted flag when the task is posted. A non-zero value for Clear causes RICPS to clear the task's posted flag in its task control block when the task is posted. If Clear is 0, the task control block posted flag is left unchanged.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 06h.
CX = 0000h for no wait at all.
0001h to FFFEh for timeout count.
FFFFh for wait indefinitely.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+C CALL FORMAT
int far WaitTimeout (Timeout, Clear)
unsigned int Timeout; /* Wait timeout */
/* 0x0000 no wait */
/* 0xFFFF wait indefinitely */
/* 0xnnnn timeout count */
int Clear; /* Clear posted flag */
Entry Parameters
Timeout specifies the time, in 5-millisecond increments, to wait before ending the WaitTimeout. 0x0000 means do not wait. 0xFFFF means to wait indefinitely.
Clear is used to clear the posted flag. A value of 1 means clear the posted flag and 0 means do not clear the posted flag.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
/* Wait with timeout 500ms, */
ReturnCode = WaitTimeout(100, 1); /* then clear posted flag */
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
This service may not be called from a hardware interrupt handler.
This service changes the specified task's priority to the specified value or returns the current task priority. A new task priority of 0 does not change the task's priority, but the current task priority is returned.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 07h.
AL = Task number.
CL = New task priority.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
CL = Previous task priority;
(Current task priority if new task priority is 0.)
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 14h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
int far ChangePriority (Task, NewPriority, OldPriority)
unsigned char Task; /* Task # */
unsigned char NewPriority; /* New priority or 0 to */
/* query old priority */
unsigned char far *OldPriority; /* Previous task priority */
/* (current priority if */
/* NewPriority = 0) */
Entry Parameters
Task is the task number of the task who's priority is to be changed.
NewPriority is the new task priority. A value of 0 queries the current task priority.
Exit Parameters
OldPriority is a pointer to the previous task priority. If NewPriority = 0, OldPriority is a pointer to the value of the current task priority.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
unsigned char ReturnedTaskPriority; /* Returned task priority */
/* ... Fill in TaskNumber ... */
/* Change priority to 1 */
ReturnCode = ChangePriority(TaskNumber, 1, &ReturnedTaskPriority);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0014h Invalid task number.
This service may not be called from a hardware interrupt handler.
This service enables post code queuing for a task. If the task's post code in the task control block (TCB) is not 0 when post code queueing is enabled, an error is returned. The post code queue must not overflow a segment boundary. When attempting to enable post code queuing, if it is already enabled, an error is returned.
The length of the post code queue should be 2 times the maximum number of post codes to queue, plus 2. For example, to queue 10 post codes, the post code queue length must be at least (2 x 10) + 2 = 22 bytes.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 08h.
ES = Post code queue segment.
DX = Post code queue offset (Offset + Length - 2 < FFFFh).
CX = Post code queue length (in bytes; 1 < Length < 65,535).
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 13h | Invalid data | +---------+-------------------+C CALL FORMAT
int far PostCodeQEnable (PostCodeQueue, Length) unsigned int far *PostCodeQueue; /*Post code queue area */ unsigned int Length; /*Post code queue length*/Entry Parameters
PostCodeQueue is a pointer to an area used to manage a post code queue. The length of the post code area should be at least 2 times the maximum number of post codes to queue plus 2 bytes long.
Length is the length, in bytes, of the post code queue area.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned int PostCodeQueueArea[100]; /* Post code queue area */
/* Enable Post Code Management, */
/* with a queue size = 200 bytes */
/* (can hold 99 post codes) */
ReturnCode = PostCodeQEnable(PostCodeQueueArea, 200);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0013h Invalid data
This service may not be called from a hardware interrupt handler. This routine requests that post code queuing be disabled. If post code queuing has not been previously enabled, an error is returned. The post code queue must be empty to disable post code queuing.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 09h.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+C CALL FORMAT
int far PostCodeQDisable (void)
Entry Parameters
None.
Exit Parameters
None.
Example Call
#include "ricps.h" int ReturnCode; /* Return code */ ReturnCode = PostCodeQDisable(); /* Disable Post Code Management */RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
If post code queuing is enabled, this service returns the oldest post code in the queue but does not remove it from the queue. (The "oldest" post code means the least recently queued post code.) PostCodeQuery also returns a count of post codes in the queue (including the returned post code). If the post code queue is empty, the returned post code value is 0, meaning no post code. If the post code queue becomes full, the next post code overwrites the oldest post code in the queue and the wrap flag is set. If post code queuing is not enabled, this service returns the specified task's post code from the task control block (TCB). (Refer to the Realtime Interface Co-Processor Firmware Technical Reference and the Realtime Interface Co-Processor Software Technical Reference Volume 2 for a discussion of a task control block and posted flag.)
ASSEMBLER INTERFACE
This service can also be used to determine if post code queuing is enabled. If post codes are not queued, the zero flag = 1 and CX < 2. If post codes are queued, the zero flag indicates whether wrap has occurred. If wrap has not occurred, the zero flag is 0, and CX is the count of the items in the post code queue; otherwise, the zero flag is 1 and CX is the queue length, which must be greater than 1.
INVOCATION: INT 5Eh
Entry Parameters
AH = 0Ah.
AL = Task number.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Zero Flag = 0 if post codes are queued and no wrap has occurred;
1 if post codes are queued and have wrapped or if
post codes are not queued.
DX = TCB post code if post codes are not queued and TCB
post code is not 0; least recently posted post code
if post codes are queued and count is not 0;
otherwise, unchanged.
CX = Number of items in post code queue if post codes are queued;
0000h if post codes are not queued and TCB post code is 0;
0001h if post codes are not queued and TCB post code is not 0.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 014h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
This service can also be used to determine if post code queuing is enabled. If post codes are not queued, *WrapFlag = 1 and *PostCount < 2. If post codes are queued, the wrap flag indicates whether wrap has occurred. If wrap has not occurred, the wrap flag is 0, and *PostCount is the count of the items in the post code queue; otherwise, *WrapFlag is 1 and *PostCount is the queue length, which must be greater than 1.
int far PostCodeQuery (Task, PostCode, WrapFlag, PostCount)
unsigned char Task; /*Task # */
unsigned int far *PostCode; /*Post code, else 0 */
unsigned int far *WrapFlag; /*Post code queue wrap flag */
/* 0 if wrap has not occurred */
/* 1 if wrap has occurred */
unsigned int far *PostCount;/*Count of items in post code */
/* queue if post codes are queued;*/
/*0000h if post codes are not */
/* queued and TCB post code = 0; */
/*0001h if post codes are not */
/* queued and TCB post code != 0. */
Entry Parameters
Task is the task number of the task who's post code is to be queried.
Exit Parameters
PostCode is a pointer to the queried post code. PostCode is a pointer to 0 if there is no post code.
WrapFlag is a pointer to a value that indicates if the post code queue has wrapped or not. WrapFlag points to a 0 if wrap has not occurred and a 1 if wrap has occurred. Wrap occurs when the post code queue becomes full and the next post code overwrites the oldest post code in the queue.
PostCount is a pointer to a count of the number of post codes in the post code queue if post codes are queued. The count is 0x0000 if post codes are not queued and the TCB post code = 0. It is 0x0001 if post codes are not queued and the TCB post code not = 0.
EXAMPLE CALL
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
unsigned int PostCode; /* Post code */
unsigned int WrapFlag; /* Post code queue area wrap flag */
unsigned int PostCount; /* Post code count */
/* ... Fill in TaskNumber ... */
/* Query post code */
ReturnCode = PostCodeQuery(TaskNumber, &PostCode, &WrapFlag, &PostCount);
RETURN CODES
0000h Normal completion; no errors.
0014h Invalid task number.
If post code queuing is enabled, this service removes the oldest post code in the queue, and returns the count of how many post codes are in the queue, including the returned post code. (The "oldest" post code means the least recently queued post code.) If the post code queue is empty, the returned post code value is 0, meaning no post code. If the post code queue becomes full, the next post code overwrites the oldest post code in the queue and the wrap flag sets. Getting a post code from the post code queue resets the wrap flag. If post code queuing is not enabled, this service returns the specified task's post code from the task control block (TCB). Refer to the Realtime Interface Co-Processor Firmware Technical Reference and the Realtime Interface Co-Processor Software Technical Reference Volume 2 for a discussion of a task control block.
If any post codes remain on the post code queue after the oldest post code is returned, the task's posted flag in the task control block is set. This ensures that a subsequent wait returns immediately, because there are still unprocessed post codes in the post code queue. A task can clear its posted flag after calling this service to wait without processing the remaining post codes on the queue.
ASSEMBLER INTERFACE
This service can also be used to determine if post code queuing is enabled. If post code queuing is not enabled, the zero flag = 1 and CX < 2. If post codes are queued, the zero flag indicates if wrap has occurred. If wrap has not occurred, the zero flag is 0 and CX is the count of the items in the post code queue; otherwise, the zero flag is 1 and CX is the queue length, which must be greater than 1.
INVOCATION: INT 5Eh
Entry Parameters
AH = 0Bh.
AL = Task number.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Zero Flag = 0 if post codes are queued and no wrap has occurred;
1 if post codes are queued and have wrapped or if post
codes are not queued.
DX = TCB post code if post codes are not queued and TCB post
code is not 0; least recently posted post code if post
codes are queued and count is not 0; otherwise, unchanged.
CX = Number of items in post code queue if post codes are queued;
0000h if post codes are not queued and TCB post code is 0;
0001h if post codes are not queued and TCB post code is not 0.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 014h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
This service can also be used to determine if post code queuing is enabled. If post code queuing is not enabled, *WrapFlag = 1 and *PostCount < 2. If post codes are queued, the wrap flag indicates if the wrap has occurred. If the wrap has not occurred, the wrap flag is 0, and *PostCount is the count of the items in the post code queue; otherwise, *WrapFlag is 1 and *PostCount is the queue length, which must be greater than 1.
int far PostCodeGet (Task, PostCode, WrapFlag, PostCount)
unsigned char Task; /*Task # */
unsigned int far *PostCode; /*Post code, else 0 */
unsigned int far *WrapFlag; /*Post code queue wrap flag */
/* 0 if wrap has not occurred */
/* 1 if wrap has occurred */
unsigned int far *PostCount;/*Count of items in post code */
/* queue if post codes are queued;*/
/*0000h if post codes are not */
/* queued and TCB post code = 0; */
/*0001h if post codes are not */
/* queued and TCB post code != 0. */
Entry Parameters
Task is the task number of the task with the oldest post code to be returned.
Exit Parameters
PostCode is a pointer to the returned post code. PostCode is a pointer to 0 if there is no post code.
WrapFlag is a pointer to a value that indicates if the post code queue has wrapped or not. WrapFlag points to a 0 if wrap has not occurred and a 1 if wrap has occurred. Wrap occurs when the post code queue fills and the next post code overwrites the oldest post code in the queue.
PostCount is a pointer to a count of the number of post codes in the post code queue if post codes are queued. The count is 0x0000 if post codes are not queued and the TCB post code = 0. It is 0x0001 if post codes are not queued and the TCB post code not = 0.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
unsigned int PostCode; /* Post code */
unsigned int WrapFlag; /* Post code queue area wrap flag */
unsigned int PostCount; /* Post code count */
/* ... Fill in TaskNumber ... */
/* Get post code */
ReturnCode = PostCodeGet(TaskNumber, &PostCode, &WrapFlag, &PostCount);
RETURN CODES
0000h Normal completion; no errors.
0014h Invalid task number.
This service removes all post codes from the post code queue of the specified task, if post codes are queued, and clears the post code in the specified task control block (TCB). Refer to the Realtime Interface Co-Processor Firmware Technical Reference and the Realtime Interface Co-Processor Software Technical Reference Volume 2 for a discussion of a task control block.) If the post code queue has wrapped, this resets the wrap flag. (For a discussion of the wrap flag, see "PostCodeGet (0Bh)".)
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 0Ch.
AL = Task number.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 014h | Invalid task | | | number | +---------+-------------------+C CALL FORMAT
int far PostCodeClear (Task) unsigned char Task; /* Task # */Entry Parameters
Task is the task number of the task who's post code queue is to be cleared.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
/* ... Fill in TaskNumber ... */
/* Clear post code */
ReturnCode = PostCodeClear(TaskNumber);
RETURN CODES
0000h Normal completion; no errors.
0014h Invalid task number.
This service allows a co-processor adapter task to reconcile a known task or resource name with the corresponding task or resource number. If a task or resource is not named, the name is not found and an error is returned.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 0Dh.
For RICPS:
AL = Device type:
00h Task
01h User Interrupt Vector
02h Storage Block
03h SCC/CIO Port
04h DMA Channel
05h FIFO Queue
06h Hardware Timer
07h Software Timer
08h RS-232-C Port
09h SCC Port
0Ah CIO Port
0Bh RS-422-A Port
20h LIFO Queue
21h Priority Queue
22h Semaphore
For RICPSE:
AL = Device type:
00h Task
01h User Interrupt Vector
02h Storage Block
04h DMA Channel
05h FIFO Queue
06h Hardware Timer
07h Software Timer
09h SCC Port
0Ah CIO Port
0Ch Communications Port
0Dh Expanded Memory
CL = Name Length (name length from 1 through 255).
ES:DI = Pointer to desired resource name or task name.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
CL = Task number or resource number, if device type is not
Semaphore, Storage Block, or Expanded Memory Page.
ES = Storage Block Segment, if device type is Storage Block.
Expanded Memory Handle, if device type is Expanded Memory.
ES:CX = Semaphore handle, if device type is Semaphore.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 13h | Invalid data | +---------+-------------------+ | 17h | Name Not found | +---------+-------------------+C CALL FORMAT
int far ResolveName (DeviceType, NameLength, Name, ResourceNum)
unsigned char DeviceType; /* See list in Entry Parameters */
unsigned char NameLength; /* Length of name */
char far *Name; /* Name to resolve */
void far *ResourceNum; /* Resource number, storage block*/
/* segment, Semaphore handle, or */
/* Expanded Memory Handle */
/* returned here */
Entry Parameters
DeviceType is the type of resource to be resolved from a known name to an unknown number.
NameLength is the length, in bytes, of the name being resolved.
Name is a pointer to the name to resolve.
Exit Parameters
ResourceNum is a pointer to the returned resource number of the resource with the specified name.
Example Call
#includeRETURN CODES#include "ricps.h" int ReturnCode; /* Return code */ unsigned char ReturnedTaskNumber; /* Returned task number */ /* Resolve task name: "Task_Name"*/ ReturnCode = ResolveName(DEVTYPE_TASK, strlen("Task_Name"), "Task_Name", &ReturnedTaskNumber);
0000h Normal completion; no errors.
0013h Invalid data.
0017h Name not found.
This service may not be called from a hardware interrupt handler.
This service decreases the semaphore count by one and, if the result is negative, places the task in a wait queue for the semaphore. When the task gains control of the semaphore, it is posted with the semaphore post code (0056h). A task waiting for a semaphore can also be posted by a Post Supervisor Call, a Post Service Interrupt, or a Timeout Post. This service applies to both system and RAM semaphores and only the task itself may issue the request on its own behalf.
Before a task attempts to do a SemRequest, the task's posted flag must be 0, or the SemRequest is a "no-operation." To facilitate the updating of a task's posted flag in its task control block (TCB), a Clear parameter is provided with the C Call Format. Refer to the Realtime Interface Co-Processor Firmware Technical Reference and the Realtime Interface Co-Processor Software Technical Reference Volume 2 for a discussion of a task control block and posted flag.)
The Clear parameter allows a task to optionally clear its posted flag when it is posted. A non-zero value for Clear causes RICPS to clear the task's posted flag in the task control block when the task is posted. If Clear is 0, the task control block posted flag is left unchanged.
Note:
Specifying a 0 timeout value does not cause the task to wait when the semaphore is not readily available. Instead, the task is immediately posted with a Timeout Post code value of 0054h. This allows a task to perform an alternative job if the requested resource is not available at that moment.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 0Eh.
ES:DI = The semaphore handle of the requested semaphore. For a system
semaphore, this is the value returned when the semaphore is
allocated via the Alloc Supervisor Call. For a RAM semaphore, this
is the address of the 8-byte area used to manage the semaphore.
CX = 0000h for no wait (see note above)
0001h to FFFEh for maximum timeout count to wait on a semaphore.
FFFFh for wait indefinitely on a semaphore.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 05h | Access denied | +---------+-------------------+ | 21h | Invalid semaphore | +---------+-------------------+ | 22h | Semaphore closed | +---------+-------------------+C CALL FORMAT
int far SemRequest (SemHand, Timeout, Clear)
SEMHANDLE SemHand; /* Semaphore handle */
unsigned int Timeout; /* Wait timeout */
/* 0x0000 no timeout */
/* 0xFFFF wait indefinitely */
/* 0xnnnn timeout count */
int Clear; /* Clear posted flag */
Entry Parameters
SemHand is the semaphore handle of the requested semaphore. For a system semaphore, this is the value returned when the semaphore is allocated via the Alloc Supervisor Call. For a RAM semaphore, this is the address of the 8-byte area used to manage the semaphore.
Timeout specifies the time, in 5-millisecond increments, to wait before ending the SemRequest. A 0x0000 means do not wait; 0xFFFF means to wait indefinitely for the semaphore.
Clear is used to clear the posted flag. A value of 1 means clear the posted flag and 0 means do not clear the posted flag.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
SEMHANDLE SemaphoreHandle;
/* ... Fill in SemaphoreHandle ... */
/* Request a semaphore with a 5 */
/* millisecond timeout and then */
/* clear the posted flag */
ReturnCode = SemRequest(SemaphoreHandle, 0x0001, 1);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
0021h Invalid semaphore.
0022h Semaphore closed.
This service increments the semaphore count by one and posts the highest priority task waiting for the semaphore with a semaphore post code value of 0056h. If several tasks of equal priority are waiting for the semaphore, the task that requested the semaphore first is posted. This service applies to both RAM and system semaphores.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 0Fh.
ES:DI = For a system semaphore, this is the value returned when the
semaphore is allocated via the Alloc Supervisor Call. For a
RAM semaphore, this is the address of the 8-byte area used to
manage the semaphore.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 21h | Invalid semaphore | +---------+-------------------+ | 23h | Semaphore count | | | maximum | +---------+-------------------+C CALL FORMAT
int far SemRelease (SemHand) SEMHANDLE SemHand; /* Semaphore handle */Entry Parameters
SemHand is the semaphore handle of the requested semaphore. For a system semaphore, this is the value returned when the semaphore is allocated via the Alloc Supervisor Call. For a RAM semaphore, this is the address of the 8-byte area used to manage the semaphore.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
SEMHANDLE SemaphoreHandle; /* Semaphore handle */
/* ... Fill in SemaphoreHandle ... */
/* Release a semaphore */
ReturnCode = SemRelease(SemaphoreHandle);
RETURN CODES
0000h Normal completion; no errors.
0021h Invalid semaphore.
0023h Semaphore count maximum.
This service returns the signed integer count value of the semaphore at the time of call. This service applies to both RAM and system semaphores.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 10h.
ES:DI = For a system semaphore, this is the value returned when the
semaphore is allocated via the Alloc Supervisor Call. For a
RAM semaphore, this is the address of the 8-byte area used
to manage the semaphore.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
AX = Semaphore value if no error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 21h | Invalid semaphore | +---------+-------------------+C CALL FORMAT
int far SemTest (SemHand, SemValue) SEMHANDLE SemHand; /* Semaphore handle */ int far *SemValue; /* Returned semaphore value */Entry Parameters
SemHand is the semaphore handle of the requested semaphore. For a system semaphore, this is the value returned when the semaphore is allocated via the Alloc Supervisor Call. For a RAM semaphore, this is the address of the 8-byte area used to manage the semaphore.
Exit Parameters
SemValue is a pointer to the returned semaphore value.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
SEMHANDLE SemaphoreHandle; /* Semaphore handle */
int SemaphoreValue; /* Returned value of the semaphore */
/* ... Fill in SemaphoreHandle ... */
/* Test a semaphore */
ReturnCode = SemTest(SemaphoreHandle, &SemaphoreValue);
RETURN CODES
0000h Normal completion; no errors.
0021h Invalid semaphore.
This service initializes the count of a semaphore. This routine must be called to initialize a RAM semaphore before it can be used. To create a RAM semaphore, the user should pass the doubleword address (the semaphore handle) of an 8-byte area for the Realtime Interface Co-Processor Programming Services to manage the semaphore. When a system semaphore is allocated, its initial default count is 1. Tasks may also vary this initial default count via the SemInit service. This service assumes that no tasks are waiting for the semaphore when the call to SemInit is made. To change the count of a semaphore already in use, close and reallocate (only system semaphores) the semaphore, then call SemInit with the new count. This service applies to both RAM and system semaphores.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 11h.
AL = 00h
ES:DI = For a system semaphore, this is the value returned when the
semaphore is allocated via the Alloc Supervisor Call. For a
RAM semaphore, this is the address of the 8-byte area used
to manage the semaphore.
CX = Semaphore count.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 21h | Invalid semaphore | +---------+-------------------+C CALL FORMAT
int far SemInit (SemHand, SemValue, Reserved) SEMHANDLE SemHand; /* Semaphore handle */ int SemValue; /* Initialize semaphore value */ unsigned char Reserved; /* Must be 0 */Entry Parameters
SemHand is the semaphore handle of the requested semaphore. For a system semaphore, this is the value returned when the semaphore is allocated via the Alloc Supervisor Call. For a RAM semaphore, this is the address of the 8-byte area used to manage the semaphore.
SemValue is the requested initial value of the semaphore.
Reserved is a reserved parameter; it must be equal to 0.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
SEMHANDLE SemaphoreHandle; /* Semaphore handle */
/* ... Fill in SemaphoreHandle ... */
/* Initialize a semaphore */
/* to a count of 10 */
ReturnCode = SemInit(SemaphoreHandle, 10, 0);
RETURN CODES
0000h Normal completion; no errors.
0021h Invalid semaphore.
This service closes a semaphore. If a task owning a system semaphore unloads, tasks waiting for all but RAM semaphores are notified. SemClose is intended primarily to gracefully terminate the use of a RAM semaphore; however, it can also be used on system semaphores. Any tasks waiting for the semaphore return from the wait call with an error code indicating that the semaphore has been closed. This provides an exit for tasks to terminate use of a RAM semaphore. If used for a system semaphore, the semaphore reverts to the initial default state (the semaphore count equals 1 and no tasks are waiting).
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 12h.
ES:DI = For a system semaphore, this is the value returned when the
semaphore is allocated via the Alloc Supervisor Call. For a
RAM semaphore, this is the address of the 8-byte area used
to manage the semaphore.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AL = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AL Code | Meaning | +=========+===================+ | 21h | Invalid semaphore | +---------+-------------------+C CALL FORMAT
int far SemClose (SemHand) SEMHANDLE SemHand; /* Semaphore handle */Entry Parameters
SemHand is the semaphore handle of the requested semaphore. For a system semaphore, this is the value returned when the semaphore is allocated via the Alloc Supervisor Call. For a RAM semaphore, this is the address of the 8-byte area used to manage the semaphore.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
SEMHANDLE SemaphoreHandle; /* Semaphore handle */
/* ... Fill in SemaphoreHandle ... */
/* Close a semaphore */
ReturnCode = SemClose(SemaphoreHandle);
RETURN CODES
0000h Normal completion; no errors.
0021h Invalid semaphore.
This service registers the use of mailboxes and may not be called from an interrupt handler. It must be called before a task can open a mailbox. If this is the first task to call Mailbox services, the shared storage pool is configured at this time. The MaxBoxes parameter specifies the maximum number of mailboxes the task can open.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 13h.
AL = TaskNum.
CX = MaxBoxes.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 0005h | Access denied | +---------+-------------------+ | 8001h | Already | | | registered | +---------+-------------------+ | 8005h | Storage exhausted | +---------+-------------------+C CALL FORMAT
int far MBXRegister (TaskNum, Reserved, MaxBoxes) int TaskNum; /* Task # */ int Reserved; /* Reserved */ int MaxBoxes; /* Number of mailboxes */Entry Parameters
TaskNum The task number of the task for which the use of mailboxes
is to be registered.
Reserved A reserved parameter; it must be equal to 0.
MaxBoxes The requested maximum number of mailboxes the task can open.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
unsigned char TaskNumber; /* Task number */
/* ... Fill in TaskNumber ... */
/* Register 10 mailboxes */
ReturnCode = MBXRegister(TaskNumber, 0, 10);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
8001h Already registered.
8005h Storage exhausted.
This service deregisters the use of mailboxes and may not be called from an interrupt handler. It is called after all mailboxes are closed and the task has finished using the mailbox facility. If no other tasks are using the mailbox facility or shared storage pool, the shared pool returns to free storage.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 14h.
AL = Task number.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 0005h | Access denied | +---------+-------------------+ | 8006h | Mailboxes open | +---------+-------------------+ | 800Dh | Mailbox not | | | registered | +---------+-------------------+C CALL FORMAT
int far MBXDeregister (void)
Entry Parameters
None.
Exit Parameters
None.
Example Call
#include "ricps.h" int ReturnCode; /* Return code */ /* ... Work with mailboxes ... */ ReturnCode = MBXDeregister(); /* Deregister mailboxes */RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
8006h Mailboxes open.
800Dh Mailbox not registered.
The MBXOpen service opens and initializes a mailbox for the task and may not be called from an interrupt handler.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 15h.
AL = Task number.
ES:BX = Pointer to following control block:
+----------+-------------------+ | DWORD@ | MBXNumber (WORD) | +----------+-------------------+ | DWORD@ | MBXName (ASCIIZ) | +----------+-------------------+ | WORD | MBXType | +----------+-------------------+ | WORD | MaxMessages | +----------+-------------------+ | DWORD@ | Reserved (size 8 | | | bytes) | +----------+-------------------+ | WORD | PostFlag | +----------+-------------------+ | WORD | EventFlag | +----------+-------------------+ | DWORD@ | Service Routine | +----------+-------------------+ | DWORD@ | MBXAddress | | | (DWORD) | +----------+-------------------+Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
MBXAddress returned in control block.
MBXNumber returned in control block.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 0005h | Access denied | +---------+-------------------+ | 0013h | Invalid data | +---------+-------------------+ | 8004h | Mailbox in use | +---------+-------------------+ | 8005h | Mailboxes | | | exhausted | +---------+-------------------+ | 8007h | Invalid mailbox | +---------+-------------------+ | 8009h | Invalid mailbox | | | name | +---------+-------------------+ | 800Ah | Invalid mailbox | | | type | +---------+-------------------+ | 800Ch | No service | | | routine. | +---------+-------------------+ | 800Dh | Mailbox not | | | registered. | +---------+-------------------+C CALL FORMAT
int far MBXOpen (MBXNumber, MBXName, MBXType, MaxMessages,
Reserved, PostFlag, EventFlag, ServiceRoutine,
MBXAddress)
int far *MBXNumber; /* Mailbox number */
char far *MBXName; /* Mailbox name */
int MBXType; /* Mailbox type */
int MaxMessages; /* Maximum number of messages */
char far *Reserved; /* Reserved space in task */
/* header segment (8 bytes) */
int PostFlag; /* Post flag */
int EventFlag; /* Event flag */
MBX_AST ServiceRoutine; /* Mailbox service routine */
MBX_ADRS far *MBXAddress; /* Mailbox address returned */
/* here */
Entry Parameters
SERVICE ROUTINE ASSEMBLER INTERFACE
Entry Parameters
SS:SP points to the following:
+-----------+---------+-------------------------------+
| SS:SP + 0 | DWORD@ | Return Address |
+-----------+---------+-------------------------------+
| SS:SP + 4 | WORD | MBXNumber |
+-----------+---------+-------------------------------+
| SS:SP + 6 | WORD@ | Message |
+-----------+---------+-------------------------------+
Exit Parameters
AX = The return code to be returned to the caller of MBXSend. The return code from the service routine is returned to the caller of MBXSend. Service routines should return 0 or choose return codes that allow the MBXSend caller to distinguish between the ServiceRoutine return code and other MBXSend return codes.
Service Routine C CALL FORMAT
int far ServiceRoutine(MBXNumber, Message);
int MBXNumber;
char far *Message;
Exit Parameters
MBXAddress The address of the opened mailbox is returned here.
NULL is returned if there are any errors.
Example Call
#include "ricps.h"
char Reserved[8] = {0};
int ReturnCode; /* Return code */
int MBXNumber; /* Mailbox number */
MBX_ADRS MBX_Address; /* Address of the mailbox */
/* ... Register mailbox(es) ... */
/* ... Fill in MBXNumber ... */
/* Open mailbox 0, maximum number */
/* of message = 1, name = */
/* "TestMBX", no notify options, */
/* type = FIFO */
ReturnCode = MBXOpen(&MBXNumber, "TestMBX", MBX_FIFO, 1, Reserved,
0, 0, 0, &MBX_Address);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
8013h Invalid data.
8004h Mailbox in use.
8005h Mailboxes exhausted.
8007h Invalid mailbox.
8009h Invalid mailbox name.
800Ah Invalid mailbox type.
800Ch No service routine.
800Dh Mailbox not registered.
800Fh Mailbox storage exhausted.
The MBXClose service closes a mailbox and may not be called from an interrupt handler.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 16h.
AL = Task number.
CX = Mailbox number.
BX = Mailbox disposition.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 0005h | Access denied. | +---------+-------------------+ | 8007h | Invalid mailbox. | +---------+-------------------+ | 800Dh | Mailbox not | | | registered. | +---------+-------------------+C CALL FORMAT
int far MBXClose (MBXNumber, MBXDisp) int MBXNumber; /* Mailbox number */ int MBXDisp; /* Mailbox disposition */Entry Parameters
MBXNumber The mailbox number to be closed.
MBXDisp The disposition of any messages remaining in the mailbox.
A non-zero value purges any messages in the mailbox. If
the message was allocated from the shared pool, it is also
returned to the pool. A value of 0 prevents new messages
from being placed in the mailbox, but allows the task to
finish receiving the remaining messages. When the last
message is received via MBXReceive, the mailbox
automatically closes.
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
int MBXNumber; /* Mailbox number */
/* ... Work with mailboxes ... */
/* ... Fill in MBXNumber ... */
/* Close the mailbox and purge */
/* unopened messages */
ReturnCode = MBXClose(MBXNumber, 1);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied
8007h Invalid mailbox.
800Dh Mailbox not registered.
The MBXSend service puts a message in the specified mailbox. If the destination mailbox has a maximum number of messages set and already contains the maximum number of messages, an error is returned. If the mailbox being sent to is serviced by a task service routine, the return code from the service routine is passed to the caller of MBXSend.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 17h.
CX:DX = Mailbox address.
ES:BX = Message pointer.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 0000h | Normal | | | completion, no | | | error. | +---------+-------------------+ | 8003h | Mailbox full. | +---------+-------------------+ | 8007h | Invalid mailbox. | +---------+-------------------+ | nnnnh | User-defined | | | service routine | | | return code. | +---------+-------------------+C CALL FORMAT
int far MBXSend (MBXAddress, Message) MBX_ADRS MBXAddress; /* Destination mailbox */ char far *Message; /* Message to be sent */Entry Parameters
+=========+==========+==========+==========+ | Byte | Definiti | Descript | Comments | | | on | ion | | +=========+==========+==========+==========+ | 00h-03h | Reserved | Used by | Complete | | | header | RICPS | d by | | | | | RICPS | +---------+----------+----------+----------+ | >03h | Message | User-def | | | | | ined | | | | | data | | +---------+----------+----------+----------+Exit Parameters
None.
Example Call
#includeRETURN CODES#include "ricps.h" int ReturnCode; /* Return code */ MBX_ADRS MBXAddress; /* Address of the mailbox */ char far *Message; /* Message buffer */ /* ... Get mailbox address ... */ Message = MBXAllocMsg(strlen("Test Message")); if (Message != NULL) { strcpy(Message, "Test Message"); /* Send the message to the mailbox */ ReturnCode = MBXSend(MBX_Addr, Message); }
0000h Normal completion; no errors.
8003h Mailbox full.
8007h Invalid mailbox.
nnnnh User-defined service routine return code.
The MBXReceive service is used to get the next message in the mailbox, and may not be called from an interrupt handler. If MaxMessages is set to 0 for the MBXOpen call, this routine always returns the error mailbox empty.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 18h.
AL = TaskNum.
CX = MBXNumber.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
ES:BX = Message.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 0005h | Access denied. | +---------+-------------------+ | 8002h | Mailbox empty. | +---------+-------------------+ | 8007h | Invalid mailbox. | +---------+-------------------+ | 800Dh | Mailbox not | | | registered. | +---------+-------------------+C CALL FORMAT
int far MBXReceive (MBXNumber, Message)
int MBXNumber; /* Mailbox number */
char far * far *Message; /* Pointer to message */
/* returned here */
Entry Parameter
Exit Parameters
#include "ricps.h"
int ReturnCode; /* Return code */
int MBXNumber; /* Mailbox number */
char far *MessagePointer; /* Message pointer */
/* ... Fill in MBXNumber ... */
/* Receive a message */
ReturnCode = MBXReceive(MBXNumber, &MessagePointer);
RETURN CODES
0000h Normal completion; no errors.
0005h Access denied.
8002h Mailbox empty.
8007h Invalid mailbox.
800Dh Mailbox not registered.
This service returns a count of the number of messages in the mailbox, and may not be called from an interrupt handler. If MaxMessages was set to 0 for the MBXOpen call, this service always returns a count of 0.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 19h.
AX = TaskNum.
CX = MBXNumber.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
DX = Count.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 8007h | Invalid mailbox. | +---------+-------------------+ | 800Dh | Mailbox not | | | registered. | +---------+-------------------+C CALL FORMAT
int far MBXCount (MBXNumber, Count) int MBXNumber; /* Mailbox number */ int far *Count; /* Count returned here */Entry Parameter
Exit Parameters
#include "ricps.h"
int ReturnCode; /* Return code */
int MBXNumber; /* Mailbox number */
/* Message pointer */
int MBXMessageCount; /* Message count */
/* ... Fill in MBXNumber ... */
/* Check count of messages in the */
/* mailbox */
ReturnCode = MBXCount(MBXNumber, &MBXMesssageCount);
RETURN CODES
0000h Normal completion; no errors.
8007h Invalid mailbox.
800Dh Mailbox not registered.
The MBXAdrs service obtains the address of a mailbox, given the mailbox's name.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 1Ah.
DS:SI = MBXName.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
CX:DX = MBXAddress.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 800Bh | Mailbox name | | | unknown. | +---------+-------------------+C CALL FORMAT
int far MBXAdrs (MBXName, MBXAddress) char far *MBXName; /* Mailbox name */ MBX_ADRS *MBXAddress; /* MBX_ADRS returned here */Entry Parameters
Exit Parameters
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
MBX_ADRS MBXAdr_Returned_Addr /* Returned address of the mailbox*/
/* Find the address of the mailbox*/
/* named TestMBX */
ReturnCode = MBXAdrs("TestMBX", &MBXAdr_Returned_Addr);
RETURN CODES
0000h Normal completion; no errors.
800Bh Mailbox name unknown.
The MBXName service is used to obtain the name of a mailbox, given the mailbox's address.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 1Bh.
CX:DX = MBXAddress.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
ES:DI = MBXName.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 8007h | Invalid mailbox. | +---------+-------------------+C CALL FORMAT
int far MBXName (MBXAddress, &MBXName)
MBX_ADRS MBXAddress; /* Mailbox address */
char far **MBXName; /* Mailbox name pointer returned */
/* here */
Entry Parameters
Exit Parameters
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
MBX_ADRS MBXAddress; /* Address of the mailbox */
char far *MBXName; /* Returned name pointer of the mailbox */
/* ... Fill in the mailbox address ... */
/* Find the name of the mailbox */
ReturnCode = MBXName(MBXAddress, &MBXName);
RETURN CODES
0000h Normal completion; no errors.
8007h Invalid mailbox.
The MBXAllocMsg function allocates a message buffer from the shared storage pool. If the requested amount of storage is not available, NULL is returned.
When more than half of the remaining storage is requested, the MBXAllocMsg function returns all of the remaining storage to the requestor.
INVOCATION: INT 5Eh
Entry Parameters
AH = 1Ch.
CX = Message size in bytes.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
ES:BX = Message pointer if no error; null if error
C CALL FORMAT
char far *MBXAllocMsg (MsgSize) unsigned int MsgSize; /* Message size in bytes */Entry Parameters
Return Value
#include "ricps.h"
int ReturnCode; /* Return code */
char far *Message; /* Message buffer */
/* Allocate a message buffer */
Message = MBXAllocMsg(strlen("Test Message"));
The MBXFreeMsg routine returns a message buffer allocated via the
MBXAllocMsg service to the shared storage pool.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 1Dh.
ES:BX = Message pointer.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 8008h | Invalid message | | | buffer. | +---------+-------------------+C CALL FORMAT
int far MBXFreeMsg (Message) char far *Message; /* Message buffer to free */Entry Parameter
Exit Parameters
None.
Example Call
#include "ricps.h" int ReturnCode; /* Return code */ char far *Message; /* Message buffer */ /* ... Allocate a message buffer initialize message */ ReturnCode = MBXFreeMsg(Message); /* Return a message buffer */RETURN CODES
0000h Normal completion; no errors.
8008h Invalid message buffer.
The MBXConfigMsgPool routine configures the shared message pool to the requested size in paragraphs if it has not already been configured. One paragraph equals 16 bytes. If the shared message pool has already been configured, an error is returned.
ASSEMBLER INTERFACE
INVOCATION: INT 5Eh
Entry Parameters
AH = 1Eh.
CX = Pool size in paragraphs.
Exit Parameters
Carry Flag = 0 if no error;
1 if error.
AX = Unchanged if no error;
error code if error.
Errors
+=========+===================+ | AX Code | Meaning | +=========+===================+ | 800Eh | Mailbox pool | | | already | | | configured. | +---------+-------------------+ | 800Fh | Mailbox storage | | | exhausted. | +---------+-------------------+C CALL FORMAT
int far MBXConfigMsgPool (PoolSize) unsigned int PoolSize; /* Pool size in paragraphs */Entry Parameter
Exit Parameters
None.
Example Call
#include "ricps.h"
int ReturnCode; /* Return code */
/* Configure the message pool */
/* for 32K */
ReturnCode = MBXConfigMsgPool(0x0800);
RETURN CODES
0000h Normal completion; no errors.
800Eh Mailbox pool already configured.
800Fh Mailbox storage exhausted.
This section contains a list of the RICPS return codes. The RICPS returns an indication of the successful or unsuccessful execution of the requested operation.
The following message codes can be returned by the Realtime Control Microcode commands that are associated with Realtime Control Microcode and RICPS system unit commands.
+=======+=======+============================================================+ | Byte | Byte | Meaning | | 0 | 1 | | +=======+=======+============================================================+ | 02h | 02h | Insufficient storage | | | | Insufficient storage for system semaphores | | | | Insufficient storage for message pool | +-------+-------+------------------------------------------------------------+ | 02h | 03h | Invalid command data; name length = 0 or invalid device | | | | type specified | | | | Invalid command data (maximum semaphore number is 0) | +-------+-------+------------------------------------------------------------+ | 02h | 05h | Invalid task number | +-------+-------+------------------------------------------------------------+ | 02h | 06h | Task already loaded | +-------+-------+------------------------------------------------------------+ | 02h | 09h | System semaphores already enabled | | | | Message pool already allocated | +-------+-------+------------------------------------------------------------+ | 02h | 0Eh | Task number not available | +-------+-------+------------------------------------------------------------+ | 02h | 0Fh | Name not found | +-------+-------+------------------------------------------------------------+
The RICPS post code values are listed here:
TIMEOUT 0054h
EVENT 0055h
SEMAPHORE 0056h
The Realtime Interface Co-Processor Communications Support package makes it easier for the application to use the asynchronous communications facilities provided by the Realtime Interface Co-Processor adapters. This package provides an interface for asynchronous communications support and allows applications to be independent of the co-processor adapter's communications hardware device (Zilog** 8030 Serial Communications Controller, Signetics** SN26562 Dual Universal Serial Communications Controller, or Zilog** 8036 Counter/Timer and Parallel I/O Unit). It supports the RS-232-C, RS-422-A, and V.35 electrical interfaces.
The RICCS contains a driver task that performs the physical interface to the communications hardware devices and shelters application tasks from this hardware. The RICCS driver prepares and accesses a communication line for transmitting data to, and receiving data from an attached device.
Note:
The RICCS asynchronous driver task requires approximately 28KB of co-processor adapter storage.
The asynchronous RICCS Level A commands support the physical layer. These commands are implemented via a library of object module subroutines to be linked with the application tasks. The name of the library is RICCS.LIB. These subroutines serve as the interface between application tasks and the RICCS driver task.
The Level A commands included in RICCS are:
The RICCS C language support provided with the RICCS requires the Realtime Interface Co-Processor C Language Support. The RICCS C language support consists of an include file, RICCS.H, providing access to the Level A subroutines that come with Realtime Interface Co-Processor Communications Support. The include file contains data structures and library routine declarations allowing applications to access the RICCS.COM driver.
C language tasks should include the file RICCS.H. During compilation, the /Zp option should be used to pack the data structures. Any memory model can be used for the task. During the link step, the Level A subroutine library, RICCS.LIB, should be linked to the user's object module along with the standard C libraries specified in the Realtime Interface Co-Processor C Language Support User's Guide.
The RICCS.H and RICCS.LIB files are on the RICES Programs diskette.
Once the RICCS has been loaded, it initializes variables and allocates resources to handle software interrupts, timer interrupts, and memory.
Note:
No hardware allocation is done at this time. Port and DMA allocations are made when the port is opened. The RICCS driver task is responsible for allocating all the required resources (for example: ports, DMA channels, and timers) for communications; therefore, the application task does not have to allocate these resources.
If the RCS_PORTDEFINITION command is omitted at startup, the RICCS driver assumes the default port definition (all ports are active and software interrupt 75h is used to communicate with the RICCS driver task). Initial line characteristics and other information can be provided (through commands) to the RICCS driver task. These commands are optional; if they are omitted, the RICCS driver assumes the following default values:
Port definition, line characteristics, and other information must be provided through various commands if the defaults values are not used. The default values may be changed by placing the commands in the application task or writing a startup task.
The sample programs provided with this user's guide have a startup task program and can be used to pass the configuration information to the RICCS driver.
To handle the I/O for multiple ports expediently, the RICCS driver task runs at a high task priority. Changes to the default task priority should be done at startup. The default task priority is three (3), but an application task can change that default task priority at startup. Application tasks should run at a lower priority than RICCS (priorities 4 through 255).
Software interrupt vectors are used to interface to the RICCS driver. Interrupt 75h is the default software interrupt vector. Up to eight additional software interrupt vectors can be added by using the RCS_PORTDEFINITION command.
Other software packages can use the software interrupt vector 75h; therefore, RICCS allows the user to specify different software interrupt vectors. This feature allows the application to use RICCS while using another software package with software interrupt vector 75h.
For most commands, task synchronization is either automatic (deferred commands) or unnecessary (immediate commands). The application tasks resumes execution following the call to the command subroutine only after the command has been completely processed. (For deferred commands, this is accomplished by a suspend/resume sequence within the command subroutine.)
Exceptions to the automatic or unnecessary task synchronization are the RCS_READ and RCS_WRITE commands when issued with the no-wait option. These two commands allow the application code to continue execution after the call, parallel with the I/O operation. The application must then issue an explicit wait to be posted when the I/O operation completes or check the Post Code field periodically. The status flags in the command control block should be checked after the post to verify that the operation has completed.
The command control block is available for reuse as soon as control is returned to the application code after the RICCS call.
Exceptions to the command control block availability are the RCS_READ and RCS_WRITE commands when issued with the no-wait option. These two commands allow the application code to continue execution after the call, parallel with the I/O operation. The application must then verify that the I/O operation has completed by checking the post code or checking the status flags for completion before reusing the control block.
The RICCS driver allows the sharing of ports. If the PORTSHARING parameter to RCS_OPEN is on, up to 16 tasks can have a port open at the same time. Multiple tasks writing to a port is a relatively normal situation. It is the responsibility of the tasks involved to coordinate their individual uses of the port.
Each port must be programmed with the following physical line characteristics:
The RCS_SETLINECTRL command issued after the first RCS_OPEN command has been processed should establish these characteristics.
RCS_SETLINECTRL can be reissued to an open port at any time to change the characteristics as needed.
Warning: Data will be lost if this command is issued during data transfer.
The RCS_CLOSE command can be used to specify that current line characteristics are to be retained across sequential open/close cycles without reissuing RCS_SETLINECTRL. Selecting the current values option of the RCS_CLOSE command ensures that the same characteristics are retained at the next RCS_OPEN.
If no RCS_SETLINECTRL has been issued, or if the port has been closed with the "return to default values" option (rather than "retain current values"), RCS_OPEN initializes the port to the system default values (1200 baud, 1 stop bit, even parity, and 7 data bits).
A command code identifies each Level A command, and each command has a defined command control block. The table that describes each command control block contains a "Set By" column. This column indicates what is responsible for loading a particular parameter. The following is a list of code names used in the "Set By" column of the command control block descriptions table.
+============+=========================+ | Set By | Meaning | | Code Name | | +============+=========================+ | RCS | Communications Support | | | Driver | +------------+-------------------------+ | RCS SUB | Communications Support | | | Subroutines | +------------+-------------------------+ | APP | Applications task(s) | +------------+-------------------------+For control block entries involving timings all timing parameters are expressed in 10-millisecond units. Each timing parameter is defined as a signed integer. A user can vary the timing parameter interval from a minimum of 10 milliseconds (one count) to a maximum of 5 minutes and 28 seconds (32767 counts); however, the RICCS driver rounds up the time values to the next higher multiple of the interrupt clock period.
The parameters passed to the RICCS driver task are validated and the appropriate return codes are returned in the command control blocks.
Unused bits in parameters should be cleared to 0 for future use.
The following sections describe the operation of each command. The command control blocks, entry parameters, exit parameters, and call formats are described with each command.
The RCS_PORTDEFINITION command can be issued at any time. Its primary function is to configure the driver at each port startup and defines configuration parameters to the RICCS driver task. The defaults that are specified in the "Entry Parameters" discussion apply if this command is not issued.
The RCS_PORTDEFINITION command should be performed prior to a RCS_OPEN command because the information in the RCS_PORTDEFINITION command is used during the open. Any RCS_PORTDEFINITION command applies to subsequent RCS_OPEN commands for the specified port. The RCS_PORTDEFINITION command:
Maximizing DMA implies that the driver is free to use DMA even though the application has not requested it. Maximizing DMA causes all writes and reads to use DMA unless error substitution or echo is turned on.
Note:
Maximizing DMA only applies to the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.
ASSEMBLER INTERFACE
PUSH Segment of RCS_PORTDEFINITION Control Block PUSH Offset of RCS_PORTDEFINITION Control Block CALL _rcs_portdefinition ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ALLOCATE THE PORT DEFINITION CONTROL BLOCK (PDCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
PDCB RCSS_PORTDEFINITION <,,0,,,1,0,0,0,0,0,0,27H,1,2,0,0>
; CALL THE RCS_PORTDEFINITION SUBROUTINE TO DEFINE FOR PORT 0 THE
; RS-232-C CONTROL SIGNALS THAT ARE ACTUALLY CONNECTED ON THE, IBM
; X.25 INTERFACE CO-PROCESSOR. ADD SOFTWARE INTERRUPT VECTOR 27H TO
; COMMUNICATE WITH THE RICCS DRIVER AND THE DRIVER WILL NOT MAXIMIZE DMA.
LEA DI,PDCB ;LOAD OFFSET OF PDCB
PUSH CS ;SEGMENT OF PDCB
PUSH DI ;OFFSET OF PDCB
CALL _rcs_portdefinition ;CALL LEVEL A SUB TO DO
;PORT DEFINITION COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP PDCB.PDCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_portdefinition pdcb; rcs_portdefinition(&pdcb);PDCB is the RCS_PORTDEFINITION Control Block.
Example Call
#include "riccs.h"
/* Default logical device names */
unsigned char Ldn [ ]= "SCCO";
/* Allocate the Port Definition control block (pdcb) */
/* and initialize parameters. */
struct rcss_portdefinition pdcb = {0,0,0,0,0,1,0,{0},
0,0x27,1,2,0,0};
/* Initialize logical device name */
memcpy (pdcb.pdcb_logicaldevicename, Ldn, 4);
/* Call the RCS_PORTDEFINITION subroutine to define */
/* for port 0 the RS-232-C control signals that are */
/* actually connected on the IBM X.25 Interface */
/* Co-Processor. Add software interrupt vector 27h to */
/* communicate with the RICCS driver and */
/* the driver will not maximize DMA. */
rcs_portdefinition(&pdcb);
if (pdcb.pdcb_retcode == 0)
.
.
RCS_PORTDEFINITION Control Block (PDCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 00h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task number| | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | RESERVED1 | Reserved. | Must be 0 | APP | | 03h | | Used by RICCS | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | CHANGEDSTATUS | A present or a | 0=No change | RCS | | | | previous | 1=Changed | | | | | RCS_PORTDEFINITION | Bit 0: | | | | | command has | Changed by present call | | | | | changed the port | Bit 1: | | | | | configuration. | Changed by a previous call| | +------+----------------+--------------------+---------------------------+-----+ | 07h | ACTIVEDEVICE | Active or inactive | 0=Inactive | APP | | | | port | 1=Active | | +------+----------------+--------------------+---------------------------+-----+ | 08h | PORTID | Physical port | 0=Port 0 | APP | | | | identification | 1=Port 1 | | | | | | 2=Port 2 | | | | | | 3=Port 3 | | | | | | 4=Port 4 | | | | | | 5=Port 5 | | | | | | 6=Port 6 | | | | | | 7=Port 7 | | +------+----------------+--------------------+---------------------------+-----+ | 09h- | LOGICALDEVNAME | A string containing| | APP | | 0Ch | | a logical device | | | | | | name for the port | | | +------+----------------+--------------------+---------------------------+-----+ | 0Dh | DRIVERTASKNUM | Task number of the | This parameter will be | APP | | | (Reserved) | RICCS driver | ignored in Version 1.01 | | | | | | or higher | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | SOFTWAREINT | Software interrupt | Used to communicate with | APP | | | | vector | RICCS | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | CONCTRL | Indicates whether | Bit0: | APP | | | | the CONNECT byte | 0=No change to current | | | | | defined the | RS-232-C control signal | | | | | RS-232-C control | connections | | | | | signal connections | 1=CONNECT defines the | | | | | | RS-232-C control signal | | +------+----------------+--------------------+---------------------------+-----+ | 10h | CONNECT | Identifies which | 0=Off | APP | | | | RS-232-C control | 1=On | | | | | signals are | Bit0 : RTS | | | | | actually connected | Bit1 : DTR | | | | | | Bit2 : RI | | | | | | Bit3 : DCD | | | | | | Bit4 : DSR | | | | | | Bit5 : CTS | | | | | | Bit6 : RS (output) | | | | | | Bit7 : Reserved | | +------+----------------+--------------------+---------------------------+-----+ | 11h | MAXDMA | Indicates if the | 0=No change | APP | | | | driver should | 1=Do not maximize DMA | | | | | maximize the use | 2=Maximize DMA | | | | | of DMA | | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | RESERVED2 | Reserved for | Must be 0 | APP | | 13h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
RESERVED1 reserved; value must be 0.
ACTIVEDEVICE indicates whether the port is active or inactive. By default, all ports are active.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | Inactive | | +-------+--------------------+ | | 1 | Active | +-----+-------+--------------------+PORTID is the physical port identification. The values are:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Port 0 | +------------+------------------------+ | 1 | Port 1 | +------------+------------------------+ | 2 | Port 2 | +------------+------------------------+ | 3 | Port 3 | +------------+------------------------+ | 4 | Port 4 | +------------+------------------------+ | 5 | Port 5 | +------------+------------------------+ | 6 | Port 6 | +------------+------------------------+ | 7 | Port 7 | +------------+------------------------+LOGICALDEVNAME is a four-character ASCII string that contains a logical device name for a port. Four null characters indicate that the LOGICALDEVNAME should not be changed from its previous value. The default values are:
+============+========================+ | Value | Meaning | +============+========================+ | "SCC0" | Port 0 | +------------+------------------------+ | "SCC1" | Port 1 | +------------+------------------------+ | "SCC2" | Port 2 | +------------+------------------------+ | "SCC3" | Port 3 | +------------+------------------------+ | "SCC4" | Port 4 | +------------+------------------------+ | "SCC5" | Port 5 | +------------+------------------------+ | "SCC6" | Port 6 | +------------+------------------------+ | "SCC7" | Port 7 | +------------+------------------------+DRIVERTASKNUM is the task number of the RICCS driver (this parameter will be ignored in Version 1.01 or higher).
SOFTWAREINT is an additional software interrupt vector used by the application task(s) to communicate with the RICCS driver task. A value of 0 indicates that no new software interrupt vector is to be added. By default, applications use interrupt 75h to communicate with the RICCS driver.
CONCTRL is the control byte for the CONNECT byte that follows.
Note:
This parameter needs to be set when using the IBM X.25 Interface Co-Processor/2, the IBM Realtime Interface Co-Processor Portmaster Adapter/A, or the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 because several of the control signal lines float when not connected, causing spurious interrupts. For these adapters, use the CONCTRL and CONNECT parameters to indicate which control signals are not connected.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | No change to | | | | current RS-232-C | | | | connections | | +-------+--------------------+ | | 1 | CONNECT defines the| | | | RS-232-C control | | | | signal connections | +-----+-------+--------------------+CONNECT is a byte that defines the RS-232-C control signal connections. The byte is a series of bit flags, one per control signal. The following table provides the bit assignments for each control signal. The default is all control signal lines connected.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Control signal is not | | | connected | +------------+------------------------+ | 1 | Control signal is | | | connected | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Ring Indicator (RI) | | | | +--------------- Data Carrier Detect (DCD) | | | +------------------ Data Set Ready (DSR) | | +--------------------- Clear To Send (CTS) | +------------------------ Rate Select (RS) +--------------------------- ReservedMAXDMA indicates if the RICCS driver should maximize the use of DMA. By default DMA is not maximized.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | Do not maximize DMA | +------------+------------------------+ | 2 | Maximize DMA | +------------+------------------------+
Note:
This parameter applies to IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 and IBM Realtime Interface Co-Processor Portmaster Adapter/A adapters.
RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
CHANGEDSTATUS indicates if the present RCS_PORTDEFINITION command has changed the port configuration, a previous RCS_PORTDEFINITION command has changed the port configuration, or both. Each bit can have a value of 0 or 1.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | Changed | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Changed by present call | | | | | | +--------- Changed by a previous call | | | | | +------------ Reserved | | | | +--------------- Reserved | | | +------------------ Reserved | | +--------------------- Reserved | +------------------------ Reserved +--------------------------- ReservedRETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 0600h | Invalid device name | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1800h | Invalid driver task | | | number | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 1D00h | Too many interrupt | | | vectors | +------------+------------------------+
The RCS_OPEN command allows the application task to inform the RICCS driver that it wishes to communicate through a port:
This command registers the application task with the RICCS driver as a valid task that can perform subsequent commands for the port and uses logical device names to identify the ports. If no other application task opened this port, the command causes the RICCS driver to set up the interface hardware based on default settings or previously set values. This command must be issued before any other commands (except the RCS_PORTDEFINITION, RCS_DEFEI or RCS_SHUTDOWN commands).
The command, by defining a password in the PASSWORD parameter, allows a local set of tasks to share the port and prevents other applications from using the port. The first task opening the port may specify a password and any subsequent task opening the port must provide the same password.
The command can be used to inform the RICCS driver if DMA is to be used for data input or data output.
Only ports 0 and 1 are capable of DMA input and output on the Realtime Interface Co-Processor, IBM Realtime Interface Co-Processor Multiport, and IBM Realtime Interface Co-Processor Multiport/2. The IBM X.25 Interface Co-Processor/2 is capable of DMS on its single port. All eight ports are capable of DMA input and output on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2.
If the communication hardware is Signetics**, DMA may be used for fixed length reads, as well as variable length reads.
The RCS_OPEN command is used to initiate the switching between the asynchronous and synchronous drivers. Setting the SWITCHPREP parameter to "YES" initializes the switch; however, both the asynchronous and synchronous drivers must be loaded on the co-processor adapter. If both drivers are not loaded, the switch preparation failed return code (2100h) is returned.
The asynchronous and synchronous switching feature allows the use of modems using asynchronous communication for call setup and synchronous communication for data transfer. The switching feature prevents control signals from being dropped and calls from being disconnected during driver switching.
If asynchronous communication is used first, the SWITCHPREP parameter of the RCS_OPEN command is used to initiate preparations for the switch. When asynchronous communication finishes, the switch is made using the DRIVER parameter of the RCS_CLOSE command. If synchronous communication is used first, no action is needed by the application until closing the port. When synchronous communication finishes, the switch is made using the DRIVER parameter of the RCS_S_CLOSE command.
Note:
When using asynchronous and synchronous switching this feature precludes the use of DMA I/O for the asynchronous driver, even if DMA was specified in the RCS_OPEN, RCS_DMAREADCTRL, or RCS_DMAWRITECTRL.ASSEMBLER INTERFACE
PUSH Segment of RCS_OPEN Control Block PUSH Offset of RCS_OPEN Control Block CALL _rcs_open ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; DEFINE PASSWORD
PASSWORD EQU 1234
; ALLOCATE THE OPEN CONTROL BLOCK (OCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
OCB RCSS_OPEN <,,,,,'S','C','C','0',1,0,0,0,0,0,PASSWORD,0,>
; CALL THE RCS_OPEN SUBROUTINE TO OPEN PORT 0 AND
; ALLOW IT TO BE SHARED BY A LOCAL SET OF TASKS.
LEA DI,OCB ;LOAD OFFSET OF OCB
PUSH CS ;SEGMENT OF OCB
PUSH DI ;OFFSET OF OCB
CALL _rcs_open ;CALL LEVEL A SUB TO DO
;OPEN COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP OCB.OCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_open ocb; rcs_open(&ocb);OCB is the RCS_OPEN Control Block
Example Call
#include "riccs.h"
/* Default Logical Device Name */
/* Define Password */
unsigned char Ldn[ ] = "SCC0";
unsigned int Password = 1234;
/* Allocate the Open control block (ocb) */
/* and initialize parameters. */
struct rcss_open ocb = {0,0,0,0,0,{0},1,0,0,0,0,0, Password, 0};
/* Initialize Logical Device Name. */
memcpy (ocb.ocb_logicaldevname,Ldn,4);
/* Call the RCS_OPEN subroutine to open port 0 and */
/* allow it to be shared by a local set of tasks. */
rcs_open(&ocb);
if (ocb.ocb_retcode == 0)
.
.
RCS_OPEN Control Block (OCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 01h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task number| | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS Return Codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | VERREL | Version number and | Equals 0103h | RCS | | 07h | | release index | 0100h=1.00 | | | | | information | 0101h=1.01 | | | | | | 0102h=1.02 | | | | | | 0103h=1.03 | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | LOGICALDEVNAME | A string containing| | APP | | 0Bh | | a logocal device | | | | | | name for the port | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch | PORTSHARING | Support port | Bit0: | APP | | | | sharing | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 0Dh | SYNCH | Synchronization | 0=Asynchronous | APP | | | | method used on the | 1=Bitsynchronous | | | | | line | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | DMAWRITE | Support DMA on | Bit0: | APP | | | | RCS_WRITE commands | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | DMAREAD | Support DMA on | Bit0: | APP | | | | RCS_READ commands | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | DMAREADLENGTH | The actual length | This parameter is | APP | | 11h | (Reserved) | of data for DMS | reserved and not used in | | | | | read | Version 1.01 ir higher | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | DMAREADTIMEOUT | Time to complete | This parameter is | APP | | 13h | (Reserved) | the DMA read | reserved and not used in | | | | | | Version 1.01 or higher | | +------+----------------+--------------------+---------------------------+-----+ | 14h- | PASSWORD | Password for local | 0=No password | APP | | 15h | | port sharing | Non-zero=Password | | +------+----------------+--------------------+---------------------------+-----+ | 16h | SWITCHPREP | Prepare for later | Bit0: | APP | | | | switch to | 0=No | | | | | synchronous dirver | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 17h- | RESERVED2 | Reserved for | Must be 0 | APP | | 1Fh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
LOGICALDEVNAME should be a four-character ASCII string that contains a logical device name for the port. The default values are:
+============+========================+ | Value | Meaning | +============+========================+ | "SCC0" | Port 0 | +------------+------------------------+ | "SCC1" | Port 1 | +------------+------------------------+ | "SCC2" | Port 2 | +------------+------------------------+ | "SCC3" | Port 3 | +------------+------------------------+ | "SCC4" | Port 4 | +------------+------------------------+ | "SCC5" | Port 5 | +------------+------------------------+ | "SCC6" | Port 6 | +------------+------------------------+ | "SCC7" | Port 7 | +------------+------------------------+PORTSHARING indicates whether or not the port should be shared. Sharing can be limited to a local set of tasks by using the PASSWORD parameter described below:
Note:
Up to 16 tasks can have the port open at the same time.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | No | | +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+SYNCH indicates the synchronization method (asynchronous or synchronous) used on the line. This provides a check that the correct driver is assigned to the port and is receiving the command. The possible values are:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Asynchronous | +------------+------------------------+ | 1 | Bit synchronous | +------------+------------------------+DMAWRITE indicates whether to support DMA on an RCS_WRITE command.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | No | | +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+Note:
If requesting asynchronous and synchronous switching, this parameter is not used.
DMAREAD indicates whether to support DMA on an RCS_READ command.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | No | | +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+Note:
If requesting asynchronous and synchronous switching, this parameter is not used.
DMAREADLENGTH is the actual length of data for the DMA read. This value is only used if the application task specifies a Driver Input Buffer.
Note:
This parameter is not used in Version 1.01 or higher.
DMAREADTIMEOUT is the time, in 10-millisecond units, to complete the DMA read operation prior to timing out. DMAREADTIMEOUT is reset and restarted when the driver initiates each DMA read. A value of -1 indicates an infinite timeout. This value is only used if the application task specifies a Driver Input Buffer.
Note:
This parameter is not used in Version 1.01 or higher.
PASSWORD is the 16-bit value that allows local port sharing when a task opens a port and no other task has the port open. This value is recorded as the password. Other tasks that subsequently attempt to open the port must specify this same value to successfully open the port. A value of 0 specified by the first task opening the port implies that no password protection is used and any task can open the port.
SWITCHPREP indicates the asynchronous driver should make preparations for later switching to the synchronous driver. When an RCS_OPEN command is performed by the asynchronous driver, the asynchronous driver owns the port. However, in order for a switch to be made to the synchronous driver, the resource must be owned by the synchronous driver. Setting the SWITCHPREP parameter causes the two drivers to open the port so that the synchronous driver owns the port and the asynchronous driver uses the port. These actions assume both drivers are loaded.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | No | | +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
DEVHANDLE is the device handle returned by the RICCS driver task. The device handle should be used in all subsequent calls for the port being opened.
VERREL is the Version and Release Index information returned by RICCS. VERREL consists of two bytes:
+============+========================+ | Value | Meaning | +============+========================+ | 0100h | Version 1.00 | +------------+------------------------+ | 0101h | Version 1.01 | +------------+------------------------+ | 0102h | Version 1.02 | +------------+------------------------+ | 0103h | Version 1.03 | +------------+------------------------+RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0001h | Successful and no DMA | | | write | +------------+------------------------+ | 0002h | Successful and no DMA | | | read | +------------+------------------------+ | 0003h | Successful and no DMA | +------------+------------------------+ | 0200h | Too many tasks sharing | | | port | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 0400h | Device already open | +------------+------------------------+ | 0600h | Invalid device name | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1800h | Invalid driver task | | | number | +------------+------------------------+ | 1900h | Device not active | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 1C00h | Hardware already | | | allocated | +------------+------------------------+ | 1E00h | Incompatible port type | +------------+------------------------+ | 1F00h | Invalid password | +------------+------------------------+ | 2000h | No password protection | +------------+------------------------+ | 2100h | Switch preparation | | | failed | +------------+------------------------+
The RCS_CLOSE command informs the RICCS driver that the application task no longer needs to communicate through the port. If other tasks have the port open, they keep their access to the port, and nothing else is done. If this was the only task that opened the port, the RICCS driver ceases communications through the port and frees it and any associated buffers. Once the RCS_CLOSE command is issued, an RCS_OPEN command must be issued before any further communications can be attempted. The line characteristics, RS-232-C control signal values, receive break duration, control input flow, control output flow, error substitution, notify status and echo status in effect when the RCS_CLOSE command is performed are retained unless the caller requests the default values be re-instated. Application tasks may use the RCS_CLOSE command to pass control between the asynchronous and synchronous drivers.
ASSEMBLER INTERFACE
PUSH Segment of RCS_CLOSE Control Block PUSH Offset of RCS_CLOSE Control Block CALL _rcs_close ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CLOSE CONTROL BLOCK (CCB) AND INITIALIZE PARAMETERS
; SET BY THE APPLICATION TASK.
CCB RCSS_CLOSE <,,,,1,-1,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE CCB. CALL
; THE RCS_CLOSE SUBROUTINE TO CLOSE THE PORT, RETURNING
; THE CONFIGURATION VALUES TO THE SYSTEM DEFAULTS AND KEEP
; THE PORT RESOURCE.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CCB.CCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;CCB
LEA DI,CCB ;LOAD OFFSET OF CCB
PUSH CS ;SEGMENT OF CCB
PUSH DI ;OFFSET OF CCB
CALL _rcs_close ;CALL LEVEL A SUB TO DO
;CLOSE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CCB.CCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_close ccb; rcs_close(&ccb);CCB is the RCS_CLOSE Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Close control block (ccb) */
/* and initialize parameters. */
struct rcss_close ccb = {0,0,0,0,1,-1,0};
/* Initialize the device handle parameter in the ccb. Call */
/* the RCS_CLOSE subroutine to close the port, return */
/* the configuration values to the system defaults, and keep */
/* the port resource.
*/
ccb.ccb_devhandle = ocb.ocb_devhandle;
rcs_close(&ccb);
if (ccb.ccb_retcode == 0)
.
.
RCS_CLOSE Control Block (CCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 02h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | CONFIGVALUES | Determines which | 0=Retain current values | APP | | 07h | | configuration | 1=Return to defaults | | | | | values to save | | | +------+----------------+--------------------+---------------------------+-----+ | 08h | DRIVER | Determines whether | -1=Current driver | APP | | | | the port resource | (asynchronous) and | | | | | should be returned.| return the port | | | | | | 0=Current driver | | | | | | (asynchronous) and | | | | | | keep the port | | | | | | 1=Pass control to the | | | | | | synchronous driver | | +------+----------------+--------------------+---------------------------+-----+ | 09h | RESERVED | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
CONFIGVALUES gives the user an option for saving the port configuration values after an RCS_CLOSE command has been issued. Option zero retains:
Note:
If two application tasks have the port open and one task issues an RCS_CLOSE, the current configuration values are retained, regardless of the setting of this parameter. The port is not closed until the last application has issued an RCS_CLOSE.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | Retain current | | | | values | | +-------+--------------------+ | | 1 | Return to defaults | +-----+-------+--------------------+DRIVER allows the application task to specify whether the port resource should be returned or kept. Retaining the asynchronous driver and returning the port resource causes the output control signals to drop. Retaining the asynchronous driver and keeping the port resource maintains the communication line control signals. If switching between drivers, the DRIVER parameter enables control to pass between the asynchronous and synchronous drivers without adversely affecting the communication line in the process.
Note:
If two or more application tasks have the port open and one task issues an RCS_CLOSE, the current driver is retained regardless of the setting of this parameter. The port is not closed until the last application has issued an RCS_CLOSE.
+=====+======================================================================+ | Val | Meaning | | ue | | +=====+======================================================================+ | -1 | Retain current driver (asynchronous) and return the port resource | +-----+----------------------------------------------------------------------+ | 0 | Retain current driver (asynchronous) and keep the port resource | +-----+----------------------------------------------------------------------+ | 1 | Pass control to the synchronous driver | +-----+----------------------------------------------------------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_SETLINECTRL sets characteristics that determine how the communications line operates. This command may be issued at any time; however, changing the BITRATERCV, BITRATETRANS, STOPBITS, PARITY, and DATABITS causes the hardware to be reset. A reset aborts active reads and writes.
RICCS initially uses the following default values: 1200 bps, 1 stop bit, even parity, and 7 data bits. Once an RCS_SETLINECTRL command is performed, the new values are retained until changed by a subsequent RCS_SETLINECTRL command or an RCS_CLOSE command. This feature allows characteristics to be set by one task (such as a startup task) and the port to be used by another task, independent of the specific characteristics.
Note:
The descriptions of the BITRATERCV and BITRATETRANS parameters contain a list of all supported bit rates. The bit rates supported depend on the type of electrical interface board, the type of adapter, the system requirements, and the I/O mode. When selecting bit rates, refer to the hardware technical reference for your co-processor adapter for more information.
ASSEMBLER INTERFACE
PUSH Segment of RCS_SETLINECTRL Control Block PUSH Offset of RCS_SETLINECTRL Control Block CALL _rcs_setlinectrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE SET LINE CONTROL CONTROL BLOCK (SLCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
SLCB RCSS_SETLINECTRL<,,,,15,15,3,3,3,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE SLCB. CALL
; THE RCS_SETLINECTRL SUBROUTINE TO SET THE BIT RATE FOR THE
; TRANSMITTING AND RECEIVING DEVICE TO 9600 BITS PER SECOND,
; WITH 2 STOP BITS, EVEN PARITY, AND 7 DATA BITS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV SLCB.SLCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN SLCB
LEA DI,SLCB ;LOAD OFFSET OF SLCB
PUSH CS ;SEGMENT OF SLCB
PUSH DI ;OFFSET OF SLCB
CALL _rcs_setlinectrl ;CALL LEVEL A SUB TO DO
;SET LINE CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SLCB.SLCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_setlinectrl slcb; rcs_setlinectrl(&slcb);SLCB is the RCS_SETLINECTRL Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Set Line Control control block (slcb) */
/* and initialize parameters. */
struct rcss_setlinectrl slcb = {0,0,0,0,15,15,3,3,3,0};
/* Initialize the device handle parameter in the slcb. Call */
/* the RCS_SETLINECTRL subroutine to set the bit rate for the */
/* transmitting and receiving device to 9600 bits per second, */
/* with 2 stop bits, even parity, and 7 data bits. */
slcb.slcb_devhandle = ocb.ocb_devhandle;
rcs_setlinectrl(&slcb);
if (slcb.slcb_retcode == 0)
.
.
RCS_SETLINECTRL Control Block (SLCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command | Equals 03h | RCS | | | | code | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return | See RICCS return codes | RCS | | 05h | | code | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | BITRATERCV | Bits per second | See BITRATERCV description| APP | | | | for receiving | in the RCS_SETLINECTRL | | | | | device | command | | +------+----------------+--------------------+---------------------------+-----+ | 07h | BITRATETRANS | Bits per second | See BITRATETRANS | APP | | | | for transmitting | description in the | | | | | device | RCS_SETKINECTRL command | | +------+----------------+--------------------+---------------------------+-----+ | 08h | STOPBITS | Number of stop | 0=No change | APP | | | | bits | 1=1 stop bit | | | | | | 2=1.5 stop bits | | | | | | 3=2 stop | | +------+----------------+--------------------+---------------------------+-----+ | 09h | PARITY | Parity mode | 0= No change | APP | | | | | 1= No parity | | | | | | 2=Odd parity | | | | | | 3=Even parity | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah | DATABITS | Number of data | 0=No change | APP | | | | bits | 1=5 data bits | | | | | | 2=6 data bits | | | | | | 3=7 data bits | | | | | | 4=8 data bits | | +------+----------------+--------------------+---------------------------+-----+ | 0Bh- | RESERVED | Reserved for | Must be 0 | APP | | 0Eh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
BITRATERCV is the number of bits per second at which the communication chips should receive data.
Note:
For the Realtime Interface Co-Processor and the IBM Realtime Interface Co-Processor Multiport, ensure that the jumpers have been set correctly for the desired clocking. For the IBM Realtime Interface Co-Processor Multiport/2 and the IBM X.25 Interface Co-Processor/2, ensure that the clock source has been set correctly with the reference diskette for the desired clocking.
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 0 | No change | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps (default) | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 19 | 76,800 bps | +------------+------------------------+ | 20 | 115,200 bps | +------------+------------------------+ | 21 | 460,800 bps | +------------+------------------------+Note:
The bit rates of 57,600 bps, 76,800 bps, 115,200 bps, and 460,800 bps are only supported on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.However, bit rates of 76,800 bps, 115,200 bps, and 460,800 bps are not supported when using the Selectable Interface Board/A on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters. External clocking from TRxC cannot be selected for an RS-422-A port on an IBM Realtime Interface Co-Processor.
BITRATETRANS is the number of bits per second at which the the communication chips should transmit data.
Note:
For the Realtime Interface Co-Processor and the IBM Realtime Interface Co-Processor Multiport, ensure that the jumpers have been set correctly for the desired clocking. For the IBM Realtime Interface Co-Processor Multiport/2 and the IBM X.25 Interface Co-Processor/2, ensure that the clock source has been set correctly with the reference diskette for the desired clocking.
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 0 | No change | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps (default) | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 19 | 76,800 bps | +------------+------------------------+ | 20 | 115,200 bps | +------------+------------------------+ | 21 | 460,800 bps | +------------+------------------------+Note:
The bit rates of 57,600 bps, 76,800 bps, 115,200 bps, and 460,800 bps are only supported on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters. However, bit rates of 76,800 bps, 115,200 bps, and 460,800 bps are not supported when using the Selectable Interface Board/A on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters. External clocking from TRxC cannot be selected for an RS-422-A port on an IBM Realtime Interface Co-Processor.
STOPBITS is the number of stop bits to be used by the asynchronous transmitter and receiver circuits for character encoding and decoding.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | 1 stop bit (default) | +------------+------------------------+ | 2 | 1.5 stop bits | +------------+------------------------+ | 3 | 2 stop bits | +------------+------------------------+PARITY is the parity used for each character encoding and decoding.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | No parity | +------------+------------------------+ | 2 | Odd parity | +------------+------------------------+ | 3 | Even parity (default) | +------------+------------------------+DATABITS is the number of data bits for each character encoding and decoding.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | 5 data bits | +------------+------------------------+ | 2 | 6 data bits | +------------+------------------------+ | 3 | 7 data bits (default) | +------------+------------------------+ | 4 | 8 data bits | +------------+------------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_RETLINECTRL command allows the application task to obtain the current settings of various communications line characteristics, including the bit rates, the number of stop bits, parity, and the number of data bits. This command can be issued at any time.
ASSEMBLER INTERFACE
PUSH Segment of RCS_RETLINECTRL Control Block PUSH Offset of RCS_RETLINECTRL Control Block CALL _rcs_retlinectrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RETURN LINE CONTROL CONTROL BLOCK (RLCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
RLCB RCSS_RETLINECTRL<,,,,,,,,,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RLCB. CALL THE
; RCS_RETLINECTRL SUBROUTINE TO RETURN THE CURRENT BIT RATE, STOP
; BIT, PARITY, AND DATA BIT VALUES.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV RLCB.RLCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN RLCB
LEA DI,RLCB ;LOAD OFFSET OF RLCB
PUSH CS ;SEGMENT OF RLCB
PUSH DI ;OFFSET OF RLCB
CALL _rcs_retlinectrl ;CALL LEVEL A SUB TO DO
;RETURN LINE CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RLCB.RLCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_retlinectrl rlcb; rcs_retlinectrl(&rlcb);RLCB is the RCS_RETLINECTRL Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Return Line Control control block (rlcb) */
/* and initialize parameters. */
struct rcss_retlinectrl rlcb;
/* Initialize the device handle parameter in the rlcb. Call the */
/* RCS_RETLINECTRL subroutine to return the current bit rate, stop */
/* bit, parity, and data bit values. */
rlcb.rlcb_devhandle = ocb.ocb_devhandle;
rcs_retlinectrl(&rlcb);
if (rlcb.rlcb_retcode == 0)
.
.
RCS_RETLINECTRL Control Block (RLCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 04h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | BITRATERCV | Bits per second | See BITRARERCV description| RCS | | | | for receiving | in the RCS_RETLINECTRL | | | | | device | command | | +------+----------------+--------------------+---------------------------+-----+ | 07h | BITRATETRANS | Bits per second | See BITRARETRANS | RCS | | | | for transmitting | description in the | | | | | device | RCS_RETLINECTRL command | | +------+----------------+--------------------+---------------------------+-----+ | 08h | STOPBITS | Number of stop | 1=1 stop bit | RCS | | | | bits | 2=1.5 stop bits | | | | | | 3=2 stop bits | | +------+----------------+--------------------+---------------------------+-----+ | 09h | PARITY | Parity mode | 1=No parity | RCS | | | | | 2=Odd parity | | | | | | 3=Even parity | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah | DATABITS | Number of data | 1=5 data bits | RCS | | | | bits | 2=6 data bits | | | | | | 3=7 data bits | | | | | | 4=8 data bits | | +------+----------------+--------------------+---------------------------+-----+ | 0Bh- | RESERVED | Reserved for | Must be 0 | RCS | | 0Eh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
BITRATERCV is the number of bits per second at which the asynchronous receive device operates when the communication chips receives data. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 19 | 76,800 bps | +------------+------------------------+ | 20 | 115,200 bps | +------------+------------------------+ | 21 | 460,800 bps | +------------+------------------------+Note:
Bit rates of 57,600 bps, 76,800 bps, 115,200 bps, and 460,800 bps are only supported by the RS-422-A electrical interface on the IBM Realtime Interface Co-Processor Portmaster Adapter/A, and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.Bit rates of 76,800 bps, 115,200 bps, and 460,800 bps are not supported when using the Selectable Interface Board/A on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.
BITRATETRANS is the number of bits per second at which the asynchronous transmit device operates when the communication chips transmit data. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 19 | 76,800 bps | +------------+------------------------+ | 20 | 115,200 bps | +------------+------------------------+ | 21 | 460,800 bps | +------------+------------------------+Note:
Bit rates of 57,600 bps, 76,800 bps, 115,200 bps, and 460,800 bps are only supported by the RS-422-A electrical interface on the IBM Realtime Interface Co-Processor Portmaster Adapter/A, and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.Bit rates of 76,800 bps, 115,200 bps, and 460,800 bps are not supported when using the Selectable Interface Board/A on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.
STOPBITS is the number of stop bits used by the asynchronous transmitter and receiver circuits for character encoding and decoding. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | 1 stop bit | +------------+------------------------+ | 2 | 1.5 stop bits | +------------+------------------------+ | 3 | 2 stop bits | +------------+------------------------+PARITY is the parity used for each character encoding and decoding. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | No parity | +------------+------------------------+ | 2 | Odd parity | +------------+------------------------+ | 3 | Even parity | +------------+------------------------+DATABITS is the number of data bits used for each character encoding and decoding. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | 5 data bits | +------------+------------------------+ | 2 | 6 data bits | +------------+------------------------+ | 3 | 7 data bits | +------------+------------------------+ | 4 | 8 data bits | +------------+------------------------+RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_RESET command resets the Serial Communication Controller interface hardware for a port, causing any active reads and writes to be aborted. This command is used when the application task detects an unusual condition indicating that the hardware is in an unknown state. This command resets the port to the current line characteristics, RS-232-C control signals, receive break duration, control input flow, control output flow, error substitution, notify status and echo status.
ASSEMBLER INTERFACE
PUSH Segment of RCS_RESET Control Block PUSH Offset of RCS_RESET Control Block CALL _rcs_reset ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RESET CONTROL BLOCK (RSTCB) AND INITIALIZE PARAMETERS
; SET BY THE APPLICATION TASK.
RSTCB RCSS_RESET <,,,,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RSTCB.
; CALL THE RCS_RESET SUBROUTINE TO RESET THE PORT.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV RSTCB.RSTCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN RSTCB
LEA DI,RSTCB ;LOAD OFFSET OF RSTCB
PUSH CS ;SEGMENT OF RSTCB
PUSH DI ;OFFSET OF RSTCB
CALL _rcs_reset ;CALL LEVEL A SUB TO DO
;RESET COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RSTCB.RSTCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_reset rstcb; rcs_reset(&rstcb);RSTCB is the RCS_RESET Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Reset control block (rstcb). */
struct rcss_reset rstcb;
/* Initialize the device handle parameter in the rstcb. */
/* Call the RCS_RESET subroutine to reset the port. */
rstcb.rstcb_devhandle = ocb.ocb_devhandle;
rcs_reset(&rstcb);
if (rstcb.rstcb_retcode == 0)
.
.
RCS_RESET Control Block (rstcb)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 05h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | RESERVED | Reserved for | Must be 0 | APP | | 07h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle that was obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_SHUTDOWN command terminates a specific RICCS driver (e.g. the asynchronous driver or synchronous driver using either the Zilog** or Signetics** serial chips) or all RICCS drivers either immediately or after all application tasks have closed their ports. When performing the RCS_SHUTDOWN command, RICCS stops all transmissions, frees all resources, and exits from the co-processor adapter.
Warning: This command should be used with caution; it unloads the RICCS driver task from the co-processor adapter.
ASSEMBLER INTERFACE
PUSH Segment of RCS_SHUTDOWN Control Block PUSH Offset of RCS_SHUTDOWN Control Block CALL _rcs_shutdown ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ALLOCATE THE SHUT DOWN CONTROL BLOCK (SDCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
SDCB RCSS_SHUTDOWN <,,0,,1,0,10h>
; CALL THE RCS_SHUTDOWN SUBROUTINE TO WAIT UNTIL THE PORT
; HAS BEEN CLOSED, BEFORE UNLOADING THE RICCS.COM TASK.
LEA DI,SDCB ;LOAD OFFSET OF SDCB
PUSH CS ;SEGMENT OF SDCB
PUSH DI ;OFFSET OF SDCB
CALL _rcs_shutdown ;CALL LEVEL A SUB TO DO
;SHUT DOWN COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SDCB.SDCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_shutdown sdcb; rcs_shutdown(&sdcb);SDCB is the RCS_SHUTDOWN Control Block
Example Call
#include "riccs.h"
/* Allocate the Shutdown control block (sdcb) */
/* and initialize parameters. */
struct rcss_shutdown sdcb = {0,0,0,0,1,0x10};
/* Call the RCS_SHUTDOWN subroutine to wait until the port */
/* has been closed before unloading the RICCS.COM task. */
rcs_shutdown(&sdcb);
if (sdcb.sdcb_retcode == 0)
.
.
RCS_SHUTDOWN Control Block (SDCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 06h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | RESERVED1 | Reserved; used by | Must be 0 | APP | | 03h | | RICCS | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | TYPESHUTDOWN | Type of shutdown | Bit0: | APP | | | | | 0=No wait | | | | | | 1=Wait | | +------+----------------+--------------------+---------------------------+-----+ | 07h | DRIVERID | Specific driver | 00h=All drivers | APP | | | | to shutdown | 10h=All Asynch | | | | | | 20h=All Synch | | | | | | 21h=Synch/Zilog** | | | | | | 22h=Synch/Signetics** | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
RESERVED reserved; value must be 0.
TYPESHUTDOWN indicates whether to shutdown immediately or wait until the application(s) close all ports.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | 0 | 0 | No Wait | | +-------+--------------------+ | | 1 | Wait | +-----+-------+--------------------+DRIVERID identifies which RICCS driver(s) should be shutdown. The following hex values are valid for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 00h | All drivers | +------------+------------------------+ | 10h | All asynchronous | | | drivers | +------------+------------------------+ | 20h | All synchronous | | | drivers | +------------+------------------------+ | 21h | Synchronous/Zilog** | | | driver | +------------+------------------------+ | 22h | Synchronous/Signetics* | | | * driver | +------------+------------------------+Note:
If no driver is loaded that matches the requested shutdown driver identification, the invalid driver identification return code (2200h) is returned.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1800h | Invalid driver task | | | number | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 2200h | Invalid driver | | | identification | +------------+------------------------+
The application task uses the RCS_READ command to obtain received data from an attached device. The data is placed in the application's input buffer specified in the RCS_READ command. The RCS_READ command has numerous options that allow the application task to control how it receives data.
The application task selects either to wait for the read to complete or to continue execution while completing the read. The no-wait RCS_READ feature requires the user's task to issue its own wait or check the post code. The user's task should check the READSTATUS parameter to determine when a no-wait RCS_READ has completed. The RICCS driver posts a no-wait RCS_READ with a post code value of 08h.
The driver is capable of queueing up to four read commands per port. The next RCS_READ is initiated immediately upon completion of the current RCS_READ. An alternative to issuing multiple RICCS read commands is to use a driver input buffer for storing received data.
If a Driver Input Buffer has been defined, the RCS_READ command does not directly read from the port, because the RICCS driver, based on previous commands, is continually reading data from the port and placing it in the Driver Input Buffer. The RCS_READ command causes data in the Driver Input Buffer to be transferred to the application's input buffer. If not enough data is in the buffer to complete the read, remaining data is read directly into the application's input buffer. This feature, if utilized, ensures that the RICCS driver is always prepared to accept data inputs, allowing the application task to process the data at its own pace. If a read error occurs while using a Driver Input Buffer, this buffer should be flushed. The use of a Driver Input Buffer simplifies application programming.
If no Driver Input Buffer has been defined, the RCS_READ command causes input data to be placed directly into the application's input buffer. The direct method is more efficient on a per character basis, but it requires the application task to issue RCS_READ commands rapidly to ensure that no data is lost.
The timeout feature of the command is used to ensure that the application task regains control within the specified period of time. A timeout value of 0 completes the read immediately, returning only the data already in the Driver Input Buffer and up to the amount specified in the RCS_READ command.
Note:
If multiple reads are issued, different control blocks must be used.
Warning: Ports 0 and 1 on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 with the 8 port RS-422-A physical interface receive data errors in the first message. It is the user's responsibility to handle this situation.
ASSEMBLER INTERFACE
PUSH Segment of RCS_READ Control Block PUSH Offset of RCS_READ Control Block CALL _rcs_read ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVHANDLE HAS BEEN
; RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE APPLICATION INPUT BUFFER.
RDBUFFER DB 100 DUP (0) ;READ BUFFER
; ALLOCATE THE READ CONTROL BLOCK (RCB) AND INITIALIZE PARAMETERS
; SET BY THE APPLICATION TASK.
RCB RCSS_READ <,,,,,,RDBUFFER,02H,0,80,1F4H,64H,0,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RCB. CALL
; THE RCS_READ SUBROUTINE TO DO A FIXED LENGTH, WAIT READ.
; IT WILL RECEIVE EIGHTY CHARACTERS AND WAIT FOR THE READ
; TO COMPLETE. THE READ MUST COMPLETE IN 5 SECONDS AND THE
; FIRST CHARACTER MUST BE RECEIVED IN 1 SECOND OR THE READ
; WILL TIMEOUT.
MOV BX,CS ;GET BUFFER SEGMENT
;SET READ BUFFER
;SEGMENT
MOV WORD PTR RCB.RCB_READBUFFER+2,BX
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV RCB.RCB_DEVHANDLE,AX ;STORE DEVICE HANDLE IN
;RCB
LEA DI,RCB ;LOAD OFFSET OF RCB
PUSH CS ;SEGMENT OF RCB
PUSH DI ;OFFSET OF RCB
CALL _rcs_read ;CALL LEVEL A SUB TO DO
;READ COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RCB.RCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_read rcb; rcs_read(&rcb);RCB is the RCS_READ Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Application Input Buffer */
char rdbuffer[100];
/* Allocate the Read control block (rcb) */
/* and initialize parameters. */
struct rcss_read rcb = {0,0,0,0,0,0,rdbuffer,0x02,0,
80,0x01f4,0x064,0,0,0};
/* Initialize the device handle parameter in the rcb. Call */
/* the RCS_READ subroutine to do a fixed length, wait read. */
/* It will receive eighty characters and wait for the read */
/* to complete. The read must complete in 5 seconds and the */
/* first character must be received in 1 second or the read */
/* will timeout. */
rcb.rcb_devhandle = ocb.ocb_devhandle;
rcs_read(&rcb);
if (rcb.rcb_retcode == 0)
.
.
RCS_READ Control Block (RCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 07h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | READSTATUS | Status bits | See READSTATUS description| RCS | | 07h | | pertaining to the | in the RCS_READ command | | | | | RCS_READ command | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | READCOUNT | Actual count of | | RCS | | 09h | | characters read | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | READBUFFER | Address of the | Segment:offset | APP | | 0Dh | | application input | | | | | | buffer | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | READMODE | Fixed/variable | Bit 0: 0=Fixed | APP | | | | | 1=Variable | | | | | Wait/no wait | Bit 1: 0=No wait | | | | | | 1=Wait | | | | | RS-232-C signal | Bit 2: 0=No termination on| | | | | action | state change | | | | | | 1=Terminate read on| | | | | | state change | | | | |Input buffer logical| Bit 3: 0=Logical | | | | | or physical address| 1=Physical | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | POSTTASKNUM | Task to be posted | Task is not required to | APP | | | | when a no-wait | have port open | | | | | completes | 0=Post task issuing the | | | | | | read. | | | | | |>0=Task number of task to | | | | | | post. | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | LENGTH | Number of | Equals bytes | APP | | 11h | | characters to be | Fixed read: Actual length | | | | | read | Variable read: | | | | | | Maximum length | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | TIMEOUT | Time to complete | Equals 10-ms. units | APP | | 13h | | the read | 0=Immediate timeout | | | | | | -1=Infinite timeout | | +------+----------------+--------------------+---------------------------+-----+ | 14h- |FIRSTCHARTIMEOUT| Time to receive the|Equals 10-millisecond units| APP | | 15h | | first character | -1=Infinite timeout | | +------+----------------+--------------------+---------------------------+-----+ | 16h- |INTERCHARTIMEOUT| Time between |Equals 10-millisecond units| APP | | 17h | | characters being | -1=Infinite timeout | | | | | received | | | +------+----------------+--------------------+---------------------------+-----+ | 18h- | STADDRESS | Address of the | Required for variable | APP | | 1Bh | | state table | length read | | | | | | Segment:offset | | | | | | See RCS_GENSTATETABLE | | +------+----------------+--------------------+---------------------------+-----+ | 1Ch- | RESERVED2 | Reserved for | Must be 0 | APP | | 1Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
READBUFFER is the address of the application input buffer.
Note:
This buffer is not a Driver Input Buffer. The Driver Input Buffer is defined using the RCS_DRIVERINPUTBUFFER command.
READMODE indicates:
+=====+=====+============================================+ | Bit |Value| Meaning | +=====+=====+============================================+ | | 0 | Fixed | | 0 +-----+--------------------------------------------+ | | 1 | Variable | +-----+-----+--------------------------------------------+ | | 0 | No wait | | 1 +-----+--------------------------------------------+ | | 1 | Wait | +-----+-----+--------------------------------------------+ | | 0 | No termination on state change | | 2 +-----+--------------------------------------------+ | | 1 | Terminate read on state change | +-----+-----+--------------------------------------------+ | | 0 | Input buffer is logical address | | 3 +-----+--------------------------------------------+ | | 1 | Input buffer is physical address | | | | Note: This bit only applies if a DMA | | | | and Peripheral Interface Chip | | | | (DMAPIC) DMA is used for reads. If | | | | a physical address is used and error | | | | substitution is turned on, error | | | | substitution is performed. | +-----+-----+--------------------------------------------+POSTTASKNUM is the task number posted when a no-wait read completes. This task number does not have to be the number of the task issuing the RCS_READ command. The task specified by this parameter is not required to have the port open.
+=======+===============+ | Value | Meaning | +=======+===============+ | 0 | Task issuing | | | the read | | | should be | | | posted. | | | (Default) | +-------+---------------+ | >0 | Task number | | | to post when | | | a no-wait | | | read | | | completes. | +-------+---------------+LENGTH indicates the actual number of characters to read for a fixed length RCS_READ, and indicates the maximum number of characters to read for a variable length RCS_READ.
TIMEOUT is the time, in 10-millisecond units, to complete the RCS_READ command prior to timing out. The timeout applies only to the individual occurrence of the RCS_READ command. The timer begins when the driver executes the RCS_READ command, not when the command is queued. A value of 0 indicates an immediate timeout and -1 indicates an infinite timeout.
FIRSTCHARTIMEOUT is the time, in 10-millisecond units, to receive the first character prior to timing out. The FIRSTCHARTIMEOUT applies only to the individual occurrence of the RCS_READ command. The timer begins when the driver executes the RCS_READ command, not when the command is queued. A value of -1 indicates an infinite timeout.
INTERCHARTIMEOUT is the time, in 10-millisecond units, between characters received before timing out. The INTERCHARTIMEOUT does not take effect until the first character has been received. A value of -1 indicates an infinite timeout between characters.
STADDRESS is the address of the State Table required for the variable length RCS_READ. For information on how to generate the State Table, see "RCS_GENSTATETABLE".
RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command. The return code is not loaded until the read completes READSTATUS (bit 0 is set).
READSTATUS is a collection of status bits pertaining to the RCS_READ command. and should not be checked until the read completes (bit 0 is set). These bits pertain to the time between the completion of the previous RCS_READ command to the completion of the current RCS_READ command. READSTATUS has the following bit format:
+=====+=======+==============================================================+ | Bit | Value | Meaning | +=====+=======+==============================================================+ | | 0 | RCS_READ command not completed yet | | 0 +-------+--------------------------------------------------------------+ | | 1 | RCS_READ command completed | +-----+-------+--------------------------------------------------------------+ | | 0 | No control signal state change since last RCS_SETCTRLSIGNAL, | | | | RCS_RETCTRLSIGNAL, or RCS_READ. | | 1 +-------+--------------------------------------------------------------+ | | 1 | Control signal state change since last | | | | RCS_SETCTRLSIGNAL,RCS_RETCTRLSIGNAL, or RCS_READ. | | | | Note: State changes occurring after an RCS_OPEN | | | | or RCS_RESET, but before an initial RCS_SETCTRLSIGNAL, | | | | RCS_RETCTRLSIGNAL, or RCS_READ command, are not | | | | reported. Ring Indicator (RI) presence is indicated in | | | | bit 4, because its duration is not expected to be | | | | very long. | +-----+-------+--------------------------------------------------------------+ | | 0 | Transmission started | | 2 +-------+--------------------------------------------------------------+ | | 1 | Transmission stopped | +-----+-------+--------------------------------------------------------------+ | | 0 | Input buffer not full | | 3 +-------+--------------------------------------------------------------+ | | 1 | Input buffer full | | | | Note: This status bit applies only to variable length reads. | +-----+-------+--------------------------------------------------------------+ | | 0 | No Ring Indicator signal present | | 4 +-------+--------------------------------------------------------------+ | | 1 | Ring Indicator signal present | +-----+-------+--------------------------------------------------------------+ | | 0 | No Break Signal detected | | 5 +-------+--------------------------------------------------------------| | | 1 | Break Signal detected | | | | Note: The minimum duration required for a received break | | | | signal can be set by using RCS_SETMINBREAK. | +-----+-------+--------------------------------------------------------------+ | 6 | 0 | Reserved (will be zero) | +-----+-------+--------------------------------------------------------------+ | | 0 | Input data flow allowed | | 7 +-------+--------------------------------------------------------------+ | | 1 | Input data flow should be inhibited | | | | Note: Once high threshold is reached this bit is set. The | | | | clearing of this bit occurs after reaching low | | | | threshold. | +-----+-------+--------------------------------------------------------------+ | | 0 | RCS_READ command did not timeout | | 8 +-------+--------------------------------------------------------------+ | | 1 | RCS_READ command timeout | +-----+-------+--------------------------------------------------------------+ | 9 | 0 | Reserved (will be zero) | +-----+-------+--------------------------------------------------------------+ | | 0 | No character overrun occurred | | 10 +-------+--------------------------------------------------------------+ | | 1 | Character overrun occurred | | | | Note: Overrun means that the communications hardware | | | | indicated an overrun error. | +-----+-------+--------------------------------------------------------------+ | | 0 | No parity error occurred | | 11 +-------+--------------------------------------------------------------+ | | 1 | Parity error occurred | +-----+-------+--------------------------------------------------------------+ | | 0 | No framing error occurred | | 12 +-------+--------------------------------------------------------------+ | | 1 | Framing error occurred | +-----+-------+--------------------------------------------------------------+ | 13 | 0 | Reserved (will be zero) | +-----+-------+--------------------------------------------------------------+ | | 0 | RCS_READ was not terminated by another command | | 14 +-------+--------------------------------------------------------------+ | | 1 | RCS_READ was terminated by an RCS_SETLINECTRL, RCS_SHUTDOWN, | | | | RCS_RESET, RCS_CANCELREADS, or other command | +-----+-------+--------------------------------------------------------------+ | | 0 | No other receiver error detected | | 15 +-------+--------------------------------------------------------------+ | | 1 | Other receiver error detected | +-----+-------+--------------------------------------------------------------+READCOUNT indicates the actual number of characters read. This count is not loaded until the read completes (READSTATUS bit 0 is set).
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1200h | Read error | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_GENSTATETABLE utility generates a state table from an easily coded Variable Length Read Control Block (VLRCB). This utility enables the RICCS driver to handle a variety of protocols efficiently.
The Variable Length Read Control Block is used to define the following control sequences that affect variable length read:
Application tasks should call RCS_GENSTATETABLE once for each unique VLRCB (multiple VLRCBs are allowed) during initialization of the task, and then pass the generated state table address to the RICCS driver in the RCS_READ command.
A portion of the VLRCB consists of variables that inform the driver how to handle transparent input data. Transparent mode allows binary data to be sent and received while preventing data characters from being misinterpreted as control characters. Many asynchronous protocols incorporate the transparent mode method used in the IBM Binary Synchronous Communications (BSC) protocol. The RICCS driver handles transparent mode by following the BSC method when receiving data.
Note:
The RICCS does not have BSC communications capability.
In BSC transparent mode the data portion of a message is framed by an SOM sequence and an EOM sequence. Binary data characters can appear to match the EOM sequence; therefore, the sender of the data must scan the binary data and search for data characters matching the EOM sequence, the Insert Character. If no match is found; no conflict exists. If a match is found, an additional Insert Character must be placed in the data at the point where the match was found. This process continues until the end of data is reached.
Note:
When using RICCS application the user is responsible for inserting the transparent characters in transmitted data.
The receiver of the data also scans the data, beginning immediately after recognition of the SOM sequence. If a match is found, the next character is interrogated. If the next character also matches the Insert Character, it is discarded. The procedure removes all inserted characters and prevents the received data from matching the EOM sequence. Upon request, the RICCS driver strips the insert character from the received data for the user application task.
Different protocols use various SOM sequences and EOM sequences when implementing this method. The VLRCB allows the application task to switch on transparent mode and to define the Insert Character, SOM sequences, and EOM sequences. When handling transparent mode, all EOM sequences must start with the Insert Character.
RCS_GENSTATETABLE allows the application task to select if characters received before the SOM or TERM sequences should be discarded or stored in the application task's input buffer. The inserted transparency characters (described previously) can also be discarded or stored. The application task selects either 128 or 256 bytes for the size of the character set for the protocol in use.
RCS_GENSTATETABLE determines if the specified protocol allows DMA use for variable length reads. If DMA can be used for variable length reads, RCS_GENSTATETABLE sets control variables in the state table for RICCS to use when starting a read.
When using the state table, the following assumptions about the asynchronous protocols are made:
PUSH Segment of RCS_GENSTATETABLE Control Block PUSH Offset of RCS_GENSTATETABLE Control Block CALL _rcs_genstatetable ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; DEFINE STATE TABLE.
STATE_TAB DB 1000 DUP (0) ;STATE TABLE
; ALLOCATE THE CONTROL SEQUENCES AND INITIALIZE PARAMETERS SET BY
; THE APPLICATION TASK.
TERMCSB RCSS_CSB <4,'P','Q','R','S'> ;TERMINATION
TERMCSB1 RCSS_CSB <3,'J','K','L'> ;TERMINATION
TERMCSB2 RCSS_CSB <2,'M','N'> ;TERMINATION
TERMCSB3 RCSS_CSB <1,'Q'> ;TERMINATION
SOMCSB RCSS_CSB <3,'A','B','C'> ;START OF MESSAGE
EOMCSB RCSS_CSB <3,'X','Y','Z'> ;END OF MESSAGE
; ALLOCATE THE VARIABLE LENGTH READ CONTROL BLOCK (VLRCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
VLRCB RCSS_GENSTATETABLE
<03H,X,0,0,STATE_TAB,1000,,,4,1,1,TERMCSB,SOMCSB,EOMCSB>
; FOR A VARIABLE LENGTH READ, CALL THE RCS_GENSTATETABLE UTILITY
; TO GENERATE A STATE TABLE WITH A MAXIMUM SIZE OF 1000 BYTES.
; THE TRANSPARENT MODE IS HANDLED, THE INSERT CHARACTER 'X'
; IS DELETED, CHARACTERS PRIOR TO RECEIVING THE START
; OF MESSAGE OR TERMINATION SEQUENCE ARE STORED, AND THE
; PROTOCOL USES A 128 BYTE CHARACTER SET. FOUR TERMINATION, ONE
; START OF MESSAGE, AND ONE END OF MESSAGE CONTROL SEQUENCE IS
; DEFINED.
MOV BX,CS ;GET STATE TABLE AND
;CONTROL SEQUENCES
;SEGMENTS
;SET STATE TABLE
;AND CONTROL
;SEQUENCES SEGMENTS
MOV WORD PTR VLRCB.VLRCB_STADDRESS+2,BX
MOV WORD PTR VLRCB.VLRCB_TERMADDRESS+2,BX
MOV WORD PTR VLRCB.VLRCB_SOMADDRESS+2,BX
MOV WORD PTR VLRCB.VLRCB_EOMADDRESS+2,BX
LEA DI,VLRCB ;LOAD OFFSET OF VLRCB
PUSH CS ;SEGMENT OF VLRCB
PUSH DI ;OFFSET OF VLRCB
CALL _rcs_genstatetable ;CALL LEVEL A SUB TO DO
;GENERATE STATE TABLE
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP VLRCB.VLRCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
C CALL FORMAT
struct rcss_genstatetable vlrcb; rcs_genstatetable(&vlrcb);VLRCB is the Variable Length Read Control Block
Example Call
#include "riccs.h"
/* State table */
char state_tab[1000];
/* Initialize Control Sequences */
struct rcss_csb termcsb [4] = {0x01,"H"}, {0x02,"IJ"},
{0x03,"PQR"},{0x04,"DEFG"}; /* Termination */
struct rcss_csb somcsb = {0x03,"ABC"}; /* Start of Message */
struct rcss_csb eomcsb = {0x03,"XYZ"}; /* End of Message */
/* Allocate the Variable length read control block (vlrcb) and */
/* initialize parameters. */
struct rcss_genstatetable vlrcb = {0x03,'X',0,0,state_tab,1000,0,0,4,
1,1, termcsb,&somcsb,&eomcsb};
/* For a variable length read, call the RCS_GENSTATETABLE utility */
/* to generate a state table with a maximum size of 1000 bytes. */
/* The transparent mode is handled, the insert character 'X' */
/* is deleted, characters prior to receiving the start */
/* of message or termination sequence are stored, and the */
/* protocol uses a 128 byte character set. Four termination, one */
/* start of message, and one end of message control sequence is */
/* defined. */
rcs_genstatetable(&vlrcb);
if (vlrcb.vlrcb_retcode == 0)
.
.
Variable Length Read Control Block (VLRCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | OPTIONS | Options for the |Bit 0: | APP | | | | variable length | 0=Non-Transparent mode | | | | | read | 1=Transparent mode | | | | | |Bit 1: | | | | | | 0=Store redundant insert | | | | | | character | | | | | | 1=Delete redundant insert | | | | | | character | | | | | |Bit 2: | | | | | | 0=Store characters prior | | | | | | to SOM/TERM | | | | | | 1=Delete characters prior | | | | | | to SOM/TERM | | | | | |Bit 3: | | | | | | 0=Protocol uses 7-bit | | | | | | character set | | | | | | 1=Protocol uses 8-bit | | | | | | character set | | +------+----------------+--------------------+---------------------------+-----+ | 01h | INSERTCHAR | Character inserted | | APP | | | | when operating in | | | | | | transparent mode | | | +------+----------------+--------------------+---------------------------+-----+ | 02h | RESERVED1 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 03h | RESERVED2 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | STADDRESS | Address of state | Segment:offset | APP | | 07h | | table | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | STMAXSIZE | Size of space | Equals bytes | APP | | 09h | | provided for state | | | | | | table | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | RETCODE | Return code | See RICCS return codes | RCS | | 0Bh | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 0Ch- | STSIZE | State table size | Equals bytes | RCS | | 0Dh | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 0Eh- | NUMTERMBLKS | Number of | | APP | | 0Fh | | termination blocks | | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | NUMSOMBLKS | Number of Start of | | APP | | 11h | | Message blocks | | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | NUMEOMBLKS | Number of End of | | APP | | 13h | | Message blocks | | | +------+----------------+--------------------+---------------------------+-----+ | 14h- | TERMADDRESS | Address of first | Segment:offset | APP | | 17h | | Ternimation block | | | +------+----------------+--------------------+---------------------------+-----+ | 18h- | SOMADDRESS | Address of first | Segment:offset | APP | | 1Bh | | Start of Message | | | | | | block | | | +------+----------------+--------------------+---------------------------+-----+ | 1Ch- | EOMADDRESS | Address of first | Segment:offset | APP | | 1Fh | | End of Message | | | | | | block | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
OPTIONS is a set of bits indicating which options to perform for variable length reads.
+=====+=======+==============================================================+
| Bit | Value | Meaning |
+=====+=======+==============================================================+
| | 0 | Non-transparent mode |
| 0 +-------+--------------------------------------------------------------+
| | 1 | Transparent mode |
+-----+-------+--------------------------------------------------------------+
| | 0 | Store redundant insert character |
| 1 +-------+--------------------------------------------------------------+
| | 1 | Delete redundant insert character |
| | | {Only if Bit 0 = 1 (transparent mode)} |
+-----+-------+--------------------------------------------------------------+
| | 0 | Store characters prior to SOM/TERM |
| 2 +-------+--------------------------------------------------------------+
| | 1 | Purge characters prior to SOM/TERM |
+-----+-------+--------------------------------------------------------------+
| | 0 | Protocol uses 7 bit character set |
| 3 +-------+--------------------------------------------------------------+
| | 1 | Protocol uses 8 bit character set |
+-----+-------+--------------------------------------------------------------+
Bit assignments:
7 6 5 4 3 2 1 0
| | | | | | | +--- Transparent mode
| | | | | | +------ Delete redundant insert character
| | | | | +--------- Purge characters prior to SOM/TERM
| | | | +------------ Protocol uses 8-bit character set
| | | +--------------- Reserved
| | +------------------ Reserved
| +--------------------- Reserved
+------------------------ Reserved
INSERTCHAR is the character to be inserted when operating in
transparent mode.
RESERVED1 reserved; value must be 0.
RESERVED2 reserved; value must be 0.
STADDRESS is the address of the State Table.
STMAXSIZE is the maximum size of the space provided for the state table. If the maximum size is reached, RCS_GENSTATETABLE aborts, returning the insufficient space return code (1600h). For a given protocol, the size of the STMAXSIZE (in bytes) can be approximated as follows:
STMAXSIZE = 10 + CS + NS (UC + 1)
NUMTERMBLKS is the number of Termination Blocks.
NUMSOMBLKS is the number of Start of Message Blocks.
NUMEOMBLKS is the number of End of Message Blocks.
TERMADDRESS is the address of the first Termination Block.
SOMADDRESS is the address of the first Start of Message Block.
EOMADDRESS is the address of the first End of Message Block.
Exit Parameters
RETCODE is the return code from the called command.
STSIZE is the actual size of the State Table.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1600h | Insufficient space | +------------+------------------------+Control Sequence Blocks
The Control Sequence Block (CSB) is a 5-byte block used to define Termination Control Sequence Blocks, Start of Message Control Sequence Blocks, and End of Message Control Sequence Blocks. The structure definition for the Control Sequence Block is RCSS_CSB.
Control Sequence Block (CSB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | LENTRAIL | Length of control | Bits 0-3: | APP | | | | sequence. Number | Maximum length=4 | | | | | of characters | Bits 4-7: | | | | | trailing the | Maximum trailing | | | | | control sequence | characters=7 | | +------+----------------+--------------------+---------------------------+-----+ | 01h- | CONTROLSEQ | Control sequence | Maximum length of control | APP | | 04h | | | sequence string=4 bytes | | +------+----------------+--------------------+---------------------------+-----+LENTRAIL contains bits 0-3, the length of control sequence in bytes, and bits 4-7, the number of characters that trail the control sequence, generally error check characters.
CONTROLSEQ is a 4-byte field containing a variable length control sequence string (4 byte maximum) that specifies the characters that must exactly match the input characters.
The application task uses the RCS_DRIVERINPUTBUFFER command to define a buffer to RICCS for data input. Without the existence of the Driver Input Buffer, physical reads would occur directly into the application's input buffer defined in the RCS_READ command. When a Driver Input Buffer is defined, the driver is always prepared to accept data inputs. Only one Driver Input Buffer per port can be active at any time. Subsequent Driver Input Buffer commands discard the existing buffer and erase any data in the buffer. The active Driver Input Buffer should not be accessed by the application task.
The application task specifies the Driver Input Buffer and determines its size. The Driver Input Buffer should be large enough to handle the largest message that can be received, +10 bytes (used by the RICCS driver for buffer control). To properly utilize this feature, this buffer should be large enough to handle multiple input messages.
ASSEMBLER INTERFACE
PUSH Segment of RCS_DRIVERINPUTBUFFER Control Block PUSH Offset of RCS_DRIVERINPUTBUFFER Control Block CALL _rcs_driverinputbuffer ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE THE DRIVER INPUT BUFFER
DIBUFFER DB 100 DUP (0) ;DRIVER INPUT BUFFER
; ALLOCATE THE DRIVER INPUT BUFFER CONTROL BLOCK (DIBCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DIBCB RCSS_DRIVERINPUTBUFFER<,,,,DIBUFFER,1,90,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE DIBCB. CALL THE
; RCS_DRIVERINPUTBUFFER SUBROUTINE TO SET THE INPUT BUFFERING
; METHOD TO DRIVER INPUT BUFFER AND ALLOCATE A NINETY BYTE
; DRIVER INPUT BUFFER.
MOV BX,CS ;GET BUFFER SEGMENT
;SET DRIVER INPUT
;BUFFER SEGMENT
MOV WORD PTR DIBCB.DIBCB_DRIVERBUFFER+2,BX
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV DIBCB.DIBCB_DEVHANDLE,AX ;STORE DEVICE HANDLE IN
;DIBCB
LEA DI,DIBCB ;LOAD OFFSET OF DIBCB
PUSH CS ;SEGMENT OF DIBCB
PUSH DI ;OFFSET OF DIBCB
CALL _rcs_driverinputbuffer ;CALL LEVEL A SUB TO DO
;DRIVER INPUT BUFFER COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DIBCB.DIBCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_driverinputbuffer dibcb; rcs_driverinputbuffer(&dibcb);DIBCB is the RCS_DRIVERINPUTBUFFER Control Block Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Driver Input Buffer */
char dibuffer[100];
/* Allocate the Driver Input Buffer control block (dibcb) */
/* and initialize parameters. */
struct rcss_driverinputbuffer dibcb = {0,0,0,0,dibuffer,1,90,0};
/* Initialize the device handle parameter in the dibcb. Call the */
/* RCS_DRIVERINPUTBUFFER subroutine to set the input buffering */
/* method to Driver Input Buffer and allocate a ninety byte */
/* Driver Input Buffer. */
dibcb.dibcb_devhandle = ocb.ocb_devhandle;
rcs_driverinputbuffer(&dibcb);
if (dibcb.dibcb_retcode == 0)
.
.
RCS_DRIVERINPUTBUFFER Control Block (DIBCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 08h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | DRIVERBUFFER | Address of the | Segment:offset | APP | | 09h | | Driver Input Buffer| | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | BUFFERMETHOD | Input buffering | 0=Direct method | APP | | 0Bh | | method | 1=Driver Input Buffer | | | | | | method | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch- |DRIVERBUFFLENGTH| Size of the Driver | Equals the number of bytes| APP | | 0Dh | | Input Buffer | Buffer cannot cross | | | | | | segment boundary | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh- | RESERVED | Reserved for | Must be 0 | APP | | 0Fh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
DRIVERBUFFER is the address of the Driver Input Buffer. This value is used only if an application task specifies BUFFERMETHOD = 1 (Driver Input Buffer).
BUFFERMETHOD indicates which buffer should be used for data input. This parameter may be used to convert back to the direct buffer method.
+=====+=======+==============================================================+ | Bit | Value | Meaning | +=====+=======+==============================================================+ | | 0 | Direct buffering (default) | | 0 +-------+--------------------------------------------------------------+ | | 1 | Driver Input Buffer | +-----+-------+--------------------------------------------------------------+DRIVERBUFFLENGTH is the size, in bytes, of the Driver Input Buffer. Include 10 bytes for overhead when determining the size of the buffer. This value is used only if an application task specifies BUFFERMETHOD = 1 (Driver Input Buffer).
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1300h | Driver Input Buffer | | | undefined | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_WRITE command transmits data and allows the application to control how the write is performed. The number of bytes is transmitted from the application's output buffer, as specified in the RCS_WRITE command. Normal writes are queued if a previous write is pending or if transmissions are stopped. There can be up to 16 queued writes per port for normal writes.
The application task can specify that the write should occur immediately, ignoring whether transmissions are stopped or started. Writes already in progress are allowed to complete unless transmissions are stopped. If transmissions are stopped, the write in progress is terminated and the immediate write is performed. Up to four immediate writes can be queued per port.
Several other features provide flexibility to the application task. The "timeout" feature ensures that the application regains control within a specified period of time if the write has not completed.
Note:
The timeout feature has the following effect on the RCS_WRITE command:The application task can select either to wait until the write completes or select to continue execution while the write completes. The no-wait RCS_WRITE feature requires the user's task to issue its own wait or to check the post code for completion. The user's task should check the WRITESTATUS parameter to determine when a no-wait RCS_WRITE has completed. The RICCS driver posts a no-wait RCS_WRITE with a post code value of 18h.
- If transmissions are stopped and an RCS_WRITE is queued (not in progress), no timeout occurs
- If transmissions are stopped and an RCS_WRITE is in progress, a timeout can occur.
For attached devices that cannot receive data as quickly as their bit rate allows, a character spacing feature induces a time delay between each byte transmitted. Specifying a character spacing value in the RCS_WRITE command precludes the use of DMA for the write, even if DMA was specified in the RCS_OPEN or RCS_DMAWRITECTRL command.
Note:
The IBM X.25 Interface Co-Processor/2, IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters require the Request To Send (RTS) control signal to be on before transmission can occur. If transmissions are turned off, transmissions are stopped until the signal is turned back on. It is the application programmer's responsibility to ensure that this signal is on; however, this signal is on by default. (The RCS_SETCTRLSIGNAL command can be used to turn on the RTS signal.)
ASSEMBLER INTERFACE
PUSH Segment of RCS_WRITE Control Block PUSH Offset of RCS_WRITE Control Block CALL _rcs_write ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE APPLICATION OUTPUT BUFFER.
WRBUFFER DB 1000 DUP ('A') ;WRITE BUFFER
; ALLOCATE THE WRITE CONTROL BLOCK (WCB) AND INITIALIZE PARAMETERS
; SET BY THE APPLICATION TASK.
WCB RCSS_WRITE <,,,,,,WRBUFFER,02H,0,80,1F4H,-1,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE WCB. CALL THE
; RCS_WRITE SUBROUTINE TO TRANSMIT EIGHTY CHARACTERS, WAITING
; FOR THE WRITE TO COMPLETE. THE WRITE MUST COMPLETE IN 5 SECONDS.
MOV BX,CS ;GET BUFFER SEGMENT
;SET WRITE BUFFER
;SEGMENT
MOV WORD PTR WCB.WCB_WRITEBUFFER+2,BX
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV WCB.WCB_DEVHANDLE,AX ;STORE DEVICE HANDLE IN
;WCB
LEA DI,WCB ;LOAD OFFSET OF WCB
PUSH CS ;SEGMENT OF WCB
PUSH DI ;OFFSET OF WCB
CALL _rcs_write ;CALL LEVEL A SUB TO DO
;WRITE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP WCB.WCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
C CALL FORMAT
struct rcss_write wcb; rcs_write(&wcb);WCB is the RCS_WRITE Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Application Output Buffer */
char wrbuffer[1000] = "A";
/* Allocate the Write control block (wcb) */
/* and initialize parameters. */
struct rcss_write wcb = {0,0,0,0,0,0,wrbuffer,0x02,
0,80,0x01f4,-1,0};
/* Initialize the device handle parameter in the wcb. Call the */
/* RCS_WRITE subroutine to transmit eighty characters, waiting */
/* for the write to complete. The write must complete in 5 */
/* seconds. */
wcb.wcb_devhandle = ocb.ocb_devhandle;
rcs_write(&wcb);
if (wcb.wcb_retcode == 0)
.
.
RCS_WRITE Control Block (WCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 09h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | WRITESTATUS | Status bits | See WRITESTATUS | RCS | | 07h | | pertaining to the | description on the | | | | | RCS_WRITE command | RCS_WRITE command | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | WRITECOUNT | Actual count of | | RCS | | 09h | | characters written | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | WRITEBUFFER | Address of | Segment:offset | APP | | 0Dh | | application output | | | | | | buffer | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | TYPEWRITE | Type of write | Bit 0: | APP | | | | | 0=Normal | | | | | | 1=Immediate | | | | | No Wait/Wait | Bit 1: | | | | | | 0=No wait | | | | | | 1=Wait | | | | | Output buffer | Bit 3: | | | | | logical or physical| 0=Logical | | | | | address | 1=Physical | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | POSTTASKNUM | Task number to be | Task is not required to | APP | | | | posted when a | to have port open | | | | | no-wait write | 0=post task issuing the | | | | | completes | write. | | | | | | >0=Task number of task to | | | | | | post. | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | LENGTH |Number of characters| Equals bytes | APP | | 11h | | to write | | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | TIMEOUT | Time to complete | Equals 10 millisecond | APP | | 13h | | write | units | | | | | | -1=Infinite timeout | | +------+----------------+--------------------+---------------------------+-----+ | 14h- | CHARSPACING | Time between | Equals 10 millisecond | APP | | 15h | | transmitting | units | | | | | characters | -1=No spacing | | +------+----------------+--------------------+---------------------------+-----+ | 16h- | RESERVED2 | Reserved for | Must be 0 | APP | | 17h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
WRITEBUFFER is the address of the application output buffer.
TYPEWRITE indicates:
+=====+=======+==============================================================+ | Bit | Value | Meaning | +=====+=======+==============================================================+ | | 0 | Normal | | 0 +-------+--------------------------------------------------------------+ | | 1 | Immediate | +-----+-------+--------------------------------------------------------------+ | | 0 | No wait | | 1 +-------+--------------------------------------------------------------+ | | 1 | Wait | +-----+-------+--------------------------------------------------------------+ | 2 | 0 | Reserved | +-----+-------+--------------------------------------------------------------+ | | 0 | Output buffer is logical address | | 3 +-------+--------------------------------------------------------------+ | | 1 | Output buffer is physical address | | | | Note: This bit only applies if DMAPIC DMA is used for writes.| +-----+-------+--------------------------------------------------------------+POSTTASKNUM is the task number posted when a no-wait write completes. This task number does not have to be the number of the task issuing the RCS_WRITE command. The task specified by this parameter is not required to have the port open.
+=======+===============+ | Value | Meaning | +=======+===============+ | 0 | Task issuing | | | the write | | | should be | | | posted. | | | (Default) | +-------+---------------+ | >0 | Task number | | | to post when | | | a no-wait | | | write | | | completes. | +-------+---------------+LENGTH is the actual number of characters to write.
TIMEOUT is the time, in 10-millisecond units, to complete the RCS_WRITE command prior to timing out. The timeout applies only to the individual occurrence of the RCS_WRITE command. The timer begins when the driver executes the RCS_WRITE command. A value of -1 indicates an infinite timeout. This timeout is used for a DMA RCS_WRITE command.
Note:
Short duration timeouts can be a problem if required transmission time (dependent on bit rate) exceeds the timeout.
CHARSPACING is the minimum time, in 10-millisecond units, between transmissions of each character. A value of -1 indicates no spacing between transmission of each character. RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command. The return code is not loaded until the write commands completes (WRITESTATUS bit 0 is set).
WRITESTATUS is a collection of status bits relating to the RCS_WRITE command should not be checked until the write completes (bit 0 is set). WRITESTATUS has the following format:
+=====+=======+==============================================================+ | Bit | Value | Meaning | +=====+=======+==============================================================+ | | 0 | RCS_WRITE command not completed yet | | 0 +-------+--------------------------------------------------------------+ | | 1 | RCS_WRITE command completed | +-----+-------+--------------------------------------------------------------+ | | 0 | No control signal state change since last RCS_SETCTRLSIGNAL, | | | | RCS_RETCTRLSIGNAL, or RCS_WRITE | | 1 +-------+--------------------------------------------------------------+ | | 1 | Control signal state change since last RCS_SETCTRLSIGNAL, | | | | RCS_RETCTRLSIGNAL, or RCS_WRITE | | | | Note: State changes occurring after an RCS_OPEN or RCS_RESET,| | | | but before an initial RCS_SETCTRLSIGNAL, | | | | RCS_RETCTRLSIGNAL, or RCS_WRITE command are not | | | | reported. | +-----+-------+--------------------------------------------------------------+ | | 0 | Transmissions started | | 2 +-------+--------------------------------------------------------------+ | | 1 | Transmissions stopped | +-----+-------+--------------------------------------------------------------+ | 3 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 4 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 5 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 6 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 7 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | | 0 | RCS_WRITE command did not timeout | | 8 +-------+--------------------------------------------------------------+ | | 1 | RCS_WRITE command timeout | +-----+-------+--------------------------------------------------------------+ | 9 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 10 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 11 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 12 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | 13 | 0 | Reserved (will be 0) | +-----+-------+--------------------------------------------------------------+ | | 0 | Write was not terminated by another command | | 14 +-------+--------------------------------------------------------------+ | | 1 | Write was terminated by an Immediate RCS_WRITE, RCS_SHUTDOWN,| | | | RCS_CANCELWRITES, RCS_SENDBREAK, RCS_RESET, or other command.| +-----+-------+--------------------------------------------------------------+ | | 0 | No other transmitter error detected | | 15 +-------+--------------------------------------------------------------+ | | 1 | Other transmitter error detected | +-----+-------+--------------------------------------------------------------+WRITECOUNT indicates the actual number of characters written. This count is not loaded until the write completes (WRITESTATUS bit 0 is set).
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1400h | Write error | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_SENDBREAK command causes the RICCS driver to instruct the interface hardware to generate a break signal. The application task controls the duration of this signal. The generation of the break signal waits for a write in progress to complete. If transmissions are stopped, the RICCS driver terminates a write in progress and generates the break immediately.
ASSEMBLER INTERFACE
PUSH Segment of RCS_SENDBREAK Control Block PUSH Offset of RCS_SENDBREAK Control Block CALL _rcs_sendbreak ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE SEND BREAK CONTROL BLOCK (SBCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
SBCB RCSS_SENDBREAK <,,,,30,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE SBCB. CALL THE
; RCS_SENDBREAK SUBROUTINE TO SEND A BREAK SIGNAL LASTING 300
; MILLISECONDS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV SBCB.SBCB_DEVHANDLE,AX ;STORE DEVICE HANDLE IN
;SBCB
LEA DI,SBCB ;LOAD OFFSET OF SBCB
PUSH CS ;SEGMENT OF SBCB
PUSH DI ;OFFSET OF SBCB
CALL _rcs_sendbreak ;CALL LEVEL A SUB TO DO
;SEND BREAK COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SBCB.SBCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_sendbreak sbcb; rcs_sendbreak(&sbcb);SBCB is the RCS_SENDBREAK Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Send Break control block (sbcb) */
/* and initialize parameters. */
struct rcss_sendbreak sbcb = {0,0,0,0,30,0};
/* Initialize the device handle parameter in the sbcb. Call the */
/* RCS_SENDBREAK subroutine to send a break signal lasting 300 */
/* milliseconds. */
sbcb.sbcb_devhandle = ocb.ocb_devhandle;
rcs_sendbreak(&sbcb);
if (sbcb.sbcb_retcode == 0)
.
.
RCS_SENDBREAK Control Block (SBCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Ah | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | SENDDURATION | How long the break | Equals 10 millisecond | APP | | 07h | | signal should last | units | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
SENDDURATION indicates how long the break signal should last. The time is expressed in 10-millisecond units. When setting the SENDDURATION parameter, use the following formula:
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1400h | Write error | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_SETMINBREAK command defines the minimum time a received break signal must persist to be recognized by the RICCS driver. The application task(s) controls the minimum duration for this signal to be recognized. If no RCS_SETMINBREAK command is issued, the default is 300 milliseconds.
ASSEMBLER INTERFACE
PUSH Segment of RCS_SETMINBREAK Control Block PUSH Offset of RCS_SETMINBREAK Control Block CALL _rcs_setminbreak ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE SET MINIMUM BREAK CONTROL BLOCK (SMBCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
SMBCB RCSS_SETMINBREAK <,,,,60,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE SMBCB. CALL THE
; RCS_SETMINBREAK SUBROUTINE TO DEFINE 600 MILLISECONDS AS THE
; MINIMUM TIME A RECEIVED BREAK SIGNAL MUST PERSIST IN ORDER FOR
; THE RICCS DRIVER TO RECOGNIZE A BREAK SIGNAL.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV SMBCB.SMBCB_DEVHANDLE,AX ;STORE DEVICE HANDLE IN
;SMBCB
LEA DI,SMBCB ;LOAD OFFSET OF SMBCB
PUSH CS ;SEGMENT OF SMBCB
PUSH DI ;OFFSET OF SMBCB
CALL _rcs_setminbreak ;CALL LEVEL A SUB TO DO
;CLOSE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SMBCB.SMBCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_setminbreak smbcb; rcs_setminbreak(&smbcb);SMBCB is the RCS_SETMINBREAK Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Set Minimum Break control block (smbcb) */
/* and initialize parameters. */
struct rcss_setminbreak smbcb = {0,0,0,0,60,0};
/* Initialize the device handle parameter in the smbcb. Call the */
/* RCS_SETMINBREAK subroutine to define 600 milliseconds as the */
/* minimum time a received break signal must persist in order for */
/* the RICCS driver to recognize a break signal. */
smbcb.smbcb_devhandle = ocb.ocb_devhandle;
rcs_setminbreak(&smbcb);
if (smbcb.smbcb_retcode == 0)
.
.
RCS_SETMINBREAK Control Block (SMBCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Bh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | MINDURATION | How long it takes | Equals 10-millisecond | APP | | 07h | | RICCS to recognize | units | | | | | a received break | | | | | | signal | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
MINDURATION indicates how long a received break signal must persist for the RICCS driver to recognize the break signal. The time is expressed in 10-millisecond units.
When setting the MINDURATION parameter, the following formula should be used:
MINDURATION = actual break duration expected minus 1 character time rounded to the next higher multiple of 10 milliseconds.
The minimum value for MINDURATION is 2 (20 milliseconds).
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_ECHO command is used to inform the RICCS driver whether or not to echo each received character back to the sending device. If DMA is on for reads, the received character is not echoed back to the sending device. The driver contains a 32-byte buffer for holding characters to be echoed. The default used at RICCS startup is echo off.
ASSEMBLER INTERFACE
PUSH Segment of RCS_ECHO Control Block PUSH Offset of RCS_ECHO Control Block CALL _rcs_echo ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE ECHO CONTROL BLOCK (ECB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
ECB RCSS_ECHO <,,,,1,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE ECB.
; CALL THE RCS_ECHO SUBROUTINE TO SET ECHO ON.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV ECB.ECB_DEVHANDLE,AX ;STORE DEVICE HANDLE IN
;ECB
LEA DI,ECB ;LOAD OFFSET OF ECB
PUSH CS ;SEGMENT OF ECB
PUSH DI ;OFFSET OF ECB
CALL _rcs_echo ;CALL LEVEL A SUB TO DO
;ECHO COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP ECB.ECB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_echo ecb; rcs_echo(&ecb);ECB is the RCS_ECHO Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Echo control block (ecb) */
/* and initialize parameters. */
struct rcss_echo ecb = {0,0,0,0,1,0,0};
/* Initialize the device handle parameter in the ecb. */
/* Call the RCS_ECHO subroutine to set echo on. */
ecb.ecb_devhandle = ocb.ocb_devhandle;
rcs_echo(&ecb);
if (ecb.ecb_retcode == 0)
.
.
RCS_ECHO Control Block (ECB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Ch | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | ECHO | Echo mode | Bit 0: | APP | | | | | 0=Off | | | | | | 1=On | | +------+----------------+--------------------+---------------------------+-----+ | 07h | RESERVED1 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED2 | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
ECHO indicates whether to support echoplex.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | Off (default) | | 0 +-------+--------------------+ | | 1 | On | +-----+-------+--------------------+RESERVED1 reserved; value must be 0.
RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_STOPTRANS command is used to inform the RICCS driver that no further transmissions are allowed until an RCS_STARTTRANS command is issued. If the application task detects conditions that indicate transmission should be stopped, this command informs the RICCS driver of the condition and causes any writes in progress to be suspended (not terminated). If a DMA write has begun, it is allowed to complete.
ASSEMBLER INTERFACE
PUSH Segment of RCS_STOPTRANS Control Block PUSH Offset of RCS_STOPTRANS Control Block CALL _rcs_stoptrans ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE STOP TRANSMISSIONS CONTROL BLOCK (STPCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
STPCB RCSS_STOPTRANS <,,,,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE STPCB.
; CALL THE RCS_STOPTRANS SUBROUTINE TO STOP TRANSMISSIONS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV STPCB.STPCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN STPCB
LEA DI,STPCB ;LOAD OFFSET OF STPCB
PUSH CS ;SEGMENT OF STPCB
PUSH DI ;OFFSET OF STPCB
CALL _rcs_stoptrans ;CALL LEVEL A SUB TO DO
;STOPTRANS COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP STPCB.STPCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_stoptrans stpcb; rcs_stoptrans(&stpcb);STPCB is the RCS_STOPTRANS Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Stop Transmission control block (stpcb). */
struct rcss_stoptrans stpcb;
/* Initialize the device handle parameter in the stpcb. */
/* Call the RCS_STOPTRANS subroutine to stop transmissions. */
stpcb.stpcb_devhandle = ocb.ocb_devhandle;
rcs_stoptrans(&stpcb);
if (stpcb.stpcb_retcode == 0)
.
.
RCS_STOPTRANS Control Block (STPCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Dh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | RESERVED | Reserve for | Must be 0 | APP | | 07h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_STARTTRANS command informs the RICCS driver that conditions causing transmission to be stopped no longer exist. The driver allows transmission and resuming pending writes.
ASSEMBLER INTERFACE
PUSH Segment of RCS_STARTTRANS Control Block PUSH Offset of RCS_STARTTRANS Control Block CALL _rcs_starttrans ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE START TRANSMISSIONS CONTROL BLOCK (STCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
STCB RCSS_STARTTRANS <,,,,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE STCB.
; CALL THE RCS_STARTTRANS TO RE-START TRANSMISSIONS IF
; TRANSMISSIONS WERE STOPPED BY RCS_STOPTRANS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV STCB.STCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN STCB
LEA DI,STCB ;LOAD OFFSET OF STCB
PUSH CS ;SEGMENT OF STCB
PUSH DI ;OFFSET OF STCB
CALL _rcs_starttrans ;CALL LEVEL A SUB TO DO
;START TRANSMISSION
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP STCB.STCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_starttrans stcb; rcs_starttrans(&stcb);STCB is the RCS_STARTTRANS Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Start Transmissions control block (stcb). */
struct rcss_starttrans stcb;
/* Initialize the device handle parameter in the stcb. */
/* Call the RCS_STARTTRANS to re-start transmissions if */
/* transmissions were stopped by RCS_STOPTRANS. */
stcb.stcb_devhandle = ocb.ocb_devhandle;
rcs_starttrans(&stcb);
if (stcb.stcb_retcode == 0)
.
.
RCS_STARTTRANS Control Block (STCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Eh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | RESERVED | Reserve for | Must be 0 | APP | | 07h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1A00h | Control signal not | | | present | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_SETCTRLSIGNAL command allows the application task to control the state of three RS-232-C output control signals and the use of three RS-232-C input control signals. Request to Send (RTS) and Data Terminal Ready (DTR) are output signals for all ports on all co-processor adapters. Rate Select (RS) is an output signal in the following configurations:
The application task may specify the following input control signals to the RCS_SETCTRLSIGNAL command at any time to turn these signals on or off:
Note:
The IBM X.25 Interface Co-Processor/2, the IBM Realtime Interface Co-Processor Portmaster Adapter/A, and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters require the Request To Send control signal to be on before transmissions can occur. If the Request To Send signal is turned off, transmissions are stopped until the signal is turned back on. It is the application programmer's responsibility to ensure that this signal is on; however, the signal is on by default.ASSEMBLER INTERFACE
PUSH Segment of RCS_SETCTRLSIGNAL Control Block PUSH Offset of RCS_SETCTRLSIGNAL Control Block CALL _rcs_setctrlsignal ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE SET CONTROL SIGNAL CONTROL BLOCK (SSCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
SSCB RCSS_SETCTRLSIGNAL <,,,,3FH,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE SSCB. CALL
; THE RCS_SETCTRLSIGNAL SUBROUTINE TO TURN RTS AND DTR ON,
; AND TO REQUIRE CTS, DSR, AND DCD FOR TRANSMISSIONS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV SSCB.SSCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN SSCB
LEA DI,SSCB ;LOAD OFFSET OF SSCB
PUSH CS ;SEGMENT OF SSCB
PUSH DI ;OFFSET OF SSCB
CALL _rcs_setctrlsignal ;CALL LEVEL A SUB TO DO
;SET CONTROL SIGNAL
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SSCB.SSCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_setctrlsignal sscb; rcs_setctrlsignal(&sscb);SSCB is the RCS_SETCTRLSIGNAL Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Set Control Signal control block (sscb) */
/* and initialize parameters. */
struct rcss_setctrlsignal sscb = {0,0,0,0,0x3f,0};
/* Initialize the device handle parameter in the sscb. Call */
/* the RCS_SETCTRLSIGNAL subroutine to turn RTS and DTR on, */
/* and to require CTS, DSR, and DCD for transmissions. */
sscb.sscb_devhandle = ocb.ocb_devhandle;
rcs_setctrlsignal(&sscb);
if (sscb.sscb_retcode == 0)
.
.
RCS_SETCTRLSIGNAL Control Block (SSCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Fh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | CTRLSIGNAL | I/O control signals| 0=Signal Off | APP | | | | for the RS-232-C | 1=Signal on | | | | |electrical interface| Bit0: RTS | | | | | | Bit1: DTR | | | | | | Bit2: Reserved | | | | | | Bit3: DCD | | | | | | Bit4: DSR | | | | | | Bit5: CTS | | | | | | Bit6: RS (output) | | | | | | Bit7: Reserved | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserve for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
CTRLSIGNAL indicates the state of the output control signals and which signals are required for transmission. CTRLSIGNAL is used only for the RS-232-C and V.35 electrical interface.
The output signals RTS, DTR, and RS are controlled by the application task setting the appropriate bits to 1 to turn the signal on, and 0 to turn the signal off. By default, RTS and DTR are on and RS is off.
The application task informs the RICCS driver which of the input signals DCD, DSR and CTS must be on before data can be transmitted. Setting the appropriate bits to 1 indicates that a signal is required for transmission; setting them to 0 indicates that a signal is not required. The defaults for CTS, DSR, and DCD are off.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Signal off | +------------+------------------------+ | 1 | Signal on | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Reserved | | | | +--------------- Data Carrier Detect (DCD) | | | +------------------ Data Set Ready (DSR) | | +--------------------- Clear To Send (CTS) | +------------------------ Rate Select (RS) output +--------------------------- ReservedRESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0004h | Successful and not | | | RS-232-C or V.35 | +------------+------------------------+ | 0008h | Successful and not | | | port 0 or 1 | +------------+------------------------+ | 000Ch | Successful and not | | | RS-232-C, V.35, or | | | port 0 or 1 | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Internal queue full | +------------+------------------------+ | 1700h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_RETCTRLSIGNAL command allows the application task to obtain the state of seven RS-232-C control signals, as described in the following section. This command can be issued at any time, and allows tasks to make use of the signals by using this command with the RCS_SETCTRLSIGNAL command.
Note:
Rate Select (RS) is an output signal on the IBM Realtime Interface Co-Processor, IBM Realtime Interface Co-Processor Multiport, IBM Realtime Interface Co-Processor Multiport/2, and the IBM X.25 Interface Co-Processor/2 adapters. It is also an output signal on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters with the Selectable Interface Board/A,
ASSEMBLER INTERFACE
PUSH Segment of RCS_RETCTRLSIGNAL Control Block PUSH Offset of RCS_RETCTRLSIGNAL Control Block CALL _rcs_retctrlsignal ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE HAS
; BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RETURN CONTROL SIGNAL CONTROL BLOCK (RSCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
RSCB RCSS_RETCTRLSIGNAL <,,,,,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RSCB. CALL
; THE RCS_RETCTRLSIGNAL SUBROUTINE TO RETURN THE CURRENT
; STATE OF THE RS-232-C CONTROL SIGNALS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
MOV RSCB.RSCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN RSCB
LEA DI,RSCB ;LOAD OFFSET OF RSCB
PUSH CS ;SEGMENT OF RSCB
PUSH DI ;OFFSET OF RSCB
CALL _rcs_retctrlsignal ;CALL LEVEL A SUB TO DO
;RETURN CONTROL SIGNAL
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RSCB.RSCB_RETCODE,0 ;RETURN CODE 0?
JNE ERR_RTN ;NO
.
.
C CALL FORMAT
struct rcss_retctrlsignal rscb; rcs_retctrlsignal(&rscb);RSCB is the RCS_RETCTRLSIGNAL Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Return Control Signal control block (rscb). */
struct rcss_retctrlsignal rscb;
/* Initialize the device handle parameter in the rscb. Call */
/* the RCS_RETCTRLSIGNAL subroutine to return the current */
/* state of the RS-232-C control signals. */
rscb.rscb_devhandle = ocb.ocb_devhandle;
rcs_retctrlsignal(&rscb);
if (rscb.rscb_retcode == 0)
.
.
RCS_RETCTRLSIGNAL Control Block (RSCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 10h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | CTRLSIGNAL | I/O control signals| 0=Signal Off | RCS | | | | for the RS-232-C | 1=Signal on | | | | |electrical interface| Bit0: RTS | | | | | | Bit1: DTR | | | | | | Bit2: RI | | | | | | Bit3: DCD | | | | | | Bit4: DSR | | | | | | Bit5: CTS | | | | | | Bit6: RS (output) | | | | | | Bit7: RS (input) | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserve for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
CTRLSIGNAL indicates the state of the RS-232-C electrical interface.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Signal off | +------------+------------------------+ | 1 | Signal on | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Ring Indicator (RI) | | | | +--------------- Data Carrier Detect (DCD) | | | +------------------ Data Set Ready (DSR) | | +--------------------- Clear To Send (CTS) | +------------------------ Rate Select (RS) output +--------------------------- Rate Select (RS) inputRETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0004h | Successful and not | | | RS-232-C or V.35 port | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_DMAREADCTRL command allows application tasks to turn DMA on and off for reads. If this command is not issued, DMA for reads will, by default, be off unless
When turning DMA on for reads, the following aspects of RICCS operation should be noted:
When turning DMA off for reads:
ASSEMBLER INTERFACE
PUSH Segment of RCS_DMAREADCTRL control block PUSH Offset of RCS_DMAREADCTRL control block CALL _rcs_dmareadctrl ADD SP,4
Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE DMA READ CONTROL CONTROL BLOCK (DRCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DRCB RCSS_DMAREADCTRL <,,,,1,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE DRCB. CALL
; THE RCS_DMAREADCTRL SUBROUTINE TO TURN ON DMA FOR READS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV DRCB.DRCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN DRCB
LEA DI,DRCB ;LOAD OFFSET OF DRCB
PUSH CS ;SEGMENT OF DRCB
PUSH DI ;OFFSET OF DRCB
CALL _rcs_dmareadctrl ;CALL LEVEL A SUB TO DO
;DMA READ CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DRCB.DRCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_dmareadctrl drcb; rcs_dmareadctrl(&drcb);DRCB is the DMA Read Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the DMA Read Control control block (drcb) */
/* and initialize parameters. */
struct rcss_dmareadctrl drcb = {0, 0, 0, 0, 1, 0};
/* Initialize the device handle parameter in the drcb. */
/* Call the RCS_DMAREADCTRL subroutine to turn on DMA */
/* for reads. */
drcb.drcb_devhandle = ocb.ocb_devhandle;
rcs_dmareadctrl (&drcb);
if (drcb.drcb_retcode == 0)
.
.
RCS_DMAREADCTRL Control Block (DRCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 11h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | DMAREAD | Support DMA on a | Bit 0: | APP | | | | RCS_READ | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserve for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
DMAREAD indicates whether or not to support DMA on a RCS_READ command.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | No | | 0 +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0002h | Successful and No DMA | | | read | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_DMAWRITECTRL command allows application tasks to turn DMA on and off for writes. If this command is not issued, DMA for writes will, by default, be off, unless:
When turning DMA on for writes
When turning DMA off for writes
ASSEMBLER INTERFACE
PUSH Segment of RCS_DMAWRITECTRL control block PUSH Offset of RCS_DMAWRITECTRL control block CALL _rcs_dmawritectrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE DMA WRITE CONTROL CONTROL BLOCK (DWCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DWCB RCSS_DMAWRITECTRL <,,,,1,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE DWCB. CALL
; THE RCS_DMAWRITECTRL SUBROUTINE TO TURN ON DMA FOR WRITES.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV DWCB.DWCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN DWCB
LEA DI,DWCB ;LOAD OFFSET OF DWCB
PUSH CS ;SEGMENT OF DWCB
PUSH DI ;OFFSET OF DWCB
CALL _rcs_dmawritectrl ;CALL LEVEL A SUB TO DO
;DMA WRITE CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DWCB.DWCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_dmawritectrl dwcb; rcs_dmawritectrl (&dwcb);DWCB is the DMA Write Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the DMA Write Control control block (dwcb) */
/* and initialize parameters. */
struct rcss_dmawritectrl dwcb = {0, 0, 0, 0, 1, 0};
/* Initialize the device handle parameter in the dwcb. */
/* Call the RCS_DMAWRITECTRL subroutine to turn on DMA */
/* for writes. */
dwcb.dwcb_devhandle = ocb.ocb_devhandle;
rcs_dmawritectrl (&dwcb);
if (dwcb.dwcb_retcode == 0)
.
.
RCS_DMAWRITECTRL Control Block (DWCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 12h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | DMAWRITE | Support DMA on a | Bit 0: | APP | | | | RCS_WRITE | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserve for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle that was obtained from the RCS_OPEN command. This is the "handle" that is used when referring to the open port.
DMAWRITE indicates whether to support DMA on a RCS_WRITE command.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | No | | 0 +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0001h | Successful and No DMA | | | write | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_CTRLINFLOW command allows application tasks to specify actions to control the flow of data from the attached device. These actions may be turned on, off, or changed as often as needed. By default, this flow control feature is turned off. Both INBAND (XON/XOFF) and OUT OF BAND (control signals) actions are supported.
Application tasks may use this command to cause flow control action to be taken upon termination of direct reads. When a direct read completes, the control signals, indicated by the application are dropped. When the next direct read is started, RICCS takes the reverse action. Before the next direct read is started, the application task may raise the control signals itself by using the RCS_SETCTRLSIGNAL command. If this is done, RICCS still raises the control signals when the next read is started.
When a Driver Input Buffer (DIB) is in use, thresholds and actions may be set to allow RICCS to automatically control the flow of data from the attached device. When the high threshold is exceeded because too many characters are in the DIB, either the XOFF character is sent or the specified control signals are dropped. When the DIB empties below the low threshold, the reverse action is taken.
The default action upon reaching high threshold is to send the XOFF character. Threshold values are expressed as the percentage of bytes in use in the DIB. By default, the high threshold is 80 percent and the low threshold is 20 percent. RICCS uses integer arithmetic when calculating the DIB thresholds.
Using the RCS_CTRLINFLOW command, the application task may also specify the two flow control characters that may be transmitted to the attached device.
Note:
All writes (non-DMA and DMA) in progress are allowed to complete before the XOFF character is transmitted to the attached device.If a non-DMA write is in progress and transmissions are stopped, the XOFF character is sent immediately.
ASSEMBLER INTERFACE
PUSH Segment of RCS_CTRLINFLOW control block PUSH Offset of RCS_CTRLINFLOW control block CALL _rcs_ctrlinflow ADD SP,4
Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CONTROL INPUT FLOW CONTROL BLOCK (CICB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
CICB RCSS_CTRLINFLOW <,,,,1,0,0,0,0,0,0,0,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE COCB. CALL
; THE RCS_CTRLINFLOW SUBROUTINE TO ENABLE DEFAULT INPUT
; CONTROL FLOW.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CICB.CICB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN CICB
LEA DI,CICB ;LOAD OFFSET OF CICB
PUSH CS ;SEGMENT OF CICB
PUSH DI ;OFFSET OF CICB
CALL _rcs_ctrlinflow ;CALL LEVEL A SUB TO DO
;CONTROL INFLOW COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CICB.CICB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_ctrlinflow cicb; rcs_ctrlinflow (&cicb);CICB is the Control Input Flow Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Control Input Flow control block (cicb) and */
/* initialize parameters. */
struct rcss_ctrlinflow cicb = {0, 0, 0, 0, 1, 0, 0, 0,
0, 0, 0, 0, 0, 0};
/* Initialize the device handle parameter in the cicb. */
/* Call the RCS_CTRLINFLOW subroutine to enable default */
/* input control flow. */
cicb.cicb_devhandle = ocb.ocb_devhandle;
rcs_ctrlinflow (&cicb);
if (cicb.cicb_retcode == 0)
.
.
RCS_CTRLINFLOW Control Block (CICB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 13h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | INCTRL | Indicates whether | 0 = Off | APP | | | | input flow control | 1 = On | | | | | is on or off and | Bit 0:Control on/off | | | | | whether new values | 0=No new values | | | | | are being supplied.| 1=New values | | | | | | Bit 1:XON/XOFF values | | | | | | Bit 2:Direct read values | | | | | | Bit 3:Threshold values | | | | | | Bit 4:DIB values | | +------+----------------+--------------------+---------------------------+-----+ | 07h | XONCHAR | Character used to | | APP | | | | inform the attached| | | | | | device to start tx | | | +------+----------------+--------------------+---------------------------+-----+ | 08h | XOFFCHAR | Character used to | | APP | | | | inform the attached| | | | | | device to stop tx | | | +------+----------------+--------------------+---------------------------+-----+ | 09h- | RESERVED1 | Reserve for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch | READSIGNALS | Signals to drop | 0 = Do not drop | APP | | | | upon a direct read | 1 = Drop signal | | | | | completion | Bit0: RTS | | | | | | Bit1: DTR | | | | | | Bit2: Reserved | | | | | | Bit3: Reserved | | | | | | Bit4: Reserved | | | | | | Bit5: Reserved | | | | | | Bit6: RS (output) | | | | | | Bit7: Reserved | | +------+----------------+--------------------+---------------------------+-----+ | 0Dh | HIGHTHRESH | Point at which to | Expressed as a percent of | APP | | | | stop tx from | DIB bytes in use | | | | | attached device | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | LOWTHRESH | Point at which to | Expressed as a percent of | APP | | | | start tx from | DIB bytes in use | | | | | attached device | | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | DIBACTION | Action to take upon| Bit0: | APP | | | | reaching high | 0 = Send XOFF | | | | | threshold | 1 = Drop signals | | +------+----------------+--------------------+---------------------------+-----+ | 10h | DIBSIGNALS | Signals to drop | 0 = Do not drop | APP | | | | upon reaching high | 1 = Drop signal | | | | | threshold | Bit0: RTS | | | | | | Bit1: DTR | | | | | | Bit2: Reserved | | | | | | Bit3: Reserved | | | | | | Bit4: Reserved | | | | | | Bit5: Reserved | | | | | | Bit6: RS (output) | | | | | | Bit7: Reserved | | +------+----------------+--------------------+---------------------------+-----+ | 11h- | RESERVED2 | Reserved for | Must be 0 | APP | | 15h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
INCTRL indicates whether control of input flow should be turned on or off and whether new values are being supplied in the command. The bit assignments and values are:
+=====+=======+===========================+ | Bit | Value | Meaning | +=====+=======+===========================+ | | 0 | Turn control off | | 0 +-------+---------------------------+ | | 1 | Turn control on | +-----+-------+---------------------------+ | | 0 | No new XON/XOFF values | | 1 +-------+---------------------------+ | | 1 | New XON/XOFF values | +-----+-------+---------------------------+ | | 0 | No new direct read values | | 2 +-------+---------------------------+ | | 1 | New direct read values | +-----+-------+---------------------------+ | | 0 | No new threshold values | | 3 +-------+---------------------------+ | | 1 | New threshold values | +-----+-------+---------------------------+ | | 0 | No new DIB values | | 4 +-------+---------------------------+ | | 1 | New DIB values. | +-----+-------+---------------------------+XONCHAR is the value transmitted to the attached device to indicate that RICCS is ready to receive data and transmissions should be started. By default this value is 11h, the actual XON character defined in the ASCII character set.
XOFFCHAR is the value transmitted to the attached device to indicate that RICCS is not ready to receive data and transmissions should be stopped. By default this value is 13h, the XOFF character defined in the ASCII character set.
RESERVED1 reserved; value must be 0.
READSIGNALS indicates which control signals are dropped when the direct read completes. Any combination of the three output control signals Request To Send (RTS), Data Terminal Ready (DTR), and Rate Select (RS) may be specified to be dropped upon direct read completion. The default is to drop RTS.
Each of the three signals correspond to a bit in this parameter. If the bit is set, that control signal is to be dropped. If the bit is clear, the control signal is not affected. The bit assignments for this parameter match the bit positions assigned in the RCS_SETCTRLSIGNAL command. The following are the bit assignments and valid values for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Do not drop signals | +------------+------------------------+ | 1 | Drop signals | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Reserved | | | | +--------------- Reserved | | | +------------------ Reserved | | +--------------------- Reserved | +------------------------ Rate Select (RS) output +--------------------------- ReservedHIGHTHRESH indicates the point at which the action should be taken to stop transmissions from the attached device. This value is expressed as a percent of DIB bytes in use. By default, the high threshold is 80 percent.
LOWTHRESH indicates the point at which the action should be taken to re-start transmissions from the attached device. This value is expressed as a percent of DIB bytes in use. By default, the low threshold is 20 percent.
DIBACTION indicates the action taken when the DIB high threshold is exceeded. The possible actions are to either send an XOFF character, the default, or to drop control signals. The following values are valid for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Send XOFF | +------------+------------------------+ | 1 | Drop signals | +------------+------------------------+DIBSIGNALS indicates which control signals are dropped when the DIB high threshold is exceeded and the DIBACTION was set to drop signals. Any combination of the three output control signals (RTS, DTR and RS) may be specified to be dropped upon reaching high threshold. The default is to drop RTS. Each of the three signals corresponds to a bit in this parameter. If the bit is set, that control signal is to be dropped. If the bit is clear, the control signal is not affected. The bit assignments for this parameter match the bit positions assigned in the RCS_SETCTRLSIGNAL command. The following are the bit assignments for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Do not drop signals | +------------+------------------------+ | 1 | Drop signals | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Reserved | | | | +--------------- Reserved | | | +------------------ Reserved | | +--------------------- Reserved | +------------------------ Rate Select (RS) output +--------------------------- ReservedRESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_CTRLOUTFLOW command allows application tasks to specify the action taken when flow control characters are received from the attached device. Recognition of these characters may be turned on or off.
If a read is in progress and this command was issued to turn control output flow on or off, the read is allowed to complete before turning control output flow on or off.
The application task may also specify the two flow control characters that may be received from the attached device.
If this command is not issued, control output flow, by default, is turned off. By default, the XON and XOFF characters, as defined in the ASCII character set, is used (11h and 13h respectively).
Notes:
ASSEMBLER INTERFACE
PUSH Segment of RCS_CTRLOUTFLOW control block PUSH Offset of RCS_CTRLOUTFLOW control block CALL _rcs_ctrloutflow ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CONTROL OUTPUT FLOW CONTROL BLOCK (COCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
COCB RCSS_CTRLOUTFLOW <,,,,1,0,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE COCB. CALL
; THE RCS_CTRLOUTFLOW SUBROUTINE TO ENABLE DEFAULT OUTPUT
; CONTROL FLOW.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV COCB.COCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN COCB
LEA DI,COCB ;LOAD OFFSET OF COCB
PUSH CS ;SEGMENT OF COCB
PUSH DI ;OFFSET OF COCB
CALL _rcs_ctrloutflow ;CALL LEVEL A SUB TO DO
;CONTROL OUTFLOW COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP COCB.COCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_ctrloutflow cocb; rcs_ctrloutflow (&cocb);COCB is the Control Output Flow Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Control Output Flow control block (cocb) */
/* and initialize parameters. */
struct rcss_ctrloutflow cocb = {0, 0, 0, 0, 1, 0, 0, 0};
/* Initialize the device handle parameter in the cocb. */
/* Call the RCS_CTRLOUTFLOW subroutine to enable default */
/* output control flow. */
cocb.cocb_devhandle = ocb.ocb_devhandle;
rcs_ctrloutflow (&cocb);
if (cocb.cocb_retcode == 0)
.
.
RCS_CTRLOUTFLOW Control Block (COCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 14h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | OUTCTRL | Indicates whether | 0 = Off | APP | | | | output flow control| 1 = On | | | | | is on or off and | Bit0: Control on/off | | | | | whether new values | 0=No new values | | | | | are being supplied | 1=New values | | | | | for the XON and | Bit1: XON/XOFF New values | | | | | XOFF characters. | | | +------+----------------+--------------------+---------------------------+-----+ | 07h | XONCHAR | Character used to | | APP | | | | start tx to the | | | | | | attached device | | | +------+----------------+--------------------+---------------------------+-----+ | 08h | XOFFCHAR | Character used to | | APP | | | | stop tx to the | | | | | | attached device | | | +------+----------------+--------------------+---------------------------+-----+ | 09h- | RESERVED | Reserved for | Must be 0 | APP | | 0Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
OUTCTRL indicates whether control output flow should be turned on or off and whether new XON/XOFF values are being supplied in the command. The bit assignments and values are:
+=====+=======+========================+ | Bit | Value | Meaning | +=====+=======+========================+ | | 0 | Turn control off | | 0 +-------+------------------------+ | | 1 | Turn control on | +-----+-------+------------------------+ | | 0 | No new XON/XOFF values | | 1 +-------+------------------------+ | | 1 | New XON/XOFF values | +-----+-------+------------------------+XONCHAR is the value received from the attached device indicating that the device is ready to receive data and transmissions should be started. By default this value is 11h, the XON character defined in the ASCII character set.
XOFFCHAR is the value received from the attached device indicating that the device is not ready to receive data and transmissions should be stopped. By default this value is 13h, the XOFF character defined in the ASCII character set.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_CANCELREADS command cancels RCS_READ commands that have been issued, but not completed. The command allows the flexibility of cancel conditions. The application task may specify whether to cancel the in-progress, queued, or all reads. The application may also select whether RCS_READ commands from all tasks should be canceled, or only the ones from a specific task.
When the RCS_READ commands are canceled, the:
Note:
When an in-progress read is canceled, the next read is immediately started.
ASSEMBLER INTERFACE
PUSH Segment of RCS_CANCELREADS control block PUSH Offset of RCS_CANCELREADS control block CALL _rcs_cancelreads ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CANCEL READS CONTROL BLOCK (CRCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
CRCB RCSS_CANCELREADS <,,,,3,4,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE CRCB. CALL
; THE RCS_CANCELREADS SUBROUTINE TO CANCEL IN-PROGRESS AND
; QUEUED READS FOR TASK 4.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CRCB.CRCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN CRCB
LEA DI,CRCB ;LOAD OFFSET OF CRCB
PUSH CS ;SEGMENT OF CRCB
PUSH DI ;OFFSET OF CRCB
CALL _rcs_cancelreads ;CALL LEVEL A SUB TO DO
;CANCEL READS COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CRCB.CRCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_cancelreads crcb; rcs_cancelreads (&crcb);CRCB is the Cancel Reads Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Cancel Reads control block (crcb) and */
/* initialize parameters. */
struct rcss_cancelreads crcb = {0, 0, 0, 0, 3, 4, 0};
/* Initialize the device handle parameter in the crcb. */
/* Call the RCS_CANCELREADS subroutine to cancel */
/* in-progress and queued reads for task 4. */
crcb.crcb_devhandle = ocb.ocb_devhandle;
rcs_cancelreads (&crcb);
if (crcb.crcb_retcode == 0)
.
.
RCS_CANCELREADS Control Block (CRCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 15h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | TYPECOND | Type of RCS_READ | 1=In progress | APP | | | | command(s) to be | 2=Queued | | | | | canceled | 3=Both (all) | | +------+----------------+--------------------+---------------------------+-----+ | 07h | TASKCOND | Task number of | Task number to match | APP | | | | RCS_READ command(s)| (FFh = all tasks) | | | | | to be canceled | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
TYPECOND specifies the type of RCS_READ command(s) to be canceled. The application may select that only the in-progress read be canceled, only reads that are queued (but not in-progress) be canceled, or all types of reads be canceled. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Cancel in-progress | | | read | +------------+------------------------+ | 2 | Cancel queued read(s) | +------------+------------------------+ | 3 | Cancel in-progress and | | | queued read(s) | +------------+------------------------+TASKCOND specifies the task number that must match for RCS_READ command(s) to be canceled. The application may select that only reads issued by a specific task be canceled, by placing that task's number in this parameter. The application may specify that reads issued by all tasks be canceled, by placing a FFh in this parameter.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_CANCELWRITES command cancels RCS_WRITE commands that have been issued, but not yet completed. The RCS_SENDBREAK command is considered an output command by the RICCS driver, and is canceled along with RCS_WRITE commands. The command allows the flexibility of various cancel conditions. The application task may specify whether to cancel the in-progress, queued, or all writes. The application has the option of canceling a specific RCS_WRITE command, given the RCS_WRITE Control Block address. The application may also select whether RCS_WRITE commands from all tasks should be canceled, or only the ones from a specific task.
When RCS_WRITE commands are canceled, the:
ASSEMBLER INTERFACE
PUSH Segment of RCS_CANCELWRITES control block PUSH Offset of RCS_CANCELWRITES control block CALL _rcs_cancelwrites ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CANCEL WRITES CONTROL BLOCK (CWCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
CWCB RCSS_CANCELWRITES <,,,,3,4,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE CWCB. CALL
; THE RCS_CANCELWRITES SUBROUTINE TO CANCEL IN-PROGRESS AND
; QUEUED WRITES FOR TASK 4.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CWCB.CWCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN CWCB
LEA DI,CWCB ;LOAD OFFSET OF CWCB
PUSH CS ;SEGMENT OF CWCB
PUSH DI ;OFFSET OF CWCB
CALL _rcs_cancelwrites ;CALL LEVEL A SUB TO DO
;CANCEL WRITES COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CWCB.CWCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_cancelwrites cwcb; rcs_cancelwrites (&cwcb);CWCB is the Cancel Writes Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Cancel Writes control block (cwcb) and */
/* initialize parameters. */
struct rcss_cancelwrites cwcb = {0, 0, 0, 0, 3, 4, 0};
/* Initialize the device handle parameter in the cwcb. */
/* Call the RCS_CANCELWRITES subroutine to cancel */
/* in-progress and queued writes for task 4. */
cwcb.cwcb_devhandle = ocb.ocb_devhandle;
rcs_cancelwrites (&cwcb);
if (cwcb.cwcb_retcode == 0)
.
.
RCS_CANCELWRITES Control Block (CWCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 16h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | TYPECOND | Type of RCS_WRITE | 1 = In progress | APP | | | | command(s) to be | 2 = Queued | | | | | canceled | 3 = Both (in progress | | | | | | and queued) | | | | | | 4 = Specific | | +------+----------------+--------------------+---------------------------+-----+ | 07h | TASKCOND | Task number of | Task number to match | APP | | | |RCS_WRITE command(s)| (FFh = all tasks) | | | | | to be canceled | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | WCBADDR | Address of specific| Segment:offset | APP | | 0Bh | | RCS_WRITE control | | | | | | block to cancel | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch- | RESERVED | Reserved for | Must be 0 | APP | | 0Fh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
TYPECOND specifies the type of RCS_WRITE command(s) canceled. The application may select that only the in-progress write be canceled, only writes that are queued (but not in-progress) be canceled, both types of writes be canceled, or a specific RCS_WRITE command be canceled. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Cancel in-progress | | | write | +------------+------------------------+ | 2 | Cancel queued write(s) | +------------+------------------------+ | 3 | Cancel in-progress and | | | queued write(s) | +------------+------------------------+ | 4 | Cancel specific write | +------------+------------------------+TASKCOND specifies the task number that must match for RCS_WRITE command(s) to be canceled. This parameter further qualifies the TYPECOND parameter. The application may select that only writes issued by a specific task be canceled, by placing that tasks' number in this parameter. The application may specify that writes issued by all tasks be canceled, by placing a FFh in this parameter.
WCBADDR is the address of the RCS_WRITE Control Block (WCB) for the specific write to be canceled. This RCS_WRITE command is not canceled if it is in progress.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_ERRORSUB command allows application tasks to specify the action taken when characters are received in error (parity, framing, and overrun). This command substitutes the specified character for the character in error. This command allows the application to turn the error substitution on or off and specify the character that replaces any characters received in error. Error substitution, by default, is off. RICCS always flags the error in the READSTATUS parameter of the RCS_READ Control Block.
Note:
Error substitution is not supported when performing DMA Reads on IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2
ASSEMBLER INTERFACE
PUSH Segment of RCS_ERRORSUB control block PUSH Offset of RCS_ERRORSUB control block CALL _rcs_errorsub ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE ERROR SUBSTITUTION CONTROL BLOCK (ESCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
ESCB RCSS_ERRORSUB <,,,,1,0FFh,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE ESCB. CALL
; THE RCS_ERRORSUB SUBROUTINE TO ENABLE ERROR SUBSTITUTION.
; CHARACTERS RECEIVED IN ERROR WILL BE REPLACED BY 0FFh.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV ESCB.ESCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN ESCB
LEA DI,ESCB ;LOAD OFFSET OF ESCB
PUSH CS ;SEGMENT OF ESCB
PUSH DI ;OFFSET OF ESCB
CALL _rcs_errorsub ;CALL LEVEL A SUB TO DO
;ERROR SUBSTITUTION CMD
ADD SP,4 ;ADJUST STACK POINTER
CMP ESCB.ESCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_errorsub escb; rcs_errorsub (&escb);ESCB is the Error Substitution Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Error Substitution control block (escb) */
/* and initialize parameters. */
struct rcss_errorsub escb = {0, 0, 0, 0, 1, 0xFF, 0};
/* Initialize the device handle parameter in the escb. */
/* Call the RCS_ERRORSUB subroutine to enable error */
/* substitution. Characters recieved in error will be */
/* replaced with 0xFF. */
escb.escb_devhandle = ocb.ocb_devhandle;
rcs_errorsub (&escb);
if (escb.escb_retcode == 0)
.
.
RCS_ERRORSUB Control Block (ESCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 17h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | SUBCTRL | Error substitution | Bit0: | APP | | | | on/off | 0 = Off | | | | | | 1 = On | | +------+----------------+--------------------+---------------------------+-----+ | 07h | SUBCHAR | Character to | Must be supplied every | APP | | | | substitute | time error substitution is| | | | | | turned on | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | P | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle used when referring to the open port.
SUBCTRL indicates whether to turn error substitution on or off.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | Off | | 0 +-------+--------------------+ | | 1 | On | +-----+-------+--------------------+SUBCHAR is the character substituted for any characters received in error. This character must be provided each time error substitution is turned on.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_NOTIFY command notifies the application task as specific events occur. This command defines to RICCS an event mask, an event table, and a task number to be posted when events occur. The event mask specifies the combination of events for which notification should be made. The event table is used to inform the application task which event occurred. This command may be issued at any time to change these parameters; however, RICCS allows only one set of parameters per port to be current.
The application task must define an event table, one per port, to be used by the RICCS driver. This event table actually resides within the application task and its size must be 34 words. The event table must be in the following format:
+=======+===================+================================================+ | Word | Type | Meaning | +=======+===================+================================================+ | 0 | Unsigned integer | Event(s) occurred (Event 0-15) | +-------+-------------------+------------------------------------------------+ | 1 | Unsigned integer | Event(s) occurred (Events 16-31) | +-------+-------------------+------------------------------------------------+ | 2 | Unsigned or | Event 0 counter | | | signed integer | | +-------+-------------------+------------------------------------------------+ | : | | : | +-------+-------------------+------------------------------------------------+ | 33 | Unsigned or | Event 31 counter | | | signed integer | | +-------+-------------------+------------------------------------------------+The first two words of the event table (one bit per event) are event flags used by RICCS for notification control. When an event occurs, the appropriate bit is set to 1. The application task is responsible for clearing these bits. The next 32 words of the event table (one word per event) map directly to the event assignments specified in EVENTS parameter. These words are used as counters for each event.
When an event occurs RICCS:
After the task is posted it can:
The application should disable interrupts when it modifies the event flags and counters, because the asynchronous driver may modify them during hardware interrupts.
Note:
This command is intended to provide notification services to applications which have special needs for this type of service. When a notifiable event occurs, a "post" is performed. The user should be aware that this may decrease RICCS performance.
ASSEMBLER INTERFACE
PUSH Segment of RCS_NOTIFY control block PUSH Offset of RCS_NOTIFY control block CALL _rcs_notify ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE AN EVENT NOTIFICATION TABLE.
EVTAB DW 34 DUP (0)
; ALLOCATE THE EVENT TABLE AND NOTIFY CONTROL BLOCK (NCB)
; AND INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
NCB RCSS_NOTIFY <,,,,0FFCFh,EVTAB,2,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE NCB. CALL
; THE RCS_NOTIFY SUBROUTINE TO HAVE TASK 2 NOTIFIED OF ALL
; EVENTS.
MOV AX,OCB.OCB_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV NCB.NCB_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN NCB
MOV WORD PTR NCB.NCB_EVTAB+2,CS ;SAVE SEGMENT OF EVTAB
LEA DI,NCB ;LOAD OFFSET OF NCB
PUSH CS ;SEGMENT OF NCB
PUSH DI ;OFFSET OF NCB
CALL _rcs_notify ;CALL LEVEL A SUB TO DO
;NOTIFY COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP NCB.NCB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_notify ncb; rcs_notify (&ncb);NCB is the Notify Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Event Table and Notify control block */
/* (ncb) and initialize parameters. */
unsigned int evtab[34&rbracket.;
struct rcss_notify ncb = {0, 0, 0, 0, 0xFFCF, evtab, 2};
/* Initialize the device handle parameter in the ncb. */
/* Call the RCS_NOTIFY subroutine to have task 2 */
/* notified of all events. */
ncb.ncb_devhandle = ocb.ocb_devhandle;
rcs_notify (&ncb);
if (ncb.ncb_retcode == 0)
.
.
RCS_NOTIFY Control Block (NCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 18h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | EVENTS | Events description | See the EVENTS description| APP | | 09h | | | in the RCS_NOTIFY command | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | EVTAB | Address of Event | Segment:offset | APP | | 0Dh | | Table | The Event Table must | | | | | | be 34 words. | | | | | | 0 = not present. | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | NOTIFYTASK | Task number of task| Task is not required to | APP | | | | to be posted | have the port open. | | | | | | 0 = not present | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh- | RESERVED | Reserve for | Must be 0 | APP | | 13h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_OPEN command. This is the handle use when referring to the open port.
EVENTS is a set of bits indicating which events cause notification to the application task. Setting a bit to 1 indicates the corresponding event causes notification to the application task. Setting a bit to 0 indicates the corresponding event does not cause notification to the application task. The bit assignments for this parameter are:
+============+========================+ | Bit | Meaning | +============+========================+ | 0 | XON Received | +------------+------------------------+ | 1 | XOFF Received | +------------+------------------------+ | 2 | RICCS Shutdown | +------------+------------------------+ | 3 | Hardware Overrun Error | +------------+------------------------+ | 4 | Reserved | +------------+------------------------+ | 5 | Reserved | +------------+------------------------+ | 6 | CTS Signal Asserted | | | (on) | +------------+------------------------+ | 7 | CTS Signal Negated | | | (off) | +------------+------------------------+ | 8 | DCD Signal Asserted | | | (on) | +------------+------------------------+ | 9 | DCD Signal Negated | | | (off) | +------------+------------------------+ | 10 | DSR Signal Asserted | | | (on) | +------------+------------------------+ | 11 | DSR Signal Negated | | | (off) | +------------+------------------------+ | 12 | RS Signal Asserted | | | (on) | +------------+------------------------+ | 13 | RS Signal Negated | | | (off) | | | Note: Bits 12 and 13 | | | only apply if Half | | | Rate Select is an | | | input signal. | +------------+------------------------+ | 14 | RI Signal Asserted | | | (on) | +------------+------------------------+ | 15 | RI Signal Negated | | | (off) | +------------+------------------------+ | 16 | DIB High Threshold | | | Reached | +------------+------------------------+ | 17 | DIB Low Threshold | | | Reached | +------------+------------------------+ | 18 - 31 | Reserved | +------------+------------------------+EVTAB is the address of the thirty-four (34) word event table. A value of 0 may be present in this parameter if this command is issued to change events.
NOTIFYTASK is the task number posted when one of the specified events occur. This does not have to be the task that is issuing the RCS_NOTIFY command. The task specified in this parameter is not required to have the port open. A value of 0 may be present in this parameter if this command is issued to change events.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_DEFEI command allows application tasks to define to RICCS the features of a new electrical interface board unknown to RICCS and which cannot be automatically configured by RICCS. Defining the electrical interface board allows RICCS to maintain compatibility and provide support to the electrical interface board. This command is issued upon RICCS start-up to define the features for the internal RICCS variables. The new electrical interface board is not recognized until this command is performed. The RCS_DEFEI command must be done prior to the RCS_OPEN command.
When using the Selectable Interface Board/A on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, this command must be issued to configure ports 0 through 2, unless the ports are using the RS-232-C physical interface.
Note:
This support applies only to IBM electrical interface boards or boards compatible with IBM electrical interface boards.
ASSEMBLER INTERFACE
PUSH Segment of RCS_DEFEI control block PUSH Offset of RCS_DEFEI control block CALL _rcs_defei ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE DEFINE ELECTRICAL INTERFACE CONTROL BLOCK
; (DEICB) INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DEICB RCSS_DEFEI <,,,,0Fh,,,0Fh,,,1111h,,,55h,,,3333h,,,,3333h,,,,55h>
; CALL THE RCS_DEFEI SUBROUTINE TO DEFINE FOUR SYNCHRONOUS-CAPABLE
; RS-422-A PORTS WITH SIGNETICS** HARDWARE AND DMA.
LEA DI,DEICB ;LOAD OFFSET OF DEICB
PUSH CS ;SEGMENT OF DEICB
PUSH DI ;OFFSET OF DEICB
CALL _rcs_defei ;CALL LEVEL A SUB TO DO
;DEFINE ELECTRICAL
;INTERFACE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DEICB.DEICB_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_defei deicb; rcs_defei (&deicb);DEICB is the Define Electrical Interface Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccs.h"
/* Allocate the Define Electrical Interface control */
/* block (deicb) and initialize parameters. */
struct rcss_defei deicb = {0, 0, 0, 0, 0x0F, 0, 0x0F,
0, 0x1111, 0, 0x55, 0,
0x2222L, 0, 0x2222L, 0,
0x55, 0};
/* Call the RCS_DEFEI subroutine to define four */
/* synchronous-capable RS-422-A ports with Signetics** */
/* hardware and DMA. */
rcs_defei (&deicb);
if (deicb.deicb_retcode == 0)
.
.
RCS_DEFEI Control Block (DEICB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 19h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device handle | | APP | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | PORTS | Identifies which | 0=Not defining | APP | | | | port(s) the | 1=Defining | | | | | features are | Bit0=Port0 | | | | | defining | Bit1=Port1 | | | | | | Bit2=Port2 | | | | | | Bit3=Port3 | | | | | | Bit4=Port4 | | | | | | Bit5=Port5 | | | | | | Bit6=Port6 | | | | | | Bit7=Port7 | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED2 | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah | SYNCAPABLE | Indicates whether | 0=Asynchronous only | APP | | | | the port is capable| 1=Synchronous Capable | | | | | of synchronous | Bit0=Port 0 | | | | | operation | Bit1=Port 1 | | | | | | Bit2=Port 2 | | | | | | Bit3=Port 3 | | | | | | Bit4=Port 4 | | | | | | Bit5=Port 5 | | | | | | Bit6=Port 6 | | | | | | Bit7=Port 7 | | +------+----------------+--------------------+---------------------------+-----+ | 0Bh- | RESERVED3 | Reserved for | Must be 0 | APP | | 0Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh- | TYPEEI | Standard supported | 0000=RS-232-C | APP | | 11h | | by the port | 0001=RS-422-A | | | | | | 0010=V.35 | | | | | | Four bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | RESERVED4 | Reserved for | Must be 0 | APP | | 1Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 1Eh- | TYPEHARD | Communication | 00=Zilog** | APP | | 1Fh | | ation hardware | 01=Signetics** | | | | | support by the port| Two bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 20h- | RESERVED5 | Reserved for | Must be 0 | APP | | 25h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 26h- | DMARXCAPABLE | Indicates the type | 0000=Not DMA Capable | APP | | 29h | | of receive DMA | 0001=186 DMA | | | | | used for the port | 0010=DMA PIC | | | | | | Four bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 2Ah- | RESERVED6 | Reserved for | Must be 0 | APP | | 35h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 36h- | DMATXCAPABLE | Indicates the type | 0000=Not DMA Capable | APP | | 39h | | of transmit DMA | 0001=186 DMA | | | | | used for the port | 0010=DMA PIC | | | | | | Four bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 3Ah- | RESERVED7 | Reserved for | Must be 0 | APP | | 45h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 46h- | HRSELECT | Indicates the | 00=No HRS | APP | | 47h | | direction half | 01=HRS-Input | | | | | rate select signal | 10=HRS-Output | | | | | | 11=HRS-Both | | | | | | Two bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 48h- | RESERVED8 | Reserved for | Must be 0 | APP | | 51h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
RESERVED1 reserved; value must be 0.
PORTS identifies the port(s) for which the electrical interface features are being defined. Each port corresponds to a bit in this parameter. If the bit is set to 1, the electrical interface features specified in this command are defining that port. If the bit is set to 0, the electrical interface features specified in this command are not defining that port. The following are the bit assignments for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Not defining | +------------+------------------------+ | 1 | Defining | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Port 0 | | | | | | +--------- Port 1 | | | | | +------------ Port 2 | | | | +--------------- Port 3 | | | +------------------ Port 4 | | +--------------------- Port 5 | +------------------------ Port 6 +--------------------------- Port 7RESERVED2 reserved; value must be 0.
SYNCAPABLE indicates whether the port is capable of synchronous operation. Each port corresponds to a bit in this parameter. If the bit is set to 1, the new electrical interface board is capable of handling the synchronous protocol for the particular port(s). If the bit is to 0, the new electrical interface board identification is not capable of handling the synchronous protocol for the particular port(s). The following are the bit assignments for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Asynchronous only | +------------+------------------------+ | 1 | Synchronous capable | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Port 0 | | | | | | +--------- Port 1 | | | | | +------------ Port 2 | | | | +--------------- Port 3 | | | +------------------ Port 4 | | +--------------------- Port 5 | +------------------------ Port 6 +--------------------------- Port 7RESERVED3 reserved; value must be 0.
TYPEEI indicates which standard is supported by the new electrical interface board. Four bits are assigned for each port and the following values are valid for this parameter.
+============+========================+ | Value | Meaning | +============+========================+ | 0000 | RS-232-C | +------------+------------------------+ | 0001 | RS-422-A | +------------+------------------------+ | 0010 | V.35 | +------------+------------------------+ Bit assignments 31-28 27-24 23-20 19-16 15-12 11-8 7-4 3-0 | | | | | | | +------ Port 0 | | | | | | +------------ Port 1 | | | | | +------------------ Port 2 | | | | +------------------------ Port 3 | | | +------------------------------ Port 4 | | +------------------------------------- Port 5 | +-------------------------------------------- Port 6 +--------------------------------------------------- Port 7RESERVED4 reserved; value must be 0.
TYPEHARD indicates which communication hardware supports the new electrical interface board. Two bits are assigned for each port and the following values are valid for this parameter.
+============+========================+ | Value | Meaning | +============+========================+ | 00 | Zilog** | +------------+------------------------+ | 01 | Signetics** | +------------+------------------------+ Bit assignments: 15-14 13-12 11-10 9-8 7-6 5-4 3-2 1-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +--------- Port 1 | | | | | +-------------- Port 2 | | | | +------------------- Port 3 | | | +------------------------ Port 4 | | +------------------------------ Port 5 | +------------------------------------- Port 6 +-------------------------------------------- Port 7RESERVED5 reserved; value must be 0.
DMARXCAPABLE indicates the type of receive DMA used for the port.
+============+========================+ | Value | Meaning | +============+========================+ | 0000 | No DMA Capability | +------------+------------------------+ | 0001 | 186 DMA Capability | +------------+------------------------+ | 0010 | DMAPIC Capability | +------------+------------------------+ Bit assignments: 31-28 27-24 23-20 19-16 15-12 11-8 7-4 3-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +---------- Port 1 | | | | | +---------------- Port 2 | | | | +---------------------- Port 3 | | | +---------------------------- Port 4 | | +----------------------------------- Port 5 | +------------------------------------------ Port 6 +------------------------------------------------- Port 7RESERVED6 reserved; value must be 0.
DMATXCAPABLE indicates the type of transmit DMA used for the port.
+============+========================+ | Value | Meaning | +============+========================+ | 0000 | No DMA Capability | +------------+------------------------+ | 0001 | 186 DMA Capability | +------------+------------------------+ | 0010 | DMAPIC Capability | +------------+------------------------+ Bit assignments: 31-28 27-24 23-20 19-16 15-12 11-8 7-4 3-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +--------- Port 1 | | | | | +-------------- Port 2 | | | | +-------------------- Port 3 | | | +-------------------------- Port 4 | | +--------------------------------- Port 5 | +---------------------------------------- Port 6 +----------------------------------------------- Port 7RESERVED7 reserved; value must be 0.
HRSELECT indicates the direction of the Half Rate Select signal.
+============+========================+ | Value | Meaning | +============+========================+ | 00 | No Half Rate Select | | | Capability | +------------+------------------------+ | 01 | Half Rate Select - | | | Input | +------------+------------------------+ | 10 | Half Rate Select - | | | Output | +------------+------------------------+ | 11 | Half Rate Select - | | | Both | +------------+------------------------+ Bit assignments: 15-14 13-12 11-10 9-8 7-6 5-4 3-2 1-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +--------- Port 1 | | | | | +-------------- Port 2 | | | | +------------------- Port 3 | | | +------------------------ Port 4 | | +------------------------------ Port 5 | +------------------------------------- Port 6 +-------------------------------------------- Port 7RESERVED8 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 0400h | Device already open | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 1E00h | Incompatible port type | +------------+------------------------+
This section contains a list of the RICCS return codes. The RICCS returns an indication of the successful or unsuccessful execution of the requested operation in the RETCODE parameter. The application should examine the high-order byte of the RETCODE parameter for the return code.
Some commands execute successfully, but have an information return code returned in the low byte of the RETCODE parameter.
This section provides programming tips for Realtime Interface Co-Processor Asynchronous Communications Support.
This section provides a user with the information needed to write a macro assembler application task to interface directly with the RICCS driver. Interfacing directly with the driver requires a user-written Level A subroutine. The following paragraphs describe the common design of all the subroutines and the design for the subroutines after the command has been processed by the driver. The subroutines are common until the command process check. After checking the processing status of the command, the subroutines vary, depending on the type of Level A subroutines.
The application task must initialize the RCS subroutine control block, set the RETCODE parameter to negative one (-1), and clear the resume flag in the DEVHANDLE parameter.
The application task must load the following registers:
After loading the registers, generate the interrupt to interface with the driver and check bit 7 in the AL register for the processed interrupt.
The following list shows the deferred commands in RICCS:
All deferred commands, except no-wait RCS_READ and no-wait RCS_WRITE, perform the following operation:
Note:
If the resume flag is set, the command proceeds to step 3; if it is not set, the command:
The following list shows the immediate commands in RICCS:
All immediate commands return immediately to the application task.
The string parameters LOGICALDEVICENAME and CONTROLSEQ do not have a byte reserved for the null character; therefore, application tasks written in C Language should use the MEMCPY function to initialize these parameters. For more information on these parameters, refer to the following sections:
The Macro Assembler/2 include file, RICCS.ASM, contains the Level A data structures and library routine declarations for each asynchronous command, provides the variables needed for each command, and allows an application written in Macro Assembler to link with the Level A subroutines. The include file is on the RICES Programs diskette.
The RICCS Post Code Values are:
The Realtime Interface Co-Processor Communications Support package makes it easier for the application to use the synchronous communications facilities provided by the Realtime Interface Co-Processor adapters. This package provides an interface for bit synchronous communications support and allows applications to be independent of the co-processor adapter's communications hardware device (Zilog** 8030 Serial Communications Controller, Signetics** SN26562 Dual Universal Serial Communications Controller, or Zilog** 8036 Counter/Timer and Parallel I/O Unit). The services support the RS-232-C, RS-422-A, and V.35 electrical interfaces.
The RICCS contains driver tasks that perform the physical interface to the communications hardware devices and shelter application tasks from this hardware. The RICCS drivers prepare and access a communication line for transmitting data to and receiving data from an attached device.
Note:
Each RICCS bit synchronous driver task requires approximately 28Kb of co-processor adapter storage.
Two versions of the bit synchronous driver are provided. One version provides lower layer, bit synchronous support for the Zilog** hardware. The other version provides the identical support for the Signetics** hardware.
Note:
The Signetics** synchronous driver supports only DMA I/O. Message chaining is used for all reads and is selectable for writes. Refer to the RCS_S_OPEN command for the SHAREFLAGS parameter.
The synchronous RICCS Level A commands support the physical layer. These commands are implemented via a library of object module subroutines to be linked with the application tasks. The name of the library is RICCS.LIB. These subroutines serve as the interface between application tasks and the RICCS driver tasks.
The Level A commands included in RICCS are:
The C language support provided with the RICCS requires the Realtime Interface Co-Processor C Language Support. The language support consists of an include file, RICCSS.H, providing access to the Level A subroutines that come with Realtime Interface Co-Processor Communications Support. The include file contains data structures and library routine declarations allowing applications to access the RICCSSZ.EXE (Zilog**) and RICCSSS.EXE (Signetics**) drivers.
C language tasks should include the file RICCSS.H. During compilation, the /Zp option should be used to pack the data structures. Any memory model can be used for the task. During the link step, the Level A subroutine library, RICCS.LIB, should be linked to the user's object module along with the standard C libraries specified in the Realtime Interface Co-Processor C Language Support User's Guide.
The RICCSS.H and RICCS.LIB files are on the IBM Realtime Interface Co-Processor Extended Services Programs diskette.
Once the RICCS has been loaded, it initializes variables and allocates resources to handle software interrupts, timer interrupts, and memory.
Note:
No hardware allocation is done at this time. Port and DMA allocations are made when the port is opened. The RICCS driver task is responsible for allocating all the required resources (for example: ports, DMA channels, and timers) for communications; therefore, the application task does not have to allocate these resources.
If the RCS_S_PORTDEFINITION command is omitted at startup, the RICCS driver assumes the default port definition (all ports are active and software interrupt 75h is used to communicate with the RICCS driver task). Initial line characteristics and other information can be provided (through commands) to the RICCS driver task. These commands are optional; if they are omitted, the RICCS driver assumes default values.
Port definition, line characteristics, and other information must be provided through various commands if the defaults are not used. The default values may be changed by placing the commands in the application task or writing a startup task.
The sample programs provided with this user's guide have a startup task program and can be used to pass the configuration information to the RICCS driver.
To handle the I/O for multiple ports expediently, the RICCS driver task runs at a high task priority. Changes to the default task priority should be done at startup. The default task priority is three (3), but an application task can change that default task priority at startup. Application tasks should run at a lower priority than RICCS (priorities 4 through 255).
Software interrupt vectors are used to interface to the RICCS driver. Interrupt 75h is the default software interrupt vector. Up to eight additional software interrupt vectors can be added by using the RCS_S_PORTDEFINITION command.
Other software packages can use the software interrupt vector 75h; therefore, RICCS allows the user to specify different software interrupt vectors. This feature allows the application to use RICCS while using another software package with software interrupt vector 75h.
For most commands, task synchronization is either automatic (deferred commands) or unnecessary (immediate commands). The application task resumes execution following the call to the command subroutine only after the command has been completely processed. (For deferred commands, this is accomplished by a suspend/resume sequence within the command subroutine.)
Exceptions to the automatic or unnecessary task synchronization are the RCS_S_READ and RCS_S_WRITE commands when issued with the no-wait option. These two commands allow the application code to continue execution after the call, parallel with the I/O operation. The application must then issue an explicit wait to be posted when the I/O operation completes or check the Post Code field periodically. The status flags in the command control block should be checked after the post to verify that the operation has completed.
The command control block is available for reuse as soon as control is returned to the application code after the RICCS call.
Exceptions to the command control block availability are the RCS_S_READ and RCS_S_WRITE commands when issued with the no-wait option. These two commands allow the application code to continue execution after the call, parallel with the I/O operation. The application must then verify that the I/O operation has completed, by checking the post code and checking the status flags for completion before reusing the control block.
The RICCS driver allows the sharing of ports. If the PORTSHARING parameter to RCS_S_OPEN is on, up to 16 tasks can have a port open at the same time. Multiple tasks writing to a port is a relatively normal situation and the tasks involved are responsible for coordinating their individual uses of the port.
Each port must be programmed with the following physical line characteristics:
The RCS_S_SETLINECTRL command issued after the first RCS_S_OPEN command has been processed should establish these characteristics.
RCS_S_SETLINECTRL can be reissued to an open port at any time to change the characteristics as needed.
Warning: Data will be lost if the RCS_S_SETLINECTRL command is issued during data transfer.
The RCS_S_CLOSE command can be used to specify that current line characteristics are to be retained across sequential open/close cycles without reissuing RCS_S_SETLINECTRL. Selecting the current values option of the RCS_S_CLOSE command ensures that the same characteristics are retained at the next RCS_S_OPEN.
If no RCS_S_SETLINECTRL has been issued, or if the port has been closed with the return to default values option (rather than retain current values), RCS_S_OPEN initializes the port to the following system default values:
A command code identifies each Level A command, and each command has a defined command control block. The column "Set By Code Name", in the description of the command control block, indicates who is responsible for loading a particular parameter. The following is a list of code names used in the "Set By Code Name" column of the command control block descriptions.
+=================+===============+ | Set By Code | Meaning | | Name | | +=================+===============+ | RCS | RICCS driver | +-----------------+---------------+ | RCS SUB | RICCS | | | subroutines | +-----------------+---------------+ | APP | Application | | | task(s) | +-----------------+---------------+For control block entries involving timings, all timing parameters are expressed in 10 millisecond units. Each timing parameter is defined as a signed integer. A user may vary the timing parameter interval from a minimum of 10-milliseconds (1 count) to a maximum of 5 minutes and 28 seconds (32767 counts). The RICCS rounds up the time values to the next higher multiple of the interrupt clock period.
Unused bits in parameters should be cleared to 0 for future use.
The parameters that are passed to the RICCS driver task are validated and the appropriate return codes are in the command control blocks. See "Synchronous Return Codes" for a list of return codes.
The following sections describe the operation of each command. The command control blocks, entry parameters, exit parameters, and call formats are described with each command.
The RCS_S_PORTDEFINITION command can be issued at any time. It configures the driver at each port startup and defines configuration parameters to the RICCS driver task.
The RCS_S_PORTDEFINITION command should be given prior to a RCS_S_OPEN command because the information in the RCS_S_PORTDEFINITION command is used during the open. Any RCS_S_PORTDEFINITION command applies to subsequent RCS_S_OPEN commands for the specified port. The RCS_S_PORTDEFINITION command:
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_PORTDEFINITION control block PUSH Offset of RCS_S_PORTDEFINITION control block CALL _rcs_s_portdefinition ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ALLOCATE THE PORT DEFINITION CONTROL BLOCK (PDCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
PDCB RCSS_S_PORTDEFINITION <,,,,,1,0,0,0,0,0,0,27H,1,2,0>
; CALL THE RCS_S_PORTDEFINITION SUBROUTINE TO DEFINE FOR PORT 0
; THE RS-232-C CONTROL SIGNALS THAT ARE ACTUALLY CONNECTED AND
; ADD SOFTWARE INTERRUPT VECTOR 27H TO COMMUNICATE WITH THE
; RICCS SYNCHRONOUS DRIVER.
LEA DI,PDCB ;LOAD OFFSET OF PDCB
PUSH CS ;SEGMENT OF PDCB
PUSH DI ;OFFSET OF PDCB
CALL _rcs_s_portdefinition ;CALL LEVEL A SUB TO DO
;PORT DEFINITION COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP PDCB.PDCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_portdefinition pdcb; rcs_s_portdefinition (&pdcb);PDCB is the RCS_S_PORTDEFINITION Control Block
Example Call
#include "riccss.h"
/* Default logical device name */
unsigned char ldn[]="SCCO";
/* Allocate the Port Definition control block (pdcb) and */
/* initialize parameters. */
struct rcss_s_portdefinition pdcb = {0, 0, 0, 0, 0, 1, 0,
0, 0, 0x27, 1, 2, 0}
/* Initialize logical device name */
memcpy (pdcb.pdcb_s_logicaldevicename, ldn, 4};
/* Call the RCS_S_PORTDEFINITION subroutine to define */
/* for port 0 the RS-232-C control signals that are */
/* actually connected and add software interrupt vector */
/* 27h to communicate with the RICCS synchronous driver. */
rcs_s_portdefinition (&pdcb);
if (pdcb.pdcb_s_retcode == 0)
.
.
RCS_S_PORTDEFINITION Control Block (PDCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 00h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | RESERVED1 | Reserved for | Must be 0 | APP | | 03h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | CHANGEDSTATUS | A present or | 0=No change | RCS | | | | previous | 1=Changed | | | | |RCS_S_PORTDEFINITION| Bit0: Changed by present | | | | | command has | call | | | | | changed the port | Bit1: Changed by previous | | | | | configuration | call | | +------+----------------+--------------------+---------------------------+-----+ | 07h | ACTIVEDEVICE | Active or inactive | Bit0: | APP | | | | port | 0=Inactive | | | | | | 1=Active | | +------+----------------+--------------------+---------------------------+-----+ | 08h | PORTID | Physical port | 0=Port 0 | APP | | | | identification | 1=Port 1 | | | | | | 2=Port 2 | | | | | | 3=Port 3 | | | | | | 4=Port 4 | | | | | | 5=Port 5 | | | | | | 6=Port 6 | | | | | | 7=Port 7 | | +------+----------------+--------------------+---------------------------+-----+ | 09h- | LOGICALDEVNAME | A string containing| | APP | | 0Ch | | a logical device | | | | | | name for a port | | | +------+----------------+--------------------+---------------------------+-----+ | 0Dh | RESERVED2 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | SOFTWAREINT | Software interrupt | | APP | | | | vector used to | | | | | | communicate with | | | | | | RICCS | | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | CONCTRL | Indicates whether | Bit0: | APP | | | | the CONNECT | 0=No change to current | | | | | parameter defines | RS-232-C control signal | | | | | the RS-232-C | connections | | | | | control signal | 1=CONNECT defines the | | | | | connections | RS-232-C control signal | | | | | | connections | | +------+----------------+--------------------+---------------------------+-----+ | 10h | CONNECT | Identifies which | 0=Not connected | APP | | | | RS-232-C control | 1=Connected | | | | | signals are | Bit0: RTS | | | | | actually connected | Bit1: DTR | | | | | | Bit2: RI | | | | | | Bit3: DCD | | | | | | Bit4: DSR | | | | | | Bit5: CTS | | | | | | Bit6: RS | | | | | | Bit7: Reserved | | +------+----------------+--------------------+---------------------------+-----+ | 11h- | RESERVED3 | Reserved for | Must be 0 | APP | | 15h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
RESERVED1 reserved; value must be 0.
ACTIVEDEVICE indicates whether the port is active or inactive. By default, all ports are active.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | Inactive | | 0 +-------+--------------------+ | | 1 | Active | +-----+-------+--------------------+PORTID is the physical port identification. The values are:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | PORT 0 | +------------+------------------------+ | 1 | PORT 1 | +------------+------------------------+ | 2 | PORT 2 | +------------+------------------------+ | 3 | PORT 3 | +------------+------------------------+ | 4 | PORT 4 | +------------+------------------------+ | 5 | PORT 5 | +------------+------------------------+ | 6 | PORT 6 | +------------+------------------------+ | 7 | PORT 7 | +------------+------------------------+LOGICALDEVNAME is a four-character ASCII string containing a logical device name for a port. Four null characters indicate that the LOGICALDEVNAME should not be changed from its previous value. The default values are:
+============+========================+ | Value | Meaning | +============+========================+ | "SCC0" | PORT 0 | +------------+------------------------+ | "SCC1" | PORT 1 | +------------+------------------------+ | "SCC2" | PORT 2 | +------------+------------------------+ | "SCC3" | PORT 3 | +------------+------------------------+ | "SCC4" | PORT 4 | +------------+------------------------+ | "SCC5" | PORT 5 | +------------+------------------------+ | "SCC6" | PORT 6 | +------------+------------------------+ | "SCC7" | PORT 7 | +------------+------------------------+RESERVED2 reserved; value must be 0.
SOFTWAREINT is an additional software interrupt vector used by the application task to communicate with RICCS driver task. A value of 0 indicates that no software interrupt vector should be added. By default, applications use interrupt 75h to communicate with the RICCS driver.
CONCTRL is the control byte for the CONNECT parameter described as follows:
Note:
This parameter only needs to be set when using the IBM X.25 Interface Co-Processor/2, the IBM Realtime Interface Co-Processor Portmaster Adapter/A, or the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 because several of the control signal lines float when not connected, causing spurious interrupts. For these adapters, use the CONCTRL and CONNECT parameters to indicate which control signals are not connected.
+=====+=======+==============================================================+ | Bit | Value | Meaning | +=====+=======+==============================================================+ | | 0 | No change to currect RS-232-C connections | | 0 +-------+--------------------------------------------------------------+ | | 1 | CONNECT defines the RS-232-C control signal connections | +-----+-------+--------------------------------------------------------------+CONNECT is a byte that defines the RS-232-C control signal connections. The byte is a series of bit flags, one per control signal, as shown in the following table. The default is all control signals connected.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Control signal is not | | | connected | +------------+------------------------+ | 1 | Control signal is | | | connected | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Ring Indicator (RI) | | | | +--------------- Data Carrier Detect (DCD) | | | +------------------ Data Set Ready (DSR) | | +--------------------- Clear To Send (CTS) | +------------------------ Rate Select (RS) +--------------------------- ReservedRESERVED3 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
CHANGEDSTATUS indicates if a present RCS_S_PORTDEFINITION command has changed the port configuration, a previous RCS_S_PORTDEFINITION command has changed the port configuration, or both. Each bit may have a value of 0 or 1.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | Changed | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Changed by Present Call | | | | | | +--------- Changed by a Previous Call | | | | | +------------ Reserved | | | | +--------------- Reserved | | | +------------------ Reserved | | +--------------------- Reserved | +------------------------ Reserved +--------------------------- ReservedRETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 0600h | Invalid device name | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1800h | Invalid driver task | | | number | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 1D00h | Too many interrupt | | | vectors | +------------+------------------------+
The RCS_S_OPEN command allows the application task to inform the RICCS driver how it intends to communicate through a port:
This command registers the application task with the RICCS driver as a valid task that performs subsequent commands to the port. If no other application task has this port open, performing this command causes RICCS to setup the interface hardware, based on default settings or previously set values. This command must be issued before any other commands (except the RCS_S_PORTDEFINITION, RCS_S_SHUTDOWN, or RCS_S_DEFEI commands).
The command, by defining a password in the PASSWORD parameter, allows a local set of tasks to share the port and prevents other applications from using the port. The first task opening the port may specify a password and any subsequent task opening the port must provide the same password.
The command is used to inform the RICCS if DMA can be used for data input or data output.
Only ports 0 and 1 are capable of DMA input and output on the Realtime Interface Co-Processor, IBM Realtime Interface Co-Processor Multiport, and IBM Realtime Interface Co-Processor Multiport/2. The IBM X.25 Interface Co-Processor/2 is capable of DMA on its single port. All eight ports are capable of DMA input and output on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2
One 80186 DMA channel, at the user's option, may be shared between reads and writes. The channel is used in applications when data is alternately sent and received, and it conserves the two DMA channels available on most co-processor adapters. No sharing is needed when using the DMA and Peripheral Interface Chip (DMAPIC) on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2. When sharing a DMA channel, an active DMA read operation stops when a write is performed. The application is responsible for working within a flow control framework which ensures no data is received during a write operation.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_OPEN control block PUSH Offset of RCS_S_OPEN control block CALL _rcs_s_open ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ALLOCATE THE OPEN CONTROL BLOCK (OCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
OCB RCSS_S_OPEN <,,,,,'S','C','C','0',1,0,0,0,0,0,0>
; CALL THE RCS_S_OPEN SUBROUTINE TO OPEN PORT 0, ALLOWING
; IT TO BE SHARED BY OTHER TASKS.
LEA DI,OCB ;LOAD OFFSET OF OCB
PUSH CS ;SEGMENT OF OCB
PUSH DI ;OFFSET OF OCB
CALL _rcs_s_open ;CALL LEVEL A SUB TO DO
;OPEN COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP OCB.OCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_open ocb; rcs_s_open (&ocb);OCB is the RCS_S_OPEN Control Block.
Example Call
#include "riccss.h"
/* Default logical device name */
unsigned char Ldn [ ] = "SCC0";
/* Allocate the Open control block (ocb) and initialize */
/* parameters. */
struct rcss_s_open ocb = {0, 0, 0, 0, 0, {0}, 1, 0,
0, 0, 0, 0, 0}:
/*Initialize logical device name */
memcpy (ocb.ocb_s_logicaldevname, Ldn, 4);
/* Call the RCS_S_OPEN subroutine to open port 0, */
/* allow it to be shared by other tasks. */
rcs_s_open (&ocb);
if (ocb.ocb_s_retcode == 0)
.
.
RCS_S_OPEN Control Block (OCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 01h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | VERREL | Version number and | Equals 0103h | RCS | | 07h | | release index | 0100h=1.00 | | | | | information | 0101h=1.01 | | | | | | 0102h=1.02 | | | | | | 0103h=1.03 | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | LOGICALDEVNAME | A string containing| | APP | | 0Bh | | a logical device | | | | | | name for the port | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch | PORTSHARING | Support port | Bit0: | APP | | | | sharing | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 0Dh | SYNCH | Synchronization | 0=Asynchronous | APP | | | | method used on the | 1=Bit synchronous | | | | | line | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | DMAWRITE | Support DMA on | Bit0: | APP | | | | RCS_S_WRITE | 0=No | | | | | commands | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | DMAREAD | Support DMA on | Bit0: | APP | | | | RCS_S_READ | 0=No | | | | | commands | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | RESERVED1 | Reserved for | Must be 0 | APP | | 13h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 14h- | PASSWORD | Local port sharing | 0 = No password | APP | | 15h | | password | Non-zero = Password | | +------+----------------+--------------------+---------------------------+-----+ | 16h | SHAREDMA | Share one DMA | Bit0: | APP | | | | channel for | 0=do not share DMA channel| | | | | RCS_S_READ and | 1=Share DMA channel | | | | | RCS_S_WRITE | | | +------+----------------+--------------------+---------------------------+-----+ | 17h | HOLDINIT | Communication | Bit0: | APP | | | | hardware | 0=No | | | | | initialization to | 1=Yes | | | | | held | | | +------+----------------+--------------------+---------------------------+-----+ | 18h | SASIZE | Size of station | 0=No change to station | APP | | | | address | address | | | | | | 1=Station address is one | | | | | | byte | | | | | | 2=Station address is two | | | | | | bytes | | +------+----------------+--------------------+---------------------------+-----+ | 19h- | STATIONADDR | Address of the | This address must match | APP | | 1Ah | | station for | the address in the data | | | | | receiving data | frame | | | | | frames | | | +------+----------------+--------------------+---------------------------+-----+ | 1Bh | SHAREFLAGS | Indicates if the | Bit0: | APP | | | | frame flag should | 0=Do not share | | | | | be shared for DMA | 1=Share flags | | | | | writes | | | +------+----------------+--------------------+---------------------------+-----+ | 1Ch- | RESERVED2 | Reserved for | Must be 0 | APP | | 1Fh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
LOGICALDEVNAME should be a four-character ASCII string that contains a logical device name for the port. The default values are:
+============+========================+ | Value | Meaning | +============+========================+ | "SCC0" | Port 0 | +------------+------------------------+ | "SCC1" | Port 1 | +------------+------------------------+ | "SCC2" | Port 2 | +------------+------------------------+ | "SCC3" | Port 3 | +------------+------------------------+ | "SCC4" | Port 4 | +------------+------------------------+ | "SCC5" | Port 5 | +------------+------------------------+ | "SCC6" | Port 6 | +------------+------------------------+ | "SCC7" | Port 7 | +------------+------------------------+PORTSHARING indicates whether or not the port should be shared. Sharing can be limited to a local set of tasks by using the PASSWORD parameter described below.
Note:
Up to 16 tasks can have the port open at the same time.
+=====+=======+===============+ | Bit | Value | Meaning | +=====+=======+===============+ | | 0 | No | | 0 +-------+---------------+ | | 1 | Yes | +-----+-------+---------------+SYNCH indicates the synchronization method (asynchronous or synchronous) that is in use on the line. This checks that the correct driver is assigned to the port and is receiving the command. The possible values are:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Asynchronous | +------------+------------------------+ | 1 | Bit synchronous | +------------+------------------------+DMAWRITE indicates whether to support DMA on RCS_S_WRITE commands.
Note:
This parameter is ignored by the synchronous Signetics** driver because all input and output is performed using DMA.
+=====+=======+===============+ | Bit | Value | Meaning | +=====+=======+===============+ | | 0 | No | | 0 +-------+---------------+ | | 1 | Yes | +-----+-------+---------------+DMAREAD indicates whether to support DMA on RCS_S_READ commands.
Note:
This parameter is ignored by the synchronous Signetics** driver because all input and output is performed using DMA.
+=====+=======+===============+ | Bit | Value | Meaning | +=====+=======+===============+ | | 0 | No | | 0 +-------+---------------+ | | 1 | Yes | +-----+-------+---------------+RESERVED1 reserved; value must be 0.
PASSWORD is the 16-bit value that restricts port sharing. When a task opens a port and no other task has the port open, this value is recorded as the password. Any other task that subsequently attempts to open the port must specify this same value to successfully open the port. A value of 0 specified by the first task opening the port, implies that no password protection is used and any task can open the port.
SHAREDMA indicates that one DMA channel is used for DMA reads and writes. DMA does not have to be turned on for reads and writes when the command is issued; however, the sharing of one DMA channel will not occur until DMA is eventually turned on for both reads and writes. DMA is turned on by using either the RCS_S_OPEN, RCS_S_DMAREADCTRL, or RCS_S_DMAWRITECTRL commands. When sharing a DMA channel, an active DMA read is stopped when a write must be performed.
+=====+=======+==========================+ | Bit | Value | Meaning | +=====+=======+==========================+ | | 0 | Do not share DMA channel | | 0 +-------+--------------------------+ | | 1 | Share DMA channel | +-----+-------+--------------------------+Note:
This parameter is ignored by the synchronous Signetics** driver because each port has two DMA channels.
HOLDINIT is a flag that indicates initialization of the communications hardware is to be held (not performed) until an RCS_S_SETLINECTRL command is issued. The hardware is normally initialized the first time the driver opens the port. When the flag is set, an RCS_S_SETLINECTRL command must be issued prior to any RCS_S_READ or RCS_S_WRITE commands. If another task has the port open when this command is issued, the normal action is to do no initialization; therefore, the driver ignores the HOLDINIT flag.
+=====+=======+===============+ | Bit | Value | Meaning | +=====+=======+===============+ | | 0 | No | | 0 +-------+---------------+ | | 1 | Yes | +-----+-------+---------------+SASIZE indicates the size of the station address. The default SASIZE is one byte.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change to station | | | address | +------------+------------------------+ | 1 | Station address is one | | | byte (default) | +------------+------------------------+ | 2 | Station address is two | | | bytes | +------------+------------------------+Note:
A 2-byte station address is only valid for the synchronous Signetics** line driver. The invalid parameters return code (0300h) is returned if this value is set when using the synchronous Zilog** line driver.
STATIONADDR is the address of the station for receiving data frames. The address contained in the data frame must match this address or the broadcast address (FFh or FFFFh) for the frame to be forwarded to the application task. A value of 0 turns off address filtering; therefore, all messages are passed to the application. By default, address filtering is off. If the station address is 1 byte, then the application must insure that the high byte of this parameter is 0. To disable address filtering set the STATIONADDR parameter to 0 and the SASIZE parameter to 1 or 2.
SHAREFLAGS indicates if the synchronization flag should be shared, if possible, when processing RCS_S_WRITE commands.
+=====+=======+========================+ | Bit | Value | Meaning | +=====+=======+========================+ | | 0 | Do not share the flags | | 0 +-------+------------------------+ | | 1 | Share the flags | +-----+-------+------------------------+
Note:
This parameter will be ignored by the synchronous Zilog** driver.RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
DEVHANDLE is the device handle returned by RICCS.
VERREL is the version number and release index information returned by RICCS. VERREL consists of two bytes:
This value is 0103h for the product defined in this chapter.
+============+========================+ | Value | Meaning | +============+========================+ | 0100h | 1.00 | +------------+------------------------+ | 0101h | 1.01 | +------------+------------------------+ | 0102h | 1.02 | +------------+------------------------+ | 0103h | 1.03 | +------------+------------------------+RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0001h | Successful and no DMA | | | write | +------------+------------------------+ | 0002h | Successful and no DMA | | | read | +------------+------------------------+ | 0003h | Successful and no DMA | +------------+------------------------+ | 0200h | Too many tasks sharing | | | the port | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 0400h | Device already open | +------------+------------------------+ | 0600h | Invalid device name | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1800h | Invalid driver task | | | number | +------------+------------------------+ | 1900h | Device not active | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 1C00h | Hardware already | | | allocated | +------------+------------------------+ | 1E00h | Incompatible port type | +------------+------------------------+ | 1F00h | Invalid password | +------------+------------------------+ | 2000h | No password protection | +------------+------------------------+
The RCS_S_CLOSE command informs RICCS that the application task no longer needs to communicate with the device. If other tasks have the port open, they keep their access to the port, and nothing else is done. If this was the only task that opened the port, RICCS ceases communications with the device and frees the port and any associated buffers. Once the RCS_S_CLOSE command is performed, an RCS_S_OPEN command must be issued before any further communications to the device can be attempted. The line characteristics and RS-232-C control signal values in effect when the RCS_S_CLOSE command is performed are retained unless the caller requests that the default values be re-instated. Application tasks may use the RCS_S_CLOSE command to pass control between the synchronous and asynchronous drivers.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_CLOSE control block PUSH Offset of RCS_S_CLOSE control block CALL _rcs_s_close ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CLOSE CONTROL BLOCK (CCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
CCB RCSS_S_CLOSE <,,,,1,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE CCB. CALL
; THE RCS_S_CLOSE SUBROUTINE TO CLOSE THE PORT, RETURNING
; THE CONFIGURATION VALUES TO THE SYSTEM DEFAULTS, AND KEEPING
; THE PORT RESOURCE.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CCB.CCB_S_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN CCB
LEA DI,CCB ;LOAD OFFSET OF CCB
PUSH CS ;SEGMENT OF CCB
PUSH DI ;OFFSET OF CCB
CALL _rcs_s_close ;CALL LEVEL A SUB TO DO
;CLOSE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CCB.CCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_close ccb; rcs_s_close (&ccb);CCB is the RCS_S_CLOSE Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Close control block (ccb) and initialize */
/* parameters. */
struct rcss_s_close ccb = {0, 0, 0, 0, 1, 0, 0};
/* Initialize the device handle parameter in the ccb. */
/* Call the RCS_S_CLOSE subroutine to close the port, */
/* returning the configuration values to the system */
/* defaults, and keep the port resource */
ccb.ccb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_close (&ccb);
if (ccb.ccb_s_retcode == 0)
.
.
RCS_S_CLOSE Control Block (CCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 02h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | CONFIGVALUES | Determines which | Bit 0 : | APP | | 07h | | configuration | 0=Retain current values | | | | | values to dave | 1=Return to defaults | | +------+----------------+--------------------+---------------------------+-----+ | 08h | DRIVER | Whether the port | -1=Current driver | APP | | | | resource should | (synchronous) and | | | | | be returned | return the port resource| | | | | | 0=Current driver | | | | | | (synchronous) and keep | | | | | | the port resource | | | | | | 1=Asynchronous driver | | | | | | (temporary) | | | | | | 2=Asynchronous driver | | | | | | (permanent) | | +------+----------------+--------------------+---------------------------+-----+ | 09h- | RESERVED | Reserved for | Must be 0 | APP | | 0Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
CONFIGVALUES gives the user an option for saving the port configuration values after an RCS_S_CLOSE command has been issued. Option zero retains the current line characteristics and RS-232-C control signal values. Option one returns to the default values after issuing an RCS_S_CLOSE command.
Note:
If two or more application tasks have the port open and one task issues an RCS_S_CLOSE, the current configuration values are retained, regardless of the setting of this parameter. The port is not closed until the last application has issued an RCS_S_CLOSE.
+=====+=======+========================+ | Bit | Value | Meaning | +=====+=======+========================+ | | 0 | Retain current values | | 0 +-------+------------------------+ | | 1 | Return to defaults | +-----+-------+------------------------+DRIVER allows the application task to specify whether the port resource should be returned or kept. Retaining the synchronous driver and returning the port resource causes the output control signal to drop. Retaining the synchronous driver and keeping the port resource maintains the communication line control signals. If switching between drivers, the DRIVER parameter enables control to pass between the synchronous and asynchronous drivers without adversely affecting the communication line in the process. Control may be passed temporarily, which means the application task intends to switch back to the synchronous driver at some point, or control may be passed permanently, meaning no switch back to the synchronous driver is planned. If control is permanently passed and the application task later decides to switch back to the synchronous driver, the SWITCHPREP parameter of the asynchronous driver's RCS_OPEN command can be used to do this.
Note:
If two or more application tasks have the port open and one task issues an RCS_S_CLOSE, the current driver will be retained regardless of the setting of this parameter. The port is not closed until the last application has issued an RCS_S_CLOSE.
+=======+=============================+ | Value | Meaning | +=======+=============================+ | -1 | Return the port resource. | +-------+-----------------------------+ | 0 | Keep the port resource. | +-------+-----------------------------+ | 1 | Pass temporary control to | | | asynchronous driver | +-------+-----------------------------+ | 2 | Pass permanent control to | | | asynchronous driver | +-------+-----------------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
This command sets characteristics that determine how the communications line operates. This command may be issued at any time; however, changing the BITRATERCV, BITRATETRANS, DATABITS, DUPLEX, CRC, and ENCODING causes the hardware to be reset. A reset aborts active reads and writes.
RICCS initially uses default values for these characteristics. See the descriptions of each characteristic for the default values. Once an RCS_S_SETLINECTRL command is performed, the new values are retained until changed by a subsequent RCS_S_SETLINECTRL command or an RCS_S_CLOSE command. This feature allows one task to set characteristics and another task to use the same ports, independent of the specific characteristics.
Note:
The descriptions of the BITRATERCV and BITRATETRANS parameters contain a list of all supported bit rates. The bit rates supported depend on the type of electrical interface board, the type of adapter, the system requirements, and the I/O mode. When selecting bit rates, refer to the hardware technical reference for your co-processor adapter for more information.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_SETLINECTRL control block PUSH Offset of RCS_S_SETLINECTRL control block CALL _rcs_s_setlinectrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE SET LINE CONTROL CONTROL BLOCK (SLCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
SLCB RCSS_S_SETLINECTRL <,,,,15,15, 0, 2, 4, 2, 1, -1, 1, 2, 2,
0, 0, 0 >
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE SLCB. CALL
; THE RCS_S_SETLINECTRL SUBROUTINE TO SET THE BIT RATE FOR
; THE TRANSMITTING AND RECEIVING DEVICE TO 9600 BITS PER
; SECOND. ALL OTHER PARAMETERS KEEP THEIR DEFAULT VALUES.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV SLCB.SLCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN SLCB
LEA DI,SLCB ;LOAD OFFSET OF SLCB
PUSH CS ;SEGMENT OF SLCB
PUSH DI ;OFFSET OF SLCB
CALL _rcs_s_setlinectrl ;CALL LEVEL A SUB TO DO
;SET LINE CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SLCB.SLCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_setlinectrl slcb; rcs_s_setlinectrl (&slcb);SLCB is the RCS_S_SETLINECTRL Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Set Line Control control block (slcb) */
/* and initialize parameters. */
struct rcss_s_setlinectrl slcb = {0, 0, 0, 0, 15, 15,
0, 2, 4, 2, 1, -1, 1, 2, 2, 0, 0, 0 };
/* Initialize the device handle parameter in the slcb. */
/* Call the RCS_S_SETLINECTRL subroutine to set the bit */
/* rate for the transmitting and receiving device to */
/* 9600 bits per second. All other parameters keep */
/* their default values. */
slcb.slcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_setlinectrl (&slcb);
if (slcb.slcb_s_retcode == 0)
.
.
RCS_S_SETLINECTRL Control Block (SLCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 03h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | BITRATERCV | Bits per second for| See BITRATERCV description| APP | | | | receiving device | in the RCS_S_SETLINECTRL | | | | | | command | | +------+----------------+--------------------+---------------------------+-----+ | 07h | BITRATETRANS | Bits per second for| See BITRATETRANS | APP | | | | transmitting device| description in the | | | | | | RCS_S_SETLINECTRL command | | +------+----------------+--------------------+---------------------------+-----+ | 08h | RESERVED1 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 09h | IDLEPAT | Pattern sent when | 0=No change | APP | | | | link connection is | 1=Mark | | | | | in idle state | 2=Flag | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah | DATABITS | Number of data |0=No change | APP | | | | bits per character |1=5 data bits per character| | | | | |2=6 data bits per character| | | | | |3=7 data bits per character| | | | | |4=8 data bits per character| | +------+----------------+--------------------+---------------------------+-----+ | 0Bh | DUPLEX | Duplex mode | 0=No change | APP | | | | (half or full) | 1=Half-duplex | | | | | | 2=Duplex | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch- | HDXDELAY | Delay before | 0=No change | APP | | 0Dh | | dropping RTS after | >0=Delay time Equals 10 | | | | | a half-duplex write| millisecond units | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh- | IDLEDETECT | Idle detect timeout| 0=No change | APP | | 0Fh | | value | -1=Infinite timeout | | | | | | >0=Timeout value Equals | | | | | | 10 millisecond units | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | STOPTRANS | Stop transmission | 0=No change | APP | | 11h | | timeout value | -1=Infinite timeout | | | | | | >0=Timeout value Equals | | | | | | 10 millisecond units | | +------+----------------+--------------------+---------------------------+-----+ | 12h | CRC | CRC calculation | 0=No change | APP | | | | and preset value | 1=CRC-CCITT 0s | | | | | | 2=CRC-CCITT 1s | | | | | | 3=CRC-16 0s | | | | | | 4=CRC-16 1s | | +------+----------------+--------------------+---------------------------+-----+ | 13h | ENCODING | The method of data | 0=No change | APP | | | | encoding used | 1=NRZ | | | | | | 2=NRZI | | | | | | 3=FM1 | | | | | | 4=FM0 | | +------+----------------+--------------------+---------------------------+-----+ | 14h | SASIZE | Size of station | 0=No change to station | APP | | | | address | address | | | | | | 1=Station address is one | | | | | | byte | | | | | | 2=Station address is two | | | | | | bytes | | +------+----------------+--------------------+---------------------------+-----+ | 15h- | STATIONADDR | Address of the | This address must match | APP | | 16h | | station for | the address in the data | | | | | receiving data | frame | | | | | frames | | | +------+----------------+--------------------+---------------------------+-----+ | 17h- | RESERVED2 | Reserved for | Must be 0 | APP | | 1Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
BITRATERCV is the number of bits per second at which the the communication chip should receive data. When using the IBM Realtime Interface Co-Processor, IBM Realtime Interface Co-Processor Multiport, IBM Realtime Interface Co-Processor Multiport/2, and IBM X.25 Interface Co-Processor/2 adapters, if a nonzero value is passed in this parameter on Zilog**-based boards, the BITRATETRANS parameter must also contain an equal nonzero value, a -1, or a -2. The default BITRATERCV is external clocking (RTxC).
Note:
For the Realtime Interface Co-Processor and the IBM Realtime Interface Co-Processor Multiport, ensure that the jumpers have been set correctly for the preferred clocking. For the IBM Realtime Interface Co-Processor Multiport/2 and the IBM X.25 Interface Co-Processor/2, ensure that the clock source has been set correctly with the reference diskette for the preferred clocking.
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | | | (default) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 0 | No change | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 19 | Reserved | +------------+------------------------+ | 20 | Reserved | +------------+------------------------+ | 21 | 230,400 | +------------+------------------------+Note:
The bit rates of 1800, 3600 and 7200 bps are not supported by the synchronous Signetics** driver. The bit rates of 57,600 bps and 230,400 bps are only supported by the synchronous Signetics** driver. External clocking from TRxC cannot be selected for a RS-422-A port on an IBM Realtime Interface Co-Processor. The synchronous Zilog** driver does not support an internally clocked bit rate of 38,400 bps if NRZI encoding is used. Internal transmit clocking cannot be selected for a V.35 port on an IBM Realtime Interface Co-Processor.
BITRATETRANS is the number of bits per second at which the communication chips should transmit data. When using the IBM Realtime Interface Co-Processor, IBM Realtime Interface Co-Processor Multiport, IBM Realtime Interface Co-Processor Multiport/2, and IBM X.25 Interface Co-Processor/2 adapters, if a non zero value is passed in this parameter on Zilog-based** boards the BITRATERCV parameter must also contain an equal non zero value, a -1, or a -2. The default BITRATRANS is external clocking (TRxC).
Note:
For the Realtime Interface Co-Processor and the IBM Realtime Interface Co-Processor Multiport, ensure that the jumpers have been set correctly for the desired clocking. For the IBM Realtime Interface Co-Processor Multiport/2 and the IBM X.25 Interface Co-Processor/2, ensure that the clock source has been set correctly with the reference diskette for the desired clocking.
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | | | (default) | +------------+------------------------+ | 0 | No change | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 19 | Reserved | +------------+------------------------+ | 20 | Reserved | +------------+------------------------+ | 21 | 230,400 bps | +------------+------------------------+Note:
The bit rates of 1800, 3600 and 7200 bps are not supported by the synchronous Signetics** driver. The bit rates of 57,600 bps and 230,400 bps are only supported by the synchronous Signetics** driver. The synchronous Zilog** driver does not support an internally clocked bit rate of 38,400 bps if NRZI encoding is used. External clocking from TRxC cannot be selected for a RS-422-A port on an IBM Realtime Interface Co-Processor. Internal transmit clocking cannot be selected for a V.35 port on an IBM Realtime Interface Co-Processor.
RESERVED1 reserved; value must be 0.
IDLEPAT is the pattern sent when the link connection is in an idle state.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | Mark | +------------+------------------------+ | 2 | Flag (default) | +------------+------------------------+Note:
A co-processor adapter in a secondary station cannot be attached directly on a multidrop line.
DATABITS is the number of data bits for each character. The following are the valid values for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | 5 bits per character | +------------+------------------------+ | 2 | 6 bits per character | +------------+------------------------+ | 3 | 7 bits per character | +------------+------------------------+ | 4 | 8 bits per character | | | (default) | +------------+------------------------+DUPLEX indicates if the line is duplex or half-duplex. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | Half-duplex | +------------+------------------------+ | 2 | Duplex (default) | +------------+------------------------+In duplex mode, RICCS does not alter RS-232-C control signals before and after data transmission; however, before transmitting data, RICCS waits for required input control signals, as specified by the application with the RCS_S_SETCTRLSIGNAL command. By default, the RTS and DTR signals are on. The duplex setting covers a half-duplex configuration that gives the application responsibility for transmission control.
In half-duplex mode (RS-232-C interface), RICCS raises and lowers the RTS control signal. This controls transmission on the half-duplex line. When transmitting data in half-duplex mode, RICCS:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | >0 | Delay value | +------------+------------------------+If an application issues a new write request in the time between the end of the last write and the end of the half duplex delay, the new write will start immediately. It will not have to wait for RTS to be dropped and then raised again.
IDLEDETECT is the idle time allowed between receipts of frames (between ending flag characters). The Idle Detect times are expressed in 10-millisecond units. The Idle Detect Timer re-starts each time an ending flag is received. When a write starts in half-duplex mode, the timer is canceled and restarted when the write completes. If the timer expires, a bit is set in the READSTATUS parameter of the active or next RCS_S_READ command to indicate the error and the command is terminated immediately. When the Idle Detect Timeout value changes (by this command), the Idle Detect timer is restarted with the new value. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | -1 | Infinite timeout | | | (default) | +------------+------------------------+ | >0 | Timeout value | +------------+------------------------+STOPTRANS is the amount of time transmissions stop before transmitted frames are returned with an error flag. This ensures that RCS_S_WRITE commands do not wait indefinitely for transmissions to start. The timer starts when transmissions stop and cancel when transmissions start again. The following values are valid for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | -1 | Infinite timeout | | | (default) | +------------+------------------------+ | >0 | Timeout value | +------------+------------------------+CRC indicates which CRC calculation and which preset values are to be used. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | CRC-CCITT, preset to | | | 0s | +------------+------------------------+ | 2 | CRC-CCITT, preset to | | | 1s (default) | +------------+------------------------+ | 3 | CRC-16, preset to 0s | +------------+------------------------+ | 4 | CRC-16, preset to 1s | +------------+------------------------+Note:
The synchronous Zilog** driver allows only the CRC-CCITT calculation. The invalid parameters return code (0300h) is returned by the synchronous Zilog** driver if CRC-16 is specified.ENCODING specifies the data encoding method to be used. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change | +------------+------------------------+ | 1 | NRZ | +------------+------------------------+ | 2 | NRZI (default) | +------------+------------------------+ | 3 | FM1 | +------------+------------------------+ | 4 | FM0 | +------------+------------------------+SASIZE indicates the size of the station address. The default SASIZE is one byte.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | No change to station | | | address | +------------+------------------------+ | 1 | Station Address is one | | | byte (default) | +------------+------------------------+ | 2 | Station Address is 2 | | | bytes | +------------+------------------------+Note:
A 2-byte station address is only valid for the synchronous Signetics** line driver. The invalid parameters return code is returned if this value is set when using the synchronous Zilog** line driver.
STATIONADDR is the address of the station for receiving data frames. The address contained in the data frame must match this address or the broadcast address (FFh or FFFFh) for the frame's acceptance. A value of 0 turns off address filtering; therefore, all messages are passed to the application. By default, address filtering is off. If the station address is 1 byte, then the application must insure that the high byte of this parameter is 0. To disable address filtering set the STATIONADDR parameter to 0 and the SASIZE parameter to 1 or 2.
RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
This command allows the application task to obtain the current settings of various communications line characteristics, including the bit rates, idle pattern, the amount of time transmissions can be stopped, CRC calculations, data encoding method, the number of data bits, the duplex method, the half duplex delay time, the amount of idle time allowed between the receipt of frames, the size of the station address, and the address of the station receiving data frames. This command can be issued at any time.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_RETLINECTRL control block PUSH Offset of RCS_S_RETLINECTRL control block CALL _rcs_s_retlinectrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RETURN LINE CONTROL CONTROL BLOCK (RLCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
RLCB RCSS_S_RETLINECTRL <>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RLCB. CALL
; THE RCS_S_RETLINECTRL SUBROUTINE TO RETURN THE LINE
; CHARACTERISTICS OF THE PORT.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV RLCB.RLCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN RLCB
LEA DI,RLCB ;LOAD OFFSET OF RLCB
PUSH CS ;SEGMENT OF RLCB
PUSH DI ;OFFSET OF RLCB
CALL _rcs_s_retlinectrl ;CALL LEVEL A SUB TO DO
;RETURN LINE CONTROL
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RLCB.RLCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_retlinectrl rlcb; rcs_s_retlinectrl (&rlcb);RLCB is the RCS_S_RETLINECTRL Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Return Line Control control block (rlcb) */
/* and initialize parameters. */
struct rcss_s_retlinectrl rlcb;
/* Initialize the device handle parameter in the rlcb. */
/* Call the RCS_S_RETLINECTRL subroutine to return the */
/* line characteristics of the port. */
rlcb.rlcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_retlinectrl (&rlcb);
if (rlcb.rlcb_s_retcode == 0)
.
.
RCS_S_RETLINECTRL Control Block (RLCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 04h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | BITRATERCV | Bits per second for| See BITRATERCV description| RCS | | | | receiving device | in the RCS_S_RETLINECTRL | | | | | | command | | +------+----------------+--------------------+---------------------------+-----+ | 07h | BITRATETRANS | Bits per second for| See BITRATETRANS | RCS | | | | transmitting device| description in the | | | | | | RCS_S_RETLINECTRL command | | +------+----------------+--------------------+---------------------------+-----+ | 08h | RESERVED1 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 09h | IDLEPAT | Pattern sent when | 1=Mark | RCS | | | | link connection is | 2=Flag | | | | | in idle state | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah | DATABITS | Number of data | 1=5 data bits | RCS | | | | bits per character | 2=6 data bits | | | | | | 3=7 data bits | | | | | | 4=8 data bits | | +------+----------------+--------------------+---------------------------+-----+ | 0Bh | DUPLEX | Duplex mode | 1=Half-duplex | RCS | | | | (half or full) | 2=Duplex | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch- | HDXDELAY | Delay before | >0=Delay time Equals 10 | RCS | | 0Dh | | dropping RTS after | millisecond units | | | | | a half-duplex write| | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh- | IDLEDETECT | Idle detect | -1=Infinite timeout | RCS | | 0Fh | | timeout value | >0=Timeout value Equals | | | | | | 10 millisecond units | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | STOPTRANS | Stop transmission | -1=Infinite timeout | RCS | | 11h | | timeout value | >0=Timeout value Equals | | | | | | 10 millisecond units | | +------+----------------+--------------------+---------------------------+-----+ | 12h | CRC | CRC calculation | 1=CRC-CCITT 0's | RCS | | | | and preset value | 2=CRC-CCITT 1's | | | | | | 3=CRC-16 0's | | | | | | 4=CRC-16 1's | | +------+----------------+--------------------+---------------------------+-----+ | 13h | ENCODING | The method of data | 1=NRZ | RCS | | | | encoding used | 2=NRZI | | | | | | 3=FM1 | | | | | | 4=FM0 | | +------+----------------+--------------------+---------------------------+-----+ | 14h | SASIZE | Size of station | 1=Station address is one | RCS | | | | address | byte | | | | | | 2=Station address is two | | | | | | bytes | | +------+----------------+--------------------+---------------------------+-----+ | 15h- | STATIONADDR | Address of the | | RCS | | 16h | | station receiving | | | | | | the data frames. | | | +------+----------------+--------------------+---------------------------+-----+ | 17h- | RESERVED2 | Reserved for | Must be 0 | APP | | 1Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
RESERVED1 reserved; value must be 0.
RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
BITRATERCV is the number of bits per second at which the synchronous receive device operates when the communication chips receives data. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 21 | 230,400 bps | +------------+------------------------+BITRATETRANS is the number of bits per second at which the synchronous transmit device operates when it transmits data. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | -2 | External clock (RTxC) | +------------+------------------------+ | -1 | External clock (TRxC) | +------------+------------------------+ | 1 | 50 bps | +------------+------------------------+ | 2 | 75 bps | +------------+------------------------+ | 3 | 110 bps | +------------+------------------------+ | 4 | 134.5 bps | +------------+------------------------+ | 5 | 150 bps | +------------+------------------------+ | 6 | 300 bps | +------------+------------------------+ | 7 | 600 bps | +------------+------------------------+ | 8 | 1200 bps | +------------+------------------------+ | 9 | 1800 bps | +------------+------------------------+ | 10 | 2000 bps | +------------+------------------------+ | 11 | 2400 bps | +------------+------------------------+ | 12 | 3600 bps | +------------+------------------------+ | 13 | 4800 bps | +------------+------------------------+ | 14 | 7200 bps | +------------+------------------------+ | 15 | 9600 bps | +------------+------------------------+ | 16 | 19,200 bps | +------------+------------------------+ | 17 | 38,400 bps | +------------+------------------------+ | 18 | 57,600 bps | +------------+------------------------+ | 21 | 230,400 bps | +------------+------------------------+IDLEPAT is the idle pattern being transmitted when the link connection is in an idle state. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Mark | +------------+------------------------+ | 2 | Flag | +------------+------------------------+DATABITS is the number of data bits for each character. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | 5 bits per character | +------------+------------------------+ | 2 | 6 bits per character | +------------+------------------------+ | 3 | 7 bits per character | +------------+------------------------+ | 4 | 8 bits per character | +------------+------------------------+DUPLEX indicates if the line is duplex or half-duplex. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Half-duplex | +------------+------------------------+ | 2 | Duplex | +------------+------------------------+HDXDELAY is the amount of time to delay before RTS is dropped after a half-duplex write. Delay times are expressed in 10 millisecond units.
IDLEDETECT is the amount of idle time allowed between receipts of frames (between ending flag characters). One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | -1 | Infinite timeout | | | (default) | +------------+------------------------+ | >0 | Timeout value | +------------+------------------------+STOPTRANS is the amount of time transmissions can be stopped before the RCS_S_WRITE commands are returned with an error flag. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | -1 | Infinite timeout | | | (default) | +------------+------------------------+ | >0 | Timeout value | +------------+------------------------+CRC indicates which CRC calculation and which preset values are in use. One of the following values is returned:
+============+==========================+ | Value | Meaning | +============+==========================+ | 1 | CRC-CCITT, Preset to 0's | +------------+--------------------------+ | 2 | CRC-CCITT, Preset to 1's | +------------+--------------------------+ | 3 | CRC-16, Preset to 0's | +------------+--------------------------+ | 4 | CRC-16, Preset to 1's | +------------+--------------------------+ENCODING specifies the data encoding method in use. One of the following values is returned:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | NRZ | +------------+------------------------+ | 2 | NRZI | +------------+------------------------+ | 3 | FM1 | +------------+------------------------+ | 4 | FM0 | +------------+------------------------+SASIZE indicates the size of the station address in use. One of the following values is returned.
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Station address is one | | | byte | +------------+------------------------+ | 2 | Station address is two | | | bytes | +------------+------------------------+STATIONADDR is the address of the station for receiving data frames.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_RESET command resets the Serial Communications Controller interface hardware for a port, causing any active reads and writes to be aborted. This command is used when the application task detects some unusual condition indicating that the hardware is in an unknown state. This command resets the port to the current line characteristics and RS-232-C control signals.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_RESET control block PUSH Offset of RCS_S_RESET control block CALL _rcs_s_reset ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RESET CONTROL BLOCK (RSTCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
RSTCB RCSS_S_RESET <>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RSTCB. CALL
; THE RCS_S_RESET SUBROUTINE TO RESET THE PORT.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV RSTCB.RSTCB_S_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN RSTCB
LEA DI,RSTCB ;LOAD OFFSET OF RSTCB
PUSH CS ;SEGMENT OF RSTCB
PUSH DI ;OFFSET OF RSTCB
CALL _rcs_s_reset ;CALL LEVEL A SUB TO DO
;RETURN LINE CONTROL
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RSTCB.RSTCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_reset rstcb; rcs_s_reset (&rstcb);RSTCB is the RCS_S_RESET Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Reset control block (rstcb) and */
/* initialize parameters. */
struct rcss_s_reset rstcb;
/* Initialize the device handle parameter in the rstcb. */
/* Call the RCS_S_RESET subroutine to reset the port. */
rstcb.rstcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_reset (&rstcb);
if (rstcb.rstcb_s_retcode == 0)
.
.
RCS_S_RESET Control Block (RSTCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 05h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | RESERVED | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
This command terminates a specific RICCS driver (for example, the asynchronous driver or the synchronous driver using either the Zilog** or Signetics** serial chips) or all RICCS drivers either immediately or after all application tasks have closed their ports. When performing the RCS_S_SHUTDOWN command, RICCS stops all transmissions, frees all resources, and exits from the co-processor adapter.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_SHUTDOWN control block PUSH Offset of RCS_S_SHUTDOWN control block CALL _rcs_s_shutdown ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RETURN LINE CONTROL CONTROL BLOCK (SDCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
SDCB RCSS_S_SHUTDOWN <,,,,1,20h>
; CALL THE RCS_S_SHUTDOWN SUBROUTINE TO WAIT UNTIL THE PORT
; HAS BEEN CLOSED BEFORE UNLOADING ALL SYNCHRONOUS DRIVER TASKS.
LEA DI,SDCB ;LOAD OFFSET OF SDCB
PUSH CS ;SEGMENT OF SDCB
PUSH DI ;OFFSET OF SDCB
CALL _rcs_s_shutdown ;CALL LEVEL A SUB TO DO
;SHUTDOWN COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SDCB.SDCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_shutdown sdcb; rcs_s_shutdown (&sdcb);SDCB is the RCS_S_SHUTDOWN Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Return Line Control control block (sdcb) */
/* and initialize parameters. */
struct rcss_s_shutdown sdcb = {0, 0, 0, 0, 1, 0x20, 0};
/* Call the RCS_S_SHUTDOWN subroutine to wait until the */
/* port has been closed before unloading all synchronous */
/* driver tasks. */
rcs_s_shutdown (&sdcb);
if (sdcb.sdcb_s_retcode == 0)
.
.
RCS_S_SHUTDOWN Control Block (SDCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 06h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | RESERVED1 | Reserved for | Must be 0 | APP | | 03h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | TYPESHUTDOWN | Type of shutdown | Bit 0: | APP | | | | | 0=No wait | | | | | | 1=Wait | | +------+----------------+--------------------+---------------------------+-----+ | 07h | DRIVERID | Specific driver to | 00h=All drivers | APP | | | | shutdown | 10h=All Asynch | | | | | | 20h=All Synch | | | | | | 21h=Synch/Zilog** | | | | | | 22h=Synch/Signetics** | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED2 | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
RESERVED1 reserved; value must be 0.
TYPESHUTDOWN indicates whether to shutdown immediately or wait until the application closes all ports.
+=====+=======+========================+ | Bit | Value | Meaning | +=====+=======+========================+ | | 0 | Np Wait | | 0 +-------+------------------------+ | | 1 | Wait | +-----+-------+------------------------+DRIVERID identifies which RICCS driver should be shutdown. The following values are valid for this parameter.
+============+========================+ | Value | Meaning | +============+========================+ | 00h | All drivers | +------------+------------------------+ | 10h | All asynchronous | | | driver | +------------+------------------------+ | 20h | All synchronous | | | drivers | +------------+------------------------+ | 21h | Synchronous Zilog** | | | driver | +------------+------------------------+ | 22h | Synchronous | | | Signetics** driver | +------------+------------------------+Note:
If no driver is loaded that matches the requested shutdown driver identification, the invalid driver identification return code (2200h) is returned.
RESERVED2 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1800h | Invalid driver task | | | number | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 2200h | Invalid driver | | | identification | +------------+------------------------+
This command obtains data from an attached device. The data is placed in the application's input buffer specified in the RCS_S_READ command. Flags are not stored in the application's input buffer, but an extra 2 bytes should be allocated in each buffer for the frame check sequence (FCS).
Note:
The communications hardware has altered the FCS; consequently, the applications task cannot use the FCS.
RICCS uses the STATIONADDR parameter (defined by the RCS_S_OPEN or RCS_S_SETLINECTRL commands) to filter received data, passing only those frames addressed to this station. By default, no address filtering is done; frames for all devices are accepted.
The RCS_S_READ command allows the application task to control how it receives the data. The application task may wait for the read to complete, or continue execution even though the read is not completed. The no-wait read feature requires the user's task to issue its own wait or check the post code for completion. The user's task should check the READSTATUS parameter to determine when a no-wait read has completed. The post code value for a no-wait RCS_S_READ is 09h.
The number of outstanding RCS_S_READ commands is limited only by the size of the co-processor adapter memory. The next read initiates immediately upon completion of the current read. If a complete frame is not yet in the buffer, the read remains pending until the complete frame is received. The RCS_S_READ command reads input data directly into the application's input buffer. The application task should issue multiple RCS_S_READ commands to ensure that no data is lost.
The idle detect time-out feature (specified by setting the IDLEDETECT parameter in the RCS_S_SETLINECTRL command) ensures that the application task regains control within the specified period of time.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_READ control block PUSH Offset of RCS_S_READ control block CALL _rcs_s_read ADD SP,4
Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE APPLICATION INPUT BUFFER. ALLOCATE TWO EXTRA BYTES
; FOR THE FRAME CHECK SEQUENCE.
RDBUFFER DB 83 DUP (0) ;READ BUFFER
; ALLOCATE THE READ CONTROL BLOCK (RCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
RCB RCSS_S_READ <,,,,,,RDBUFFER,2,,80,,0 >
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RCB. CALL
; THE RCS_S_READ SUBROUTINE TO DO A WAIT READ OF UP TO
; 80 BYTES.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV RCB.RCB_S_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN RCB
;SET BUFFER SEGMENT
MOV WORD PTR RCB.RCB_S_READBUFFER+2,CS
LEA DI,RCB ;LOAD OFFSET OF RCB
PUSH CS ;SEGMENT OF RCB
PUSH DI ;OFFSET OF RCB
CALL _rcs_s_read ;CALL LEVEL A SUB TO DO
;READ COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RCB.RCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_read rcb; rcs_s_read (&rcb);RCB is the RCS_S_READ Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Define the application input buffer. */
char rdbuffer[83&rbracket.;
/* Allocate the Read control block (rcb) and */
/* initialize parameters. */
struct rcss_s_read rcb = {0, 0, 0, 0, 0, 0, rdbuffer,
2, 0, 80, 0, 0};
/* Initialize the device handle parameter in the rcb. */
/* Call the RCS_S_READ subroutine to do a wait read of */
/* up to 80 bytes. */
rcb.rcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_read (&rcb);
if (rcb.rcb_s_retcode == 0)
.
.
RCS_S_READ Control Block (RCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 07h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | READSTATUS | Status bits | See READSTATUS description| RCS | | 07h | | pertaining to the | in the RCS_S_READ command | | | | | RCS_S_READ command | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | READCOUNT | Actual count of | | RCS | | 09h | | characters read | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | READBUFFER | Address of the | Segment:offset | APP | | 0Dh | | application input | | | | | | buffer | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | READMODE | No wait/Wait | Bit 0: Reserved | APP | | | | RS-232-C signal | Bit 1: | | | | | action input buffer| 0=No wait | | | | | logocal or physical| 1=Wait | | | | | address | Bit 2: | | | | | | 0=No termination on | | | | | | state change | | | | | | 1=Terminate read on | | | | | | state change | | | | | | Bit 3: | | | | | | 0=Logical | | | | | | 1=Physical | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | POSTTASKNUM | Task number ot be | Task is not required to | APP | | | | posted when a | to have the port open | | | | | no-wait read | 0=Port task issuing the | | | | | completes | read. | | | | | | >0=Task number of task to | | | | | | post. | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | MAXLENGTH | Maximum number of | Equals bytes | APP | | 11h | | characters to be | | | | | | read | | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | RESERVED2 | Reserved | Used by RICCS | RCS | | 29h | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 2Ah- | RESERVED3 | Reserved for | Must be 0 | APP | | 2Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
READBUFFER is the address of the application's input buffer. The buffer should be at least as large as the value indicated in the MAXLENGTH parameter.
READMODE indicates whether or not to wait for the read to complete, the action to take if any RS-232-C input control signals change state, and if the application's input buffer is a logical or physical address. (This feature is used only with the RIC Portmaster/A adapter.) The RCS_S_SETCTRLSIGNAL command defines the RS-232-C control signals.
+=====+=======+==============================================================+ | Bit | Value | Meaning | +=====+=======+==============================================================+ | 0 | 0 | Reserved | +-----+-------+--------------------------------------------------------------+ | | 0 | No Wait | | 1 +-------+--------------------------------------------------------------+ | | 1 | Wait | +-----+-------+--------------------------------------------------------------+ | | 0 | No termination on state change | | 2 +-------+--------------------------------------------------------------+ | | 1 | Ternimate state change | +-----+-------+--------------------------------------------------------------+ | | 0 | Input buffer is logical address | | 3 +-------+--------------------------------------------------------------+ | | 1 | Input buffer is physical address | +-----+-------+--------------------------------------------------------------+Note:
Bit 3 applies only if DMAPIC DMA is used for reads. This bit is not recognized in the synchronous Zilog** driver.
POSTTASKNUM is the task number posted when a no-wait read completes. This task number does not have to be the number of the task issuing the RCS_S_READ command. The task specified by this parameter is not required to have the port open.
+=========+===============+ | Value | Meaning | +=========+===============+ | 0 | Task issuing | | | the read | | | should be | | | posted. | | | (Default) | +---------+---------------+ | >0 | Task number | | | of the task | | | to post when | | | a no-wait | | | read | | | completes. | +---------+---------------+MAXLENGTH indicates the maximum number of characters read per frame. If this length is exceeded, a read return code (1200h) is returned. When determining the maximum frame length, include 2 bytes for the frame check sequence (FCS).
Note:
Although two FCS characters are placed in the buffer, they have been modified and are not the true FCS characters plus 1 extra byte.
RESERVED3 reserved for future use; value must be 0.
Exit Parameters
RETCODE is the return code from the called command. The return code is not loaded until the read completes (READSTATUS bit 0 is set).
READSTATUS is a collection of status bits pertaining to the RCS_S_READ command. These bits are not available and should not be checked until the read completes (bit 0 is set). These bits pertain to the time between the completion of the previous RCS_S_READ command to the completion of the current RCS_S_READ command. READSTATUS has the following bit format:
+====+=====+=================================================================+ | Bit|Value| Meaning | +====+=====+=================================================================+ | | 0 | RCS_S_READ command not completed yet | | 0 +-----+-----------------------------------------------------------------| | | 1 | RCS_S_READ command completed | +----+-----+-----------------------------------------------------------------+ | | 0 | No control signal catae change since last RCS_S_SETCTRLSIGNAL, | | | | RLSIGNAL, RCS_S_RETCTRLSIGNAL, or RCS_S_READ. | | 1 +-----+-----------------------------------------------------------------+ | | 1 | Control signal state change since last RCS_S_SETCTRLSIGNAL, | | | | or RCS_S_READ. | | | | Note: State changes occurring after an RCS_S_OPEN or | | | | RCS_S_RESET, but before an initial RCS_S_SETCTRLSIGNAL, | | | | RCS_S_RETCTRLSIGNAL, or RCS_S_READ command, are not | | | | reported. Ring Indicator (RI) presence is indicated in | | | | bit 4, since its duration is not expected to be very long.| +----+-----+-----------------------------------------------------------------+ | | 0 | Transmission started | | 2 +-----+-----------------------------------------------------------------+ | | 1 | Transmission stopped | +----+-----+-----------------------------------------------------------------+ | | 0 | Input buffer not full | | 3 +-----+-----------------------------------------------------------------+ | | 1 | Input buffer full (Maximum length exceeded) | +----+-----+-----------------------------------------------------------------+ | | 0 | No Ring Indicator signal present | | 4 +-----+-----------------------------------------------------------------+ | | 1 | Ring Indicator signal present | +----+-----+-----------------------------------------------------------------+ | | 0 | Residual count 0 | | 5 +-----+-----------------------------------------------------------------+ | | 1 | Resident count non-zero | +----+-----+-----------------------------------------------------------------+ | 6 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 7 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | | 0 | No idle detect | | 8 +-----+-----------------------------------------------------------------+ | | 1 | Idle detect timeout | +----+-----+-----------------------------------------------------------------+ | 9 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | | 0 | No character overrun occurred | | 10 +-----+-----------------------------------------------------------------+ | | 1 | Character overrun occurred | +----+-----+-----------------------------------------------------------------+ | | 0 | The received frame was not aborted | | 11 +-----+-----------------------------------------------------------------+ | | 1 | The receive frame was aborted | +----+-----+-----------------------------------------------------------------+ | | 0 | No CRC error | | 12 +-----+-----------------------------------------------------------------+ | | 1 | CRC error occurred | +----+-----+-----------------------------------------------------------------+ | 13 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | | 0 | RCS_S_READ was not terminated by another command | | 14 +-----+-----------------------------------------------------------------+ | | 1 | ECS_S_READ was terminated by an RCS_S_SETLINECTRL, | | | | RCS_S_SHUTDOWN, RCS_S_RESET, RCS_S_CANCELREADS, or other command| +----+-----+-----------------------------------------------------------------+ | | 0 | No other receiver error detected | | 15 +-----+-----------------------------------------------------------------+ | | 1 | Other receiver error detected | +----+-----+-----------------------------------------------------------------+READCOUNT indicates the actual number of characters read. This count does not include the Frame Check Sequence (FCS) and is not loaded until the read completes (READSTATUS bit 0 is set).
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1200h | Read error | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
This command transmits data and allows the application task to control how the write is performed. The number of bytes from the application's output buffer are transmitted as specified in the RCS_S_WRITE command. RICCS prefixes the frame (data from application output buffer) with a flag, and terminates the frame with a frame check sequence (FCS) and a flag. For example, to send an SDLC frame, the first byte is the address field, the second byte is the control field, and the remaining bytes in the buffer are the information field. If a TX underrun occurs, RICCS sends an abort sequence and resends the frame.
The application task specifies that the RCS_S_WRITE command occurs normally or immediately. A normal write is placed at the end of the queue if a previous write is pending or if transmissions are stopped. An immediate write is placed at the beginning of the queue. The number of outstanding RCS_S_WRITE commands is only limited by the size of co-processor adapter memory.
In half-duplex mode, the following aspects of RICCS operations are important:
The stop transmissions time-out feature (specified by setting the STOPTRANS parameter on the RCS_S_SETLINECTRL command) ensures that the application will regain control within a specified period of time. The application task can choose to wait until the write completes or to continue execution, even though the write has not been completed. The no-wait write feature requires the user's task to issue its own wait or check the post code for completion. The user's task should check the WRITESTATUS parameter to determine when a no-wait write has completed. The post code value for a no-wait RCS_S_WRITE is 19h. The application task determines if it should be posted after each write completes, after all writes complete, or not be posted.
Note:
The IBM X.25 Interface Co-Processor/2, IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters require the request to send (RTS) control signal to be on before transmission can occur. If RTS is turned off, transmissions are stopped until the signal is turned back on. It is the application programmer's responsibility to ensure that this signal is on; however, this signal is on by default. (The RCS_S_SETCTRLSIGNAL command can be used to turn on the RTS signal.)
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_WRITE control block PUSH Offset of RCS_S_WRITE control block CALL _rcs_s_write ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE APPLICATION OUTPUT BUFFER.
WRBUFFER DB 80 DUP (0) ;WRITE BUFFER
; ALLOCATE THE WRITE CONTROL BLOCK (WCB) AND INITIALIZE
; PARAMETERS SET BY THE APPLICATION TASK.
WCB RCSS_S_WRITE <,,,,,,WRBUFFER,2,,80,,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE WCB. CALL
; THE RCS_S_WRITE SUBROUTINE TO DO A WAIT WRITE OF 80 BYTES.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV WCB.WCB_S_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN WCB
;SET BUFFER SEGMENT
MOV WORD PTR WCB.WCB_S_WRITEBUFFER+2,CS
LEA DI,WCB ;LOAD OFFSET OF WCB
PUSH CS ;SEGMENT OF WCB
PUSH DI ;OFFSET OF WCB
CALL _rcs_s_write ;CALL LEVEL A SUB TO DO
;WRITE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP WCB.WCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_write wcb; rcs_s_write (&wcb);WCB is the RCS_S_WRITE Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Define the application output buffer. */
char wrbuffer[80&rbracket.;
/* Allocate the Write control block (wcb) and */
/* initialize parameters. */
struct rcss_s_write wcb = {0, 0, 0, 0, 0, 0, wrbuffer,
2, 0, 80, 0, 0};
/* Initialize the device handle parameter in the wcb. */
/* Call the RCS_S_WRITE subroutine to do a wait write of */
/* 80 bytes. */
wcb.wcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_write (&wcb);
if (wcb.wcb_s_retcode == 0)
.
.
RCS_S_WRITE Control Block (WCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 09h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | WRITESTATUS | Status bits | See WRITESTATUS | RCS | | 07h | |pertaining to the | description on the | | | | |RCS_S_WRITE command | RCS_S_WRITE command | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | WRITECOUNT | Actual count of | | RCS | | 09h | | characters written | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | WRITEBUFFER | Address of | Segment:offset | APP | | 0Dh | | application output | | | | | | buffer | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | TYPEWRITE | Type of write | Bit 0: | APP | | | | | 0=Normal | | | | | | 1=Immediate | | | | | No Wait/Wait | Bit 1: | | | | | | 0=No wait | | | | | | 1=Wait | | | | | Output buffer | Bit3: | | | | | logical or | 0=Logical | | | | | physical address | 1=Physical | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh | TYPEPOST | Indicates how RICCS| 0=Post | APP | | | | should post an | 1=Post if last write | | | | | application task | 2=No post | | | | | upon completing a | | | | | | RCS_S_WRITE command| | | +------+----------------+--------------------+---------------------------+-----+ | 10h- | LENGTH | Number of | Equals bytes | APP | | 11h | | characters to write| | | +------+----------------+--------------------+---------------------------+-----+ | 12h | POSTTASKNUM | Task number to be | Task is not required to | APP | | | | posted when a | have the port open | | | | | no-wait write | 1=Post task issuing the | | | | | completes. | write. | | | | | | >0=Task number of task | | | | | | to post. | | +------+----------------+--------------------+---------------------------+-----+ | 13h | RESERVED1 | Reserved for | Must be 0 | APP | | | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 14h- | IDLEOVERRIDE | Override idle | Equals 10 millisecond | APP | | 15h | | Detect timeout | units | | | | | value (1 time) | -1=Infinite timeout | | | | | | 0=No override | | | | | | >0=Override value | | +------+----------------+--------------------+---------------------------+-----+ | 16h- | RESERVED2 | Reserved | Used by RICCS | RCS | | 2Bh | | | | | +------+----------------+--------------------+---------------------------+-----+ | 2Ch- | RESERVED3 | Reserved for | Must be 0 | APP | | 2Fh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
WRITEBUFFER is the address of the applications output buffer.
TYPEWRITE indicates if the write is to be handled normally or immediately, whether or not to wait for the write to complete, and if the applications output buffer is a logical or physical address.
+=====+=======+====================================+ | Bit | Value | Meaning | +=====+=======+====================================+ | | 0 | Normal | | 0 +-------+------------------------------------+ | | 1 | Immediate | +-----+-------+------------------------------------+ | | 0 | No wait | | 1 +-------+------------------------------------+ | | 1 | Wait | +-----+-------+------------------------------------+ | 2 | 0 | Reserved | +-----+-------+------------------------------------+ | | 0 | Output buffer is logical address | | 3 +-------+------------------------------------+ | | 1 | Output buffer is physical address | +-----+-------+------------------------------------+Note:
Bit 3 applies only if DMAPIC DMA is used for writes. This bit is not recognized in the synchronous Zilog** driver.
TYPEPOST indicates how RICCS should post an application task upon completing a RCS_S_WRITE command. This parameter is only applicable for no-wait writes, since the application is resumed upon completion of a wait write.
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Post | +------------+------------------------+ | 1 | Post if last write | +------------+------------------------+ | 2 | No Post | +------------+------------------------+LENGTH is the actual number of characters to write.
POSTTASKNUM is the task number posted when a no-wait write completes. This number does not have to be the number of the task issuing the RCS_S_WRITE command. The task specified by this parameter is not required to have the port open.
+=========+===============+ | Value | Meaning | +=========+===============+ | 0 | Task issuing | | | the write | | | should be | | | posted. | | | (Default) | +---------+---------------+ | >0 | Task number | | | of the task | | | to post when | | | a no-wait | | | write | | | completes. | +---------+---------------+IDLEOVERRIDE is the timeout value used, one time, for the Idle Detect Timeout, and is expressed in 10-millisecond units. This parameter is used when the normal Idle Detect Timeout value is relatively large, except when expecting a response to a transmission (RCS_S_WRITE). In this case, using the IDLEOVERRIDE allows one RCS_S_WRITE command to replace the following sequence of commands:
RESERVED3 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command. The return code is not loaded until the writes complete (WRITESTATUS bit 0 is set).
WRITESTATUS is a collection of status bits pertaining to the RCS_S_WRITE command. These bits are not available and should not be checked until the write completes (bit 0 is set). WRITESTATUS has the following format:
+====+=====+=================================================================+ | Bit|Value| Meaning | +====+=====+=================================================================+ | | 0 | RCS_S_WRITE command not completed yet | | 0 +-----+-----------------------------------------------------------------+ | | 1 | RCS_S_WRITE command completed | +----+-----+-----------------------------------------------------------------+ | | 0 | No control signal state change since last RCS_S_SETCTRLSIGNAL, | | | | RLSIGNAL, RCS_S_RETCTRLSIGNAL, or RCS_S_WRITE | | 1 +-----+-----------------------------------------------------------------+ | | 1 | Control signal state change since last RCS_S_SETCTRLSIGNAL, | | | | RCS_S_RETCTRLSIGNAL, or RCS_S_WRITE | | | | Note: State changes occurring after an RCS_S_OPEN or | | | | RCS_S_RESET, but before an initial RCS_S_SETCTRLSIGNAL, | | | | RCS_S_RETCTRLSIGNAL, or RCS_S_WRITE command are not | | | | reported. | +----+-----+-----------------------------------------------------------------+ | 2 | 0 | Transmissions started | | +-----+-----------------------------------------------------------------+ | | 1 | Transmissions stopped | +----+-----+-----------------------------------------------------------------+ | 3 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | | 0 | No transmission underrun occurred | | 4 +-----+-----------------------------------------------------------------+ | | 1 | Transmission underrun occurred, frame was retransmitted | +----+-----+-----------------------------------------------------------------+ | 5 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 6 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 7 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | | 0 | No stop transmission timeout | | 8 +-----+-----------------------------------------------------------------+ | | 1 | Stop transmission timeout | +----+-----+-----------------------------------------------------------------+ | 9 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 10 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 11 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 12 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | 13 | 0 | Reserved (will be 0) | +----+-----+-----------------------------------------------------------------+ | | 0 | RCS_S_WRITE was not terminated by another command | | 14 +-----+-----------------------------------------------------------------+ | | 1 | RCS_S_WRITE was terminated by an Immediate RCS_S_WRITE, | | | | RCS_S_CANCELWRITES, RCS_S_RESET, or other command. | +----+-----+-----------------------------------------------------------------+ | | 0 | No other transmitter error detected | | 15 +-----+-----------------------------------------------------------------+ | | 1 | Other transmitter error detected | +----+-----+-----------------------------------------------------------------+WRITECOUNT indicates the actual number of characters written. This count is not loaded until the write completes (WRITESTATUS bit 0 is set).
RETURN CODE
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1400h | Write error | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_STOPTRANS command is used to inform the RICCS driver that no further transmissions are allowed until an RCS_STARTTRANS command is issued. If the application task detects conditions that indicate transmission should be stopped, this command informs the RICCS driver of the condition and causes any writes in progress to be suspended (not terminated). If a write is in progress, RICCS sends an abort sequence to the attached device. RICCS re-starts transmissions upon receiving a RCS_S_STARTTRANS command.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_STOPTRANS control block PUSH Offset of RCS_S_STOPTRANS control block CALL _rcs_s_stoptrans ADD SP,4
Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE STOP TRANSMISSION CONTROL BLOCK (STPCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
STPCB RCSS_S_STOPTRANS <>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE STPCB. CALL
; THE RCS_S_STOPTRANS SUBROUTINE TO STOP TRANSMISSIONS UNTIL
; A CALL TO RCS_S_STARTTRANS.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV STPCB.STPCB_S_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN STPCB
LEA DI,STPCB ;LOAD OFFSET OF STPCB
PUSH CS ;SEGMENT OF STPCB
PUSH DI ;OFFSET OF STPCB
CALL _rcs_s_stoptrans ;CALL LEVEL A SUB TO DO
;STOP TRANSMISSION COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP STPCB.STPCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
C CALL FORMAT
struct rcss_s_stoptrans stpcb; rcs_s_stoptrans (&stpcb);STPCB is the RCS_S_STOPTRANS Control Block
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Stop Transmission control block (stpcb) */
/* and initialize parameters. */
struct rcss_s_stoptrans stpcb;
/* Initialize the device handle parameter in the stpcb. */
/* Call the RCS_S_STOPTRANS subroutine to stop */
/* transmissions until a call to RCS_S_STARTTRANS. */
stpcb.stpcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_stoptrans (&stpcb);
if (stpcb.stpcb_s_retcode == 0)
.
.
RCS_S_STOPTRANS Control Block (STPCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Dh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | RESERVED | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_STARTTRANS command informs RICCS that conditions causing transmission to be stopped no longer exist. The RICCS allows transmissions, resuming any pending writes.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_STARTTRANS control block PUSH Offset of RCS_S_STARTTRANS control block CALL _rcs_s_starttrans ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE START TRANSMISSION CONTROL BLOCK (STCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
STCB RCSS_S_STARTTRANS <>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE STCB. CALL
; THE RCS_S_STARTTRANS SUBROUTINE TO START TRANSMISSIONS AFTER
; A CALL TO RCS_S_STOPTRANS.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV STCB.STCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN STCB
LEA DI,STCB ;LOAD OFFSET OF STCB
PUSH CS ;SEGMENT OF STCB
PUSH DI ;OFFSET OF STCB
CALL _rcs_s_starttrans ;CALL LEVEL A SUB TO DO
;START TRANSMISSION COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP STCB.STCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_starttrans stcb; rcs_s_starttrans (&stcb);STCB is the RCS_S_STARTTRANS Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Start Transmission control block (stcb) */
/* and initialize parameters. */
struct rcss_s_starttrans stcb;
/* Initialize the device handle parameter in the stcb. */
/* Call the RCS_S_STARTTRANS subroutine to restart */
/* transmissions after a call to RCS_S_STOPTRANS. */
stcb.stcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_starttrans (&stcb);
if (stcb.stcb_s_retcode == 0)
.
.
RCS_S_STARTTRANS Control Block (STCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Eh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | RESERVED | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1A00h | Control signal not | | | present | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
This command controls the state of three RS-232-C output control signals and the use of three RS-232-C input control signals. Request To Send (RTS) and Data Terminal Ready (DTR) are output signals for all ports on all co-processor adapters. Rate Select (RS) is an output signal in the following configurations:
The application task may specify the following input control signals to the RCS_S_SETCTRLSIGNAL command at any time to turn these signals on or off:
Note:
The IBM X.25 Interface Co-Processor/2, the IBM Realtime Interface Co-Processor Portmaster Adapter/A, and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters require the RTS control signal to be on before transmissions can occur. If the RTS signal is turned off, transmissions are stopped until the signal is turned back on. It is the application programmer's responsibility to ensure that this signal is on; however, the signal is on by default. (The RCS_S_SETCTRLSIGNAL command can be used to turn the RTS signal on.)
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_SETCTRLSIGNAL control block PUSH Offset of RCS_S_SETCTRLSIGNAL control block CALL _rcs_s_setctrlsignal ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE SET CONTROL SIGNAL CONTROL BLOCK (SSCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
SSCB RCSS_S_SETCTRLSIGNAL <,,,,3BH,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE SSCB. CALL
; THE RCS_S_SETCTRLSIGNAL SUBROUTINE TO TURN RTS AND DTR ON, AND
; TO REQUIRE CTS, DSR AND DCD FOR TRANSMISSIONS.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV SSCB.SSCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN SSCB
LEA DI,SSCB ;LOAD OFFSET OF SSCB
PUSH CS ;SEGMENT OF SSCB
PUSH DI ;OFFSET OF SSCB
CALL _rcs_s_setctrlsignal ;CALL LEVEL A SUB TO DO
;SET CONTROL SIGNAL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP SSCB.SSCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_setctrlsignal sscb; rcs_s_setctrlsignal (&sscb);SSCB is the RCS_S_SETCTRLSIGNAL Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Set Control Signal control block (sscb) */
/* and initialize parameters. */
struct rcss_s_setctrlsignal sscb = {0, 0, 0, 0, 0x3B, 0},
/* Initialize the device handle parameter in the sscb. */
/* Call the RCS_S_SETCTRLSIGNAL subroutine to turn RTS */
/* and DTR on, and to require CTS, DSR and DCD for */
/* transmissions. */
sscb.sscb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_setctrlsignal (&sscb);
if (sscb.sscb_s_retcode == 0)
.
.
RCS_S_SETCTRLSIGNAL Control Block (sscb)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 0Fh | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | CTRLSIGNAL | I/O control signals| 0=Signal off | APP | | | | for the RS_232_C | 1=Signal on | | | | | interface | Bit0 : RTS | | | | | | Bit1 : DTR | | | | | | Bit2 : Reserved | | | | | | Bit3 : DCD | | | | | | Bit4 : DSR | | | | | | Bit5 : CTS | | | | | | Bit6 : RS (output) | | | | | | Bit7 : Reserved | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ENTRY PARAMETERS
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
CTRLSIGNAL indicates the state of the output control signals and indicates which signals are required for transmission. CTRLSIGNAL is used only for the RS-232-C and V.35 electrical interfaces.
The output signals RTS, DTR, and RS are controlled by the application task setting the appropriate bits to 1 to turn the signal on, and 0 to turn it off. By default RTS and DTR are on and RS is off.
The application task informs the RICCS driver which of the input signals DCD, DSR and CTS must be on before data can be transmitted. Setting the appropriate bits to one indicates that a signal is required for transmission, setting them to 0 indicates that a signal is not required. The defaults for CTS, DSR, and DCD are off.
Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Reserved | | | | +--------------- Data Carrier Detect (DCD) | | | +------------------ Data Set Ready (DSR) | | +--------------------- Clear To Send (CTS) | +------------------------ Rate Select (RS) output +--------------------------- ReservedRESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0004h | Successful and not | | | RS-232-C port or V.35 | +------------+------------------------+ | 0008h | Successful and not | | | port 0 or 1 | +------------+------------------------+ | 000Ch | Successful and not | | | RS-232-C or V.35 or | | | port 0 or 1 | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_RETCTRLSIGNAL command allows the application task to obtain the state of seven RS-232-C control signals. This command may be issued at any time and allows tasks to use the RS-232-C control signals by using this command with the RCS_S_SETCTRLSIGNAL command.
Note:
The Rate Select (RS) is an output signal on the Realtime Interface Co-Processor, IBM Realtime Interface Co-Processor Multiport, IBM Realtime Interface Co-Processor Multiport/2, and the IBM X.25 Interface Co-Processor/2 adapters. RS is an input on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 adapters.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_RETCTRLSIGNAL control block PUSH Offset of RCS_S_RETCTRLSIGNAL control block CALL _rcs_s_retctrlsignal ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE RETURN CONTROL SIGNAL CONTROL BLOCK (RSCB)
; AND INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
RSCB RCSS_S_RETCTRLSIGNAL <>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE RSCB. CALL
; THE RCS_S_RETCTRLSIGNAL SUBROUTINE TO RETURN THE CURRENT
; STATE OF THE RS-232-C CONTROL SIGNALS.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV RSCB.RSCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN RSCB
LEA DI,RSCB ;LOAD OFFSET OF RSCB
PUSH CS ;SEGMENT OF RSCB
PUSH DI ;OFFSET OF RSCB
CALL _rcs_s_retctrlsignal ;CALL LEVEL A SUB TO DO
;RETURN CONTROL SIGNAL
;COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP RSCB.RSCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_retctrlsignal rscb; rcs_s_retctrlsignal (&rscb);RSCB is the RCS_S_RETCTRLSIGNAL Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Return Control Signal control block */
/* (rscb) and initialize parameters. */
struct rcss_s_retctrlsignal rscb;
/* Initialize the device handle parameter in the rscb. */
/* Call the RCS_S_RETCTRLSIGNAL subroutine to return the */
/* current state of the RS-232-C control signals. */
rscb.rscb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_retctrlsignal (&rscb);
if (rscb.rscb_s_retcode == 0)
.
.
RCS_S_RETCTRLSIGNAL Control Block (RSCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 10h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | CTRLSIGNAL | I/O control signals| 0=Signal off | APP | | | | for the RS_232_C | 1=Signal on | | | | | interface | Bit0 : RTS | | | | | | Bit1 : DTR | | | | | | Bit2 : RI | | | | | | Bit3 : DCD | | | | | | Bit4 : DSR | | | | | | Bit5 : CTS | | | | | | Bit6 : RS (output) | | | | | | Bit7 : RS (input) | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ENTRY PARAMETERS
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
CTRLSIGNAL indicates the state of the RS-232-C electrical interface I/O control signals.
Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Request To Send (RTS) | | | | | | +--------- Data Terminal Ready (DTR) | | | | | +------------ Ring Indicator (RI) | | | | +--------------- Data Carrier Detect (DCD) | | | +------------------ Data Set Ready (DSR) | | +--------------------- Clear To Send (CTS) | +------------------------ Rate Select (RS) output +--------------------------- Rate Select (RS) inputRETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0004h | Successful and not | | | RS-232-C or V.35 port | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_DMAREADCTRL command allows application tasks to turn DMA on and off for reads. If this command is not issued, DMA for reads will, by default, be off unless the DMAREAD parameter of the RCS_S_OPEN command was set to yes.
When turning DMA on for reads, the following aspects of RICCS operation should be noted:
The following aspects of RICCS operation should be noted when turning off DMA for reads:
Note:
This command should only be used for the synchronous Zilog** driver.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_DMAREADCTRL control block PUSH Offset of RCS_S_DMAREADCTRL control block CALL _rcs_s_dmareadctrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE DMA READ CONTROL CONTROL BLOCK (DRCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DRCB RCSS_S_DMAREADCTRL <,,,,1,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE DRCB. CALL
; THE RCS_S_DMAREADCTRL SUBROUTINE TO TURN ON DMA FOR READS.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV DRCB.DRCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN DRCB
LEA DI,DRCB ;LOAD OFFSET OF DRCB
PUSH CS ;SEGMENT OF DRCB
PUSH DI ;OFFSET OF DRCB
CALL _rcs_s_dmareadctrl ;CALL LEVEL A SUB TO DO
;DMA READ CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DRCB.DRCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_dmareadctrl drcb; rcs_s_dmareadctrl (&drcb);DRCB is the RCS_S_DMAREADCTRL Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the DMA Read Control control block (drcb) */
/* and initialize parameters. */
struct rcss_dmareadctrl drcb = {0, 0, 0, 0, 1, 0};
/* Initialize the device handle parameter in the drcb. */
/* Call the RCS_S_DMAREADCTRL subroutine to turn on DMA */
/* for reads. */
drcb.drcb_devhandle = ocb.ocb_devhandle;
rcs_s_dmareadctrl (&drcb);
if (drcb.drcb_s_retcode == 0)
.
.
RCS_S_DMAREADCTRL Control Block (DRCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 11h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | DMAREAD | Support DMA on a | Bit 0: | APP | | | | RCS_S_READ | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
DMAREAD indicates whether or not to support DMA on a RCS_S_READ command.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | No | | 0 +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0002h | Successful and No DMA | | | read | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_DMAWRITECTRL command allows application tasks to turn DMA on and off for writes. If this command is not issued, DMA for writes will, by default, be off unless the DMAWRITE parameter of the RCS_S_OPEN command was set to yes.
When turning DMA on for writes, the following aspects of RICCS operation should be noted:
The following aspects of RICCS operation should be noted when turning DMA off for writes:
Note:
This command should only be used for the synchronous Zilog** driver.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_DMAWRITECTRL control block PUSH Offset of RCS_S_DMAWRITECTRL control block CALL _rcs_s_dmawritectrl ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE DMA WRITE CONTROL CONTROL BLOCK (DWCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DWCB RCSS_S_DMAWRITECTRL <,,,,1,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE DWCB. CALL
; THE RCS_S_DMAWRITECTRL SUBROUTINE TO TURN ON DMA FOR WRITES.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV DWCB.DWCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN DWCB
LEA DI,DWCB ;LOAD OFFSET OF DWCB
PUSH CS ;SEGMENT OF DWCB
PUSH DI ;OFFSET OF DWCB
CALL _rcs_s_dmawritectrl ;CALL LEVEL A SUB TO DO
;DMA WRITE CONTROL COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DWCB.DWCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_dmawritectrl dwcb; rcs_s_dmawritectrl (&dwcb);DWCB is the RCS_S_DMAWRITECTRL Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the DMA Write Control control block (dwcb) */
/* and initialize parameters. */
struct rcss_s_dmawritectrl dwcb = {0, 0, 0, 0, 1, 0};
/* Initialize the device handle parameter in the dwcb. */
/* Call the RCS_S_DMAWRITECTRL subroutine to turn on DMA */
/* for writes. */
dwcb.dwcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_dmawritectrl (&dwcb);
if (dwcb.dwcb_s_retcode == 0)
.
.
RCS_S_DMAWRITECTRL Control Block (DWCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 12h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | DMAWRITE | Support DMA on a | Bit 0: | APP | | | | RCS_S_WRITE | 0=No | | | | | | 1=Yes | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
DMAWRITE indicates whether to support DMA on a RCS_S_WRITE command.
+=====+=======+====================+ | Bit | Value | Meaning | +=====+=======+====================+ | | 0 | No | | 0 +-------+--------------------+ | | 1 | Yes | +-----+-------+--------------------+RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the call command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0001h | Successful and no DMA | | | write | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_CANCELREADS command cancels RCS_S_READ commands that have been issued, but not completed. The command allows the flexibility of cancel conditions. The application task may specify whether to cancel the in-progress, queued, or all reads. The application may also select whether RCS_S_READ commands from all tasks should be canceled, or only the ones from a specific task.
When RCS_S_READ commands are canceled, the:
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_CANCELREADS control block PUSH Offset of RCS_S_CANCELREADS control block CALL _rcs_s_cancelreads ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CANCEL READS CONTROL BLOCK (CRCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
CRCB RCSS_S_CANCELREADS <,,,,3,4,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE CRCB. CALL
; THE RCS_S_CANCELREADS SUBROUTINE TO CANCEL IN-PROGRESS AND
; QUEUED READS FOR TASK 4.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CRCB.CRCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN CRCB
LEA DI,CRCB ;LOAD OFFSET OF CRCB
PUSH CS ;SEGMENT OF CRCB
PUSH DI ;OFFSET OF CRCB
CALL _rcs_s_cancelreads ;CALL LEVEL A SUB TO DO
;CANCEL READS COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CRCB.CRCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_cancelreads crcb; rcs_s_cancelreads (&crcb);CRCB is the RCS_S_CANCELREADS Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Cancel Reads control block (crcb) and */
/* initialize parameters. */
struct rcss_s_cancelreads crcb = {0, 0, 0, 0, 3, 4, 0};
/* Initialize the device handle parameter in the crcb. */
/* Call the RCS_S_CANCELREADS subroutine to cancel */
/* in-progress and queued reads for task 4. */
crcb.crcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_cancelreads (&crcb);
if (crcb.crcb_s_retcode == 0)
.
.
RCS_S_CANCELREADS Control Block (CRCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 15h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | TYPECOND | Type of RCS_S_READ | 1=In progress | APP | | | | command(s) to be | 2=Queued | | | | | canceled | 3=Both (all) | | +------+----------------+--------------------+---------------------------+-----+ | 07h | TASKCOND | Task number of | Task number to match | APP | | | | RCS_S_READ command | (FFh=All tasks) | | | | | to be canceled | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | RESERVED | Reserved for | Must be 0 | APP | | 0Bh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
TYPECOND specifies the type of RCS_S_READ command to be canceled. The application may select that only the in-progress read be canceled, only reads that are queued (but not in-progress) be canceled, or all types of reads be canceled. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Cancel in-progress | | | read | +------------+------------------------+ | 2 | Cancel queued read(s) | +------------+------------------------+ | 3 | Cancel in-progress and | | | queued read(s) | +------------+------------------------+TASKCOND specifies the task number that must match for RCS_S_READ command(s) to be canceled. The application may select that only reads issued by a specific task be canceled, by placing that task's number in this parameter. The application may specify that reads issued by all tasks be canceled, by placing an FFh in this parameter.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_CANCELWRITES command cancels RCS_S_WRITE commands that have been issued, but not yet completed. The command allows the flexibility of various cancel conditions. The application task may specify whether to cancel the in-progress, queued, or all writes. The application has the option of canceling a specific RCS_S_WRITE command, given the RCS_S_WRITE control block address. The application may also select whether RCS_S_WRITE commands from all tasks should be canceled, or only the ones from a specific task.
When RCS_S_WRITE commands are canceled, the:
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_CANCELWRITES control block PUSH Offset of RCS_S_CANCELWRITES control block CALL _rcs_s_cancelwrites ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE CANCEL WRITES CONTROL BLOCK (CWCB) AND
; INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
CWCB RCSS_S_CANCELWRITES <,,,,3,4,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE CWCB. CALL
; THE RCS_S_CANCELWRITES SUBROUTINE TO CANCEL IN-PROGRESS AND
; QUEUED WRITES FOR TASK 4.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV CWCB.CWCB_S_DEVHANDLE,AX;STORE DEVICE HANDLE
;IN CWCB
LEA DI,CWCB ;LOAD OFFSET OF CWCB
PUSH CS ;SEGMENT OF CWCB
PUSH DI ;OFFSET OF CWCB
CALL _rcs_s_cancelwrites ;CALL LEVEL A SUB TO DO
;CANCEL WRITES COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP CWCB.CWCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_cancelwrites cwcb; rcs_s_cancelwrites (&cwcb);CWCB is the RCS_S_CANCELWRITES Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Cancel Writes control block (cwcb) and */
/* initialize parameters. */
struct rcss_s_cancelwrites cwcb = {0, 0, 0, 0, 3, 4, 0};
/* Initialize the device handle parameter in the cwcb. */
/* Call the RCS_S_CANCELWRITES subroutine to cancel */
/* in-progress and queued writes for task 4. */
cwcb.cwcb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_cancelwrites (&cwcb);
if (cwcb.cwcb_s_retcode == 0)
.
.
RCS_S_CANCELWRITES Control Block (CWCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 16h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | TYPECOND | Type of RCS_S_WRITE| 1=In progress | APP | | | | command(s) to be | 2=Queued | | | | | canceled | 3=Both (in progress and | | | | | | queued) | | | | | | 4=Specific | | +------+----------------+--------------------+---------------------------+-----+ | 07h | TASKCOND | Task number of | Task number to match | APP | | | | RCS_S_WRITE command| (FFh=All tasks) | | | | | to be canceled | | | +------+----------------+--------------------+---------------------------+-----+ | 08h- | WCBADDR | Address of specific| Segment:offset | APP | | 0Bh | | RCS_S_WRITE control| | | | | | block to cancel | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ch- | RESERVED | Reserved for | Must be 0 | APP | | 0Fh | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
TYPECOND specifies the type of RCS_S_WRITE command(s) canceled. The application may select that only the in-progress write be canceled, only writes that are queued (but not in-progress) be canceled, both types of writes be canceled, or a specific RCS_S_WRITE command be canceled. The following values are valid:
+============+========================+ | Value | Meaning | +============+========================+ | 1 | Cancel in-progress | | | write | +------------+------------------------+ | 2 | Cancel queued write(s) | +------------+------------------------+ | 3 | Cancel in-progress and | | | queued write(s) | +------------+------------------------+ | 4 | Cancel specific write | +------------+------------------------+TASKCOND specifies the task number that must match for RCS_S_WRITE command(s) to be canceled. This parameter further qualifies the TYPECOND parameter. The application may select that only writes issued by a specific task be canceled by placing that task's number in this parameter. By placing an FFh in this parameter, the application cancels all writes issued by tasks.
WCBADDR is the address of the RCS_S_WRITE Control Block (WCB) for the specific write to be canceled. This RCS_S_WRITE command is not canceled if it is in progress.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_NOTIFY command notifies the application task as specific events occur. This command defines to RICCS an event mask, an event table, and a task number to be posted when events occur. The event mask specifies the combination of events for which notification should be made. The event table is used to inform the application task which event occurred. This command may be issued at any time to change these parameters; however, RICCS allows only one set of parameters per port to be current.
The application task must define an event table, one per port, to be used by the RICCS driver. This event table actually resides within the application task and its size must be 34 words. The event table must be in the following format:
+=======+===================+============+ | Word | Type | Meaning | +=======+===================+============+ | 0 | Unsigned integer | Event(s) | | | | occurred | | | | (Event | | | | 0-15) | +-------+-------------------+------------+ | 1 | Unsigned integer | Events | | | | occurred | | | | (Events | | | | 16-31) | +-------+-------------------+------------+ | 2 | Unsigned or | Event 0 | | | signed integer | counter | +-------+-------------------+------------+ | : | | : | +-------+-------------------+------------+ | 33 | Unsigned or | Event 31 | | | signed integer | counter | +-------+-------------------+------------+The first two words of the event table (one bit per event) are event flags used by RICCS for notification control. When an event occurs, the appropriate bit is set to 1. The application task is responsible for clearing these bits. The next 32 words of the event table (one word per event) map directly to the event assignments specified in the EVENTS parameter. These words are used as counters for each event.
When an event occurs RICCS does the following:
After the task is posted it can do the following:
The application should disable interrupts when it modifies the event flags and counters, because the synchronous driver may modify them during hardware interrupts.
Note:
This command is intended to provide notification services to applications which have special needs for this type of service. When a notifiable event occurs, a post is performed. The user should be aware that this may decrease RICCS performance.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_NOTIFY control block PUSH Offset of RCS_S_NOTIFY control block CALL _rcs_s_notify ADD SP,4
Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; DEFINE AN EVENT NOTIFICATION TABLE
EVTAB DW 34 DUP (0)
; ALLOCATE THE EVENT TABLE AND NOTIFY CONTROL BLOCK (NCB)
; AND INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
NCB RCSS_S_NOTIFY <,,,,0FFCCh,EVTAB,2,0,0>
; INITIALIZE THE DEVICE HANDLE PARAMETER IN THE NCB. CALL
; THE RCS_S_NOTIFY SUBROUTINE TO HAVE TASK 2 NOTIFIED
; OF ALL EVENTS.
MOV AX,OCB.OCB_S_DEVHANDLE ;GET DEVICE HANDLE
;FROM OCB
MOV NCB.NCB_S_DEVHANDLE,AX ;STORE DEVICE HANDLE
;IN NCB
;SAVE SEGMENT OF EVTAB
MOV WORD PTR NCB.NCB_S_EVTAB+2,CS
LEA DI,NCB ;LOAD OFFSET OF NCB
PUSH CS ;SEGMENT OF NCB
PUSH DI ;OFFSET OF NCB
CALL _rcs_s_notify ;CALL LEVEL A SUB TO DO
;NOTIFY COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP NCB.NCB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_notify ncb; rcs_s_notify (&ncb);NCB is the RCS_S_NOTIFY Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Event Table and Notify control block */
/* (ncb) and initialize parameters. */
unsigned int evtab[34&rbracket.;
struct rcss_s_notify ncb = {0, 0, 0, 0, 0xFFCCL, evtab, 2};
/* Initialize the device handle parameter in the ncb. */
/* Call the RCS_S_NOTIFY subroutine to have task 2 */
/* notified of all events. */
ncb.ncb_s_devhandle = ocb.ocb_s_devhandle;
rcs_s_notify (&ncb);
if (ncb.ncb_s_retcode == 0)
.
.
RCS_S_NOTIFY Control Block (NCB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 18h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | DEVHANDLE | Device Handle | | RCS | | 03h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h- | EVENTS | Events descriptor | See the EVENTS description| APP | | 09h | | | in the RCS_S_NOTIFY | | | | | | command | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah- | EVTAB | Address of Event | Segment:offset | APP | | 0Dh | | Table | The Event Table must be | | | | | | 34 words. | | | | | | 0=Not present | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh | NOTIFYTASK | Task number of | Task is not required to | APP | | | | task to be posted | have the port open | | | | | | 0=Not present | | +------+----------------+--------------------+---------------------------+-----+ | 0Fh- | RESERVED | Reserved for | Must be 0 | APP | | 13h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
DEVHANDLE is the device handle obtained from the RCS_S_OPEN command. This is the handle used when referring to the open port.
EVENTS is a set of bits indicating which events cause notification to the application task. Setting a bit to 1 indicates that the corresponding event causes notification to the application task. Setting a bit to 0 indicates that the corresponding event does not cause notification to the application task. The bit assignments for this parameter are:
+=======+====================================================================+ | Bit | Meaning | +=======+====================================================================+ | 0 | Reserved | +-------+--------------------------------------------------------------------+ | 1 | Reserved | +-------+--------------------------------------------------------------------+ | 2 | RICCS Shutdown | +-------+--------------------------------------------------------------------+ | 3 | Hardware Overrun Error | +-------+--------------------------------------------------------------------+ | 4 | Reserved | +-------+--------------------------------------------------------------------+ | 5 | Reserved | +-------+--------------------------------------------------------------------+ | 6 | CTS Signal Asserted (on) | +-------+--------------------------------------------------------------------+ | 7 | CTS Signal Negated (off) | +-------+--------------------------------------------------------------------+ | 8 | DCD Signal Asserted (on) | +-------+--------------------------------------------------------------------+ | 9 | DCD Signal Negated (off) | +-------+--------------------------------------------------------------------+ | 10 | DSR Signal Asserted (on) | +-------+--------------------------------------------------------------------+ | 11 | DSR Signal Negated (off) | +-------+--------------------------------------------------------------------+ | 12 | RS Signal Asserted (on) | +-------+--------------------------------------------------------------------+ | 13 | RS Signal Negated (off) | | | Note: Bits 12 and 13 only apply if Half Rate Select is an input | | | signal. | +-------+--------------------------------------------------------------------+ | 14 | RI Signal Asserted (on) | +-------+--------------------------------------------------------------------+ | 15 | RI Signal Negated (off) | +-------+--------------------------------------------------------------------+ | 16-31 | Reserved | +-------+--------------------------------------------------------------------+EVTAB is the address of the 34 word event table. A value of 0 may be present in this parameter if this command is issued to change events.
NOTIFYTASK is the task number posted when one of the specified events occur. This does not have to be the task that is issuing the RCS_S_NOTIFY command. The task specified in this parameter is not required to have the port open. A value of 0 may be present in this parameter if this command is issued to change events.
RESERVED reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+
The RCS_S_DEFEI command allows application tasks to define to RICCS the features of a new electrical interface board unknown to RICCS and which cannot be automatically configured by RICCS. Defining the electrical interface board allows RICCS to maintain compatibility and provide support to the new electrical interface board. This command is issued upon RICCS startup to define the features for the internal RICCS variables. The new electrical interface board is not recognized until this command is performed. The RCS_S_DEFEI command must be done prior to the RCS_S_OPEN command.
When using the Selectable Interface Board/A on the IBM Realtime Interface Co-Processor Portmaster Adapter/A and the IBM Realtime Interface Co-Processor Multiport Adapter, Model 2, this command must be issued to configure ports 0 through 2, unless the ports are using the RS-232-C physical interface.
Note:
This support applies only to IBM electrical interface boards or boards compatible with IBM electrical interface boards.
ASSEMBLER INTERFACE
PUSH Segment of RCS_S_DEFEI control block PUSH Offset of RCS_S_DEFEI control block CALL _rcs_s_defei ADD SP,4Example Call
COM FILE IMPLEMENTATION
INCLUDE RICCSS.ASM
; ASSUME THE PORT HAS BEEN OPENED AND THE DEVICE HANDLE
; HAS BEEN RETURNED IN THE OPEN CONTROL BLOCK (OCB).
; ALLOCATE THE DEFINE ELECTRICAL INTERFACE CONTROL BLOCK
; (DEICB) INITIALIZE PARAMETERS SET BY THE APPLICATION TASK.
DEICB RCSS_S_DEFEI <,,,,0Fh,,,0Fh,,,1111h,,,,55h,,,,
3333h,,,,3333h,,,,55h>
; CALL THE RCS_S_DEFEI SUBROUTINE TO DEFINE FOUR
; SYNCHRONOUS-CAPABLE RS-422 PORTS WITH SIGNETICS** HARDWARE AND DMA.
LEA DI,DEICB ;LOAD OFFSET OF DEICB
PUSH CS ;SEGMENT OF DEICB
PUSH DI ;OFFSET OF DEICB
CALL _rcs_s_defei ;CALL LEVEL A SUB TO DO
;DEFINE ELECTRICAL
;INTERFACE COMMAND
ADD SP,4 ;ADJUST STACK POINTER
CMP DEICB.DEICB_S_RETCODE,0 ;CHECK FOR ERROR
JNE ERR_RTN ;JUMP IF ERROR
.
.
C CALL FORMAT
struct rcss_s_defei deicb; rcs_s_defei (&deicb);DEICB is the RCS_S_DEFEI Control Block.
Example Call
/* Assume the port has been opened and the device handle */
/* has been returned in the Open control block (ocb). */
#include "riccss.h"
/* Allocate the Define Electrical Interface control */
/* block (deicb) and initialize parameters. */
struct rcss_s_defei deicb = {0, 0, 0, 0, 0x0F, 0, 0x0F,
0, 0x1111, 0, 0x55, 0,
0x3333L, 0, 0x3333L, 0,
0x55, 0};
/* Call the RCS_S_DEFEI subroutine to define four */
/* synchronous-capable RS-422 ports with Signetics** */
/* hardware and DMA. */
rcs_s_defei (&deicb);
if (deicb.deicb_s_retcode == 0)
.
.
RCS_S_DEFEI Control Block (DEICB)
+======+================+====================+===========================+=====+ | Byte | Parameter | Description | Comments | Set | | | | | | By | +======+================+====================+===========================+=====+ | 00h | CMD | Command code | Equals 19h | RCS | | | | | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 01h | TASKNUM | Calling task | | RCS | | | | number | | SUB | +------+----------------+--------------------+---------------------------+-----+ | 02h- | RESERVED1 | Reserved for | Must be 0 | APP | | 03h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 04h- | RETCODE | Return code | See RICCS return codes | RCS | | 05h | | | | | +------+----------------+--------------------+---------------------------+-----+ | 06h | PORTS | Identifies which | 0=Not defining | APP | | | | port(s) the | 1=Defining | | | | | features are | Bit0 : Port0 | | | | | defining | Bit1 : Port1 | | | | | | Bit2 : Port2 | | | | | | Bit3 : Port3 | | | | | | Bit4 : Port4 | | | | | | Bit5 : Port5 | | | | | | Bit6 : Port6 | | | | | | Bit7 : Port7 | | +------+----------------+--------------------+---------------------------+-----+ | 07h- | RESERVED2 | Reserved for | Must be 0 | APP | | 09h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 0Ah | SYNCAPABLE | Indicates whether | 0=Asynchronous only | APP | | | | the port is capable| 1=Synchronous capable | | | | | of synchronous | Bit0 : Port 0 | | | | | operation | Bit1 : Port 1 | | | | | | Bit2 : Port 2 | | | | | | Bit3 : Port 3 | | | | | | Bit4 : Port 4 | | | | | | Bit5 : Port 5 | | | | | | Bit6 : Port 6 | | | | | | Bit7 : Port 7 | | +------+----------------+--------------------+---------------------------+-----+ | 0Bh- | RESERVED3 | Reserved for | Must be 0 | APP | | 0Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 0Eh- | TYPEEI | Standard supported | 0000=RS-232-C | APP | | 11h | | by the port | 0001=RS-422-A | | | | | | 0010=V.35 | | | | | | Four bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 12h- | RESERVED4 | Reserved for | Must be 0 | APP | | 1Dh | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 1Eh- | TYPEHARD | Communication | 00=Zilog** | APP | | 1Fh | | hardware supported | 01=Signetics** | | | | | by the port | Two bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 20h- | RESERVED5 | Reserved for | Must be 0 | APP | | 25h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 26h- | DMARXCAPABLE | Indicates the type | 0000=Not DMA Capable | APP | | 29h | | of receive DMA used| 0001=186 DMA | | | | | for the port | 0010=DMA PIC | | | | | | Four bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 2Ah- | RESERVED6 | Reserved for | Must be 0 | APP | | 35h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 36h- | DMATXCAPABLE | Indicates the type | 0000=Not DMA Capable | APP | | 39h | | of transmit DMA | 0001=186 DMA | | | | | used for this port | 0010=DMA PIC | | | | | | Four bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 3Ah- | RESERVED7 | Reserved for | Must be 0 | APP | | 45h | | future use | | | +------+----------------+--------------------+---------------------------+-----+ | 46h- | HRSELECT | Indicates the | 00=No HRS | APP | | 47h | | direction of the | 01=HRS-Input | | | | | half-rate select | 10=HRS-Output | | | | | signal | 11=HRS-Both | | | | | | Two bits per port | | +------+----------------+--------------------+---------------------------+-----+ | 48h- | RESERVED8 | Reserved for | Must be 0 | APP | | 51h | | future use | | | +------+----------------+--------------------+---------------------------+-----+Entry Parameters
RESERVED1 reserved; value must be 0.
PORTS identifies the port(s) for which the electrical interface features are being defined. Each port corresponds to a bit in this parameter. If the bit is set to one, the electrical interface features specified in this command are defining that port. If the bit is set to zero, the electrical interface features specified in this command are not defining that port. The following are the bit assignments for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Not defining | +------------+------------------------+ | 1 | Defining | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Port 0 | | | | | | +--------- Port 1 | | | | | +------------ Port 2 | | | | +--------------- Port 3 | | | +------------------ Port 4 | | +--------------------- Port 5 | +------------------------ Port 6 +--------------------------- Port 7RESERVED2 reserved; value must be 0.
SYNCAPABLE indicates if the port is capable of synchronous operation. Each port corresponds to a bit in this parameter. If the bit is set to one, the new electrical interface board is capable of handling the synchronous protocol for the particular port(s). If the bit is set to zero, the new electrical interface board is not capable of handling the synchronous protocol for the particular port(s). The following are the bit assignments for this parameter:
+============+========================+ | Value | Meaning | +============+========================+ | 0 | Asynchronous only | +------------+------------------------+ | 1 | Synchronous capable | +------------+------------------------+ Bit assignments: 7 6 5 4 3 2 1 0 | | | | | | | +------ Port 0 | | | | | | +--------- Port 1 | | | | | +------------ Port 2 | | | | +--------------- Port 3 | | | +------------------ Port 4 | | +--------------------- Port 5 | +------------------------ Port 6 +--------------------------- Port 7RESERVED3 reserved; value must be 0.
TYPEEI indicates which standard the new electrical interface board supports. Four bits are assigned for each port and the following values are valid for this parameter.
+============+========================+ | Value | Meaning | +============+========================+ | 0000 | RS-232-C | +------------+------------------------+ | 0001 | RS-422-A | +------------+------------------------+ | 0010 | V.35 | +------------+------------------------+ Bit assignments: 31-28 27-24 23-20 19-16 15-12 11-8 7-4 3-0 | | | | | | | +------ Port 0 | | | | | | +------------ Port 1 | | | | | +------------------ Port 2 | | | | +------------------------ Port 3 | | | +------------------------------ Port 4 | | +------------------------------------- Port 5 | +-------------------------------------------- Port 6 +--------------------------------------------------- Port 7RESERVED4 reserved; value must be 0.
TYPEHARD indicates which communication hardware supports the new electrical interface board. Two bits are assigned for each port and the following values are valid for this parameter.
+============+========================+ | Value | Meaning | +============+========================+ | 00 | Zilog** | +------------+------------------------+ | 01 | Signetics** | +------------+------------------------+ Bit assignments: 15-14 13-12 11-10 9-8 7-6 5-4 3-2 1-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +--------- Port 1 | | | | | +-------------- Port 2 | | | | +------------------- Port 3 | | | +------------------------ Port 4 | | +------------------------------ Port 5 | +------------------------------------- Port 6 +-------------------------------------------- Port 7RESERVED5 reserved; value must be 0.
DMARXCAPABLE indicates the type of receive DMA used for the port.
+============+========================+ | Value | Meaning | +============+========================+ | 0000 | No DMA Capability | +------------+------------------------+ | 0001 | 186 DMA Capability | +------------+------------------------+ | 0010 | DMAPIC Capability | +------------+------------------------+ Bit assignments: 31-28 27-24 23-20 19-16 15-12 11-8 7-4 3-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +---------- Port 1 | | | | | +---------------- Port 2 | | | | +---------------------- Port 3 | | | +---------------------------- Port 4 | | +----------------------------------- Port 5 | +------------------------------------------ Port 6 +------------------------------------------------- Port 7RESERVED6 reserved; value must be 0.
DMATXCAPABLE indicates the type of transmit DMA used for the port. Four bits are assigned for each port and the following values are valid for this parameter.
+============+========================+ | Value | Meaning | +============+========================+ | 0000 | No DMA Capability | +------------+------------------------+ | 0001 | 186 DMA Capability | +------------+------------------------+ | 0010 | DMAPIC Capability | +------------+------------------------+ Bit assignments: 31-28 27-24 23-20 19-16 15-12 11-8 7-4 3-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +--------- Port 1 | | | | | +-------------- Port 2 | | | | +-------------------- Port 3 | | | +-------------------------- Port 4 | | +--------------------------------- Port 5 | +---------------------------------------- Port 6 +----------------------------------------------- Port 7RESERVED7 reserved; value must be 0.
HRSELECT indicates the direction of the half-rate select signal.
+============+========================+ | Value | Meaning | +============+========================+ | 00 | No Half Rate Select | | | Capability | +------------+------------------------+ | 01 | Half Rate Select - | | | Input | +------------+------------------------+ | 10 | Half Rate Select - | | | Output | +------------+------------------------+ | 11 | Half Rate Select - | | | Both | +------------+------------------------+ Bit assignments: 15-14 13-12 11-10 9-8 7-6 5-4 3-2 1-0 | | | | | | | | | | | | | | | +---- Port 0 | | | | | | +--------- Port 1 | | | | | +-------------- Port 2 | | | | +------------------- Port 3 | | | +------------------------ Port 4 | | +------------------------------ Port 5 | +------------------------------------- Port 6 +-------------------------------------------- Port 7RESERVED8 reserved; value must be 0.
Exit Parameters
RETCODE is the return code from the called command.
RETURN CODES
+============+========================+ | Value | Meaning | +============+========================+ | 0000h | Successful | +------------+------------------------+ | 0100h | Invalid handle | +------------+------------------------+ | 0300h | Invalid parameters | +------------+------------------------+ | 0400h | Device already open | +------------+------------------------+ | 1100h | Shutdown in progress | +------------+------------------------+ | 1700h | Internal queue full | +------------+------------------------+ | 1B00h | Stopped or not started | +------------+------------------------+ | 1E00h | Incompatible port type | +------------+------------------------+
This section contains a list of the RICCS return codes. The RICCS returns an indication (in hex format) of the successful or unsuccessful execution of the requested operation in the RETCODE parameter. The application should examine the high-order byte of the RETCODE parameter for the return code.
Some commands execute successfully, but have an information return code returned in the low byte of the RETCODE parameter.
This section provides programming tips for Realtime Interface Co-Processor Synchronous Communications Support.
This section provides the user with the information needed to write a macro assembler application task to interface directly with the RICCS driver. Interfacing directly with the driver requires a user-written Level A subroutine. The following paragraphs describe the common design of all the subroutines and the design for the subroutines after the command has been processed by the driver. The subroutines are common until the command process check. After checking the processing status of the command, the subroutines vary, depending on the type of Level A subroutines.
The application task must initialize the RCS subroutine control block, set the RETCODE parameter to negative one (-1), and clear the resume flag in the DEVHANDLE parameter.
The application task must load the following registers:
After loading the registers, generate the interrupt to interface with the driver and check bit 7 in the AL register for the processed interrupt.
Note:
The following commands must be issued to the generic driver task number, FFh:
- RCS_S_PORTDEFINITION
- RCS_S_OPEN
- RCS_S_SHUTDOWN
- RCS_S_DEFEI
The following list shows the deferred commands in Realtime Interface Co-Processor Synchronous Communications Support:
All deferred commands, except no-wait RCS_S_READ and no-wait RCS_S_WRITE, perform the following operation:
Note:
If the resume flag is set, the command proceeds to step 3; if it is not set, the command does the following:
The following list shows the immediate commands in RICCS:
All immediate commands return immediately to the application task.
The string parameter LOGICALDEVICENAME does not have a byte reserved for the null character; therefore, application tasks written in C Language should use the MEMCPY function to initialize these parameters. For more information on these parameters, refer to the following sections:
The Macro Assembler/2 include file, RICCSS.ASM, contains the Level A data structures and library routine declarations for each synchronous command. The include file provides the variables needed for each command and allows an application written in Macro Assembler to link with the Level A subroutines. The include file is on the RICES Programs diskette.
The RICCS Post Code Values are:
Last modified: March 25, 1999