Realtime Interface Co-Processor
Extended Services
User's Guide

Third Edition (August 1996)


Table of Contents

Special Notices

  • About This Guide
  • Purpose
  • Audience
  • Organization
  • Related Publications
  • Reference Publications
  • Conventions
  • Chapter 1. General Product Description

  • Overview
  • Realtime Interface Co-Processor Programming Services (RICPS)
  • Realtime Interface Co-Processor Communications Support (RICCS)
  • Enhancement Summary for RICCS Version 1.03
  • Hardware and Software Requirements
  • Chapter 2. Getting Started

  • Installation Requirements
  • Product Contents
  • RICES Programs
  • RICES Sample Programs
  • Startup
  • Loading RICPS
  • Loading RICCS
  • Chapter 3. Programming Services (RICPS)

  • RICPS C Call Format
  • RICPS Category Descriptions
  • Interrogating the Presence of RICPS
  • Event Management
  • Wait With Timeout
  • LIFO and Priority Queues
  • Named Resources and Named Tasks
  • Non-Specific Resource Allocation
  • Non-Specific Task Numbers
  • Post Code Management
  • Semaphore Management
  • Task Priority Control
  • Timeslice Management
  • Mailbox
  • System Unit Commands
  • General Invocation
  • General Error Handling
  • Realtime Control Microcode System Unit Commands
  • Request Task Load (01h)
  • Request Task Load With Boundary (03h)
  • Request Task Load Low (0Ch)
  • Get RICPS's Task Number (20h)
  • RICPS System Unit Commands
  • Set Timeslice Interval (02h)
  • ResolveName (03h)
  • Enable System Semaphores (04h)
  • Configure Mailbox Message Pool (06h)
  • RICPS Supervisor Calls
  • Build (39h)
  • Alloc (46h)
  • Return (47h)
  • RICPS Service Interrupts
  • RICPS Presence (00h)
  • EventEnable (01h)
  • EventDisable (02h)
  • EventPost (03h)
  • EventReset (04h)
  • EventWait (05h)
  • WaitTimeout (06h)
  • ChangePriority (07h)
  • PostCodeQEnable (08h)
  • PostCodeQDisable (09h)
  • PostCodeQuery (0Ah)
  • PostCodeGet (0Bh)
  • PostCodeClear (0Ch)
  • ResolveName (0Dh)
  • SemRequest (0Eh)
  • SemRelease (0Fh)
  • SemTest (10h)
  • SemInit (11h)
  • SemClose (12h)
  • MBXRegister (13h)
  • MBXDeregister (14h)
  • MBXOpen (15h)
  • MBXClose (16h)
  • MBXSend (17h)
  • MBXReceive (18h)
  • MBXCount (19h)
  • MBXAdrs (1Ah)
  • MBXName (1Bh)
  • MBXAllocMsg (1Ch)
  • MBXFreeMsg (1Dh)
  • MBXConfigMsgPool (1Eh)
  • RICPS Return Codes
  • System Unit Command Return Codes
  • RICPS Post Code Values
  • Chapter 4. Asynchronous Communications Support

  • Asynchronous Level A Commands
  • Asynchronous RICCS C Language Support
  • Startup Considerations
  • Asynchronous RICCS Driver Task Priority
  • Asynchronous Software Interrupt Vectors
  • Asynchronous Intertask Synchronization
  • Reusing the Asynchronous Command Control Block
  • Asynchronous Port Sharing
  • Asynchronous Physical Device Characteristics
  • Asynchronous Level A Command Descriptions
  • RCS_PORTDEFINITION
  • RCS_OPEN
  • RCS_CLOSE
  • RCS_SETLINECTRL
  • RCS_RETLINECTRL
  • RCS_RESET
  • RCS_SHUTDOWN
  • RCS_READ
  • RCS_GENSTATETABLE
  • RCS_DRIVERINPUTBUFFER
  • RCS_WRITE
  • RCS_SENDBREAK
  • RCS_SETMINBREAK
  • RCS_ECHO
  • RCS_STOPTRANS
  • RCS_STARTTRANS
  • RCS_SETCTRLSIGNAL
  • RCS_RETCTRLSIGNAL
  • RCS_DMAREADCTRL
  • RCS_DMAWRITECTRL
  • RCS_CTRLINFLOW
  • RCS_CTRLOUTFLOW
  • RCS_CANCELREADS
  • RCS_CANCELWRITES
  • RCS_ERRORSUB
  • RCS_NOTIFY
  • RCS_DEFEI
  • Asynchronous Return Codes
  • Asynchronous Information Codes
  • Asynchronous Tips and Techniques
  • Interfacing Directly with the RICCS Driver
  • Asynchronous Assembler Include Files
  • RICCS Post Code Values
  • Chapter 5. Synchronous Communications Support

  • Synchronous Level A Commands
  • Synchronous RICCS C Language Support
  • Synchronous Startup Considerations
  • Synchronous RICCS Driver Task Priority
  • Synchronous Software Interrupt Vectors
  • Synchronous Intertask Synchronization
  • Reusing the Synchronous Command Control Block
  • Synchronous Port Sharing
  • Synchronous Physical Device Characteristics
  • Synchronous RICCS Level A Command Descriptions
  • RCS_S_PORTDEFINITION
  • RCS_S_OPEN
  • RCS_S_CLOSE
  • RCS_S_SETLINECTRL
  • RCS_S_RETLINECTRL
  • RCS_S_RESET
  • RCS_S_SHUTDOWN
  • RCS_S_READ
  • RCS_S_WRITE
  • RCS_S_STOPTRANS
  • RCS_S_STARTTRANS
  • RCS_S_SETCTRLSIGNAL
  • RCS_S_RETCTRLSIGNAL
  • RCS_S_DMAREADCTRL
  • RCS_S_DMAWRITECTRL
  • RCS_S_CANCELREADS
  • RCS_S_CANCELWRITES
  • RCS_S_NOTIFY
  • RCS_S_DEFEI
  • Synchronous Return Codes
  • Synchronous Information Codes
  • Synchronous Tips and Techniques
  • Interfacing Directly with the RICCS Driver
  • Synchronous Assembler Include Files
  • RICCS Post Code Values

  • INTERNATIONAL BUSINESS MACHINES PROVIDES THIS PUBLICATION "AS IS," WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

    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.


    Special Notices

    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/2
    
    The following terms, DENOTED BY A DOUBLE ASTERISK (**), used in this publication, are trademarks of other companies as follows:
    Zilog               Zilog Inc.
    Signetics           Signetics Corporation
    

    About This Guide

    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:

    The Realtime Interface Co-Processor Extended Services requires the Realtime Control Microcode, Version 1.5 or higher.

    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.

    Purpose

    The objectives of this publication are to:

    Note:

    Additional information can be found in the publications listed in "Related Publications" and "Reference Publications".

    Audience

    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.

    Organization

    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:

    The chapter also explains RICPS return codes.

    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 Publications

    Related books in the Realtime Interface Co-Processor library include:

    Reference Publications

    One or more of the following publications might be needed for reference when using this publication:

    Conventions


    Chapter 1. General Product Description


    Overview

    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:


    Realtime Interface Co-Processor Programming Services (RICPS)

    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.


    Realtime Interface Co-Processor Communications Support (RICCS)

    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:

    RICCS supports RS-232-C, RS-422-A, and V.35 electrical interface standards. Chapter 4 provides a detailed description of the Realtime Interface Co-Processor Asynchronous Communications Support and Chapter 5 provides a detailed description of the Realtime Interface Co-Processor Bit Synchronous Communications Support.

    Enhancement Summary for RICCS Version 1.03

    Version 1.03 of RICCS contains the following enhancements:

    Software Structure

    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 |
    +--------------------------------------------------------+-------------+
    

    Selectable Interface Board/A Support

    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.

    Task Posting

    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.


    Hardware and Software Requirements

    The following are minimum hardware and software requirements for the IBM Realtime Interface Co-Processor Extended Services:


    Chapter 2. Getting Started


    Installation Requirements

    The following diskettes are needed for software installation:


    Product Contents

    RICES Programs

    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:

    Filename
    Description

    READ.ME
    Describes the files on the IBM Realtime Interface Co-Processor Extended Services Programs diskette

    HISTORY.FIL
    History of programs on the IBM Realtime Interface Co-Processor Extended Services Programs diskette

    The program files are:

    Filename
    Description

    RICPS.COM
    Realtime Interface Co-Processor Programming Services task for 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.

    RICPSE.COM
    Realtime Interface Co-Processor Programming Services task for IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2.

    RICPS.LIB
    Library declarations for Realtime Interface Co-Processor Programming Services.

    RICPS.H
    C declarations include file for Realtime Interface Co-Processor Programming Services.

    RICCS.COM
    Realtime Interface Co-Processor Communications Support asynchronous driver for all IBM Realtime Interface Co-Processor adapters.

    RICCSSZ.EXE
    Realtime Interface Co-Processor Communications Support bit synchronous driver for 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.

    RICCSSS.EXE
    Realtime Interface Co-Processor Communications Support bit synchronous driver for the IBM Realtime Interface Co-Processor Portmaster Adapter/A and IBM Realtime Interface Co-Processor Multiport Adapter, Model 2.

    RICCS.LIB
    Library declarations for Realtime Interface Co-Processor Communications Support asynchronous and bit synchronous drivers.

    RICCS.H
    C declarations include file for Realtime Interface Co-Processor Communications Support asynchronous driver.

    RICCSS.H
    C declarations include file for Realtime Interface Co-Processor Communications Support bit synchronous drivers.

    RICCS.ASM
    Assembler declarations include file for Realtime Interface Co-Processor Communications Support asynchronous driver.

    RICCSS.ASM
    Assembler declarations include file for Realtime Interface Co-Processor Communications Support bit synchronous drivers.

    RICES Sample Programs

    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:


    Filename
    Description

    READ.ME
    Describes the files on the IBM Realtime Interface Co-Processor Extended Services Sample Programs diskette.

    HISTORY.FIL
    History of programs on the IBM Realtime Interface Co-Processor Extended Services Sample Programs diskette.

    SAMPLE.TXT
    Instructions on how to load and execute the sample programs.

    The program files are:


    Filename
    Description

    MAIL.CFG
    This configuration file is used with MAILSU and MAILPRT sample programs to configure the asynchronous communication support driver.

    SYNC.CFG
    This configuration file is used with SYNCSU and SYNCPRT sample programs to configure the bit synchronous communication support driver.

    ASYNC.CFG
    This configuration file is used with RASYNC sample program to configure the asynchronous communication support driver.

    MAILSU.C
    C-source code file for sample task which uses RICPS and RICCS (asynchronous). Works with the task MAILPRT on the co-processor adapter.

    MAILSU.H
    Include file for MAILSU.C; contains structures and variable definitions.

    MAILSU.EXE
    Executable sample task; must be run with MAILPRT.EXE.

    MAILPRT.C
    C-source code file for sample task that uses RICCS and RICPS.

    MAILPRT.H
    Include file for MAILPRT.C; contains structures and variable definitions.

    MAILPRT.EXE
    Sample task executable; must be run with MAILSU.EXE.

    SYNCSU.C
    C-source code file for sample task which uses the RICPS and RICCS (synchronous). Works with the task SYNCPRT on the co-processor adapter.

    SYNCSU.H
    Include file for SYNCSU.C; contains structures and variable definitions.

    SYNCSU.EXE
    Executable sample task; must be run with SYNCPRT.EXE.

    SYNCPRT.C
    C-source code file for sample task that uses RICCS and RICPS.

    SYNCPRT.H
    Include file for SYNCPRT.C; contains structures and variable definitions.

    SYNCPRT.EXE
    Executable sample task; must be run with SYNCSU.EXE.

    ICASTRUC.H
    Include file for MAILPRT.C, MAILSU.C, SYNCPRT.C, and SYNCSU.C; contains system structures and variable definitions.

    RASYNC.ASM
    Assembly source code for a sample task that uses RICCS only.

    RASYNC.EXE
    Executable sample task.
    INC.ASM
    Include file for RASYNC.ASM; contains RICCS structures.

    OS2ASYNC.C
    C-source code for the sample program that runs
    OS2SYNC.C
    on the system unit. The operating system must be OS/2. These programs communicate with the sample task either RASYNC.ASM, MAILSU.C, or SYNCSU.C running on the co-processor adapter.

    OS2ASYNC.EXE
    OS/2 system unit executable sample programs.
    OS2SYNC.EXE

    DOSASYNC.C
    C source code for the sample program that runs
    DOSSYNC.C
    on the system unit. The operating system must be DOS. These programs communicate with the sample task either RASYNC.ASM, MAILSU.C, or SYNCSU.C running on the co-processor adapter.

    DOSASYNC.EXE
    DOS system unit executable sample programs.
    DOSSYNC.EXE

    PCASYNC.H
    Include file for OS2ASYNC.C and DOSASYNC.C.

    PCSYNC.H
    Include file for OS2SYNC.C and DOSSYNC.C.

    INPUT.C
    Source file used with OS2ASYNC.C and DOSASYNC.C for reading input; must be compiled and linked with these programs.

    SINPUT.C
    Source file used with OS2SYNC.C and DOSSYNC.C for reading input; must be compiled and linked with these programs.

    Startup

    Use the following procedure to start up the RICES software. Be sure to use the instructions that apply to your operating system environment.

    1. Load the Interrupt Handler or the Device Driver.
    2. Load the Realtime Control Microcode.
    3. Load the IBM Realtime Interface Co-Processor Extended Services.

      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:

      • Realtime Interface Co-Processor Programming Services (RICPS.COM and RICPSE.COM).

      • Realtime Interface Co-Processor Communications Support (RICCS.COM, RICCSSZ.EXE, and RICCSSS.EXE).
      The RICPS and RICCS tasks are independent of each other and may be loaded separately or at the same time.

      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".

    4. Verify Installation of the IBM Realtime Interface Co-Processor Extended Services

      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
      

    Loading RICPS

    Realtime Interface Co-Processor Programming Services (RICPS) must be loaded on the co-processor before use. Any valid task number may be used.

    If the RICPS encounters any installation or initialization errors, an error is reported in the RICPS task secondary status buffer, and the RICPS task suspends itself.

    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        |
    +---------+---------+-----------------------------+
    

    Loading RICCS

    Realtime Interface Co-Processor Communications Support (RICCS) must be loaded to the co-processor adapter before use. Any valid task number may be used.

    If the RICCS encounters initialization errors, an error is reported in the RICCS task secondary status buffer and the RICCS task suspends itself.

    The possible initialization errors are:

    +=========+======================+
    | Byte 0  | Meaning              |
    +=========+======================+
    | 01h     | Initialization       |
    |         | complete error       |
    +---------+----------------------+
    | 02h     | No valid ports       |
    +---------+----------------------+
    | 21h     | Allocation error     |
    +---------+----------------------+
    

    Chapter 3. Programming Services (RICPS)

    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

    When using any of the previous services on a co-processor adapter with expanded memory such as the IBM Realtime Interface Co-Processor Portmaster Adapter/A, an address that is within expanded memory cannot be passed to the service; however, queue elements in expanded memory are supported.

    RICPS C Call Format

    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.


    RICPS Category Descriptions

    This section describes each of the categories of RICPS services. The individual services are described in detail later in this chapter.

    Interrogating the Presence of RICPS

    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.

    Event Management

    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:

    (Refer to the Realtime Interface Co-Processor Software Technical Reference Volume 3 , and the Realtime Interface Co-Processor Firmware Technical Reference for a discussion of a Post Service Interrupt and a Post Supervisor Call.) A Timeout Post occurs if the event does not occur by the time specified by the timeout parameter on the EventWait call.

    Wait With Timeout

    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.

    LIFO and Priority Queues

    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

    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.

    Non-Specific Resource Allocation

    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.

    Non-Specific Task Numbers

    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.

    Post Code Management

    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.

    Semaphore Management

    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:

    Other tasks can resolve a system semaphore handle through the ResolveName service. If the owning task unloads, tasks waiting on the system semaphore are notified. This only applies to system semaphores.

    RAM semaphores:

    Tasks must manage resolution of RAM semaphore handles. If the owning task unloads, tasks waiting on the RAM semaphore are not notified. Refer to "SemInit (11h)" for details on creating a RAM semaphore.

    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 |        |
    +------+------------+---------------------+-------------+--------+
    

    Task Priority Control

    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.)

    Timeslice Management

    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

    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 Commands

    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.

    General Invocation

    Issuing commands to the Realtime Control Microcode or RICPS is made much easier by use of the following packages:

    All of these are separate packages.

    General Error Handling

    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.


    Realtime Control Microcode System Unit Commands

    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.

    Request Task Load (01h)

    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         |
    +---------+---------+-------------------+
    

    Request Task Load With Boundary (03h)

    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         |
    +---------+---------+-------------------+
    

    Request Task Load Low (0Ch)

    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         |
    +---------+---------+-------------------+
    

    Get RICPS's Task Number (20h)

    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  |
    +---------+---------+-------------------+
    

    RICPS System Unit Commands

    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.

    Set Timeslice Interval (02h)

    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.
    

    ResolveName (03h)

    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    |
    +---------+---------+-------------------+
    

    Enable System Semaphores (04h)

    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    |
    +---------+---------+--------------------+
    

    Configure Mailbox Message Pool (06h)

    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 |
    +---------+---------+-------------------+
    

    RICPS Supervisor Calls

    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:

    1. Before the task calls the STAYRES SVC, it should disable Post Code queueing and Event Management, if they are enabled.

    2. After the task calls the STAYRES SVC, it must not use any RICPS service that involves a wait or a post of the task. However, the task may still post other tasks.

    3. After the task calls the STAYRES SVC, it will no longer have a TCB; and hence it is no longer considered a task but rather it is considered resident code. Therefore, any RICPS service that operates on its TCB must not be called by the task.

    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.

    Build (39h)

    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.
    

    Alloc (46h)

    The Alloc Supervisor Call may be used to allocate the following resources:

    For a detailed description of this function, refer to Realtime Interface Co-Processor Software Technical Reference Volume 3 and the Realtime Interface Co-Processor Firmware Technical Reference.

    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.
    

    Return (47h)

    The Return Supervisor Call returns a resource of the following types:

    For a detailed description of this function, refer to Realtime Interface Co-Processor Software Technical Reference Volume 3 and the Realtime Interface Co-Processor Firmware Technical Reference.

    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.
    

    RICPS Service Interrupts

    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.

    RICPS Presence (00h)

    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.
    

    EventEnable (01h)

    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.
    

    EventDisable (02h)

    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.
    

    EventPost (03h)

    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.
    

    EventReset (04h)

    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.
    

    EventWait (05h)

    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.
    

    WaitTimeout (06h)

    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.
    

    ChangePriority (07h)

    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.
    

    PostCodeQEnable (08h)

    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
    

    PostCodeQDisable (09h)

    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.
    

    PostCodeQuery (0Ah)

    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.
    

    PostCodeGet (0Bh)

    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.
    

    PostCodeClear (0Ch)

    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.
    

    ResolveName (0Dh)

    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

    #include 
    #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;);
    
    RETURN CODES
         0000h  Normal completion; no errors.
         0013h  Invalid data.
         0017h  Name not found.
    

    SemRequest (0Eh)

    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.
    

    SemRelease (0Fh)

    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.
    

    SemTest (10h)

    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.
    

    SemInit (11h)

    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.
    

    SemClose (12h)

    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.
    

    MBXRegister (13h)

    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.
    

    MBXDeregister (14h)

    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.
    

    MBXOpen (15h)

    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

    MBXNumber
    If this parameter is non-negative, upon input, the requested mailbox number opens for the user. If the specified mailbox is already open, an error is returned. If this value is greater than or equal to the maximum number of boxes requested in MBXRegister, an error is returned. If this parameter is negative, the first available mailbox is opened and its number is returned in this parameter.

    MBXName
    The MBXName parameter points to a null-terminated string (ASCII) containing the name of the mailbox. The length of the name including the null terminator should be 256 characters or less. If the name is already in use, an error is returned. The name pointed to by MBXName should not be changed while the mailbox is open.

    MBXType
    The MBXType parameter specifies the mailbox type. The choices are FIFO, LIFO, and priority.

    MaxMessages
    This parameter indicates the maximum number of messages to be allowed in the mailbox. A value of 0 indicates that messages are never placed in the mailbox and that an MBX_AST service routine is provided. If this parameter is 0 and the MBX_AST parameter is NULL, an error is returned. A value other than 0 indicates the maximum number of messages allowed in the mailbox.

    Reserved
    This is a pointer to a block of eight bytes of storage that must reside in the task header segment. It is reserved for use by the mailbox routines and should not be changed while the mailbox is open. It must be at least eight bytes long.

    PostFlag
    Tasks request posting upon receipt of each message in a mailbox. This value is the post code that will be used to post the task. If PostFlag is 0, no post occurs.

    EventFlag
    Tasks may request that an event be posted upon receipt of each message in a mailbox. This value is the event value used in the event post. If EventFlag is 0, no event post occurs. If both a PostFlag and EventFlag post are selected, the event post occurs first. It is the responsibility of the task to initiate event management; errors for the event post are not reported to the caller of MBXSend.

    ServiceRoutine
    This service routine, if non-NULL, is called each time a message is sent to the task. The routine should be considered an interrupt routine; processing should be kept to a minimum. When this routine receives control, the data segment is set according to the value in the task header. MBXSend may be called from within this routine, allowing a front-end mailbox processor. MBXCount, MBXAllocMsg, and MBXFreeMsg may also be called from within the service routine. The following is an example declaration of a service routine.

    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.
    

    MBXClose (16h)

    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.
    

    MBXSend (17h)

    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

    MBXAddress
    This is the destination mailbox's MBX_ADRS. It is returned on the MBXOpen call and can be resolved from a mailbox name by calling MBXAdrs. An error is returned if this parameter does not identify a valid mailbox.

    Message
    This is a pointer to the message to be placed in the mailbox. The format and length of the message is left to the task to define. If this is a priority mailbox; however, the first byte of the message should contain the message priority (0 - 255, 0 is the highest priority). If the message passed to MBXSend was not allocated by MBXAllocMsg, a reserved message header of four bytes should directly precede the message. Messages allocated by MBXAllocMsg have the required message header.
    +=========+==========+==========+==========+
    | 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
    #include 
    #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);
    }
    
    RETURN CODES
         0000h  Normal completion; no errors.
         8003h  Mailbox full.
         8007h  Invalid mailbox.
         nnnnh  User-defined service routine return code.
    

    MBXReceive (18h)

    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

    MBXNumber
    The mailbox number from which to receive a message; the number is returned on the MBXOpen call.

    Exit Parameters

    Message
    A pointer to the received message is returned here. If the mailbox is empty, NULL is returned in this field in addition to the mailbox empty error code.
    Example Call
    #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.
    

    MBXCount (19h)

    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

    MBXNumber
    The mailbox number to query.

    Exit Parameters

    Count
    The count of messages in the mailbox is returned here.
    Example Call
    #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.
    

    MBXAdrs (1Ah)

    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

    MBXName
    This parameter points to a null-terminated string containing the name of the mailbox. If there is no null terminator within the first 256 characters, an error is returned.

    Exit Parameters

    MBXAddress
    The mailbox address is returned in this field.

    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.
    

    MBXName (1Bh)

    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

    MBXAddress
    The address of the mailbox.

    Exit Parameters

    MBXName
    Where a mailbox name pointer is returned.

    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.
    

    MBXAllocMsg (1Ch)

    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.

    ASSEMBLER INTERFACE
         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

    MsgSize
    The requested amount of storage, in bytes, for a message buffer.

    Return Value

    Message
    Pointer to the allocated message buffer, or NULL if no storage is available.
    Example Call
    #include "ricps.h"
    int ReturnCode;                /* Return code               */
    char far *Message;             /* Message buffer            */
                                   /* Allocate a message buffer */
    Message = MBXAllocMsg(strlen("Test Message"));
    

    MBXFreeMsg (1Dh)

    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

    Message
    A pointer to a message buffer that was allocated via the MBXAllocMsg service.

    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.
    

    MBXConfigMsgPool (1Eh)

    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

    PoolSize
    The size in paragraphs to configure the shared message pool.

    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.
    

    RICPS Return Codes

    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.

    0000h Normal completion, no error

    0001h Invalid service interrupt number

    0005h Access denied

    0008h Insufficient storage

    0013h Invalid data

    0014h Invalid task number

    0015h Invalid timer number

    0016h Invalid queue number

    0017h Name not found

    0018h Duplicate name

    0019h Device number not available

    0020h Task number not available

    0021h Invalid semaphore

    0022h Semaphore closed

    0023h Semaphore count maximum

    8001h Already registered

    8002h Mailbox empty

    8003h Mailbox full

    8004h Mailbox in use

    8005h Mailboxes/storage exhausted

    8006h Mailboxes open

    8007h Invalid mailbox

    8008h Invalid message buffer

    8009h Invalid mailbox name

    800Ah Invalid mailbox type

    800Bh Mailbox name unknown

    800Ch No service routine

    800Dh Mailbox not registered

    800Eh Mailbox pool configured.

    800Fh Mailbox storage exhausted


    System Unit Command Return Codes

    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                                             |
    +-------+-------+------------------------------------------------------------+
    

    RICPS Post Code Values

    The RICPS post code values are listed here:

         TIMEOUT   0054h
         EVENT     0055h
         SEMAPHORE 0056h
    


    Chapter 4. Asynchronous Communications Support

    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.

    Asynchronous Level A Commands

    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:


    Asynchronous RICCS C Language Support

    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.


    Startup Considerations

    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.


    Asynchronous RICCS Driver Task Priority

    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).


    Asynchronous Software Interrupt Vectors

    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.


    Asynchronous Intertask Synchronization

    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.


    Reusing the Asynchronous Command Control Block

    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.


    Asynchronous Port Sharing

    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.


    Asynchronous Physical Device Characteristics

    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).


    Asynchronous Level A Command Descriptions

    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.

    RCS_PORTDEFINITION

    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,4
    
    Example 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)
    +--------------------------- Reserved
    
    MAXDMA 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
    +--------------------------- Reserved
    
    RETURN 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                |
    +------------+------------------------+
    

    RCS_OPEN

    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.

    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,4
    
    Example 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:

    This value is 0103h for the product defined in this chapter.
    +============+========================+
    | 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                 |
    +------------+------------------------+
    

    RCS_CLOSE

    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,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 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:

    Option 1 returns to the default values after issuing an RCS_CLOSE command.

    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 |
    +------------+------------------------+
    

    RCS_SETLINECTRL

    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,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 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 |
    +------------+------------------------+
    

    RCS_RETLINECTRL

    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,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 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 |
    +------------+------------------------+
    

    RCS_RESET

    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,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 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 |
    +------------+------------------------+
    

    RCS_SHUTDOWN

    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,4
    
    Example 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         |
    +------------+------------------------+
    

    RCS_READ

    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,4
    
    Example 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:

    The RS-232-C control signals are defined by the RCS_SETCTRLSIGNAL command.
    +=====+=====+============================================+
    | 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 |
    +------------+------------------------+
    

    RCS_GENSTATETABLE

    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:

    When the RCS_READ is issued, the RICCS driver attempts to match the SOM and TERM (not EOM) sequences. Once an SOM sequence is received, only EOM sequences are expected. EOM and TERM sequences can specify the number of trailing (expected) characters that follow.

    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:

    ASSEMBLER INTERFACE
    PUSH Segment of RCS_GENSTATETABLE Control Block
    PUSH Offset of RCS_GENSTATETABLE Control Block
    CALL _rcs_genstatetable
    ADD  SP,4
    
    Example 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.

    RCS_DRIVERINPUTBUFFER

    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,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).
    
    ;     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 |
    +------------+------------------------+
    

    RCS_WRITE

    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.

    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,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).
    
    ;       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 |
    +------------+------------------------+
    

    RCS_SENDBREAK

    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,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 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 |
    +------------+------------------------+
    

    RCS_SETMINBREAK

    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,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 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 |
    +------------+------------------------+
    

    RCS_ECHO

    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,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 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 |
    +------------+------------------------+
    

    RCS_STOPTRANS

    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,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 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 |
    +------------+------------------------+
    

    RCS_STARTTRANS

    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,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 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 |
    +------------+------------------------+
    

    RCS_SETCTRLSIGNAL

    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:

    The application task can specify what combination of these signals must be present (ON) before data transmission is allowed. These settings are retained after the application task issues an RCS_CLOSE command, unless the caller requests that the default values be re-instated; therefore, subsequent RCS_OPEN commands may use the previous settings.

    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,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 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
    +--------------------------- Reserved
    
    RESERVED 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 |
    +------------+------------------------+
    

    RCS_RETCTRLSIGNAL

    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,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 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) input
    
    RETURN 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 |
    +------------+------------------------+
    

    RCS_DMAREADCTRL

    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 |
    +------------+------------------------+
    

    RCS_DMAWRITECTRL

    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,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 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 |
    +------------+------------------------+
    

    RCS_CTRLINFLOW

    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.

    By default, the actual XON and XOFF characters, as defined in the ASCII character set, are used (11h and 13h respectively).

    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
    +--------------------------- Reserved
    
    HIGHTHRESH 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
    +--------------------------- Reserved
    
    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 |
    +------------+------------------------+
    

    RCS_CTRLOUTFLOW

    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:

    1. The XON and XOFF characters cannot be received unless a read is pending or a Driver Input Buffer is assigned.

    2. If RCS_CTRLOUTFLOW is in use, DMA can only be used for Read's on IBM Realtime Interface Co-Processor Multiport Adapter, Model 2 and IBM Realtime Interface Co-Processor Portmaster Adapter/A.

    ASSEMBLER INTERFACE

    PUSH Segment of RCS_CTRLOUTFLOW control block
    PUSH Offset of RCS_CTRLOUTFLOW control block
    CALL _rcs_ctrloutflow
    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 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 |
    +------------+------------------------+
    

    RCS_CANCELREADS

    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,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 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 |
    +------------+------------------------+
    

    RCS_CANCELWRITES

    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,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 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 |
    +------------+------------------------+
    

    RCS_ERRORSUB

    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,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 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 |
    +------------+------------------------+
    

    RCS_NOTIFY

    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,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).
    
    ;       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 |
    +------------+------------------------+
    

    RCS_DEFEI

    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,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 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 7
    
    RESERVED2 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 7
    
    RESERVED3 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 7
    
    RESERVED4 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 7
    
    RESERVED5 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 7
    
    RESERVED6 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 7
    
    RESERVED7 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 7
    
    RESERVED8 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 |
    +------------+------------------------+
    

    Asynchronous Return Codes

    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.

    00h Successful

    01h Invalid handle.

    02h Too many tasks sharing port.

    03h Invalid parameters.

    04h Device already open.

    06h Invalid device name.

    11h Shutdown in progress

    12h Read error

    13h Driver Input Buffer undefined

    14h Write error

    16h Insufficient space

    17h Internal queue full

    18h Invalid driver task number

    19h Device not active

    1Ah Control signal not present

    1Bh Stopped or not started

    1Ch Hardware already allocated

    1Dh Too many interrupt vectors

    1Eh Incompatible port type

    1Fh Invalid password

    20h No password protection

    21h Switch preparation failed

    22h Invalid driver identification

    24h No external clocking support


    Asynchronous Information Codes

    Some commands execute successfully, but have an information return code returned in the low byte of the RETCODE parameter.

    00h No information

    01h No DMA Write

    02h No DMA Read

    03h No DMA

    04h Not RS-232-C or V.35 port

    08h Not port 0 or 1

    0Ch Not RS-232-C or V.35 port and not port 0 or 1


    Asynchronous Tips and Techniques

    This section provides programming tips for Realtime Interface Co-Processor Asynchronous Communications Support.

    Interfacing Directly with the RICCS Driver

    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.

    Common Subroutine Design

    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:

    The issued command determines if the RCS Driver Task Number is the specific task number or the generic task number.

    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 commands must be issued to the generic driver task number, FFh:

    Deferred Command Processed

    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:

    1. Disable interrupts

    2. Determine if the resume flag is set

      Note:

      If the resume flag is set, the command proceeds to step 3; if it is not set, the command:
      1. Suspends the task using the SUSPEND Supervisor Call.

      2. Returns to Step 2.

    3. Clear the resume flag

    4. Enable interrupts

    5. Return to the application task.

    Immediate Command Processed

    The following list shows the immediate commands in RICCS:

    All immediate commands return immediately to the application task.

    RCS_READ or RCS_WRITE Command Processed

    1. An RCS_READ or RCS_WRITE subroutine determines the type of command (wait or no-wait).

    2. A no-wait command returns to the application task.

    3. A wait command follows the procedure of the deferred command processed.

    Initializing Level A Command String Parameters

    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:


    Asynchronous Assembler Include Files

    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.


    RICCS Post Code Values

    The RICCS Post Code Values are:

    RCS_READ
    08h

    RCS_WRITE
    18h

    RCS_NOTIFY
    28h

    RCS_S_READ
    09h

    RCS_S_WRITE
    19h

    RCS_S_NOTIFY
    29h

    Chapter 5. Synchronous Communications Support

    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.

    Synchronous Level A Commands

    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:


    Synchronous RICCS C Language Support

    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.


    Synchronous Startup Considerations

    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.


    Synchronous RICCS Driver Task Priority

    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).


    Synchronous Software Interrupt Vectors

    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.


    Synchronous Intertask Synchronization

    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.


    Reusing the Synchronous Command Control Block

    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.


    Synchronous Port Sharing

    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.


    Synchronous Physical Device Characteristics

    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:


    Synchronous RICCS Level A Command Descriptions

    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.

    RCS_S_PORTDEFINITION

    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,4
    
    Example 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)
    +--------------------------- Reserved
    
    RESERVED3 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
    +--------------------------- Reserved
    
    RETURN 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                |
    +------------+------------------------+
    

    RCS_S_OPEN

    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.

    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,4
    
    Example 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:

    +============+========================+
    | 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 |
    +------------+------------------------+
    

    RCS_S_CLOSE

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_SETLINECTRL

    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,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 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:

    HDXDELAY is the delay time before dropping RTS after the last half duplex write. Delay times are expressed in 10-millisecond units. The default delay is 10 milliseconds. The minimum value is 1 (10-milliseconds). The following values are valid:
    +============+========================+
    | 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 |
    +------------+------------------------+
    

    RCS_S_RETLINECTRL

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_RESET

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_SHUTDOWN

    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,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 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         |
    +------------+------------------------+
    

    RCS_S_READ

    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 |
    +------------+------------------------+
    

    RCS_S_WRITE

    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,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 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: When the RCS_S_WRITE completes, the Idle Detect timer cancels and restarts with the IDLEOVERRIDE value. The next time the Idle Detect timer restarts, the actual Idle Detect Timeout value is used. A value of 0 indicates that no override occurs. A value of -1 indicates that the one-time Idle Detect Timeout is infinite.

    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 |
    +------------+------------------------+
    

    RCS_S_STOPTRANS

    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 |
    +------------+------------------------+
    

    RCS_S_STARTTRANS

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_SETCTRLSIGNAL

    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:

    The application task can specify what combination of these signals must be present (ON) before data transmission is allowed. These settings are retained after the application task issues an RCS_S_CLOSE command, unless the caller requests that the default values be re-instated; therefore, subsequent RCS_S_OPEN commands may use the previous settings.

    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,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 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
    +--------------------------- Reserved
    
    RESERVED 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 |
    +------------+------------------------+
    

    RCS_S_RETCTRLSIGNAL

    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,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 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) input
    
    RETURN 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 |
    +------------+------------------------+
    

    RCS_S_DMAREADCTRL

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_DMAWRITECTRL

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_CANCELREADS

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_CANCELWRITES

    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,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 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 |
    +------------+------------------------+
    

    RCS_S_NOTIFY

    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 |
    +------------+------------------------+
    

    RCS_S_DEFEI

    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,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 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 7
    
    RESERVED2 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 7
    
    RESERVED3 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 7
    
    RESERVED4 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 7
    
    RESERVED5 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 7
    
    RESERVED6 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 7
    
    RESERVED7 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 7
    
    RESERVED8 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 |
    +------------+------------------------+
    

    Synchronous Return Codes

    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.

    00h Successful

    01h Invalid handle

    02h Too many tasks sharing port

    03h Invalid parameters

    04h Device already open

    06h Invalid device name

    11h Shutdown in progress

    12h Read error

    14h Write error

    17h Internal queue full

    18h Invalid driver task number

    19h Device not active

    1Ah Control signal not present

    1Bh Stopped or not started

    1Ch Hardware already allocated

    1Dh Too many interrupt vectors

    1Eh Incompatible port type

    1Fh Invalid password

    20h No password protection

    22h Invalid driver identification


    Synchronous Information Codes

    Some commands execute successfully, but have an information return code returned in the low byte of the RETCODE parameter.

    00h No information

    01h No DMA Write

    02h No DMA Read

    03h No DMA

    04h Not RS-232-C or V.35

    08h Not port 0 or 1

    0Ch Not RS-232-C or V.35 port and not port 0 or 1


    Synchronous Tips and Techniques

    This section provides programming tips for Realtime Interface Co-Processor Synchronous Communications Support.

    Interfacing Directly with the RICCS Driver

    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.

    Common Subroutine Design

    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:

    The issued command determines whether the RCS driver task number is the specific task number or the generic task number.

    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:

    Deferred Command Processed

    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:

    1. Disable interrupts

    2. Determine if the resume flag is set

      Note:

      If the resume flag is set, the command proceeds to step 3; if it is not set, the command does the following:
      1. Suspends the task using the SUSPEND Supervisor Call.

      2. Returns to Step 2.

    3. Clear the resume flag

    4. Enable interrupts

    5. Return to the application task.

    Immediate Command Processed

    The following list shows the immediate commands in RICCS:

    All immediate commands return immediately to the application task.

    RCS_S_READ or RCS_S_WRITE Command Processed

    1. An RCS_S_READ or RCS_S_WRITE subroutine determines the type of command (wait or no-wait).

    2. A no-wait command returns to the application task.

    3. A wait command follows the procedure of the deferred command processed.

    Initializing Level A Command String Parameters

    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:


    Synchronous Assembler Include Files

    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.


    RICCS Post Code Values

    The RICCS Post Code Values are:

    RCS_READ
    08h

    RCS_WRITE
    18h

    RCS_NOTIFY
    28h

    RCS_S_READ
    09h

    RCS_S_WRITE
    19h

    RCS_S_NOTIFY
    29h

    Last modified: March 25, 1999