Series 3000
Application Programmer’s Reference Manual Series 3000 Application Programmer’s Reference Manual
70-16309-03 Revision A — April 2000
2 Symbol Technologies, Inc. One Symbol Plaza, Holtsville N.Y. 11742 Series 3000 Application Programmer’s Reference Manual
70-16309-03 Revision A April, 2000 1996-2000 by Symbol Technologies, Inc. All rights reserved.
No part of this publication may be reproduced or used in any form, or by any electrical or mechanical means, without permission in writing from Symbol. This includes electronic or mechanical means, such as photocopying, recording, or information storage and retrieval systems. The material in this manual is subject to change without notice.
The software is provided strictly on an “as is” basis. All software, including firmware, furnished to the user is on a licensed basis. Symbol grants to the user a non-transferable and non-exclusive license to use each software or firmware program delivered hereunder (licensed program). Except as noted below, such license may not be assigned, sublicensed, or otherwise transferred by the user without prior written consent of Symbol. No right to copy a licensed program in whole or in part is granted, except as permitted under copyright law. The user shall not modify, merge, or incorporate any form or portion of a licensed program with other program material, create a derivative work from a licensed program, or use a licensed program in a network without written permission from Symbol. The user agrees to maintain Symbol’s copyright notice on the licensed programs delivered hereunder, and to include the same on any authorized copies it makes, in whole or in part. The user agrees not to decompile, disassemble, decode, or reverse engineer any licensed program delivered to the user or any portion thereof.
Symbol reserves the right to make changes to any software or product to improve reliability, function, or design.
Symbol does not assume any product liability arising out of, or in connection with, the application or use of any product, circuit, or application described herein.
No license is granted, either expressly or by implication, estoppel, or otherwise under any Symbol Technologies, Inc., intellectual property rights. An implied license only exists for equipment, circuits, and subsystems contained in Symbol products.
Symbol and Spectrum One are registered trademarks of Symbol Technologies, Inc. Other product names mentioned in this manual may be trademarks or registered trademarks of their respective companies and are hereby acknowledged. Symbol Technologies, Inc. One Symbol Plaza Holtsville, N.Y. 11742 http:www.symbol.com
iv Contents
About This Manual Introduction ...... xiii How to Use This Manual ...... xiv Notational Conventions ...... xv Format of Function Descriptions ...... xvi Function Name...... xvi Syntax ...... xvi Description ...... xvi Return Value...... xvi See Also ...... xvi Related Documentation...... xvii
Chapter 1. Utilities Introduction ...... 1-3 BATCHER.EXE...... 1-4 BATCHRF.EXE...... 1-8 DONEBEEP.COM ...... 1-14 DSKBCHK.COM ...... 1-15 DTRON.COM ...... 1-17 Font Builder ...... 1-18 KBD3000.EXE ...... 1-24 KBDMAKE.EXE ...... 1-27 Creating a Keyboard Map Manually ...... 1-32 LOADER.EXE...... 1-38 MPM3000.EXE ...... 1-48 Memory Transfer Analyzer ...... 1-51 PDCONVRT.EXE ...... 1-65 RCVHEX.EXE ...... 1-66 SENDHEX.EXE ...... 1-68 STG3000.EXE ...... 1-70 TDREM.EXE ...... 1-72 TFT3000.EXE ...... 1-74 TSRREG.EXE...... 1-76 USRCFG.EXE ...... 1-77
Chapter 2. Device Drivers Introduction ...... 2-3 The ANSI Compatibility Driver...... 2-4 ERR3000.SYS...... 2-12
iii ETA3000.SYS...... 2-13 PAN3000.SYS ...... 2-16 PGM3000.SYS ...... 2-18 FLASHDSK.SYS ...... 2-19
Chapter 3. BIOS Library Functions Introduction ...... 3-5 BIOS Library Functions (Listing)...... 3-5 BIOS LibraryFunctions (Descriptions) ...... 3-10 BiosAllocQueues ...... 3-11 BiosAllocTimer...... 3-13 BiosAutoRepeat ...... 3-14 BiosBeep ...... 3-15 BiosBeepFreq ...... 3-16 BiosBeepOff ...... 3-17 BiosCalcCRC...... 3-18 BiosChkBattery...... 3-19 BiosCheckCursor ...... 3-20 BiosCheckKey...... 3-21 BiosCheckTimer ...... 3-22 BiosClick ...... 3-24 BiosClosePort ...... 3-25 BiosClrKey ...... 3-26 BiosClrScr ...... 3-27 BiosControlDataBus ...... 3-28 BiosDelay...... 3-29 BiosExtSerialSetup ...... 3-30 BiosFreeQueues ...... 3-33 BiosFreeTimer...... 3-34 BiosGetAbortStatus ...... 3-35 BiosGetAlarm ...... 3-36 BiosGetBackLightTime ...... 3-37 BiosGetChar ...... 3-38 BiosGetCharAttr...... 3-39 BiosGetChargingRate ...... 3-40 BiosGetCommType ...... 3-41 BiosGetContextBuf...... 3-42 BiosGetCradleType ...... 3-43 BiosGetCursorMode ...... 3-44 BiosGetCursorPos ...... 3-45 BiosGetCursorSize ...... 3-46 BiosGetDate ...... 3-47 BiosGetDisplayPage ...... 3-48 iv BiosGetEMSConfig ...... 3-49 BiosGetEquipList ...... 3-50 BiosGetFont...... 3-51 BiosGetGlobalWrtProt...... 3-52 BiosGetGrantStatus ...... 3-53 BiosGetKeyboardState...... 3-54 BiosGetKybdTimeout ...... 3-55 BiosGetLogPage ...... 3-56 BiosGetLogPageCnt...... 3-57 BiosGetLogScrSize ...... 3-58 BiosGetModemStatus ...... 3-59 BiosGetPhysicalPos ...... 3-60 BiosGetPhysScrSize ...... 3-61 BiosGetPowerSource ...... 3-62 BiosGetQueuePtr ...... 3-63 BiosGetRamSize ...... 3-64 BiosGetRedLED ...... 3-65 BiosGetSerialSetup...... 3-66 BiosGetShiftStatus ...... 3-67 BiosGetTermType ...... 3-68 BiosGetTicks ...... 3-69 BiosGetTime ...... 3-70 BiosGetVersions ...... 3-71 BiosGetVideoMode ...... 3-72 BiosGetViewAngle...... 3-73 BiosGetVirScrSize ...... 3-74 BiosGetWrtProt ...... 3-75 BiosHideCursor ...... 3-76 BiosInitSerialPort ...... 3-77 BiosLED...... 3-79 BiosLineTurn ...... 3-80 BiosMapLogPage ...... 3-81 BiosMemToTextRect ...... 3-82 BiosOpenPort ...... 3-83 BiosOpticalInterface...... 3-84 BiosPortStatus...... 3-85 BiosPowerKey ...... 3-88 BiosPowerOff ...... 3-89 BiosProgramTrigger ...... 3-90 BiosPurgeQueue...... 3-91 BiosPutCharAttr...... 3-92 BiosPutCharMove ...... 3-93 BiosPutCharStay ...... 3-94 BiosPutStrMove ...... 3-95
v BiosPutStrStay ...... 3-96 BiosPutTicks ...... 3-97 BiosQueueStatus ...... 3-98 BiosRecvBlock...... 3-100 BiosRecvChar ...... 3-102 BiosReleaseModem ...... 3-104 BiosRequestModem...... 3-105 BiosResetAlarm ...... 3-106 BiosResetTimer...... 3-107 BiosResetUART ...... 3-108 BiosResumeTimer ...... 3-110 BiosScrollDown ...... 3-111 BiosScrollUp ...... 3-112 BiosSelectFont...... 3-113 BiosSendBlock ...... 3-114 BiosSendChar ...... 3-116 BiosSerialSetup...... 3-117 BiosSetAlarm ...... 3-119 BiosSetBackLight ...... 3-121 BiosSetBackLightTime...... 3-122 BiosSetChargingRate ...... 3-123 BiosSetContextBuf ...... 3-124 BiosSetCursorMode ...... 3-125 BiosSetCursorPos ...... 3-126 BiosSetCursorSize ...... 3-127 BiosSetDate ...... 3-128 BiosSetDisplayPage ...... 3-129 BiosSetGlobalWrtProt ...... 3-130 BiosSetKeyboardState ...... 3-131 BiosSetKybdTimeout...... 3-132 BiosSetLogScrSize ...... 3-133 BiosSetNotify ...... 3-134 BiosSetPhysicalPos...... 3-136 BiosSetRedLED...... 3-137 BiosSetTime...... 3-138 BiosSetTimer...... 3-139 BiosSetUART ...... 3-140 BiosSetVideoMode...... 3-142 BiosSetViewAngle ...... 3-143 BiosSetVirScrSize ...... 3-144 BiosSetWakeReason...... 3-146 BiosShowCursor...... 3-148 BiosSpottingBeam ...... 3-149 BiosSuspendTimer ...... 3-150 vi BiosTextRectToMem ...... 3-151 BiosTransDone ...... 3-152 BiosUpdateTimer ...... 3-153 BiosWakeUpReason...... 3-154 BiosWarmBoot ...... 3-155
Chapter 4. DR DOS Introduction ...... 4-3 DOS Library Functions (Listing) ...... 4-3 DOS Library Functions (Descriptions) ...... 4-4 DosAbsDiskRead ...... 4-5 DosAbsDiskWrite ...... 4-6 DosAllocMem...... 4-7 DosClose ...... 4-8 DosCreate ...... 4-9 DosFreeMem...... 4-10 DosGetCh ...... 4-11 DosGetCurDrv ...... 4-12 DosGetDate...... 4-13 DosGetIntVector...... 4-14 DosGetTime ...... 4-15 DosIoCtrlCkInput ...... 4-16 DosIoCtrlCkOutput...... 4-17 DosIoCtrlDrvRdData...... 4-18 DosIoCtrlGetInfo ...... 4-20 DosIoCtrlRdData ...... 4-21 DosIoCtrlSetInfo...... 4-22 DosIoCtrlWrData ...... 4-23 DosOpen ...... 4-25 DosRead ...... 4-26 DosReadLine...... 4-27 DosSetDate ...... 4-28 DosSetIntVector ...... 4-29 DosSetTime ...... 4-30 DosWrite ...... 4-31 DosWriteLine ...... 4-32 Interface from Microsoft C ...... 4-33 Passing Structures to Functions...... 4-33 IOCTL Commands and Error Codes ...... 4-42 IOCTL Error Codes ...... 4-42 Keyboard IOCTL Commands and Structures ...... 4-44 Keyboard/Scanning IOCTL Structures ...... 4-46 Communications IOCTL Commands and Structures ...... 4-73
vii Chapter 5. UBASIC Record Manager Introduction ...... 5-3 Basic URM Capabilities...... 5-3 Interface from Various Languages ...... 5-5 Interface from Microsoft C ...... 5-5 Loading the URM...... 5-8 UBASIC File Manager ...... 5-9 Interfacing with Low-Level Features ...... 5-10 Memory Manager ...... 5-11 UBASIC Variables ...... 5-12 URM Function Descriptions...... 5-13 blk_alloc...... 5-14 blk_delete ...... 5-15 blk_free ...... 5-16 blk_insert...... 5-17 blk_search ...... 5-18 blk_traverse...... 5-19 mclose ...... 5-20 mcreate ...... 5-21 mcrunch...... 5-23 mdelete ...... 5-24 merase ...... 5-25 mfree ...... 5-26 minit...... 5-27 minput ...... 5-28 minsert...... 5-29 mopen ...... 5-30 mprint ...... 5-31 msearch ...... 5-32 mterminate ...... 5-34 UrmOpen ...... 5-35 UrmReadField ...... 5-37 UrmWriteField ...... 5-39 UrmClose ...... 5-41 UrmPresent ...... 5-42 URM Structure Definitions...... 5-43 File Control Block (FCB) ...... 5-43 Device Name Translation Table (XlatPtrT) ...... 5-47 Separator Character Structure ...... 5-50 Modem Control Structure...... 5-55 URM Pointer Structure (UrmPtrT) ...... 5-61 FMGR Data Block Link ...... 5-69 File Information Block...... 5-69 File Directory Block ...... 5-70 viii DOS File Directory...... 5-72 Bios Parameter Block...... 5-72 DOS FAT Entries ...... 5-73 Free Block ...... 5-74 Segment Table Entry ...... 5-74 RAM Disk Driver Parameter Block ...... 5-75 File Manager First Data Segment ...... 5-76 Header of Cluster Variant Files ...... 5-77 Block Traverse Return Parameter Block ...... 5-78 File Manager Work Buffer ...... 5-78 MCREATE Parameter Blocks...... 5-82 URM Global Prototypes ...... 5-83 Error Codes (Record Manager/File Manager) ...... 5-85
Chapter 6. Miscellaneous Libraries and Functions Introduction ...... 6-3 Batch RF Interface Library ...... 6-4 BRFEnable ...... 6-5 BRFDisable ...... 6-6 BRFLoadConfig ...... 6-7 BRFGetStats ...... 6-8 Calculator Library ...... 6-9 CalcPresent ...... 6-10 Calculate ...... 6-11 Floating Point Calculation Library ...... 6-15 Error Codes...... 6-16 Sample Program...... 6-16 FppAdd ...... 6-17 FppConvert...... 6-18 FppDiv...... 6-19 FppFloatToStr...... 6-20 FppMath ...... 6-21 FppMul ...... 6-22 FppPresent ...... 6-23 FppStrToFloat...... 6-24 FppSub...... 6-25 Graphics Library ...... 6-26 SFArc ...... 6-27 SFClearArea ...... 6-28 SFClearScreen ...... 6-29 SFDisplayFile ...... 6-30 SFDrawLine ...... 6-31 SFEllipse ...... 6-32
ix SFEndGraphics...... 6-33 SFGetImage...... 6-34 SFGetPixel ...... 6-35 SFGetPosition ...... 6-36 SFImageSize ...... 6-37 SFInitGraphics ...... 6-38 SFMoveTo ...... 6-39 SFPutCharText ...... 6-40 SFPutImage...... 6-41 SFPutStrText ...... 6-42 SFRectangle...... 6-43 SFSetPixel ...... 6-44 Macro Processing Manager (MPM3000.EXE) ...... 6-45 MPMLoadFile...... 6-48 Printer Interface Library (PS1Kx.LIB) ...... 6-49 Error Codes...... 6-49 Wireless Printing ...... 6-51 Application Programming Interface (API)...... 6-52 Symbol Utility Library (SYMUTILx.LIB) ...... 6-77 KBD3000 Interface Functions ...... 6-78 KBDRestore...... 6-79 KBDLoadFile ...... 6-80 KBD3000 Error Codes ...... 6-81 Miscellaneous Functions...... 6-82 TSRLoaded ...... 6-83 TSRRegistrationCheck...... 6-84 _STORDS...... 6-85 _RESTORDS ...... 6-86
Chapter 7. Internal Modem Command Set Introduction ...... 7-5 Programming Considerations ...... 7-5 Modem Communications Port...... 7-5 Modem Capabilities...... 7-5 DTR Line and Power ...... 7-6 Sending AT Commands ...... 7-7 Opening the Communications Line ...... 7-8 Repeat Dialing ...... 7-8 Australia ...... 7-8 Europe ...... 7-8 USA and Canada ...... 7-9 Descriptions of AT Commands ...... 7-10 IM3/4 Commands ...... 7-11 x IM5/IM5S Commands ...... 7-18 IM6 Commands ...... 7-37 IM7 Commands ...... 7-48 Result Codes ...... 7-51 S Register Descriptions ...... 7-53 IM8/IM8S Modems ...... 7-68 DTE Speeds...... 7-68 DTR Line and Power ...... 7-68 IM 8 Notes...... 7-89 Differences Between IM5/5S and IM8/8S ...... 7-89 Register S14 bitmap ...... 7-98 Register S16 bitmap ...... 7-99 Register S21 bitmap ...... 7-100 Register S22 bitmap ...... 7-101 Register S23 bitmap ...... 7-102 Register S27 bitmap ...... 7-103 Register S28 bitmap ...... 7-104 Register S31 bitmap ...... 7-105 Register S37 bitmap ...... 7-106 Register S39 bitmap ...... 7-107 Register S40 bitmap ...... 7-108 Register S41 bitmap ...... 7-109 Register S80 bitmap ...... 7-110
Appendix A. Keyboard Codes
Appendix B. The Series 3000 Keyboard Introduction ...... B-1 Keyboard Operation ...... B-1 Scan Code Translation...... B-2 Meta Code Translation ...... B-2 Keyboard States ...... B-5 Limits on Keyboard Redefinition ...... B-6 Standard Keyboard Diagrams ...... B-7
Index
xi xii About This Manual
Introduction The Series 3000 Application Programmer's Reference Manual is the reference manual for the Application Development Kit (ADK). It is not meant to function as an application programmer’s guide and provides only minimal instruction on how to use the tools described in it to program a Symbol Technologies’ Series 3000 hand held computer. For instructions on writing application programs, including those on how to put together the tools and utilities that are described in this manual, refer to the Series 3000 Application Programmer's Guide.
The bulk of this manual consists of the C language interface libraries included in the ADK. Of these the largest libraries are the BIOS and DOS function libraries. By using the functions in these libraries, the application programmer has C language access to the features of the Series 3000 terminals necessary to completely integrate the terminal into the target application. These central features include bar code scanning and communications, including Spectrum One radio communications. Additional libraries allow for further enhancements, such as graphics display capabilities and custom keyboard definitions. The libraries are described in Chapters 3 through 6.
In addition to the libraries, this manual describes a number of utilities also included in the ADK. Some utilities are special purpose programs that can be included in the terminal environment, usually running as TSRs (Terminate and Stay Resident) programs. Others are programming tools necessary to build files or programs to run on the Series 3000 terminal.
Finally, the modem command set is described in Chapter 7. The commands covered include commands supported by the IM3, IM4, IM5, IM6 and IM7 internal modems.
xiii Series 3000 Application Programmer’s Reference Manual
How to Use This Manual This reference manual provides a full format description of each function in each library. In most cases, additional information is provided in other sections such as how to interface from Microsoft C, structure definitions, and a listing of structures used by the library.
The chapters in this manual are as follows:
Chapter 1, Utilities, descrobes a number of utility programs included in the ADK. Some utilities are development tools that run on the development PC. Others are small programs that you can include in the files you download to the terminal.
Chapter 2, Device Drivers, describes a number of device drivers included in the ADK.
Chapter 3, BIOS Library Functions, describes the interface functions in the Symbol BIOS library. This library provides low level control of Series 3000 terminals. These functions essentially provide a C interface for the BIOS calls described in the Series 3000 System Software Manual, which is also distributed with the ADK.
Chapter 4, DR DOS, reviews the interface functions of the Symbol DR DOS library. This library provides interface functions for file creation, opening, closing, reading and writing. It provides functions to read and write input/ output control information. It also includes functions to get an interrupt vector, to allocate memory, to manipulate date and time information, for disk reading and writing, etc.
Chapter 5, UBASIC Record Manager, describes the UBASIC Record Manager (URM) and File Manager functions. These functions provide a homogeneous file and memory management system compatible with older UBASIC-based applications. The also have a C language API.
Chapter 6, Miscellaneous Libraries and Functions, describes the functions in a number of the smaller libraries included with the ADK. These functions provide support for floating point arithmetic, printer interface, graphics, font control, and a few other features. xiv About This Manual
Chapter 7, Internal Modem Command Set, presents the Hayes compatible AT commands and S registers supported by the Symbol internal modems: IM3, IM4, IM5, IM6, and IM7.
Appendix A, Keyboard Codes, provides a table to show scan code to character code mappings for the unshifted, shifted, control, and alternate keyboard states.
Appendix B, Series 3000 Keyboard, describes how key codes are produced on the Series 3000 terminals and provides the standard keyboard definitions. Notational Conventions The following conventions are used in this manual:
• Italics highlight notes. • PC Command Line Syntax: Program names are printed in bold, mandatory parameters are italicized without brackets, optional parameters are italicized with brackets. • PC Commands are indented. • Bullets indicate action items or lists of related items. • “PC” refers to the IBM personal computer or compatible system that is running the development software. • “Terminal” refers to a Symbol Technologies Series 3000 portable data terminal. • “Operator” refers to the terminal operator. • “You” refers to the application programmer. •
pcPC
the platform (i.e., PC, S 3000) on which the function runs. • An arrow (⇒) is used as a line continuation character in a function prototype to indicate that code continued from one line to the next all belongs on one line.
xv Series 3000 Application Programmer’s Reference Manual
Format of Function Descriptions The description of each function in this manual contains the following subsections: Syntax, Description, Return Value, and See Also. The following is a sample function with each part of the format defined. Function Name Names the function. Where applicable, a small darkened text box displays the platform (PC, S3000) on which the function runs (see figure above in Notational Conventions). This text box will appear in the upper right-hand corner of the page, opposite the function name. Syntax #include <3000\header_filename.h>
function return type function_name(data type parameter1, ⇒ data type parameter2, ⇒ data type parameter3)
Note: The arrow (⇒) is used as a line continuation character in a function prototype to indicate that code continued from one line to the next all belongs on one line.
Description A description of what the function does, including warnings and a brief description of the role of each parameter. Return Value Describes the meaning of the function's return value, if one exists. Also describes the meaning of values returned to the function via pointers. See Also Lists other functions related to this one that may provide a similar or counter function. xvi About This Manual
Related Documentation The following related manuals are available for the Series 3000 terminals:
• Series 3000 Application Programmer's Guide (70-16308-xx) This manual introduces the special procedures and tools involved in developing an application program for Series 3000 terminals.
• Series 3000 System Software Manual (70-16310-xx) This manual provides low-level reference information for the Series 3000 terminals. The information is generally intended for the system programmer who needs to know what lies behind the functions provided in the C interface libraries.
• Series 3000 Application Developer’s Library (70-16311-xx) • Spectrum One Development System Application Programmer's Guide (59044-00-92) These manuals describe how to include Spectrum One radio communications in your application.
• Series 3100/3500 Product Reference Guide (70-16645-xx) • Series 3300 System Administration Manual (59040-00-90) • Series 3800 Product Reference Guide (70-32230-xx) • Series 3900 System Administration Manual (61068-00-90) • PDT 6100 Product Reference Guide (70-33222-xx) • PDT 6800 Product Reference Guide (70-32645-xx) • WSS 1000 Product Reference Guide (70-16192-xx) These manuals describe a number of procedures you need to be familiar with for programming Series 3000 terminals.
xvii Series 3000 Application Programmer’s Reference Manual
xviii Chapter 1 Utilities
Chapter Contents Introduction ...... 1-3 BATCHER.EXE...... 1-4 BATCHRF.EXE...... 1-8 DONEBEEP.COM ...... 1-14 DSKBCHK.COM ...... 1-15 DTRON.COM ...... 1-17 Font Builder ...... 1-18 KBD3000.EXE ...... 1-24 KBDMAKE.EXE ...... 1-27 LOADER.EXE...... 1-38 MPM3000.EXE ...... 1-48 Memory Transfer Analyzer ...... 1-51 PDCONVRT.EXE ...... 1-65 RCVHEX.EXE ...... 1-66 SENDHEX.EXE ...... 1-68 STG3000.EXE ...... 1-70 TDREM.EXE ...... 1-72 TFT3000.EXE ...... 1-74 TSRREG.EXE...... 1-76 USRCFG.EXE ...... 1-77
1-1 Series 3000 Application Programmer’s Reference Manual
1-2 Utilities
Introduction This chapter describes the utility programs provided with the Series 3000 ADK. Most of these utilities run on the portable terminal and either condition the operating environment or provide special features that you can include in an application. In most cases, these must be downloaded to the terminal. A few utilities run on the host PC and are provided to assist in program development.
1-3 Series 3000 Application Programmer’s Reference Manual
BATCHER.EXE S3000
BATCHER is a batch file menu manager for Series 3000 terminals. BATCHER reads an initial settings (.ini) file describing a menu and displays the menu according to the instructions in the file. BATCHER detects the dimensions of the terminal screen, so the same input file can be used for any Series 3000 terminal.
BATCHER displays up to 10 menu options plus a menu title. The current option is displayed in reverse video. If more options are defined than can be displayed on a single screen, the additional options can be viewed by scrolling the screen using the arrow keys.
When the operator selects an option, BATCHER returns a DOS error level number from 1 to 10, indicating the option selected. If the operator presses the
The TITLE section is marked by the token [TITLE]. The next line contains the title, consisting of from 1 to 20 characters.
The MENU items section is marked by the token [MENU]. Subsequent lines contain the menu options, up to 18 characters each. Up to 10 menu lines can be provided.
Blank lines are ignored, and any line beginning with a semicolon is considered a comment. Each line, including the last line, must be terminated by a CR/LF. Example The following initial settings file, DEMO.INI, defines a menu with 5 items.
[TITLE] DEFNVM 3.01-00 [MENU]
1-4 Utilities
Order Demo Scanning Demo TDREM COM1-115K TDREM COM2-115K TDREM COM1-38K
Note: The last menu item, TDREM COM1-38K, must end in a CR/LF. Running BATCHER.EXE The syntax for BATCHER is:
BATCHER filename [-Q] or BATCHER filename [-K]
The -Q option specifies quick mode (see below).
The -K option sets the initial keyboard shift state.
For example, to call BATCHER from an application program or batch file using the above example menu, enter:
BATCHER DEMO.INI
When displayed by BATCHER, the menu appears like this:
DEFNVM 3.01-00 Order Demo
Scanning Demo TDREM COM1-115K TDREM COM2-115K TDREM COM1-38K
Item 1 of 5
1-5 Series 3000 Application Programmer’s Reference Manual
Operation BATCHER allows the user to navigate through the menu by using the arrow keys.
Up Arrow Moves highlight bar up one row. Wraps to the bottom of the list when pressed at the top item.
Down Arrow Moves highlight bar down one row. Wraps to the top of the list when pressed at the bottom item.
Left Arrow Moves the highlight bar to the top item.
Right Arrow Moves the highlight bar to the bottom item.
Clear Exits BATCHER returning error level 0.
Enter Selects current item.
Any other keystroke is considered as a search character. When BATCHER is first called, the first item is highlighted. When the operator presses a key, BATCHER searches the menu strings until it finds a matching character. This item becomes the current selection and is highlighted with the current search letter in normal video (not reversed). As more characters are entered, they are added to the search string. The first match of the longer string is then highlighted with the most recent search letter in normal video. This feature is handy for use with numbered menus.
For example, using the DEMO.INI example above, the “Order Demo” item is initially highlighted. If the operator presses T, the highlight bar moves to “TDREM COM1-115K” with the T in normal video. If the operator continues typing “DREM”, the same item “TDREM COM1-115K” remains highlighted, but the current character changes to the first M. If the operator continues typing “
1-6 Utilities
Quick Mode (-Q) BATCHER also provides a Quick Mode option that allows single keystroke menu selection. In this mode, typing a single search character immediately selects (highlights) and executes the first matching item. The operator is NOT required to press
To use quick mode, include “-Q” after the file name on the BATCHER command line, for example:
BATCHER DEMO.INI -Q
Setting the Initial Keyboard Shift State -K Batcher can set the initial keyboard shift state by passing the -K switch on the command line. The -K switch requires a number be passed along with it to indicate the shift state. The number must be in decimal format and represents the bits as defined by the BiosSetKeyboardState function, which is described in the BIOS Library Functions chapter in this manual. If the -K switch is not passed to BATCHER, it takes the current shift state as the default. For example:
BATCHER DEMO.INI -Q -K64 sets the keyboard shift state to Caps Lock upon entry into batcher. Batcher restores the keyboard shift state to the original setting upon exit.
1-7 Series 3000 Application Programmer’s Reference Manual
BATCHRF.EXE Syntax BATCHRF filename
where filename is the name of an initial settings file. Description BATCHRF.EXE is a TSR that transmits data to a Spectrum One® host as a background process while a foreground program gathers data.
BATCHRF requires the name of an initial settings file. The initialization file, which must have a .INI extension, contains configuration information for BATCHRF. The initialization file has two sections: the [DATAFILE] section and the [TIMING] section (see below). Accessing BATCHRF The application program is responsible for enabling and disabling BATCHRF. Four commands are provided in BATCHRFx.LIB for controlling BATCHRF, where x is either S (small model), M (medium model), or L (large model). Refer to the Batch RF Interface Library section of the Miscellaneous Libraries and Functions chapter in this manual for descriptions of these routines.
When the application is ready to collect data and have BATCHRF transmit it, it must do the following.
The application must first create and open the data file in this way (this method is required):
fd = sopen("D:\\filename.dat", (O_RDWR | O_CREAT | O_BINARY), SH_DENYNO, (S_IREAD | S_IWRITE));
This function call opens the data file on the terminal's RAM disk (D:), creates the file and opens it in shared mode, and gives the shared file READ and WRITE attributes.
1-8 Utilities
The application then issues the BRFEnable( ) command. (The output batch data file must exist prior to issuing this command.) The application can then begin writing data to the data file, and BATCHRF begins reading from the file and transmitting.
To end the transmission of data, the application issues the BRFDisable( ) command.
Two additional commands are also provided:
BRFLoadConfig( ) allows an application to load and activate a different initialization file. This command is only valid when BATCHRF is disabled, so error checking should be done, as in the following:
#include <3000\batchrf.h>
if (!BRFLoadConfig("D:\\MYCONFIG.INI") ...error processing
if (!BRFEnable()) ...error processing
The BRFGetStats( ) function allow the application to obtain statistics about what BATCHRF is doing.
For more detailed information on BRFEnable, BFRDisable, BRFLoad Config, or BRFGetStats, refer to the Batch RF Interface Library section of the Miscellaneous Library Functions chapter in this manual. Initialization File Format The [DATAFILE] section of the initial settings file contains the parameters listed in Table 1-1. All of these parameters are required and must be set in the .INI file.
1-9 Series 3000 Application Programmer’s Reference Manual
Table 1-1. Parameters Listed in [DATAFILE] Section
Parameter Description FileName The DOS file name of the application output batch data file on the terminal. TombStoneChar A one-byte HEX value of an ASCII character to use as the tombstone character. The tombstone character is a marker which indicates that a record has been transmitted to, received by, and acknowledged by the host. EndOfRecord A sequence of 1 to 5 HEX bytes marking the end of record. The sequence must be padded to five bytes with zeros (0). The bytes are delimited by commas. HostAck A sequence of 1 to 5 HEX bytes interpreted as acknowledgment (ACK) from the host. The sequence must be padded to five bytes with zeros (0). The bytes are delimited by commas. TxEOR A boolean value telling the TSR whether or not to send the End of Record (EOR) with the record to the host: 1 = Transmit EOR 0 = Do not transmit EOR MaxRecLen The maximum record size in the file, including the EOR sequence (without trailing zeros) and the tombstone character. So, if the data can be up to 21 characters and the EOR sequence is 3 characters, MaxRecLen = 21+ 3 + 1 = 25. The maximum value allowed is 512. MaxRecRetry The number of times the system will retry an original transmission before skipping the record and going on to the next. Set this to zero (0) for infinite retries, which disables the feature.
The [TIMING] section of the initial settings file contains the parameters listed in Table 1-2. All of these parameters are required and must be set in the .INI file.
1-10 Utilities
Table 1-2. Parameters Listed in [TIMING] Section
Parameter Description TxTimer The amount of time, in decimal milliseconds, that BATCHRF waits between record transmissions (1000 recommended). EOFTimeout A boolean value enabling or disabling the End Of File terminal timeout (power off): 0 = Regular keyboard timeout applies. 1 = The terminal does not time out until either: 1. All records are transmitted or skipped, or 2. One hour passes, or 3. Low Battery occurs. RxTimeout The amount of time, in seconds, that BATCHRF waits for a response from the host. Min = 10, Max = 255.
Sample Initialization File [DATAFILE] FileName=D:\COLLECT.DAT TombStoneChar=2B EndOfRecord=1B,1B,7C,0,0 HostAck=6,0,0,0,0 TxEOR=1 MaxRecLen=1A MaxRecRetry=1
[TIMING] TxTimer=1000 EOFTimeout=1 RxTimeout=30
In the above example, the EOR is: ESC,ESC,1. The tombstone character is: +.
1-11 Series 3000 Application Programmer’s Reference Manual
Sample Data Record Each data record consists of the data itself, an End Of Record sequence, and a tombstone character. For example, consider a record with 10 characters of data: [DATA-123]. Appending the EOF sequence in the initialization file above, the record becomes:
[DATA-123],ESC,ESC,|
The commas are not included in the record. Finally, any character other than the tombstone character is appended, marking the record as not tombstoned. Using “@” the record becomes:
[DATA-123],ESC,ESC,|,@
Again, the commas are not included.
Since this record is not terminated by the tombstone character (“+”), BATCHRF transmits it to the host. Following transmission and acknowledgment by the host, BATCHRF uses the tombstone character to mark the record as transmitted. The record is now:
[DATA-123],ESC,ESC,|,+
Notes 1. Don't make the TxTimer patameter too small. A time of 500 to 1000ms is recommended. Too small a time causes the program to spend too much time interrupting to check for a record to transmit, slowing down the foreground process. 2. Each record transmitted includes the data and/or the EOR sequence. The tombstone character never gets transmitted. The maximum transmitted length is 512 bytes. 3. If the batch application program uses a normal protocol such as batch dumping of data through a cradle to send records to the host, it should inspect each record for the TombStoneChar, and send the records accordingly. It could also send all records and let the host program sort through looking for records it does not already have.
1-12 Utilities
4. Since an application typically spends most of the time waiting for keyboard or scanner input, it should use BiosGetChar( ) to get the first character. This allows the use of power save mode and keeps the application out of DOS. While in DOS the TSR cannot read from or write to either the disk file or radio. 5. After issuing a BRFDisable( ), the application must remove tombstoned records from the file before it issues the next BRFEnable( ). On enabling, BATCHRF starts examining records from the beginning of the file, examining one record every TxTimer milliseconds. If there are many tombstoned records, a long period of time can pass before the TSR finds a record to transmit. A copy of the original file can be kept for later use or downloading to the host. 6. BATCHRF requires that SHARE.EXE be loaded. SHARE.EXE is on the C:\3000 directory in the ADK. 7. BATCHRF requires a connect program to be run before calling BRFEnable ( ). Use SRCP as the connect program. 8. BATCHRF requires that SLP.SYS driver and S1.BIN drivers be loaded.
1-13 Series 3000 Application Programmer’s Reference Manual
DONEBEEP.COM PC S3000
Purpose Use DONEBEEP in a batch file to cause the PC or terminal to emit a beep. Included in a batch file to alert the operator when a task has completed. Syntax donebeep
Description DONEBEEP causes the PC or terminal to emit a beep. To use on a terminal, it must be downloaded to the terminal.
1-14 Utilities
DSKBCHK.COM S3000
Purpose DSKBCHK checks to see if the terminal has been configured with a drive B. Syntax dskbchk
Description Every terminal has a drive A (the system EPROM) and may be configured to have a drive B. If the configuration includes a drive B, you may call a batch file on drive B from A:\AUTOEXEC.BAT. For example, you can chain from the end of A:\AUTOEXEC.BAT to the beginning of B:\AUTOEXEC.BAT to set additional control and setup parameters.
Especially during development, the terminal may be set up sometimes with a drive B and sometimes without. Calling a batch file in a drive that does not exist prematurely terminates the calling batch file. Using DSKBCHK to check for the existence of drive B allows a batch file to make a conditional call, thereby avoiding the error.
DSKBCHK returns a DOS errorlevel code indicating whether drive B is present. The DOS errorlevel codes returned are:
0 Success: Drive B exists. 1 Fail: Drive B does not exist.
The following sample lines can be included in A:\AUTOEXEC.BAT and demonstrate how to use the DSKBCHK utility to transfer control conditionally:
1-15 Series 3000 Application Programmer’s Reference Manual
Sample dskbchk if errorlevel 1 goto no_b goto yes_b :no_b rem There is no drive B: quit go to end :yes_b rem This is a drive B: :end rem End
1-16 Utilities
DTRON.COM PC
Purpose Use DTRON on the host PC to raise DTR at the beginning of a data transfer to a terminal. Syntax dtron
Description When placed at the beginning of a data transfer batch file, DTRON ensures that DTR is raised before any data is sent.
When transferring data from a PC to a Series 3000 terminal, the system tries to raise DTR before sending any data. However, the time span between enabling the PC's and the terminal's data transmission may be too short for the terminal to raise DTR in time. Including DTRON in the PC batch file ensures that DTR is raised on the terminal before data transmission begins.
1-17 Series 3000 Application Programmer’s Reference Manual
Font Builder PC
Purpose Font Builder is a utility for designing fonts and building font definition tables. The resulting font definitions can be loaded into the terminal as the default font, run as a TSR, or executed by an application. Syntax FONTBLD [font_filename]
where font_filename is the name of a font file without the filename extension. If the file does not exist, Font Builder prompts for the necessary information to create one. See the Procedure section below. Procedure If you do not enter a filename on the command line, the Font Builder will prompt for one:
Load File Name (.FNT):
When you specify a filename that exists, the program loads the file. If you specify a new filename, the program prompts:
File does not exist. Create? (Y):
Press Y(es) or
You are then prompted for the font controller type:
Font Format [0-61202/3 1-61830 2-82C425]: 0
Select 0, the controller type for Series 3000 terminals.
You are then prompted for the character width. The permitted character width and height is constrained by the controller chip. For Series 3000 terminals, you can use a width of 6 or 7 and a height of 8.
1-18 Utilities
Sample FONTBLD PC6X8
Screen Windows The Font Builder screen is divided into four windows. Each window is described below.
• The Font window displays the complete character table from the font file. • The Text window displays the font characters in string format. The characters can be entered from the keyboard or copied from the font window. • The Character window displays the character being edited. • The Help window displays available commands and the method to invoke them. Commands are entered as single key commands or via
ALT-S Saves the Font Window to a font file without exiting. Specify save options in response to the prompts as displayed. ALT-Q Quits without saving. ALT-E Exits and saves the Character Table to the same font file with the same format. ALT-N Moves cursor to window n, where n = 1, 2, or 3. 1 = Font Window, 2 = Text Window, 3 = Character Window. ALT-F10 Displays the [Alt] key commands in the Help Window. Shift-F10 Displays the [Shift] key commands in the Help Window. (Supported in the Character Window only.) TAB Moves the cursor to the next window.
1-19 Series 3000 Application Programmer’s Reference Manual
Font Window Commands The following keystroke commands can be used in the Font window:
ENTER Selects the currently highlighted character for editing and places the cursor in the Character Window. Moves cursor up one character. Moves cursor down one character. Moves cursor left one character. Moves cursor right one character. Home Moves cursor to the leftmost character on the current row. End Moves cursor to the rightmost character on the current row. PgUp Moves cursor to the top character in the current column. PgDn Moves cursor to the bottom character in the current column. F1 Copies the character under the cursor to a buffer. Use this command to copy characters between the Font and Text Window. Instead of creating a character from scratch, use this to modify an existing character. F2 Copies the character in the buffer to the current character position. See [F1]. Del Deletes the currently highlighted character. Ins Undeletes - place the most recently deleted character (in the buffer) to the currently highlighted character position.
1-20 Utilities
Character Window Commands The following keystroke commands can be used in the Character window:
Moves highlight up one pixel. Moves highlight down one pixel. Moves highlight left one pixel. Moves highlight right one pixel. Home Moves highlight to the leftmost pixel on the current row. End Moves highlight to the rightmost pixel on the current row. PgUp Moves highlight to the top pixel in the current column. PgDn Moves highlight to the bottom pixel in the current column. Enter Saves the character to the Font Window. Esc Refreshes the Character Window to the character occupying the window before editing began. Space Toggles the currently highlighted pixel on or off. ++ Toggles the currently highlighted pixel on or off. Easy to use when using the keypad. Ins Turns the currently highlighted pixel ON. Del Turns the currently highlighted pixel OFF. Shift-* Toggles the highlighted pixel on or off while moving the cursor up one position.
* To use this keystroke on the PC, turn off NumLock and use the keys on the numeric keypad.
1-21 Series 3000 Application Programmer’s Reference Manual
Shift-* Toggles the highlighted pixel on or off while moving the cursor down one position. Shift-* Toggles the highlighted pixel on or off while moving the cursor to the left one position. Shift-* Toggles the highlighted pixel on or off while moving the cursor to the right one position. Shift- Toggles all the pixels in a row on or off from the Home* current cursor position to the leftmost position in the row while moving the cursor to the leftmost pixel position in the row. Shift-End* Toggles all the pixels in a row on or off from the current cursor position to the rightmost position in the row while moving the cursor to the rightmost pixel position in the row. Shift-PgUp* Toggles all the pixels in a column on or off from the current cursor position to the top of the column while moving the cursor to the top pixel position in the column. Shift-PgDn* Toggles all the pixels in a column on or off from the current cursor position to the bottom of the column while moving the cursor to the bottom pixel position in the column. Shift-Ins* Turns all the pixels in the Character Window ON. Shift-Del* Turns all the pixels in the Character Window OFF.
* To use this keystroke on the PC, turn off NumLock and use the keys on the numeric keypad.
1-22 Utilities
Text Window Commands The following keystroke commands can be used in the Text window:
BackSpace Moves the cursor to the left and clears the character. Esc Clears the window and places the cursor in the upper left- hand corner of the window. Moves cursor up one character. Moves cursor down one character. Moves cursor left one character. Moves cursor right one character. Home Moves cursor to the leftmost character on the current row. End Moves cursor to the rightmost character on the current row. PgUp Moves cursor to the top character in the current column. PgDn Moves cursor to the bottom character in the current column. Del Deletes the currently highlighted character. Ins Undeletes - place the most recently deleted character (in the buffer) to the currently highlighted character position.
1-23 Series 3000 Application Programmer’s Reference Manual
KBD3000.EXE S3000
KBD3000.EXE is a keyboard redefinition program that runs on Symbol Series 3000 terminals as a TSR.
KBD3000 uses less than 6K of memory.
KBD3000 redefines the keyboard according to data provided in a (.KBD) file generated by the Keyboard Mapping utility, which is described in the KBDMAKE.EXE section of this chapter and in the chapter on Keyboard Processing in the Series 3000 Application Programmer’s Guide.
All arguments are optional. If no arguments are given, KBD3000 just loads resident and performs no keyboard redefinition.
KBD3000 can be accessed from an application program through C interface routines. Refer to the KBD3000 Interface Functions section in the Miscellaneous Libraries and Functions chapter of this manual for descriptions.
TSRREG.EXE must be loaded before loading KBD3000; otherwise, KDB3000 will exit, returning an error to the DOS shell. For a description of the TSRREG utility, refer to the TSRREG.EXE section later in this chapter.
See below for error codes returned to DOS. Syntax KBD3000 -STD=[a
where:
-STD represents the standard attached keyboard.
1-24 Utilities
a represents automatic search mode. Finds files with the extension .KBD, and searches through those files for the specified emulation
f represents a specific file
-AUX represents the auxiliary attached keyboard.
a represents automatic search mode. Finds files with the extension .KBD, and searches through those files for the specified emulation
f represents a specific file
-RST commands the loaded TSR to restore the auxiliary (a) or standard (s) keyboard. Examples 1. This command loads a file with the current keyboard configuration which has the emulation keyword VT100 in the header. Then loads the file S3395V1.KBD from the B: drive: KBD3000 -STD=a VT100 -AUX=f B:S3395V1
2. Loads the file S3395V1.KBD from the B: drive. Performs no redefinition of the standard keyboard. KBD3000 -AUX=f B:S3395V1
3. Restores the standard keyboard to the original definition table which existed when KBD3000 was first loaded. To restore both keyboards at once use RST=s: KBD3000 -RST=s
1-25 Series 3000 Application Programmer’s Reference Manual
4. Performs no redefinition from the command line: KBD3000
KBD3000 Software Programming Interface There are several commands available for use in a C program to access the keyboard definitions. These commands are in the Symbol Utility library. There are three models of this library: \3000\LIB\SYMUTILx.LIB, where x = S, M, or L, indicating the small, medium, or large model, respectively.
Refer to the KBD3000 Interface Functions section in the Miscellaneous Libraries and Functions chapter of this manual for descriptions of these commands.
1-26 Utilities
KBDMAKE.EXE PC
The KBDMAKE.EXE (the Keyboard Mapping utility or Keyboard Mapper) is a graphical program that simplifies the process of designing a custom keyboard layout.
KBDMAKE can produce two types of keyboard definition files: resident files and KBD3000 data files. The resident file can be included in the terminal NVM image to define the default keyboard. The KBD3000 is used as a data file for KBD3000.EXE, making keyboard definition changes dynamic and eliminating the need to reboot the terminal. These files can be used separately or together, depending on the needs of the application.
The interface is intuitive, using the window, menu, button, and dialog box methods familiar to users of Microsoft Windows®. The following description highlights the procedure only; it does not attempt to be a complete explanation of how to use the program.
Note: KBDMAKE does not include support for the WSS 1000, which has a unique 3-character per key keyboard. To remap a WSS 1000 keyboard, do WHAT???? Reviewers, please fill in. Program Requirements KBDMAKE employs a graphical user interface, and so requires a VGA display on the development PC. A mouse is required for making selections on the screen.
Note: KDBMAKE must be run from the c:\3000 directory. Starting the Keyboard Mapper Start KBDMAKE by entering at the DOS command prompt:
1-27 Series 3000 Application Programmer’s Reference Manual
> set fg_display=VGA12 > cd \3000 > kbdmake
A window and menu bar is displayed with the About Keyboard Mapper dialog box. Click on OK to clear the dialog box. Creating and Editing a Keyboard Layout To edit an existing keyboard definition file, select Open under the File menu, then select the file to edit. The keyboard screen for this definition is then displayed (Figure 1-1).
Series 3300 35-key Keyboard
Keyboard States SPACE ALPHA SHIFT CTRL FUNC Unshifted
[] ’ = On/Off Shifted Control * / , \ ; Alternate LF Arrow RT Arrow UP Arrow DN Arrow + Num Lock
78 9CLEAR Caps Lock Alpha Lock 45 6BKSP Function
12 3 ENTER 0 -
Figure 1-1. Sample KBD 3000 Keyboard Screen
To create a new keyboard definition based on a standard keyboard, select New under the File menu. A dialogue box is displayed listing the currently available terminal types. Terminals are listed by general model number (e.g. 3310 is included in the 3300 type) and number of keys. Select the item that matches the terminal you are programming and click OK. The program then displays a keyboard screen, as illustrated in Figure 1-1.
1-28 Utilities
The keyboard display screen has two sections: a keypad and a keyboard panel. The current keyboard state is indicated by the darkened button in the keyboard state panel. The keypad indicates the characters assigned to each key in the current keyboard state. Click on the state button to change the shift state displayed.
1-29 Series 3000 Application Programmer’s Reference Manual
To edit the characters assigned to a key, press on that key by clicking on it. The Key Definition dialog box for this key is then displayed (Figure 1-2). The key is described in five columns:
Default - The characters assigned to this key in the standard (default) keyboard mapping. These characters never change.
Displayed - The legend shown on the key indicating the character assigned to this key and keyboard state. This field can be edited, though it should reflect the character assignment.
Overlay - This legend is included for the key when the keyboard overlay specification is printed. Unless a legend is entered, this field is left blank. It is useful when designing a keyboard overlay template.
Scan Code - The keyboard scan code generated by the key, in decimal. This value is determined from the value assigned to the key and cannot be edited.
ASCII Code - The ASCII value of the character generated by the key, in decimal. This value is determined from the value assigned to the key and cannot be edited.
LABELS Scan ASCII DEFAULTDISPLAYED OVERLAY Code Code
Unshifted a a 30 97
Shifted A A 30 65
Control ^A ^A 30 1
Alternate Alt-A Alt-A 30 0
Num Lock a a 30 97
Caps Lock A A 30 65
Alpha Lock A A 30 65
Function A A 30 65
Key ID: 6
NextPrev Default OK Cancel
Figure 1-2. Key Definition Screen
1-30 Utilities
To change the character assigned to the key for a keyboard state, click on the button in the DEFAULT column. The Key Selection dialog box is displayed (Figure 1-3).
Selection:^A Custom Scan Code: 30
ALPHABETIC NUMERIC FUNCTION/SPECIAL PUNCTUATION/MISC.
a 0 F1 No-Action b 1 F2 { c 2 F3 } d 3 F4 [ e 4 F5 ] f 5 F6 - (NUM) g 6 F7 + (NUM) h 7 F8 * (NUM) i 8 F9 . (NUM) j 9 F10 0 (NUM) k ) HOME 1 (NUM) l ! END 2 (NUM) m @ INS 3 (NUM)
OK Cancel
Figure 1-3. Key Selection Screen
To select a character, scroll through the four lists until the desired character is displayed, then click on it. The character is displayed in the Selection box and its scan code is shown in the Scan Code box. Then click on OK.
Note that not all characters can be generated in all keyboard states. For example, only shifted characters, such as upper case letters, can be generated in the shifted state. So, in the shifted state, even if you assign the character “a”, the terminal generates “A”, the shifted variant.
Repeat the above process for each key and state you need to define. Then use the Save or Save As option under the File menu to save your definition. The keyboard file can be saved in a different directory by specifying the path and a filename of up to 65 characters. Generating Keyboard Files Once the keyboard definition has been created, you generate the definition file. You can generate either or both a .KBD file or a .C source file. The .KBD file is used by KBD3000.EXE as keyboard definition data. The .C file is for including in the source for an NVM image file.
1-31 Series 3000 Application Programmer’s Reference Manual
To generate the keyboard definition file or files, select Generate under the Tools menu. Select the file type to generate and click on OK.
The Generate screen includes an Emulation field. This is a text field in which you can enter the name of an emulation, such as “VT100” or “5250.” The emulation field is used by KBD3000 to restrict its file search to keyboard definitions matching the emulation. Refer to the description of KBD3000.EXE for information on this feature. Additional Features Additional menu options are available for use in KBDMAKE. These are mostly self-explanatory.
Under the Tools menu:
Select Colors - select a color scheme
Select Printer - select the default printer
Save Settings - save the current color scheme and printer as the default.
Under the File menu:
Print - Print keyboard definitions. You can choose to print keyboard definitions for all or selected keyboard states, and can include a key-by- key listing (individual keys option). Creating a Keyboard Map Manually Although KBDMAKE.EXE automates the process of creating a keyboard map, it is possible to create one manually. In order to do this, it is necessary to first understand what mapping does and how the mapping table is organized.
When mapping occurs the scan code that is generated by the active key is changed based upon the modifier state. Each modifier state has associated with it two look up tables. The first table is a list of scan codes to be mapped, the second is the scan code to be substituted (mapped) for the scan code found in the first table.
1-32 Utilities
For example, if the keyboard is in the ‘Fn state’ and the ‘A’ key is pressed, the ‘Fn state’ table is scanned to see if the scan code for the active key (the ‘A’ key) is present in the table. If it is, the position of the ‘A’ key in the first table is used as an index into the second table. The value retrieved from the second table is the scan code to be returned for that key in that particular state. Using this scheme, keys can not only be moved, but moved based on the keyboard state, allowing greater flexibility.
The format of the scan code translation tables are as follows:
; ; AVAIL_STATE is used to control whether redefinition is enabled for each ; keyboard state. A 1 in the bit position corresponding to the keyboard ; state mask given below enables redefinition; a 0 disables it. ; AVAIL_STATE DB 11101111b; 7 6 5 4 3 2 1 0
;; Bit 0 - unshifted ;; Bit 1 - shifted ;; Bit 2 - cntrl ; ; Bit 3 - alt ;; Bit 4 - undefined ;; Bit 5 - num lock ;; Bit 6 - caps lock ;; Bit 7 - function
;
;* Initialize state translation table sizes (all 7 bytes required - 00 indicates no ; entries in that table)
;
DB table0_size ; Size of UNSHIFTED table DB table1_size ; Size of CAPS LOCK table DB table2_size ; Size of SHIFT table DB table3_size ; Size of NUM LOCK table DB table4_size ; Size of CONTROL table DB table5_size ; Size of ALTERNATE table DB table6_size ; Size of FUNCTION table
1-33 Series 3000 Application Programmer’s Reference Manual
; STATE_COUNT EQU ($ - avail_state) - 1
;------
; UNSHIFTED redefinition table ; table0 LABEL BYTE ; ; Scan Codes to redefine ; ; NONE ; ; Translations of scan codes ; ; NONE ; table0_size EQU ($ - table0)/2
;------
; CAPS LOCK redefinition table ; table1 LABEL BYTE ; ; Codes to redefine ; DB LBRACKEY, RBRACKEY, QUOTE, EQUALKEY, ASTERIKEY DB FSLASH, MINUS, PLUSKEY, PERIOD, COMMAKEY DB BSLASH, SEMIKEY, LFARR, RTARR, UPARR, DNARR DB N7KEY, N8KEY, N9KEY, N4KEY, N5KEY, N6KEY, N1KEY DB N2KEY, N3KEY, N0KEY ; ; Translations of codes ; DB AKEY, BKEY, CKEY, DKEY, EKEY DB FKEY, GKEY, HKEY, IKEY, JKEY DB KKEY, LKEY, MKEY, NKEY, OKEY, PKEY DB QKEY, RKEY, SKEY, TKEY, UKEY, VKEY, WKEY DB XKEY, YKEY, ZKEY ;
1-34 Utilities table1_size EQU ($ - table1)/2
;------
; SHIFTED redefinition table ; table2 LABEL BYTE ; ; Codes to redefine ; ; NONE ; ; Translations of codes ; ; NONE ; table2_size EQU ($ - table2)/2
;------
; NUM LOCK redefinition table ; table3 LABEL BYTE ; ; Codes to redefine ; ; NONE ; ; Translations of codes ; ; NONE ; table3_size EQU ($ - table3)/2
;------
; CONTROL redefinition table ; table4 LABEL BYTE ; ; Codes to redefine
1-35 Series 3000 Application Programmer’s Reference Manual
; DB BKSP, LBRACKEY, RBRACKEY, QUOTE, EQUALKEY DB ASTERIKEY, FSLASH, MINUS, PLUSKEY, PERIOD DB COMMAKEY, BSLASH, SEMIKEY, LFARR, RTARR DB UPARR, DNARR, N7KEY, N8KEY, N9KEY, N4KEY DB N5KEY, N6KEY, N1KEY, N2KEY, N3KEY, N0KEY ; ; Translations of codes ; DB SCRLCK, AKEY, BKEY, CKEY, DKEY DB EKEY, FKEY, GKEY, HKEY, IKEY DB JKEY, KKEY, LKEY, MKEY, NKEY DB OKEY, PKEY, QKEY, RKEY, SKEY, TKEY DB UKEY, VKEY, WKEY, XKEY, YKEY, ZKEY ; table4_size EQU ($ - table4)/2
;------
; ALTERNATE redefinition table ; table5 LABEL BYTE ; DB CNTLKEY, LBRACKEY, RBRACKEY, QUOTE, EQUALKEY DB ASTERIKEY, FSLASH, MINUS, PLUSKEY, PERIOD, COMMAKEY DB BSLASH, SEMIKEY, LFARR, RTARR, UPARR, DNARR DB N7KEY, N8KEY, N9KEY, N4KEY, N5KEY, N6KEY, N1KEY DB N2KEY, N3KEY, N0KEY ; ; Translations of codes ; DB ALTKEY, AKEY, BKEY, CKEY, DKEY DB EKEY, FKEY, GKEY, HKEY, IKEY, JKEY DB KKEY, LKEY, MKEY, NKEY, OKEY, PKEY DB QKEY, RKEY, SKEY, TKEY, UKEY, VKEY, WKEY DB XKEY, YKEY, ZKEY ; ; table5_size EQU ($ - table5)/2
1-36 Utilities
;------
; FUNCTION redefinition table ; table6 LABEL BYTE ; ; Codes to redefine ; DB SPACEKEY, CNTLKEY, BKSP, LBRACKEY, RBRACKEY DB LFARR, RTARR, UPARR, DNARR, N7KEY, N8KEY, N9KEY DB N4KEY, N5KEY, N6KEY, N1KEY, N2KEY, N3KEY DB N0KEY ; ; Translations of codes ; DB TABKEY, ALTKEY, DELETE, INSERT, TILDAKEY DB HOME, ENDKEY, PGUP, PGDN, F7, F8, F9 DB F4, F5, F6, F1, F2, F3 DB F10 ; table6_size EQU ($ - table6)/2
;------
1-37 Series 3000 Application Programmer’s Reference Manual
LOADER.EXE The NVM Loader utility, LOADER.EXE, is an executable program for downloading an NVM image file to a Series 3000 terminal. It is similar to the Command Mode program loader except that it runs off the terminal A: drive instead of requiring a reboot. Since it is an executable file, the download procedure can be initiated by an application program or batch file running on the terminal.
Note: LOADER.EXE is included in the terminal’s system image (in BIOS) in EPROM. It is not part of the Series 3000 Application Development Kit.
The NVM Loader can run interactively or automatically. When run interactively, the utility prompts the operator for communications parameters through a series of menus and prompts. These menus and prompts are self- explanatory and are not described here (refer to the chapter on Programming a Series 3000 Terminal in the Series 3000 Application Programmer’s Guide). In automatic mode, the utility can be started by an application running on the terminal and download a new NVM image without operator intervention. Communications parameters for automatic mode are provided by command line parameters and default values.
The version of LOADER.EXE included in the 3.03 System EPROM includes support for the IM5 modem. Operating Modes The NVM Loader has two modes of operation: menu and command line.
In menu mode, the terminal operator executes the command without command line parameters. The utility displays a series of screens prompting the user for the communications parameters, providing default values for each parameter. At each screen the user either selects a different value or simply presses return to accept the default. Once all parameters are provided, the operator is prompted to press Enter to begin receiving data.
1-38 Utilities
The menu interface is intelligent to the extent that later screens are skipped if an earlier parameter makes it irrelevant. For instance, if a specific modem is specified, the utility will not prompt for the baud rate since each modem supports s specific baud rate.
In command line mode, the operator executes the command with parameters to specify one or more communications parameters. Each parameter is prefixed with either a dash, “-”, or a plus, “+”. Menus are still displayed for parameters that are either not specified or are prefixed with “+”. Command line arguments prefixed with “-” are skipped.
In both modes of operation, the utility pauses for the operator to confirm proceeding with two operations: erasing NVM and beginning to receive data. These prompts can also be disabled by specifying the -A command line parameter making the entire operation automatic. In automatic mode, the entire download procedure can be conducted unattended, without operator intervention. This is useful, for instance, to allow an application running on the terminal to initiate downloading a new NVM image during off hours when no operator is available. LOADER.EXE Issues The WS-10XX BIOS and User NVM image both contained are on a single FLASH chip. The chip therefore contains the User NVM image (which is replaced by using LOADER.EXE) and the BIOS routines which LOADER.EXE executes in order to burn the chip. The implication is that when LOADER.EXE is executed it will need to read from the chip it is trying to reprogram. Unfortunately, the chip cannot be written to and read from simultaneously.
This requires that the BIOS (which contains the NVM loader routines to burn the chip) be copied to RAM before it is executed, but even before that can occur, RAM must be available into which the BIOS can be copied. The WS-10XX has a 512K RAM mode, allowing the BIOS to be copied into the extra 128K RAM making it safe for use by the NVM loader.
To enter 512K RAM mode, a new input was added to the "Force System Boot" (INT BCH) interrupt which allows the system to cold boot with a preset amount of memory.
1-39 Series 3000 Application Programmer’s Reference Manual
The proper procedure for invoking LOADER.EXE is...
If terminal type == WS-10XX (Get BIOS and Hardware Version, INT AFh) { If RAM == 640K (Get Actual Size of RAM, INT AB, fn 10h) { Cold boot in 512K mode (Force System Boot, INT BCh, AL = 2, CX = 512) } } Run A:LOADER.EXE
USER NVM Programming The WS-10XX uses a single FLASH chip to hold the BIOS, user NVM, and BIOS Program Loader. Since the FLASH part cannot be executed from and written to simultaneously, hardware and software were designed into the WS-10XX to allow the BIOS to execute from RAM (and thus be able to write to FLASH). The proper way to program user NVM is as follows:
Get Terminal Type ( ASM - Get BIOS and Hardware Version, Int AFh, C - BiosVersions() )
If Terminal Type == WS-10XX (4) Get RAM Size ( ASM - Get Actual Size of RAM, Int ABh, fn 01h, C - BiosGetRamSize() ) If RAM Size != 512 Cold Boot in 512K RAM Mode ( ASM - Int BCh, AL=2, CX=512, C - No call ) endif Map BIOS to RAM ( ASM - Map BIOS to ROM/RAM, Int ABh, AH=12h, AL=1, C - No call ) Perform NVM write operations Map BIOS to ROM ( ASM - Map BIOS to ROM/RAM, Int ABh, AH=12h, AL=0, C - No call ) Cold Boot in 640K RAM Mode ( ASM - Int BCh, AL=1, C - no call ) endif
1-40 Utilities
What happens is that if the term type is WS-10XX, you initially need to reboot into a 512K RAM mode. This frees up the top 128K of RAM for use as a BIOS shadow RAM area. After the reboot you'll detect that you're in 512K mode and then Map the BIOS to RAM. At this point you can use the NVM services. Then the BIOS is mapped back to ROM, and the unit is rebooted back to 640K mode. Program Termination The NVM loader accepts three abort keys to interrupt processing:
• F1 (Func + 1) restarts data entry without changing previously entered values. • F2 (Func + 2) restarts data entry, restoring all parameters to their defaults. • F10 (Func + 0), like F1, restarts data entry without changing previously entered values, and turns off automatic mode.
1-41 Series 3000 Application Programmer’s Reference Manual
Modem Priority Since loader can use external modems as well as internal modems in both the cradle and the terminal, a conflict can arise over which modem is to be used in the communications session. LOADER.EXE selects the modem to use according to the following priorities:
1. Internal cradle modem 2. Internal terminal modem 3. External modem Syntax The command format is:
loader [{-|+}parameter]...
Parameters:
- = skip menu
+ = show menu using selection as default
Px = Protocol, where x can be:
0 = Spectrum 1 = 2-way 2 = Standard (default)
Wx = Origination, where x can be:
0 = Answer 1 = Dial
Mx = Modem type, where x can be:
0 = None 1 =103 300 bps FDX 2 = 212 1200 bps FDX 3 = v21 300 bps FDX 4 = v23 1200 bps HDX
1-42 Utilities
5 = v22 1200 bps FDX 6 = v22bis 2400 bps FDX 7 = v42bis FDX (2400 bps with data compression and error correction, IM5 only)
Bx = Baud rate
0 =300 bps 1= 600 bps 2 =1200 bps 3 = 2400 bps 4 = 4800 bps 5 = 9600 bps 6 = 19200 bps 7 = 38400 bps
Xx = Flow control, where x can be:
0 = none 1 = Xon/Xoff 2 = RTS/CTS
Ex = Parity/Data, where x can be:
0 = Even/7 bits 1 = Odd/7 bits 2 = Space/7 bits 3 = None/8 bits
Fstr, where str is a file name up to 40 characters.
Nstr, where str is a telephone number up to 40 chars
Ax = Auto-mode, where x is the number of retries (default = 3).
1-43 Series 3000 Application Programmer’s Reference Manual
Examples The following are valid command lines:
loader -p -b -ffilename +N(213)555-1234
loader -P0 -B1 -Ffilename +n(714)555-5678 -M1
Error Messages LOADER.EXE reports four error messages: • Download Error • Modem Error • Communications Error • Spectrum One Network Error
Each error is accompanied by an error number further specifying the precise error that occurred, as listed below in Tables 1-3 through 1-6. Table 1-3. NVM Loader Utility Download Error Messages
Number Description 1 Programming voltage is not present. This error typically indicates that the terminal is not in a charging cradle or connected to an auxiliary power source as required to erase and program the EEPROM. 2 Flash EEPROM erase failure. This error typically indicates that programming voltage was lost during the EEPROM erase phase. Otherwise, a hardware failure has occurred. 3 Intel .HEX checksum error. This error should only occur when using the Standard protocol since the Spectrum One and 2-Way protocols are self- correcting. Repeat the download. 4 Invalid download address. The destination address is not within the EEPROM physical address space (A0000h to DFFFFh). The error can be the result of a communications error, an improperly built .HEX file, or missing address extension record. Try repeating the download. If the error repeats, rebuilt the .HEX file.
1-44 Utilities
Table 1-3. NVM Loader Utility Download Error Messages (Continued)
Number Description 5 Flash EEPROM programming failure. There are two typical causes of this error: 1. The image is larger than the size of the EEPROM. 2. Programming voltage was lost during programming. Otherwise, a hardware or EEPROM failure occurred. 6 Invalid Intel .HEX record type. This should not occur if USRCFG is used to build the image. If repeating the download fails, rebuild the .HEX file. 7 NVM CRC failure. After the entire .HEX file is received, the CRC tests that the file was received correctly. This error should only occur when using Standard protocol. Repeat the download. 8 User aborted. The user pressed the terminal Abort key.
Table 1-4. NVM Loader Utility Modem Error Messages
Number Description 1 Serial open error. The BIOS open service failed when attempting to initialize the modem. 2 Modem initialization failure. The modem did not correctly respond to the initialization string sent by the loader. Typically, either the modem is not connected or does not have power. Correct and repeat the download. 3 Dialing attempt failed. Failure is reported only after 10 failures at 1 minute intervals. The reason for each failure is displayed for 3 seconds. Most common causes are a wrong number, line busy or not answered, an incompatible remote modem, or an incorrectly connected local modem. 4 Answer attempt failed. The loader failed to connect to the host modem after answering an incoming phone call. The error is reported only after 3 successive failures. The result of each failed phone call is displayed for 3 seconds. The most common reasons for failure are a wrong number, and incompatible remote modem, or an incorrectly connected local modem. 5 Internal cradle modem access failure. This error is reported if, when using a modem cradle, the loader does not receive control of the modem when it requests it. The error should not occur on single-slot cradles. On multiple slot cradles this error indicates that another terminal in the cradle has control of the cradle data bus.
1-45 Series 3000 Application Programmer’s Reference Manual
Table 1-4. NVM Loader Utility Modem Error Messages (Continued)
Number Description 6 No internal modem detected. V.42bis was selected as the modem type, but no IM5 internal modem was found.
Table 1-5. NVM Loader Utility Communications Error Messages
Number Description 1 DOS device setup failure. DOS could not open the COM device driver. 2 Start protocol failure. The loader could not correctly attach itself to the host using the selected protocol. Usually, the protocol has timed out due to an incompatible setup or an incompatible host device. 3 Close protocol failure. The selected protocol failed to correctly close the protocol after sending the file request or at completion of the download. This is typically caused by losing the protocol connection between the devices. 4 Open line failure. The loader failed to connect to the remote device. This is typically caused by a faulty physical connection and the BIOS timed out waiting. 5 Serial port initialization failure. The serial port could not be configured using the parameters specified. 6 Protocol initialization failure. The selected protocol could not be correctly configured. 7 Protocol selection failure. The specified protocol could not be selected. 8 General protocol read failure. A fatal protocol error occurred while reading data from the communications line. This is usually caused by losing the communications connection between the terminal and the host. 9 General protocol write error. A fatal protocol error occurred while transmitting the file request to the host. This error is usually caused by losing the communications connection between the terminal and the host.
1-46 Utilities
Table 1-6. NVM Loader Utility Spectrum One Network Error Messages
Number Description 81h Cannot open file. The Spectrum One NCU could not open the file requested for downloading. 82h Unknown terminal type. A default file was requested for an unknown terminal type. This is usually caused by using outdated NCU software with a new terminal model. 83h File not found. The Spectrum One NCU could not find the requested file. Verify that the requested file is in the specified directory and that the file name is correct. 84h No file name. A name was not specified on the NCU for the file or file number sent by the remote. This error is reported only if using a numbered file request or the default file specification. 85h Cannot read file. The Spectrum One NCU could not read the requested file. 86h Code format not allowed (network bridge only). A numbered file was requested by the loader. The network bridge does not support numbered file requests. File names must be explicit.
1-47 Series 3000 Application Programmer’s Reference Manual
MPM3000.EXE S3000
MPM3000 (Macro Processing Manager) is a TSR that records, stores, and executes keyboard macros on Series 3000 terminals. MPM3000 runs on terminals with system EPROM 3.02 and higher.
MPM3000 requires 10K of terminal memory. TSRREG.EXE must also be running prior to executing MPM3000.EXE. Refer to the TSRREG.EXE section of this chapter for a description of the TSRREG utility.
Macros are saved on the terminal's RAM disk (D:). Each macro file can contain 32 macros of 64 keystrokes each. The file occupies 4160 bytes of space, whether or not all macro definitions are used.
A macro file is loaded using the -L command line option. If MPM3000 is already loaded, you can replace the current file by running MPM3000 again specifying the new file with the -L option. Syntax MPM3000 [-L filename] [-H xxyy] [C]
-L The -L (LOAD) option loads the macro file filename. A file must be specified with this option. The filename can be any valid DOS filename and path. All macros in that file are now active. If the -L option is not used, the default macro file, D:\CURRENT.KMF, is loaded.
-H The -H (Hotkey) option assigns a new key sequence as the Record hotkey. The value xxyy specifies the Scan Code / ASCII Code pair in hexadecimal. xx is the two digit Scan Code and yy is the two digit ASCII Code. The default Record hotkey is CTRL-R (1312h).
-C The -C option disables the macro chaining function, and keys which would branch to another macro will be treated as regular keys.
1-48 Utilities
Recording Macros 1. To Record a macro, press the Record hotkey (CTRL-R by default). A dual- toned beep indicates that the terminal is in record mode. 2. Enter the keystrokes making up the macro. Up to 63 keystrokes can be recorded, each indicated by a “blip” tone. After 63 keystrokes have been recorded, the “blip” sound stops, indicating no further keystrokes are being recorded. 3. To stop recording, press the Record hot key (CTRL-R) again. MPM3000 displays the following screen: SAVE MACRO PRESS HOT KEY _ ENTER FILE NAME D:\CURRENT.KMF CLR ABORTS
4. Press a keystroke to assign the hot key for the newly created macro. Be careful not to use the Start/Stop Record key, Abort key, or ENTER as the hot key. MPM3000 indicates that the hot key was saved. 5. Enter the name of the file where the macros are stored. The default macro file name is D:\CURRENT.KMF. Press ENTER to save the macro to the file and make it active in memory, or CLEAR to abort the new macro record. When you press ENTER, all macros currently loaded are written to the file, a quick triple beep sounds, the SAVE MACRO screen is cleared, and the original user screen is restored.
To remove a macro from the set of macros, press the Record hot key twice. When the macro file is saved, the memory the macro occupied and its hot key become available for a new macro.
A maximum of 32 macros can be created, with 63 keystrokes each. If you try to save more macros than there is space for, the OUT OF SPACE! message is displayed for two seconds.
1-49 Series 3000 Application Programmer’s Reference Manual
Chaining Macros One macro can chain to another macro by including the called macro's hot key in the calling macro. Chaining can be used to increase the number of keystrokes per macro, or to create an infinite looping macro.
When executed, control is passed to the called macro. Control is not returned to the caller, so any keys pressed after the chaining hot key are not executed. Running Macros To run a macro, simply press its hot key. During execution, all keystrokes entered at the keyboard are ignored except for the Abort key. If the user presses the Abort key, macro execution stops. MPM3000 and STG3000.EXE. MPM3000 cannot execute a soft trigger key defined by STG3000.
If both MPM3000 and STG3000 are run at the same time, it is recommended that you load STG3000 before loading MPM3000. Error Codes MPM3000 returns the following error codes:
1 = Macro file was not loaded
2 = No timers are available
3 = Invlid argument
4 = TSRREG.EXE is not loaded
1-50 Utilities
Memory Transfer Analyzer The Memory Transfer Analyzer (MTA.EXE) provides a way to examine memory transfer output of a Series 3000 terminal. You must first transfer an image of an area of memory from a Series 3000 terminal to the PC, using the RCVHEX utility, described in the RCVHEX.EXE section of this chapter, or any terminal communication software, such as QMODEM®, PROCOMM®, or HYPERTERMINAL®. Then, from the PC, use the Memory Transfer Analyzer to help you interpret the data. A special feature of the MTA provides an “Automatic” mode that automatically analyzes an image of intact memory. You can access the Memory Transfer function from within the Command Mode of a Series 3000 terminal. This function allows you to transmit an image of all or part of the memory area of your terminal to a PC. Note: The Memory Transfer Analyzer can only extract the files located in a hex file’s root directory. It cannot extract files located in the hex file’s subdirectories. This data can then be analyzed and extracted by the Memory Transfer Analyzer on the PC to recover whatever data is still present in memory, but was previously inaccessible. Figure 1-4 illustrates the basic transfer and analyze process.
Terminal PC
NVM
PC file: NVM_IMG.HEX
RAM
EMS
Figure 1-4. Memory Transfer and Analyze Process
1-51 Series 3000 Application Programmer’s Reference Manual
Recovering Intact or Corrupt Data The Memory Transfer Analyzer provides data recovery for two types of inaccessible data; Intact or Corrupt. If the Memory Transfer function in Command Mode provides you with a complete and uncorrupted image from a terminal, the MTA allows you to extract a copy of any data files which are stored in your terminal’s memory. However, if the memory in a terminal is corrupted, the MTA allows a customer support technician to locate and correct problems which prevent access to the data stored in the terminal. If data no longer resides in a terminal, obviously no program can recover it. However, if data is “lost” due to missing pointers, accidentally deleted files, or other such problems, it may be recoverable. In extreme cases, it may also be possible to perform partial data recovery. If your data has been corrupted in some way, please contact a Symbol Technologies technical support representative, who can help you with the data recovery process. If your data is still intact but is inaccessible for some reason, you may recover the data files using the following sample procedure. Sample Session: Analyzing Intact Data The following procedure explains how to analyze the intact data recovered from a Series 3000 terminal using the Memory Transfer Analyzer software on your PC. This sample procedure is divided into two sections:
• Data Transfer Transferring (recovering) data from the terminal using the Memory Transfer function in a Series 3000 terminal’s Command Mode. For information on this function, see the section on RCVHEX.EXE, later in this chapter.
• Analyzing Data Analyzing data using the Memory Transfer Analyzer software. For more information, see the following procedure.
1-52 Utilities
Analyzing the Data After transferring a memory image to your PC in a hex file, the transferred data can be analyzed. This can be accomplished using the Memory Transfer Analyzer software on your PC. The following steps explain how to use it.
1. Invoke the Memory Transfer Analyzer (MTA) on the PC using the following syntax: mta
where:
hex_filename The filename of the memory image transferred from the terminal to the PC in the Data Transfer procedure. You need not specify the .HEX extension. For example,
MTA NVM
Invoking the MTA with the input file on the command line automatically loads the file, i.e., this is equivalent to executing the Load command from the MTA main menu and then specifying the filename.
Note: Once you load a hex file image, you can save it as a .IMG file. This saves it in a different format than the original hex file image, but allows you to reload the same data much faster - use the Restore option to load the .IMG file instead
1-53 Series 3000 Application Programmer’s Reference Manual
of the original .HEX file.
Figure 1-5 illustrates the display after selecting the Restore option - filename: MTASCRNS.IMG.
PDT 3000 Series Memory Transfer Analyzer Version 3.01-00 Copyright (C) 1991-1993 Symbol Technologies
Start End File name 000000 to 09FFFF MTASCRNS 0C0F00 to 0DFFFF MTASCRNS
Restoring 'MTASCRNS.IMG'… Addr: 044C00
0 ...... 100[Range 1] 42%
Figure 1-5. Main Menu
The upper left window in this screen lists the .HEX filename and the memory addresses that it occupied in the terminal. The lower left window lists the filename(s) that were loaded or restored. The lower bar contains the main menu - or a bar graph showing the progress of a load, restore, save, or extract procedure.
2. From this menu, use the right arrow to select Evaluate.
Load Evaluate Save Restore Quit
The lower screen displays the three menu options shown in Figure 1-6.
Automatic Range Address
Figure 1-6. Evaluation Method Menu
3. From the menu, select the Automatic evaluation method (press
1-54 Utilities
If any errors occur during the automatic evaluation process, consult a customer support technician. (Errors are displayed in highlighted video mode.)
The automatic evaluation process results in a screen similar to the one shown in Figure 1-7:
PDT 3000 Series Memory Transfer Analyzer Version 3.01-00 Copyright (C) 1991-1993 Symbol Technologies
Start End File name Evaluating disk A: DFFEO 'NUL00001'
000000 to 09FFFF MTASCRNS No sectors in NUM disk image: 'NUL00001 0C0F00 to 0DFFFF MTASCRNS ' Press any Key… Evaluating disk B: DFFCO 'USR00000' Valid BPB found at C123E Valid FAT found at C125B Valid DIR found at C1339 Restoring 'MTASCRNS.IMG'… Addr: 09FE00 Evaluating disk D:003D4 Addr: 0DFF00 Valid BPB found at 1C803 Done. Valid FAT found at 1CA00 Valid DIR found at 1D200
B: D:
Figure 1-7. Display of Disk Areas Found
This screen displays the logical terminal disk areas the MTA found within the hex data block during the evaluation phase. The right portion of the screen displays the disk drive specification(s) found.
1-55 Series 3000 Application Programmer’s Reference Manual
4. Use the right and left arrows to select which disk drive directory to display. For example, if your lost data file was saved in drive B in your terminal, select B: and press
PDT 3000 Series Memory Transfer Analyzer Version 3.01-00 Copyright (C) 1991-1993 Symbol Technologies
Start End File name File Directory 000000 to 09FFFF MTASCRNS File name. Ext Attrib Clust Bytes 0C0F00 to 0DFFFF MTASCRNS CONFIG .SYS 512 COMMAND .COM 2 35872 AUTOEXEC .BAT 73 58 SCAN .EXE 74 8308 SELECT .EXE 91 4881 DEMO .BAT 101 553 Restoring 'MTASCRNS.IMG'… TDREM .EXE 103 13610 Addr: 09FE00 ETA3000 .EXE 130 1149 Addr: 0DFF00 SCAN3000 .EXE 133 1984 Done. ORDER .EXE 137 4816
Figure 1-8. List of Files Found
This screen displays a directory of the disk files found on the drive you specified.
5. Use the up and down arrows to select a disk file and press
1-56 Utilities
PDT 3000 Series Memory Transfer Analyzer Version 3.01-00 Copyright (C) 1991-1993 Symbol Technologies
Start End File name File Directory File name. Ext Attrib Clust Bytes 000000 to 09FFFF MTASCRNS 0C0F00 to 0DFFFF MTASCRNS CONFIG .SYS 512 COMMAND .COM 2 35872 AUTOEXEC .BAT 73 58 SCAN .EXE 74 8308 SELECT .EXE 91 4881 DEMO .BAT 101 553 Restoring 'MTASCRNS.IMG'… TDREM .EXE 103 13610 Addr: 09FE00 ETA3000 .EXE 130 1149 Addr: 0DFF00 SCAN3000 .EXE 133 1984 Done. ORDER .EXE 137 4816
View Extract
Figure 1-9. File Operations Menu
The lower part of the screen displays two options: View and Extract. To display the data in the file, select View. To output the contents of the file to a PC file, select Extract.
6. To recover data, select Extract. The program prompts: “Extract to?” Type any path and filename of your choice; for example, C:\TEMP\SAVEDATA.TXT. This file will contain the extracted data file. As the system extracts the file, it displays: “Extracting’(filename).’"
1-57 Series 3000 Application Programmer’s Reference Manual
PDT 3000 Series Memory Transfer Analyzer Version 3.01-00 Copyright (C) 1991-1993 Symbol Technologies
Start End File name File Directory File name. Ext Attrib Clust Bytes 000000 to 09FFFF MTASCRNS 0C0F00 to 0DFFFF MTASCRNS CONFIG .SYS 512 COMMAND .COM 2 35872 AUTOEXEC .BAT 73 58 SCAN .EXE 74 8308 SELECT .EXE 91 4881 DEMO .BAT 101 553 Extracting 'scan. exe'… TDREM .EXE 103 13610 ETA3000 .EXE 130 1149 SCAN3000 .EXE 133 1984 ORDER .EXE 137 4816
0 ...... 100[ Extract] 37%
Figure 1-10. Extracting Data
7. This completes the data recovery process for one file. Press [Esc] three times to return to the main menu. From the main menu, select Exit to return to DOS.
1-58 Utilities
Command Reference This section lists and describes the commands available from each menu of the Memory Transfer Analyzer. Load The Load command allows you to load new .HEX files into the memory image of the Memory Transfer Analyzer. Each .HEX file loaded defines one to three ranges of memory (RAM, NVM, EMS).
The MTA displays a list of the ranges currently present in the memory image at all times in the range display window (upper left hand window). Each entry in the range display window shows the starting and ending addresses of the memory area occupied by the range and the name of the .HEX file from which the range was loaded. The number of ranges that can be loaded at one time is limited to the size of the range display window (currently set to 8).
As each new .HEX file is loaded, the memory associated with the new range is loaded into the memory image. If any bytes of prior ranges are overwritten by the new range, the MTA displays an error message. Such overwritten values are no longer accessible.
When you invoke the MTA from the command line, any files listed after the utility name on the command line are passed to the Load command automatically. These ranges will appear in the range display window. Evaluate The evaluate command instructs the MTA to interpret the contents of the memory image in various ways. There are three methods of evaluation available: Automatic, Range, and Address. The following section explains each method.
Automatic Use this method of evaluating to recover your data files. If the data is intact and the image is complete (all data was transferred from the terminal’s memory and received by the
1-59 Series 3000 Application Programmer’s Reference Manual
MTA) the MTA will locate all of the disks contained within the memory.
The MTA presents a menu of the disks that are successfully located. You can select the disk you want to analyze. The MTA then displays a list of the files on the disk. You can then select which file you want to view or extract. To view the contents of the file, select View. You can view the file in either HEX or TEXT mode. To extract a copy of the file, select Extract. Extract places an extract copy of the file in a stand-alone PC file.
If any problems occur during the automatic evaluation process, the MTA reports them in the evaluation display window (far right-hand window).
Range This method provides several ways of evaluating the contents of a range of data. These modes of interpretation are selectable from a menu and are listed and described as follows:
Hex (Hexadecimal Dump)
This mode of interpretation displays the contents of the range as a hexadecimal memory dump. Each line shows eight bytes of data in hexadecimal and the ASCII equivalents for printable characters. You may edit the hexadecimal values in this mode. Simply move the cursor to a line and press
1-60 Utilities
Vector (Interrupt Vector)
This mode of interpretation displays the contents of the range as a list of IBM PC interrupt vectors. The vector table entries are listed one per line with the address, value, and meaning of each entry displayed on the line. Editing the interrupt vectors is not supported directly, but can be accomplished by switching to HEX mode.
FAT (DOS File Allocation Table)
This mode of interpretation displays the contents of the range as a DOS File Allocation Table. The entries of the table are listed one per line. The first two entries are displayed specifically because they are not true entries of the FAT. The first entry is the media ID byte. displayed in brackets: [FE]. The second entry is unused. The remaining entries are displayed as either cluster numbers or as one of the special identifiers UNUSED, RESERVED, BAD CLUSTER, and END OF FILE. Editing the FAT is not supported directly, but can be accomplished by switching to HEX mode.
DIR (DOS File Directory)
This mode of interpretation displays the contents of the range as a DOS Disk Directory. The entries of the table are listed one per line. Each line shows the filename, extension, attributes, starting cluster number, and size in bytes of the corresponding file. Editing the directory is not supported directly, but can be accomplished by switching to HEX mode.
1-61 Series 3000 Application Programmer’s Reference Manual
NVM (NVM Content Descriptor)
This mode of interpretation displays the contents of the range as an NVM Content Descriptor Table. The entries of the table are listed one per line. Each line shows the part number, version, number of CRC zones, number of sectors, number of replacement sectors, and number of entry points in the associated NVM section. Editing this table is not supported directly, but can be accomplished by switching to HEX mode.
MAP (NVM Disk Sector Map)
This mode of interpretation displays the contents of the range as an NVM Disk Sector Map. The entries of the table are listed one per line. Each line shows the starting address and size of the corresponding sector. Editing this table is not supported directly, but can be accomplished by switching to HEX mode.
CRC (NVM CRC Zone Table)
This mode of interpretation displays the contents of the range as an NVM CRC Zone Table. The entries of the table are listed one per line. Each line shows the starting address of a block over which a CRC was computed, the size of the block, and the CRC value. Editing of this table is not supported directly, but can be accomplished by switching to HEX mode.
Entry (NVM Entry Point Table)
This mode of interpretation displays the contents of the range as an NVM Entry Point Table. The entries of the table are listed one per line. Each line shows the starting address of a routine stored in the NVM. Editing this table is not supported directly, but can be accomplished by switching to HEX mode.
1-62 Utilities
BPB (BIOS Disk Parameter Block)
This mode of interpretation displays the contents of the range as a BIOS Disk Parameter Block. The entries of the BPB are listed one per line. Each line shows one field of the BPB. Consult the DOS Technical Reference Manual for details concerning the BPB structure. Editing the BPB is not supported directly, but can be accomplished by switching to HEX mode.
Address This method of evaluation allows a customer support technician to investigate the contents of a specific area of memory. The Memory Transfer Analyzer prompts for a starting and ending address. Enter the address boundaries and then choose a mode of interpreting the defined range. For a list and description of methods of interpreting the addresses, see the previous command section, “Range.” Save The Save command saves a “snapshot” of the currently loaded memory image to a binary image file. The image file contains all of the information necessary to completely reproduce the entire analysis session at a later time. The MTA uses an .IMG extension for image files.
The Save command provides the following functions and advantages:
• If you load several ranges, you can save them as a unit and reload the image (see Restore below) approximately two times faster than loading the original .HEX file (load is 85% faster than before). This is useful if several actions are to be taken on the same set of ranges at various times. • The Save command preserves any changes that you make to the memory image, since the .HEX files were loaded. This allows you to extract files from a reconstructed image at a later time. • Prior to making a change to the data, you can save the original memory image. This allows you to make changes and in case of error, to reload the original version of the memory image without having to reload all the ranges.
1-63 Series 3000 Application Programmer’s Reference Manual
Restore The Restore command allows you to load an image file (.IMG) to the memory image area of the Memory Transfer Analyzer. Image files are created by the Save command (See Save above). Loading an image file with the Restore command is ten times faster than loading a .HEX file.
When you use Restore, the contents of the image file overwrites the memory image area of the Memory Transfer Analyzer. Therefore, any data in the memory image area that was loaded prior to executing the Restore command is lost. Quit The Quit command exits from the Memory Transfer Analyzer to DOS. Any changes you made to the memory image of any loaded .HEX files are lost unless you first save them to a file. To preserve changes, use the Save command to save a copy of the memory image to a .IMG file.
1-64 Utilities
PDCONVRT.EXE PC
Description This is a Symbol converter tool which is used to convert the symbol table format produced by Microsoft C Compilers into the format compatible for Borland Turbo Debugger.
PDCONVRT.EXE replaces TDCONVRT.EXE and is backward compatible to TDCONVRT.EXE. PDCONVRT.EXE converts the symbol table of files generated with Microsoft C 7.0, Visual C++ 1.0, and Visual C++ 1.5 and produces an output file which is suitable for Turbo Debugger versions 3.1 and 4.02. Syntax PDCONVRT [options] filename
where options are:
d0: **Disable diagnostics d2: Enable module diagnostics 0td4: **Turbo Debugger 4.0 output w-wxxx: Disable warning Wxxx d1: Enable file diagnostics 0td3: Turbo Debugger 3.1 output 0n: Output filename W+Wxxx: Enable warning Wxxx
**= default
filename:the name of the file to be used in generating the output file. Example PDCONVRT-0td3 COLLECT.EXE
1-65 Series 3000 Application Programmer’s Reference Manual
RCVHEX.EXE PC
Purpose Use RCVHEX.EXE to receive a memory transfer from a Series 3000 terminal. Syntax RCVHEX filename [baud] [port]
where:
filename A file name under which to save memory image file on the PC hard disk. There is no default file name or extension.
baud Baud rate: 1200; 2400; 4800; 9600 (default); 19200; 38400
port The serial port on which data will be received. Options are:
1 = Com1 (default)
2 = Com2 Description RCVHEX.EXE receives data sent from a Series 3000 terminal sent using the Memory Transfer Analyzer (MTA.EXE) utility. The data is stored on the PC in a hex image file, using the intel HEX record format.
A file name for the memory transfer hex image must be specified. If a file by that name already exists on the PC, it is overwritten.
This baud rate must match or exceed the one set in the terminal by the MTA utility. Rates may be abbreviated to the first two or more digits (e.g., 12 or 120 for 1200).
Refer to the Memory Transfer Analyzer section of this chapter for a descripotion of the MTA utility.
1-66 Utilities
Sample This command receives data from the terminal on COM1 and stores it in the file MYDISK.HEX. Communications rate will be at 38.4K baud on COM1.
C:> rcvhex mydisk.hex 38 1
Error Conditions Some PC systems are unable to receive data at rates above 9600 baud with no errors. If RCVHEX.EXE receives errors at 19.2 or 38.4, it displays a message suggesting a lower baud rate.
If an error is detected during transmission, the following message will display:
Comm Error: XX HEX where XX is a hexadecimal numeral. Bits 0-4 of this numeral report the conditions shown in the following table:
Bit Bit Function Value Meaning 0 Data Ready 0 No complete character received 1 Complete character received 1 Overrun Error 0 No overrun error 1 New character received before RCVHEX could service the last character received 2 Parity Error 0 No parity error 1 Inappropriate parity in the character received 3 Framing Error 0 No framing error 1 Invalid stop bit in character received 4 Break Interrupt 0 No break interrupt 1 Received data line was held in spacing condition for more than one full word transmission time
1-67 Series 3000 Application Programmer’s Reference Manual
SENDHEX.EXE PC
Purpose Use SENDHEX.EXE to transfer an NVM image file from the host PC to a Series 3000 terminal. Syntax SENDHEX filename [baud] [port]
where:
filename The name of the hex file to send to the terminal.
baud Baud rate: 1200, 2400, 4800, 9600 (default), 19200, 38400
port Communications port: COM1 or COM2 Description Sendhex is a communications utility intended for downloading an NVM image file (hex file) from a host PC to a Series 3000 terminal. A file name must be provided.
The baud rate and port are optional parameters. Since the parameters are position sensitive, if you need to specify the port number, you must also specify a baud rate.
Default communication parameters are: 9600 baud Odd parity COM1 Xon/Xoff flow control 7 bit data
Versions of SENDHEX prior to 3.0 did not support flow control.
Note: We recommend using XON/XOFF when using baud rates of 19,200 and higher. Also, XON/XOFF
1-68 Utilities
cannot be used when using a multi-slot cradle with more than one terminal inserted. Sample c:> sendhex NVM11109 19200
1-69 Series 3000 Application Programmer’s Reference Manual
STG3000.EXE S3000
STG3000 defines soft trigger keys, keystrokes that act as scanner trigger.
STG3000.EXE must be used to enable laser triggering on the 3300 terminal with an integrated scanner. No additional programming requirements are placed on the application software.
Up to 20 keystrokes can be defined as soft triggers.
STG3000 runs as a TSR and can be loaded by AUTOEXEC.BAT. It requires less than 1K of TPA memory. Syntax STG3000 [/xxxx /xxxx ... /xxxx]
where each xxxx specifies the scan code and ASCII code of a keystroke in hexadecimal. Using the Soft Trigger Key When scanning is enabled, pressing and releasing one of the defined keys triggers the laser. The pressed key is not passed to the application. When scanning is disabled, keystrokes are passed as data to the application. Pressing a soft trigger keystroke again, before either the laser timeout or label acquisition, turns the laser off. Each key is identified by four hexadecimal digits. The first two digits are the scan code and the second two digits are the ASCII code. For example, the Scan/ ASCII code pair for ENTER is 1C0D. Refer to Appendix B. The Series 3000 Keyboard in this manual for scan and ASCII values of the keys for each terminal.
1-70 Utilities
Example STG3000 /3B00 /3F00 This command defines the F1 and F5 keys as soft trigger keys.
1-71 Series 3000 Application Programmer’s Reference Manual
TDREM.EXE S3000
Description The tool used to debug an application on the Symbol Technologies Series 3000 terminals is the Borland Turbo Debugger, which can work as a “Remote Debugger.” It is considered a single product, but is composed of two parts: the Host part (TD.EXE), which runs on the development PC and the Remote part (TDREMOTE.EXE), which runs on the terminal. Symbol Technologies has customized TDREMOTE.EXE for its terminals. This customized product is called “TDREM.EXE”.
For more information on the use of Borland Turbo Debugger, please refer to your Borland Turbo Debugger User Documentation. If you do not have a copy of TD.EXE (the host side of the debugger), you can also use PDEPC.EXE v6.0, available from Paradigm Systems at 1-607-748-5966. PDEPC.EXE is compatible with both TDREM and TDREM4, and replaces TD v2.x, 3.1, and 4.02.
There are currently available two versions of the remote parts of this tool: TDREM.EXE, which supports Turbo Debugger versions 2.x and 3.1 and TDREM4.EXE, which supports Turbo Debugger version 4.02.
The following chart lists C compilers with their respective applicable debugger versions, Symbol Converters, and Remote programs running on the terminal.
Compiler Version Debugger Version Symbol Converter Remote Program
Microsoft C 6.0A TD 2.X PDCONVRT TDREM or PDEPC
Microsoft C 6.0A TD 3.1 PDCONVRT TDREM or PDEPC
Microsoft C 6.0A TD 4.02 PDCONVRT TDREM4 or PDEPC
Microsoft C 7.0 TD 3.1P PDCONVRT TDREM or PDEPC
Microsoft C 7.0 TD 4.02 PDCONVRT TDREM4 or PDEPC
1-72 Utilities
Compiler Version Debugger Version Symbol Converter Remote Program
Microsoft C ++ 1.0 TD 3.1 PDCONVRT TDREM or PDEPC
Microsoft C ++ 1.0 TD 4.02 PDCONVRT TDREM4 or PDEPC
Microsoft C ++ 1.5 TD 3.1 PDCONVRT TDREM or PDEPC
Microsoft C ++ 1.5 TD 4.02 PDCONVRT TDREM4 or PDEPC
Syntax TDREM -rp# -rs# where:
-rp# communications port -rp1=COM1 -rp2=COM2
-rs# baud rate -rs1=9600 baud -rs2=19200 baud -rs3=38400 baud -rs4=115000 baud Example TDREM -rp1 -rs3
1-73 Series 3000 Application Programmer’s Reference Manual
TFT3000.EXE PC
TFT3000.EXE is a terminal file transfer program that runs on the host PC. It communicates to TDREM on the terminal. Refer to the earlier section in this chapter on TDREM.EXE . Syntax tft3000 [options] [arg1 ... argn]
Options -Sspeed Transfer speed, where speed can be: 96 or 9600 = 9600 19, 192 or 19200 =19200 38, 384 or 38400 = 38400 115, or 11500 = 115000 -Pnumber Port number, where number can be: COM1 or 1 = COM1 COM2 or 2 = COM2 -X Terminate TDREM (version 3.01 or higher) once it completes its jobs. Default parameters are: 115 K bps, COM1, and do not terminate TDREM on remote. Arguments Each argument consists of a letter followed by 0, 1, or 2 file or directory names as indicated below in Table 1-7 . The argument letter and file names must be separated by at least one space.
1-74 Utilities
Table 1-7. Terminal File Transfer Arguments
Number of Argument Letter File/Direcrory Description Value Names Required PUT P 1 Puts a file to the remote. GET G 1 Gets a file from the remote. DIR D 0 or 1 Displays a directory listing on the remote. REN R 2 Renames a file on the remote. MKDIR M 1 Makes a directory on the remote. CD C 1 Changes directory on the remote. RMDIR K 1 Removes a directory on the remote. ERASE E 1 Erases a file on the remote.
Example To send filename foo.c from the host to the terminal, at a baud rate of 38,400 through COM2:
TFT3000 -S38 -P2 P foo.c
To get a directory from the terminal, at a baud rate of 38,400, through COM2:
TFT3000 -S38 -P2 D
1-75 Series 3000 Application Programmer’s Reference Manual
TSRREG.EXE S3000
TSRREG.EXE is a TSR (Terminate and Stay Resident) registration utility that runs on the terminal. Other TSRs can use TSRREG to register their presence when they first go resident and to check whether they are already present before going resident. In this way, the TSR registration utility prevents multiple copies of the same TSR occupying memory at the same time.
The first time a TSR goes resident, it calls TSRREG and registers its ID. TSR ID numbers can range from 0001h to FFFFh. The first 50h ID numbers are reserved for use by Symbol Technologies. TSRIDS.H, on the C:\3000\3000 directory in the ADK, contains the ID numbers for currently used Symbol programs.
Subsequent calls by the TSR to TSRREG return a boolean value indicating whether or not the TSR is already resident (0 if the TSR is not installed, 1 if it is currently installed).
An application program calls TSRREG using TSRRegistrationCheck( ). This function is used both to register an ID for a TSR and to check for its presence. TSRRegistrationCheck() is in the SYMUTILx library (where x = L, M, or S). For a description of the TSRRegistrationCheck() function, refer to the Symbol Utility Library (SYMUTILx.LIB) section in the chapter on Miscellaneous Library Functions in this manual.
Before executing TSRRegistrationCheck(), the program should verify that TSRREG is running by checking to determine whether interrupt vector 50h is pointing at 0000:0000. If it is, TSRREG has not been installed and TSRRegistrationCheck( ) cannot be used.
1-76 Utilities
USRCFG.EXE PC
USRCFG.EXE, the User Configuration Tool, is the utility that generates an NVM image (.HEX file) for downloading to a Series 3000 terminal. The user specifies, either by responding to prompts, by command line arguments, or in a response file, what software components to include in the NVM image.
Typically, the NVM image includes one or more application programs and supporting data files. The NVM image must also include a system image, usually NULLSYS.HEX specifying the EPROM system, but may be a custom system image provided by Symbol Technologies. The image can also include CONFIG.SYS, AUTOEXEC.BAT, a command shell, and device drivers to configure the environment for the application. Syntax usrcfg or
usrcfg system_file [switch parameter]...[switch parameter] or
usrcfg @response_file
Interface USRCFG supports three interfaces: interactive, command line arguments, and response file.
Entering the USRCFG command without arguments initiates the interactive interface in which you are prompted for each input option. Refer to Chapter 4 of the Series 3000 Application Programmer’s Guide for a description of the prompts and responses.
1-77 Series 3000 Application Programmer’s Reference Manual
Including a command line argument specifying an input option suppresses the corresponding prompt. USRCFG still prompts for responses to parameters that you do not specify.
Each command line argument except the system file is preceded by a parameter switch. The first parameter must specify the system file, and must be either “NULLSYS.HEX” or the name of a custom system image.
Finally, you can specify all options in a response file and pass the name of the response file to USRCFG as the only argument. The recommended method of repeating and modifying an NVM configuration specification is placing the arguments in a response file. USRCFG Switches Switches fall into three categories as follows: 1. Input switches 2. Output switches 3. Print switches
This is the order in which switches must be entered on the command line or in the response file. Each switch consists of a forward slash (/) followed by one or more characters followed by a space and any parameter value. Switch letters may be in upper or lower case. Switches and parameters must be separated by a space.
Table 1-8 lists and describes USRCFG switches arranged in the categories listed above.
1-78 Utilities
Table 1-8. USRCFG Command Line or Response File Switches
Switch Description Input Switches /n arg Specifies the start of data symbol used in the .MAP file containing pointers to locations in the .EXE file. USRCFG uses this information to separate code and data for split resident programs. The default symbol is BEGDATA, as used by Microsoft C.
A /n switch applies to all following /rs arguments until another /n is specified. /c file Load file as CONFIG.SYS in the NVM image. The file is renamed “CONFIG.SYS” in the image. /nc No CONFIG.SYS file. The default CONFIG.SYS in EPROM will be used. Use this switch to suppress the interactive prompt. /s file Load file as the command shell, usually COMMAND.COM. /ns No command shell file. The default file, SHELL, in EPROM will be used. Use this switch to suppress the interactive prompt. /a file Load file as AUTOEXEC.BAT in the NVM image. The file is renamed to “AUTOEXEC.BAT” in the image. /na No AUTOEXEC.BAT file. The default AUTOEXEC.BAT in EPROM will be used. Use this switch to suppress the interactive prompt. /u file Load file as a user file. You can specify several user files, but only one per switch. For example:
/u mydata.txt /u mydata2.txt /nu No user files. Use this switch to suppress the interactive prompt. /r file Load file as a resident code file. You can specify several files, but only one per switch. /rs file Load file as a split resident code file. You can specify several files, but only one per switch.
1-79 Series 3000 Application Programmer’s Reference Manual
Table 1-8. USRCFG Command Line or Response File Switches (Continued)
/nr No resident code files. Use this switch to suppress the interactive prompt. /l label Label the NVM image as label. The label format is:
#####-CCCCCCC or #####/CCCCCCC
where #### is a five digit part number, and CCCCCCC is up to seven characters specifying the version. Output Switches /h file Output a .HEX file named file.HEX. The default filename is based on the image label. /i file Output a .IMG file named file.IMG. The default output filename is based on the image label. Note: If both the /i and /h switches are specified, supply only one filename, without an extension, for example: /i /h MYFILE. /in Generate an Intel format .HEX file. (Used with /h switch only.) /bi Generate a binary format .HEX file. (Used with /h switch only.) /co Generate a compressed format .HEX file. (Used with /h switch only.) /tr Generate a Transparent format .HEX file (used with /h switch only.) /j Use up to 256K of NVM. This switch is required to use more than 128K of NVM. /nj Use only 128K of NVM. /256 Same as /j. /128 Same as /nj. /1 Select single-sided, single-density (160K, 320 sectors, 1 head) floppy disk format. Default is /1 for 128K of NVM. /2 Select double-sided, single-density (320K, 640 sectors, 2 heads) floppy disk format. Default /2 for 256K of NVM. Available for drive B: only. /160 Same as /1 /320 Same as /2.
1-80 Utilities
Table 1-8. USRCFG Command Line or Response File Switches (Continued)
/no Do not generate .HEX or .IMG output files. Print files are still generated. Print File Switches /p file Override the default print filename using the filename specified. /np Do not generate print files. Not recommended.
Examples Command Line usrcfg nullsys.hex /s a:command.com /c c:config.sys /na /rs hellom /r hellos /u d:\commands\beep.exe /l 12345-x1.01-1 /h
Response File c:\3000\files\nullsys.hex /c prod.sys /s c:\3000\files\command.com /a prod.bat /nr /u c:\3000\progs\invntry.exe /l 00012-1.01 /h /co /256 /160 prod.hex
1-81 Series 3000 Application Programmer’s Reference Manual
1-82 Chapter 2 Device Drivers
Chapter Contents Introduction ...... 2-3 The ANSI Compatibility Driver...... 2-4 ERR3000.SYS...... 2-12 ETA3000.SYS...... 2-13 PAN3000.SYS ...... 2-16 PGM3000.SYS ...... 2-18 FLASHDSK.SYS ...... 2-19 FLSHFMT.EXE ...... 2-21 FLSHCTL.EXE ...... 2-22
2-1 Series 3000 Application Programmer’s Reference Manual
2-2 Device Drivers
Introduction This chapter describes device drivers that can be included in the terminal's CONFIG.SYS file to provide your terminal with added features.
Some of the device drivers provided are transient. A transient driver does not permanently install as most device drivers do. In some cases, only parameters need to be provided to the driver. In this case, it simply processes the parameters that are provided and does not install. Because it is transient, calling it more than once does not destroy any previous parameters.
2-3 Series 3000 Application Programmer’s Reference Manual
The ANSI Compatibility Driver S3000
The ANSI driver is provided so that your application can accept ANSI escape sequences in the data stream. Based on a captured escape sequence, the application can make appropriate BIOS calls to move the cursor, erase a portion of the screen, etc.
Note: ANSI output is very slow on a Series 3000 terminal. It is provided primarily for applications that require an ANSI driver for maximum portability. Loading Methods The ANSI driver is provided both as a driver file (ANSI3000.SYS) and as a TSR (ANSI3000.EXE). Use only one version at a time.
To load the device driver version, include the following line in the terminal CONFIG.SYS file:
DEVICE=B:ANSI3000.SYS
The driver must be included as a user file (/u) in the NVM image.
The TSR version can be included either in the terminal AUTOEXEC.BAT file or as an argument to SHELL.COM.
To include ANSI3000 in AUTOEXEC.BAT, add a line to execute it when DOS loads, as any other executable. This method requires that the terminal be using COMMAND.COM.
Since ANSI3000.EXE is just an executable file, it can be also run from the command prompt or by using any other method of launching an executable. It executes as a TSR.
2-4 Device Drivers
Small screen handling ANSI3000 includes special features to support the small Series 3000 screens. For maximum flexibility, ANSI3000 checks the logical screen size of the terminal prior to each command. All screen size specific operations then use this size. Changing logical screen sizes between operations works correctly. Cursor Positioning When an attempt is made to position the cursor to a location outside the logical screen of the terminal, ANSI3000 constrains the out of range row or column to either the highest or lowest acceptable value, as appropriate. Screen wrap When the WRAP mode is set, ANSI3000.SYS wraps a text line according to the logical screen size. If the WRAP mode is disabled, characters are discarded when they pass the logical screen boundary. Command Set ANSI3000 supports only the screen control commands. Keyboard macro definition commands are handled as invalid commands. Invalid Command Handling ANSI3000 screen control commands are a subset of the ANSI terminal escape sequence standard. If an unsupported command is entered, ANSI3000 prints all characters belonging to the command string just as if it were text. This provides a simple way for the programmer to see that the command was not executed. Limitations ANSI3000 has three limitations you should be aware of:
• Number of Parameters • Number of Characters in a Command • Maximum Value of Parameters
2-5 Series 3000 Application Programmer’s Reference Manual
Number of Parameters The command syntax for ANSI.SYS commands is shown below:
ESC [ letter ESC [ = letter ESC [ ? letter ESC [ param letter ESC [ param;...;param letter
For the command variations that allow for parameters separated by semicolons, the parameters must be saved in a buffer until the command letter is seen so that they can be properly processed at that time. The length of the buffer imposes a maximum number of arguments that a command can contain. If the command exceeds this limit, then it is handled as an invalid command.
The current limit for ANSI3000 is 20 commands. Number of Characters in a Command In order to be able to print out the command completely if it turns out to be invalid, all the characters in the command must be saved in a buffer as they are received. The length of the buffer imposes a maximum size of the commands that can be sent. If the command exceeds this limit, then it is handled as an invalid command.
The current limit for ANSI3000 is 40 characters. This limit is based on the parameter limit and a estimate of less than 2 characters per parameter on the average. Maximum Value of Parameters ANSI3000 stores parameters in binary, allocating a single byte for each parameter. This imposes a value limit of 255 on the parameters. This is not a serious limitation since the values for parameters should never exceed the maximum column value of 80.
2-6 Device Drivers
Presence Detection It may be necessary to determine from an application whether or not the ANSI3000 driver is present. ANSI.LIB and ANSI.H are included in the ADK to provide a means of detecting its presence.
With ANSI.LIB and ANSI.H appropriately included in the application, use AnsiPresent( ) to detect the presence of the ANSI3000 driver. AnsiPresent( ) returns TRUE if ANSI3000 is present and FALSE otherwise. If present, AnsiPresent( ) does not determine whether the driver or executable version is loaded. ANSI.LIB is located on the C:\3000\LIB directory and ANSI.H on the c:\3000\3000 directory in the ADK Sample Programs The ADK includes two programs to demonstrate the operation of ANSI3000:
• ANSIDEMO.C, a simple program • DISPLAY.C. a demo program Both are in the C:\3000\SAMPLE\DISPLAY directory of the ADK. Command Set The standard DOS ANSI.SYS supports both screen control commands and keyboard macro definition commands. The ANSI3000 product supports only the screen control commands. Keyboard macro definition commands are handled as invalid commands.
Following is an alphabetized list of all valid commands along with the proper syntax, list of arguments (if applicable), and a brief description. Spaces within the syntax are used only to make the sequences easier to read. Make sure there are no spaces when you use the command in a program. Also, all X and Y variables are numbers specified in ASCII digits. Attention (AT) Syntax: ESC AT nn
Sends the disconnect from SATP signal to the terminal with an error code. The value of the code determines the DOS error level setting, and through that setting, the next terminal action. For example, if the code is 00, the DOS
2-7 Series 3000 Application Programmer’s Reference Manual
error level is set to 00. The batch file uses this code to exit SATP and then activate a STEP program. Cursor Backward (CUB) Syntax: ESC [xD
Moves the cursor x columns to the left without changing rows. This sequence is ignored if the cursor is already in the far left column. Cursor Down (CUD) Syntax: ESC [yB
Moves the cursor down y rows without changing columns. This sequence is ignored if the cursor is already at the bottom line. Cursor Forward (CUF) Syntax: ESC [xC
Moves the cursor x columns to the right without changing rows. This sequence is ignored if the cursor is already in the far right column. Cursor Position (CUP) Syntax: ESC [y;xH
Moves cursor to position x,y on the screen. Cursor Up (CUU) Syntax: ESC[yA
Moves the cursor up y rows without changing columns. This sequence is ignored if the cursor is already at the top of the line. Console Position Report (CPR) Syntax: ESC [y;xR
Reports the cursor position by row and column.
2-8 Device Drivers
Device Status Report (DSR) Syntax: ESC [6n
Requests the CPR sequence from the remote terminal. Disable Character Wrap Syntax: ESC [ = 7l
Ends “wrap mode.” In this mode, characters that do not fit on the current line are lost. Enable Character Wrap (ECW) Syntax: ESC [=7h
Sets “wrap mode.” In this mode, characters that do not fit on one row are displayed on the next row. Erase Display (ED) Syntax: ESC [2J
Erases the display and moves the cursor to the top left of the screen. Erase Line (EL) Syntax: ESC [K
Erases from the cursor position to the end of the row. Horizontal and Vertical Position (HVP) Syntax: ESC [y;x f
CUP and HVP position the cursor according to the coordinates issued. The default (and null) value is the top left corner of the screen. CUP and HVP are equivalent.
2-9 Series 3000 Application Programmer’s Reference Manual
Restore Cursor Position (RCP) Syntax: ESC [u
Restores the cursor to the position stored by the SCP command. If no prior SCP command has been issued, the default position is 0,0. Save Cursor Position (SCP) Syntax: ESC [s
Stores the current cursor position. You cannot nest the RCP and SCP commands. Set Graphics Rendition (SGR) Syntax: ESC [n; ... n m
Sets various screen modes. These modes are in effect until replaced by a different SGR sequence. The possible modes to choose from are:
Argument Mode
0 Default mode (black characters on white background) 5Blink 7 Inverse video (white characters on black background) 8 Invisible (white on white) Set Screen Mode (SM) Syntax: ESC [=nl or ESC [=l or ESC [?nl
Resets the screen mode. If the display size is 8 x 20, all modes are ignored and set to 2. n may have the following values:
2-10 Device Drivers
Argument Mode
0 40 x 25 monochrome 2 80 x 25 monochrome 6 640 x 200 monochrome Example program To give an example of how to use ANSI3000 from an application program written in Microsoft C, the example program ANSIDEMO.C has been provided in the C:\3000\SAMPLE\DISPLAY directory in the ADK.
2-11 Series 3000 Application Programmer’s Reference Manual
ERR3000.SYS S3000
ERR3000.SYS is the Symbol Error Message driver. This is a permanent installable driver that processes error conditions. When it receives an error code from the BIOS, it saves the screen, issues an error message, and returns. This driver processes error conditions detected by the BIOS such as low battery, double key HIT error, key queue full, etc. Syntax To install this driver, add the following line to your terminal's CONFIG.SYS file:
DEVICE=B:ERR3000.SYS
Example DEVICE=B:ERR3000.SYS
Source Code The source code (ERR3000.ASM) for this driver is released as part of the ADK in the C:\3000\SAMPLE directory. The source is provided for three reasons:
1. The source code for this driver provides a sample of how to write a driver for this system and how to use BIOS calls. 2. Having the source code allows you to modify it for the needs of your applications. You can modify the messages, beeps, length of beeps, number of beeps, etc. This is an assembly language program that contains equates for each of these features. Therefore, a programmer may modify any of these parameters if so desired. 3. ERR3000.SYS can be modified to display error messages on the PDT 3100 4-line display. To do so, edit the ERR3000.MAKEFILE and change the last line to: masm /DFOUR.ROWS err3000; then type: NMAKE err3000.
2-12 Device Drivers
ETA3000.SYS S3000
ETA3000.SYS , which is always used with INIT.EXE (produced by BLDINIT.EXE), allows you to configure the initial terminal environment.
On a terminal with a System BIOS prior to 3.01, this driver emulates the ETA single boot process. It must be loaded in order to set the size of the:
• RAM Disk • TPA (Transient Program Area) • Communication queue sizes • Console queue size On a terminal with a System BIOS of 3.01 (or higher), this driver must be loaded if and only if the TPA size is set.
See the chapter on Terminal Initialization in the Series 3000 Application Programmer’s Guide for a description of the parameters set by INIT.EXE. This chapter also tells you how to use the Terminal Initialization Tool (BLDINIT.EXE ) to generate INIT.EXE and then how to download INIT.EXE and ETA3000.SYS to a terminal. How It Works The terminal initialization parameters are passed to this driver by INIT.EXE.
If the initialization program is not loaded, this driver will not perform any function.
If the initialization program is loaded and this driver is not, all the parameters except for those described above will still be set into the terminal during the bootup process.
ETA3000.SYS returns no error code to the DOS Shell.
2-13 Series 3000 Application Programmer’s Reference Manual
Installation To install this driver, add the following line to your terminal's CONFIG.SYS file: DEVICE=B:ETA3000.SYS
If this driver is used to set the TPA size, this line should be the last “DEVICE=” statement (this driver must be loaded last). RAM Disk Allocation If the RAM disk parameters are set in the initialization program, the algorithms given below determine how much RAM of conventional memory or EMS is allocated to the RAM disk. In these algorithms:
Rdisk_ttl = Total amount of RAM to be allocated to the RAM disk.
Rdisk_ems = Amount of EMS memory to be allocated to the RAM disk.
Act_ems = Actual amount of EMS memory available in the terminal.
Rdisk_ttl and Rdisk_ems are values passed by the initialization program. Act_ems is obtained by making a BIOS interrupt call when the driver is running.
If Rdisk_ttl >Rdisk_ems:
RAM Disk memory = Rdisk_ems taken from EMS memory + (Rdisk_ttl - Rdisk_ems) taken fromconventional RAM memory
If Rdisk_ems >Act_ems:
RAM Disk memory = Act_ems taken from EMS memory + (Rdisk_ttl - Act_ems) taken from conventional RAM memory
If Rdisk_ems < Act_ems:
RAM Disk memory = Rdisk_ems taken from EMS memory + (Rdisk_ttl - Rdisk_ems) taken from conventional RAM memory
2-14 Device Drivers
TPA Allocation If the TPA size parameters are set in the initialization program, the following algorithm determines the total size of the RAM disk (Rdisk_ttl) and the amount of EMS memory to be allocated to the RAM disk (Rdisk_ems).
Tpa_ttl = Size of TPA.
Resv_ems = Amount of EMS memory reserved for non-RAM Disk usage (possibly reserved for the EMM driver).
Act_conv = Actual amount of conventional RAM available in the terminal.
Act_ems = Actual amount of EMS memory available in the terminal.
Tpa_ttl and Resv_ems are values passed by the initialization program. Act_conv and Act_ems are obtained by making a BIOS interrupt call when the driver is running.
If Act_ems >Resv_ems
Rdisk_ttl = Act_conv + Act_ems - Resv_ems - Tpa_ttl
Rdisk_ems = Act_ems - Resv_ems
If Act_ems < Resv_ems
Rdisk_ttl = Act_conv - Tpa_ttl
Rdisk_ems = 0
2-15 Series 3000 Application Programmer’s Reference Manual
PAN3000.SYS S3000
The Screen Panning driver allows the smaller screen of the terminal to emulate larger screens. It does so by performing two functions. First, using pre-defined keys, it allows an operator to position the physical screen in order to view all parts of the virtual screen. (The virtual screen size must be larger than the physical screen size.) Second, it positions the physical screen window according to the current cursor position so that the operator always sees the part of the virtual screen to which the cursor has been moved.
Row, 0, Column 0
Physical Screen Virtual Screen (25x80)
Row 24, Column 79
Figure 2-1. Screen Panning Driver Syntax To install this driver, add the following line to your terminal's CONFIG.SYS file:
DEVICE=B:PAN3000.SYS
Example DEVICE=B:PAN3000.SYS
2-16 Device Drivers
Moving the Screen The following CTRL key sequences pan the screen as indicated:
Key Sequence Function
1. The source code for this driver provides a sample of how to write a driver for this system and how to use BIOS calls. Refer to the Video Services section in the ROM BIOS chapter of the Series 3000 System Software Manual. 2. Having the source code allows you to modify it to meet the needs of your large screen applications. This driver is not intended to provide the solution to all small screen within large screen issues. It is provided as a sample and a starting point for those who want to increase the usefulness of the driver and tailor it to their own large- screen needs.
2-17 Series 3000 Application Programmer’s Reference Manual
PGM3000.SYS S3000
PGM3000.SYS displays a message on the Series 3000 terminal screen when the operator sets the scanner trigger key through the keyboard. Syntax To install this driver, add the following line to your terminal's CONFIG.SYS file:
DEVICE=B:PGM3000.SYS
Source Code The source code for this driver is included in the ADK, version 3.01 and above, so you can modify the messages. The source file is called PGM3000.ASM and can be found in the C:\3000\SAMPLE directory in the ADK.
Once you have modified the file, use the NMAKE command to on the PGM3000. make file to generate a new PGM3000.SYS:
C:\>nmake\3000\sample\pgm3000
Operation The operator programs the trigger key by pressing FUNC followed by the desired trigger key, left or right. With PGM3000.SYS installed, one of these messages is then displayed:
RIGHT TRIGGER ->
or
<- LEFT TRIGGER
2-18 Device Drivers
FLASHDSK.SYS S3000
Introduction The Series 3000 Flash Disk Device Driver (FLASHDSK.SYS) provides the Series 3000 terminal with a DOS disk interface for the 1 MB of flash located on the Spectrum24 board. Because the flash device is an NVM device, it retains its contents even when power is not applied.
The standard DOS commands COPY, XCOPY, MKDIR, and RMDIR can be used, and programs stored on the Flash Disk can be executed. Installation and Configuration The Flash Disk device driver is installed through the CONFIG.SYS file which is usually located on B:. The command line in CONFIG.SYS is:
DEVICE=[drive:]flashdsk.sys
The Flash Disk device driver does not support any command line options.
When the device driver is loaded, it occupies a single disk drive letter in the DOS disk list. The drive letter allocated to the Flash Disk is dependent upon the other block device drivers loaded on the system before the Flash Disk drive. Generally, the drive letter E: is allocated to the Flash Disk.
The Flash Disk device driver checks for the flash in the system and fails to load if the flash is not present. If the flash has not previously been formatted as a disk, the device driver automatically formats the disk.
We recommend that you use the flash disk (E:) mainly for application and configuration file storage. It is important to note that because of the slow writing time (3-4 seconds for a small file, a minute or more for a large file), writing files during a power interruption (low battery, dead battery, suspend, power off, or power failure) could corrupt the disk. Be sure to only write data to the disk with the terminal connected to external power or with the battery fully charged to avoid problems. To avoid overwriting the flash disk by mistake, the flash disk is set to read-only mode for normal operation.
2-19 Series 3000 Application Programmer’s Reference Manual
Utilities Two related utilities, FLSHFMT.EXE and FLSHCTL.EXE, are provided to format the disk and make the disk write enabled or read only. Operation When the Flash Disk device driver is installed from CONFIG.SYS, the Flash Disk is in read-only mode. Before any disk or file commands that write to the disk (e.g., COPY, DEL, etc.) can be performed, the Flash Disk must be write- enabled by the FLSHCTL utility. In the write-enable mode, a 90 KB cache buffer is created in RAM for the disk File Allocation Table (FAT) and for a data sector. When the disk for file modification process is complete, the buffer must be written (flushed) to the flash. Failure to flush the buffer upon completion of the file commands may result in data loss in the event of a power fault. Example The following is an example of a batch file to copy files from the B: drive TO the Flash Disk E:
REM Sample program to copy files from B: to E: REM Write-enable the flash disk FLSHCTL/W copy b:*.*e: REM Flash the cache buffer FLSHCTL/F REM Set the flash disk to read-only mode FLSHCTL/RO
2-20 Device Drivers
FLSHFMT.EXE Description The format utility formats a flash disk in preparation for operation. The utility creates a new FAT and allows the user to erase all flash devices. You do not need to reboot the terminal after the format is complete. Syntax FLSHFMT /F:[XXXX] where:
/F = Number of files (16 through 1024) in Root Directory (default=64)
/Y= Suppress “Are You Sure” question
2-21 Series 3000 Application Programmer’s Reference Manual
FLSHCTL.EXE Description The FLSHCTL.EXE enables and disables the write capability of the device driver. This utility runs from either the command line or a batch file. Syntax FLSHCTL [/W] [/RO] [/F]
where:
/W Flash Disk is write enabled. /RO Flash Disk is read only. /F Flush the cache from RAM to Flash.
2-22 Chapter 3 BIOS Library Functions
Chapter Contents Introduction ...... 3-5 BIOS Library Functions (Listing)...... 3-5 BIOS LibraryFunctions (Descriptions) ...... 3-10 BiosAllocQueues ...... 3-11 BiosAllocTimer...... 3-13 BiosAutoRepeat ...... 3-14 BiosBeep ...... 3-15 BiosBeepFreq ...... 3-16 BiosBeepOff ...... 3-17 BiosCalcCRC...... 3-18 BiosChkBattery...... 3-19 BiosCheckCursor ...... 3-20 BiosCheckKey...... 3-21 BiosCheckTimer ...... 3-22 BiosClick ...... 3-24 BiosClosePort ...... 3-25 BiosClrKey ...... 3-26 BiosClrScr ...... 3-27 BiosControlDataBus ...... 3-28 BiosDelay...... 3-29 BiosExtSerialSetup ...... 3-30 BiosFreeQueues ...... 3-33 BiosFreeTimer...... 3-34 BiosGetAbortStatus ...... 3-35 BiosGetAlarm ...... 3-36 BiosGetBackLightTime ...... 3-37 BiosGetChar ...... 3-38 BiosGetCharAttr...... 3-39 BiosGetChargingRate ...... 3-40 BiosGetCommType ...... 3-41 BiosGetContextBuf...... 3-42 BiosGetCradleType ...... 3-43 BiosGetCursorMode ...... 3-44
3-1 Series 3000 Application Programmer’s Reference Manual
BiosGetCursorPos ...... 3-45 BiosGetCursorSize ...... 3-46 BiosGetDate ...... 3-47 BiosGetDisplayPage ...... 3-48 BiosGetEMSConfig ...... 3-49 BiosGetEquipList ...... 3-50 BiosGetFont...... 3-51 BiosGetGlobalWrtProt...... 3-52 BiosGetGrantStatus ...... 3-53 BiosGetKeyboardState...... 3-54 BiosGetKybdTimeout ...... 3-55 BiosGetLogPage ...... 3-56 BiosGetLogPageCnt...... 3-57 BiosGetLogScrSize ...... 3-58 BiosGetModemStatus ...... 3-59 BiosGetPhysicalPos ...... 3-60 BiosGetPhysScrSize ...... 3-61 BiosGetPowerSource ...... 3-62 BiosGetQueuePtr ...... 3-63 BiosGetRamSize ...... 3-64 BiosGetRedLED ...... 3-65 BiosGetSerialSetup...... 3-66 BiosGetShiftStatus ...... 3-67 BiosGetTermType ...... 3-68 BiosGetTicks ...... 3-69 BiosGetTime ...... 3-70 BiosGetVersions ...... 3-71 BiosGetVideoMode ...... 3-72 BiosGetViewAngle...... 3-73 BiosGetVirScrSize ...... 3-74 BiosGetWrtProt ...... 3-75 BiosHideCursor ...... 3-76 BiosInitSerialPort ...... 3-77 BiosLED...... 3-79 BiosLineTurn ...... 3-80 BiosMapLogPage ...... 3-81 BiosMemToTextRect ...... 3-82 BiosOpenPort ...... 3-83 BiosOpticalInterface...... 3-84 BiosPortStatus...... 3-85 BiosPowerKey ...... 3-88 BiosPowerOff ...... 3-89 BiosProgramTrigger ...... 3-90 BiosPurgeQueue...... 3-91
3-2 BIOS Library Functions
BiosPutCharAttr...... 3-92 BiosPutCharMove ...... 3-93 BiosPutCharStay ...... 3-94 BiosPutStrMove ...... 3-95 BiosPutStrStay ...... 3-96 BiosPutTicks ...... 3-97 BiosQueueStatus ...... 3-98 BiosRecvBlock...... 3-100 BiosRecvChar ...... 3-102 BiosReleaseModem ...... 3-104 BiosRequestModem...... 3-105 BiosResetAlarm ...... 3-106 BiosResetTimer...... 3-107 BiosResetUART ...... 3-108 BiosResumeTimer ...... 3-110 BiosScrollDown ...... 3-111 BiosScrollUp ...... 3-112 BiosSelectFont...... 3-113 BiosSendBlock ...... 3-114 BiosSendChar ...... 3-116 BiosSerialSetup...... 3-117 BiosSetAlarm ...... 3-119 BiosSetBackLight ...... 3-121 BiosSetBackLightTime...... 3-122 BiosSetChargingRate ...... 3-123 BiosSetContextBuf ...... 3-124 BiosSetCursorMode ...... 3-125 BiosSetCursorPos ...... 3-126 BiosSetCursorSize ...... 3-127 BiosSetDate ...... 3-128 BiosSetDisplayPage ...... 3-129 BiosSetGlobalWrtProt ...... 3-130 BiosSetKeyboardState ...... 3-131 BiosSetKybdTimeout...... 3-132 BiosSetLogScrSize ...... 3-133 BiosSetNotify ...... 3-134 BiosSetPhysicalPos...... 3-136 BiosSetRedLED...... 3-137 BiosSetTime...... 3-138 BiosSetTimer...... 3-139 BiosSetUART ...... 3-140 BiosSetVideoMode...... 3-142 BiosSetViewAngle ...... 3-143 BiosSetVirScrSize ...... 3-144
3-3 Series 3000 Application Programmer’s Reference Manual
BiosSetWakeReason...... 3-146 BiosShowCursor...... 3-148 BiosSpottingBeam ...... 3-149 BiosSuspendTimer ...... 3-150 BiosTextRectToMem ...... 3-151 BiosTransDone ...... 3-152 BiosUpdateTimer ...... 3-153 BiosWakeUpReason...... 3-154 BiosWarmBoot ...... 3-155
3-4 BIOS Library Functions
Introduction The functions contained in the BIOS interface library provide a C interface to Series 3000 ROM BIOS services. It is located in the BIOS.LIB file on the C:\3000\LIB directory in the ADK.
Calls to the BIOS are responsible for all direct hardware control of the terminal. The Series 3000 BIOS is based on the IBM-PC ROM BIOS. The BIOS supports all of the IBM-PC BIOS services plus additional calls required to support hardware unique to Series 3000 terminals. IBM-PC services that support hardware that does not exist on Series 3000 terminals are null operations on Series 3000 terminals.
For more information concerning ROM BIOS services, refer to the ROM BIOS chapter in the Series 3000 System Software Manual. BIOS Library Functions (Listing) Table 3-1 lists the BIOS library (BIOS.LIB) functions in order of the interrupt and function numbers of the corresponding ROM BIOS service. Descriptions of these functions in alphabetical order by function name are provided in the BIOS Library Functions (Descriptions) section that follows in this chapter. Descriptions of the associated ROM BIOS services are provided in the ROM BIOS chapter of the Series 3000 System Software Manual, presented by category of service. Table 3-1. BIOS Library of C (BIOS.LIB) Interface Functions
Function Name Interrupt Number Function Number Category BiosHideCursor A1h 01h Video BiosSetCursorSize A1h 01h Video BiosShowCursor A1h 01h Video BiosSetCursorPos A1h 02h Video BiosCheckCursor A1h 03h Video BiosGetCursorPos A1h 03h Video BiosGetCursorSize A1h 03h Video BiosSetDisplayPage A1h 05h Video BiosClrScr A1h 06h Video
3-5 Series 3000 Application Programmer’s Reference Manual
Table 3-1. BIOS Library of C (BIOS.LIB) Interface Functions (Continued)
Function Name Interrupt Number Function Number Category BiosScrollUp A1h 06h Video BiosScrollDown A1h 07h Video BiosGetCharAttr A1h 08h Video BiosPutCharAttr A1h 09h Video BiosPutCharStay A1h 0Ah Video BiosPutCharMove A1h 0Eh Video BiosGetDisplayPage A1h 0Fh Video BiosGetVideoMode A1h 0Fh Video BiosSetViewAngle A1h 80h Video BiosGetViewAngle A1h 81h Video BiosSetBackLight A1h 82h Video BiosGetPhysScrSize A1h 84h Video BiosSetCursorMode A1h 86h Video BiosGetCursorMode A1h 87h Video BiosTextRectToMem A1h 8Ah Video BiosMemToTextRect A1h 8Bh Video BiosSelectFont A1h 8Ch Video BiosGetFont A1h 8Dh Video BiosSetVideoMode A1h -- Video BiosPutStrStay A1h 1300h Video BiosPutStrMove A1h 1301h Video BiosSetBackLightTime A1h 8202h Video BiosGetBackLightTime A1h 8203h Video BiosSetVirScrSize A1h 8300h Video BiosGetVirScrSize A1h 8301h Video BiosSetLogScrSize A1h 8500h Video BiosGetLogScrSize A1h 8501h Video BiosSetPhysicalPos A1h 8900h Video BiosGetPhysicalPos A1h 8901h Video BiosGetEquipList A2h -- Equipment
3-6 BIOS Library Functions
Table 3-1. BIOS Library of C (BIOS.LIB) Interface Functions (Continued)
Function Name Interrupt Number Function Number Category BiosInitSerialPort A5h 00h Serial I/O BiosSendChar A5h 01h Serial I/O BiosRecvChar A5h 02h Serial I/O BiosGetModemStatus A5h 03h Serial I/O BiosExtSerialSetup A5h 80h Serial I/O BiosGetSerialSetup A5h 81h Serial I/O BiosOpenPort A5h 82h Serial I/O BiosClosePort A5h 83h Serial I/O BiosSendBlock A5h 84h Serial I/O BiosRecvBlock A5h 85h Serial I/O BiosQueueStatus A5h 86h Serial I/O BiosPortStatus A5h 87h Serial I/O BiosLineTurn A5h 88h/89h Serial I/O BiosTransDone A5h 8Ah Serial I/O BiosSetUART A5h 8Bh Serial I/O BiosResetUART A5h 8Ch Serial I/O BiosAllocQueues A5h 8Dh Serial I/O BiosPurgeQueue A5h 8Eh Serial I/O BiosSetNotify A5h 8Fh Serial I/O BiosControlDataBus A5h 90h Serial I/O BiosFreeQueues A5h 91h Serial I/O BiosGetQueuePtr A5h 92h Serial I/O BiosGetCommType A5h 93h Serial I/O BiosGetChar A7h 00h Keyboard BiosCheckKey A7h 01h Keyboard BiosGetShiftStatus A7h 02h Keyboard BiosClick A7h 04h Keyboard BiosAutoRepeat A7h 80h Keyboard BiosSetKybdTimeout A7h 82h Keyboard BiosGetKybdTimeout A7h 82h Keyboard
3-7 Series 3000 Application Programmer’s Reference Manual
Table 3-1. BIOS Library of C (BIOS.LIB) Interface Functions (Continued)
Function Name Interrupt Number Function Number Category BiosSetKeyboardState A7h 83h Keyboard BiosGetKeyboardState A7h 84h Keyboard BiosClrKey A7h 85h Keyboard BiosGetAbortStatus A7h 86h Keyboard BiosProgramTrigger A7h 88h Keyboard BiosClick A7h -- Keyboard BiosGetTicks AAh 00h Time BiosPutTicks AAh 01h Time BiosGetTime AAh 02h Time BiosSetTime AAh 03h Time BiosGetDate AAh 04h Time BiosSetDate AAh 05h Time BiosSetAlarm AAh 80h Time BiosGetAlarm AAh 81h Time BiosResetAlarm AAh 82h Time BiosGetRamSize ABh 01h EMS BiosGetWrtProt ABh 03h EMS BiosGetLogPageCnt ABh 04h EMS BiosGetEMSConfig ABh 05h EMS BiosMapLogPage ABh 07h EMS BiosGetContextBuf ABh 08h EMS BiosSetContextBuf ABh 09h EMS BiosSetGlobalWrtProt ABh 0Fh EMS BiosGetGlobalWrtProt ABh 10h EMS BiosGetLogPage ABh 11h EMS BiosAllocTimer ACh 00h Timer BiosFreeTimer ACh 01h Timer BiosSetTimer/ ACh 02h Timer BiosResetTimer ACh 04h Timer BiosSuspendTimer ACh 05h Timer
3-8 BIOS Library Functions
Table 3-1. BIOS Library of C (BIOS.LIB) Interface Functions (Continued)
Function Name Interrupt Number Function Number Category BiosResumeTimer ACh 06h Timer BiosCheckTimer ACh 07h Timer BiosDelay ACh 08h Timer BiosUpdateTimer ACh 09h Timer BiosBeepFreq ADh 00h Sound BiosBeepOff ADh 001h Sound BiosBeep ADh 02h Sound BiosCalcCRC AEh 01h CRC BiosGetVersions AFh -- Version BiosGetTermType AFh -- Terminal BiosPowerOff B1h 00h Power BiosSetWakeReason B1h 01h Power BiosWakeUpReason B1h 02h Power BiosChkBattery B1h 03h Power BiosPowerKey B1h 0Ch Power BiosGetPowerSource B1h 0Fh Power BiosSpottingBeam B3h 0Eh Scanner BiosWarmBoot B4h -- Warm Boot BiosLED B6h 00h,01h,02h LED BiosGetCradleType B8h 00h Cradle BiosGetChargingRate/ B8h 01h Cradle BiosSetChargingRate BiosGetRedLED/ B8h 02h Cradle BiosSetRedLED BiosGetGrantStatus/ B8h 03h Cradle BiosReleaseModem/ BiosRequestModem BiosOpticalInterface B8h 05h Cradle
3-9 Series 3000 Application Programmer’s Reference Manual
BIOS LibraryFunctions (Descriptions) This section provides descriptions of the BIOS Library functions that are listed in Table 3-1. The descriptions begin on the next page, in alphabetical order by function name. Descriptions of the associated ROM BIOS services can be found the the ROM BIOS chapter of the Series 3000 System Software Manual, where they are provided in order of interrupt number and function number within the appropriate category of service (Video, Memory, etc.).
3-10 BIOS Library Functions
BiosAllocQueues Purpose Use BiosAllocQueues( ) to set up the FIFO transmit and receive queues for the selected serial port. Syntax #include <3000\bios.h>
unsigned int _far BiosAllocQueues(int PortNumber, _SYM_QUEUE _far *Queues);
Example Call unsigned int Status; _SYM_QUEUE Queues;
_dos_allocmem( 16, &Queues.InSeg); // Alloc 256 bytes paragraph aligned _dos_allocmem( 16, &Queues.OutSeg); // Alloc 256 bytes paragraph aligned Queues.InSize = Queues.OutSize = 256;
Status = BiosAllocQueues(_SYM_COM1, Queues);
Description BiosAllocQueues sets up the FIFO transmit and receive queues for the selected serial port. This service must be called before initially opening the communications session or an error occurs on the subsequent open.
Queues must be paragraph aligned and the passed segment address must point to the first location of the queue. The actual size of the queue is the passed size minus 8 bytes of queue overhead. The maximum queue size is 32767 bytes plus 8 bytes for overhead. The minimum queue size is 24 bytes plus 8 bytes for overhead.
BiosAllocQueues calls BIOS interrupt A5h, function 8Dh.
3-11 Series 3000 Application Programmer’s Reference Manual
Returns Status Value Meaning Define name
0 Queues Setup Successfully _SYM_SUCCESS
Non-Zero Error. See description of _ErrStatusin _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also BiosFreeQueues( )
3-12 BIOS Library Functions
BiosAllocTimer Purpose Use BiosAllocTimer( ) to allocate a timer from the system timer pool. Syntax #include <3000\bios.h>
unsigned char _far BiosAllocTimer( void )
Example Call unsigned char TimerNumber;
TimerNumber = BiosAllocTimer();
Description BiosAllocTimer sets the timer status to “allocated,” and zeros the count and the dispatch address.
BiosAllocTimer calls BIOS interrupt ACh, function 00h. Returns Status Value Meaning Define name
0 Timer could not be allocated; _SYM_NO_TIMERS None Available
Non-Zero Timer Number allocated See Also BiosFreeTimer( )
3-13 Series 3000 Application Programmer’s Reference Manual
BiosAutoRepeat Purpose Use BiosAutoRepeat( ) to set the delay time for auto key repeat. Syntax #include <3000\bios.h>
extern void_far BiosAutoRepeat(unsigned int initdelay, ⇒ unsigned int repdelay);
Description The BiosAutoRepeat function sets the initial and repeat delay time of the auto key repeat. This function expects an initial and repeat delay time in milliseconds. If the initial delay time equals zero, the auto key repeat is disabled.
BiosAutoRepeat calls BIOS interrupt A7h, function 80h. Returns None
3-14 BIOS Library Functions
BiosBeep Purpose Use BiosBeep( ) to sound the terminal beep for a specified time. Syntax #include <3000\bios.h>
extern void_far BiosBeep(unsigned int msec);
Description The BiosBeep function turns on the alarm for a specified time. The length of time is specified in milliseconds.
The frequency of the alarm is fixed when calling the function to a value near the optimum for the sound generation device.
BiosBeep calls BIOS interrupt ADh, function 02h. Returns None
3-15 Series 3000 Application Programmer’s Reference Manual
BiosBeepFreq Purpose Use BiosBeepFreq( ) to turn on the speaker at a given frequency. Syntax #include <3000\bios.h>
void _far BiosBeepFreq(unsigned int Hertz );
Example Call BiosBeepFreq(1000); // Start tone at 1000 Hz
Description Turns on the series 3000 speaker at a specific frequency in Hertz. Using a parameter value of 0 (the default) selects the loudest frequency, i.e. the optimal frequency for the terminal speaker.
BiosBeepFreq calls BIOS interrupt ADh, function 00h.
The speaker will remain on until it is turned off. Returns None See Also BiosBeepOff
3-16 BIOS Library Functions
BiosBeepOff Purpose Use BiosBeepOff( ) to turn off the terminal speaker. Syntax #include <3000\bios.h>
void _far BiosBeepOff( void );
Example Call BiosBeepOff(); // Turn off speaker while beeping.
Description BiosBeepOff turns off the Series 3000 speaker by stopping the sound set by BiosBeepFreq( ).
BiosBeepOff calls BIOS interrupt ADh, function 01h. Returns None See Also BiosBeepFreq
3-17 Series 3000 Application Programmer’s Reference Manual
BiosCalcCRC Purpose Use BiosCalcCRC( ) to calculate a running CRC-16 on the specified buffer. Syntax #include <3000\bios.h>
unsigned int _far
BiosCalcCRC( char _far *DataPtr, unsigned int Length );
Example Call unsigned int CRC;
char DataPtr[128];
CRC = BiosCalcCRC(DataPtr, sizeof(DataPtr));
Description Calculates a running CRC-16 on the specified buffer. If a buffer size of 0 is specified, the function returns immediately.
BiosCalcCRC calls BIOS interrupt AEh, function 01h. Returns 16 Bit CRC of buffer
3-18 BIOS Library Functions
BiosChkBattery Purpose Use BiosChkBattery( ) to get the charge status of the terminal batteries. Syntax #include <3000\bios.h>
unsigned int_far BiosChkBattery(void);
Description The BiosChkBattery function returns the current status of the battery cells.
BiosChkBattery calls BIOS interrupt B1h, function 03h.
Caution Do not use this service in a tight loop because it will drain the charge in lithium batteries on 33xx terminals.
Returns BiosChkBattery returns a one word value:
Low byte of word = main cell status:
0 = good, 1 = low, 2 = dead.
High byte of word = lithium cell status:
0 = dead, 1 = good, 2 = lithium not supported.
3-19 Series 3000 Application Programmer’s Reference Manual
BiosCheckCursor Purpose Use BiosCheckCursor( ) to determine if the cursor is displayed. Syntax #include <3000\bios.h>
extern char_far BiosCheckCursor(void);
Description The BiosCheckCursor function checks to see if the cursor is displayed.
BiosCheckCursor calls BIOS interrupt A1h, function 03h. Returns Value Meaning
1 The cursor is displayed
0 The cursor is not displayed
3-20 BIOS Library Functions
BiosCheckKey Purpose Use BiosCheckKey( ) to determine whether there is a character in the input buffer. Syntax #include <3000\bios.h>
extern unsigned int_far BiosCheckKey(void);
Description The BiosCheckKey function checks whether an input character is available without removing it from the input buffer.
BiosCheckKey calls BIOS interrupt A7h, function 01h.
If BiosCheckKey( ) is to be used in a loop until a key is ready, a short BiosDelay( ) (approximately 100 ms) should be used if battery life is important. Returns The BiosCheckKey function returns a scan code in the upper byte, the character in the lower byte, or 0000 if no keyboard character is available. See Also BiosGetChar
3-21 Series 3000 Application Programmer’s Reference Manual
BiosCheckTimer Purpose Use BiosCheckTimer( ) to obtain information about a TimerNumber. Syntax #include <3000\bios.h>
unsigned char _far
BiosCheckTimer( unsigned char TimerNumber, ⇒ TIMERINFO _far * TimerInfo)
Example Call unsigned char Status; TIMERINFO TimerInfo; Status = BiosCheckTimer( TimerNumber, &TimerInfo ); if (!Status)
{ printf("Timer Status %u\n, TimerInfo.TimerStatus); printf("Timer Type %u\n, TimerInfo.TimerType); printf("Timer Ticks %u\n, TimerInfo.TickCount); printf("Milliseconds %lu\n, (unsigned long) (TimerInfo.TickCount * 27)); printf("Timer Addr %p\n, TimerInfo.Address); }
Description BiosCheckTimer returns the current status of the specified timer without changing the timer status.
BiosCheckTimer calls BIOS interrupt ACh, function 07h.
3-22 BIOS Library Functions
Returns Returns timer information gathered in TIMERINFO structure See Also BiosSetTimer( )
3-23 Series 3000 Application Programmer’s Reference Manual
BiosClick Purpose Use BiosClick to set the duration of the key click. Syntax #include <3000\bios.h>
extern void_far BiosClick(unsigned int time);
Description The BiosClick function sets the duration of key click if value is greater than zero. If value is zero, key clicks are disabled.
BiosClick calls BIOS interrupt A7h, function 04h. Returns None
3-24 BIOS Library Functions
BiosClosePort Purpose Use BiosClosePort( ) to close a serial port previously opened using BiosOpenPort( ). Syntax #include <3000\bios.h>
unsigned int _far BiosClosePort(int PortNumber );
Example Call unsigned Status; Status = BiosClosePort(_SYM_COM1 );
Description BiosClosePort closes a communications port previously opened using BiosOpenPort( ).
BiosClosePort calls BIOS interrupt A5h, function 83h. Returns Status Value Meaning Define name
0 Port Closed Successfully _SYM_SUCCESS
Non-Zero Error Closing Port.
See description of _ErrStatus in _SYM_SERIAL structure. Refer to BiosPortStatus below for _ErrStatus bit descriptions. See Also BiosOpenPort( )
3-25 Series 3000 Application Programmer’s Reference Manual
BiosClrKey Purpose Use BiosClrKey to specify the system abort key. Syntax #include <3000\bios.h>
extern void_far BiosClrKey(unsigned char scancode);
Description The BiosClrKey function selects the scan code to use for the abort key. The abort key allows the operator to terminate communications, delay, and beeps.
When the BIOS detects this scan code, it sets the ABORT flag. The flag remains set until the BiosGetAbortStatus function is called, after the system receives the corresponding break code for that scan code.
BiosClrKey calls BIOS interrupt A7h, Function 85h. Returns None See Also BiosGetAbortStatus
3-26 BIOS Library Functions
BiosClrScr Purpose Use BiosClrScr to clear the terminal screen. Syntax #include <3000\bios.h>
extern void_far BiosClrScr(unsigned char fillattr);
Description The BiosClrScr function clears the screen with attribute fillattr.
Valid attributes are:
Attribute Meaning
0x07 Normal Video
0x70 Reverse Video
Reverse Video is supported in the default soft fonts modes only.
BiosClrScr calls BIOS interrupt A1h, function 06h. Returns None See Also BiosScrollUp( ) BiosScrollDown( )
3-27 Series 3000 Application Programmer’s Reference Manual
BiosControlDataBus Purpose Use BiosControlDataBus( ) to request or release the CCM data bus. Syntax #include <3000\bios.h>
unsigned char _far BiosControlDataBus(unsigned char FunctionRequest);
Example Call unsigned char Status;
Status = BiosControlDataBus(_SYM_REQUEST_BUS );
Description BiosControlDataBus, when used with multi-access mode, requests or releases the data bus. This function is used mainly with the Charging and Communications Module (CCM, or cradle).
BiosControlDataBus calls BIOS interrupt A5h, function 90h. Returns Status Value Meaning Define name
0 Data Bus Control Given; Successful _SYM_SUCCESS
1Data Bus Control Request Failed
3-28 BIOS Library Functions
BiosDelay Purpose Use BiosDelay to cause a delay of specified duration. Syntax #include <3000\bios.h>
extern void_far BiosDelay(unsigned long delaytime);
Description The BiosDelay function causes a delay for a specified number of milliseconds. This function does not return until the specified time has elapsed. Calling this function saves battery life if power save is enabled.
BiosDelay calls BIOS interrupt ACh, function 08h. Returns None
3-29 Series 3000 Application Programmer’s Reference Manual
BiosExtSerialSetup Purpose Use BiosExtSerialSetup to set the extended serial port parameters for a specified port. Use BiosExtSerialSetup when the BiosSerialSetup( ) parameters need customization. Syntax #include <3000\bios.h>
unsigned char _far BiosExtSerialSetup(int PortNumber, ⇒ _SYM_SERIAL _far *SerialParams);
Example Call unsigned char Status; _SYM_SERIAL SerialParams;
/* Setup the extended serial interface for a standard 3 wire intf*/ SerialParams.BPS = _SYM_BAUD_9600; SerialParams.DataBits = _SYM_8BITS; SerialParams.Parity = _SYM_PARITY_NONE; SerialParams.StopBits = _SYM_1_STOP; SerialParams.Duplex = _SYM_FULL_DUPLEX; SerialParams.ModemDelay = 0;/* No modem delay (milliseconds)*/ SerialParams.TxCarrierWait = 0;/* No tx wait time (milliseconds) */ SerialParams.RxCarrierWait = 0;/* Ignored time if 0 */ SerialParams.CarrierLoss = 0;/*No carrier loss detect*/ SerialParams.CtrlStopChar = _SYM_CTRL_S /* 0x13;ÿ */ SerialParams.CtrlStartChar = _SYM_CTRL_Q /* 0x11; */ SerialParams.CtrlStartWait = 0;/* No control start wait time.*/
SerialParams.CTSLossTime = 0;/* No CTS loss detection */ SerialParams.RxCharWait = 0;/* No receive char wait time */ SerialParams.DSRWaitTime = 0;/* No DSR Wait Time */
3-30 BIOS Library Functions
SerialParams.CDWaitTime = 0;/* No Carrier Detect wait time.*/ SerialParams.SpaceTime = 0;/* No Space Time */ SerialParams.MarkTime = 0;/* No Mark Time */ SerialParams.LineCondFlags = 0;/* No Line Conditioning*/ SerialParams.FlowControl = _SYM_NO_FLOW_CTL;
SerialParams.ErrorMask = (_SYM_OVERRUN_DETECT | _SYM_PARITY_DETECT | _SYM_FRAMING_DETECT | _SYM_BREAK_DETECT ); SerialParams.ErrorInsChar = 0;/* No Error Insertion Character */ SerialParams.DTRSettleTime = 0; /*No DTR Settling time*/ SerialParams.ConnectTime = 0;/* No Connect Time */
Status = BiosExtSerialSetup(_SYM_COM1, &SerialParams);
Description BiosExtSerialSetup initializes the Channel Control Block (CCB) for the specified serial port using the parameters set in the _SYM_SERIAL structure. This routine is commonly used when customization of one or more parameters outside the normal three wire interface parameters does not meet the needs of the application.
To initialize the serial port to a standard three wire interface with fewer options, use BiosSerialSetup( ).
BiosExtSerialSetup calls BIOS interrupt A5h, function 80h.
3-31 Series 3000 Application Programmer’s Reference Manual
Returns Status Value Meaning Define name
0 Port Initialized Successfully _SYM_SUCCESS
1 Error initializing. See _ErrStatus _SYM_FAILED
and_ErrConfig flags in the _SYM_ SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also BiosSerialSetup( )
3-32 BIOS Library Functions
BiosFreeQueues Purpose Use BiosFreeQueues( ) to free the pointers to the current communications queues. Syntax #include <3000\bios.h> unsigned int _far BiosFreeQueues(unsigned int PortNum();
Example Call unsigned int Status; Status = BiosFreeQueues( _SYM_COM1 );
Description Deletes the current communications queues which were allocated by a previous BiosAllocQueues( ). Subsequent Opens fail if new queues are not allocated using BiosAllocQueues( ).
BiosFreeQueues calls BIOS interrupt A5h, function 91h. Returns Status Value Meaning Define name
0 Queue freed; Successful _SYM_SUCCESS
Non-Zero Error. See description of _ErrStatus in _SYM_SERIAL structure.
Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also BiosAllocQueues
3-33 Series 3000 Application Programmer’s Reference Manual
BiosFreeTimer Purpose Use BiosFreeTimer to de-allocate a timer which was previously allocated using BiosAllocTimer( ), and return it to the system timer pool. Syntax #include <3000\bios.h> void _far BiosFreeTimer( unsigned char TimerNumber )
Example Call BiosFreeTimer( TimerNumber );
Description Returns the specified timer to the system timer pool.
BiosFreeTimer calls BIOS interrupt ACh, function 01h. Returns Status Value Meaning Define name
0 Timer returned to pool _SYM_TIMER_FREED
1 TimerNumber is out of range _SYM_OUTOFRANGE See Also BiosAllocTimer( )
3-34 BIOS Library Functions
BiosGetAbortStatus Purpose Use BiosGetAbortStatus to determine the current status of the abort key. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetAbortStatus(void);
Description The BiosGetAbortStatus function returns the current status of the abort key. The abort key is selected using BiosClrKey.
BiosGetAbortStatus calls BIOS interrupt A7h, function 86h. Returns The BiosGetAbortStatus function returns:
Value Meaning
0 no abort key pressed 1 reserved 2 abort key pressed and released (since last call to this service) 3 abort key down now See Also BiosClrKey( )
3-35 Series 3000 Application Programmer’s Reference Manual
BiosGetAlarm Purpose Use BiosGetAlarm retrieve the current status of the alarm and its time and date settings. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetAlarm(unsigned char_far * DOM, ⇒ unsigned char_far * DOW, ⇒ unsigned char_far * hours, ⇒ unsigned char_far * mins, ⇒ unsigned char_far * secs);
Description The BiosGetAlarm function reads the real time clock alarm from the keyboard processor. This function expectsfar pointers for the return values.
BiosGetAlarm calls BIOS interrupt AAh, function 81h. Returns Returns the day of month to the variable DOM, returns the day of week to the variable DOW, returns the hours to the variable hours, returns the minutes to the variable mins, and returns the seconds to the variable secs.
The function return value is the alarm status, as follows:
Value Alarm Status
0Reset 1Active 2Occurred
Note: All of the return values are in Packed BCD format. See Also BiosSetAlarm, BiosResetAlarm
3-36 BIOS Library Functions
BiosGetBackLightTime Purpose Use BiosGetLightTime( ) to retrieve the current backlight timeout. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetBackLightTime(void);
Description The BiosGetBackLightTime function returns the current backlight timeout (in seconds).
BiosGetBackLightTime calls BIOS interrupt A1h, function 82h, subservice 03h. Returns Returns the current backlight timeout (in seconds) in hex. See Also BiosSetBackLightTime
3-37 Series 3000 Application Programmer’s Reference Manual
BiosGetChar Purpose Use BiosGetChar( ) to retrieve a character from the keyboard buffer. Syntax #include <3000\bios.h> extern unsigned int_far BiosGetChar(void); Description The BiosGetChar function waits until a keyboard character is available, then returns the character.
BiosGetChar calls BIOS interrupt A7h, function 00h. Returns BiosGetChar returns word whose high and low bytes have the following meaning:
If Low byte!= 0, then: Low byte = ASCII value of the key pressed High byte = scan code of the key pressed If Low byte = 0, then: High byte = scan code of the extended key pressed Examples (all values shown in Hexadecimal): Return value = 0x1E61 Low byte = 61 (1=0), so 61 is an ASCII value (in this case ’a’). High byte = 1E, the scan code of the ’a’ key. Return value = 0x3B00 Low byte = 0, so the High byte is an extended code High byte = 3B, the scan code of F1 See Also BiosCheckKey
3-38 BIOS Library Functions
BiosGetCharAttr Purpose Use BiosGetCharAttr( ) to retrieve the character and its attributes at the current cursor position. Syntax #include <3000\bios.h>
extern unsigned int_far BiosGetCharAttr(void);
Description The BiosGetCharAttr function returns a character and its attribute at the current cursor position.
Valid attributes are:
Attribute Meaning
0x07 Normal Video 0x70 Reverse Video
Note: Reverse Video is supported only in soft fonts modes.
BiosGetCharAttr calls BIOS interrupt A1h, function 08h. Returns Returns an integer which contains the character in the lower byte and attribute in the upper byte. See Also BiosPutCharAttr
3-39 Series 3000 Application Programmer’s Reference Manual
BiosGetChargingRate Purpose Use BiosGetChargingRate( ) to obtain the charging rate of a terminal in a cradle. Syntax #include <3000\bios.h>
unsigned char _far BiosGetChargingRate( void );
Example Call unsigned char ChargingInfo; ChargingInfo = BiosGetChargingRate();
Description Gets the charging rate information for the Series 3000 terminal if the terminal is in the cradle.
BiosGetChargingRate calls BIOS interrupt B8h, function 01h. Returns Status Value Description Define name 0 Terminal is not charging now _SYM_NOTCHARGING 1 Slow Charging Rate is set _SYM_SLOWRATE 2 Fast Charging Rate is set _SYM_FASTRATE 3 Service Not Supported by this cradle _SYM_NOTSUPPORT See Also BiosSetChargingRate( )
3-40 BIOS Library Functions
BiosGetCommType Purpose Use BiosGetCommType( ) to obtain information about the type of communications board attached to the specified port. Syntax #include <3000\bios.h>
unsigned char _far BiosGetCommType(unsigned char PortNumber );
Example Call unsigned char CommType; CommType = BiosGetCommType(_SYM_COM1 );
Description Returns the Id of the type of comm board attached to the terminal.
BiosGetCommType calls BIOS interrupt A5h, function 93h.
Note: On some older 33xx, Comm adapter boards report “NONE” for _Sym_Com2. Returns Status Value Description Define name
0 None (No board Attached) _SYM_NOBOARD 1 Primary Serial Channel _SYM_PRIMARY 2 COMM Adapter Board _SYM_COMMBOARD 3 Internal Modem _SYM_INTMODEM 4 Comm Adapter Board _SYM_ACOUSTIC w/ acoustic coupler See Also None
3-41 Series 3000 Application Programmer’s Reference Manual
BiosGetContextBuf Purpose Use BiosGetContextBuf to save the current EMS mapping context. Syntax #include <3000\bios.h>
extern char_far BiosGetContextBuf(char start_phy_page, ⇒ int phy_page_num, ⇒ char_far *buf_adr);
Description The BiosGetContextBuf function saves the current EMS mapping context in a buffer. This function expects a starting physical page number, the number of physical pages to save, and the address of a context save buffer. The size of the context buffer should be as returned by BiosGetEMSConfig.
BiosGetContextBuf calls BIOS interrupt ABh, function 08h. Returns Value Meaning
1 Successful 0 The starting page number or page count is out of range See Also BiosSetContextBuf BiosGetEMSConfig
3-42 BIOS Library Functions
BiosGetCradleType Purpose Use BiosGetCradleType to obtain information about the cradle in which a terminal is placed. Syntax #include <3000\bios.h>
unsigned char _far BiosGetCradleType( void );
Example Call unsigned char CradleType; CradleType = BiosGetCradleType();
Description Gets the ID number for the cradle attached to the Series 3000 terminal. This service is only available in system EPROM 2.0 and later.
BiosGetCradleType calls BIOS interrupt B8h, function 00h. Returns Status Value Description Define name
0 Not in cradle _SYM_NOCRADLE 1 Printer Interface Module _SYM_PIM 2 PC Adapter (Zero Slot Cradle) _SYM_PC 3 Old-style multi-slot cradle _SYM_OLDMULT 4 Single-slot cradle _SYM_SINGLE 5 Single-slot cradle with modem _SYM_SMODEM 6 New-style multi-slot cradle _SYM_NEWMULT 7 New-style multi-slot cradle _SYM_NMODEM with modem
3-43 Series 3000 Application Programmer’s Reference Manual
BiosGetCursorMode Purpose Use BiosGetCursorMode to determine whether the terminal is in hardware or software cursor mode. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetCursorMode(void);
Description The BiosGetCursorMode function returns the hardware or software cursor mode. In hardware mode, the system displays a hardware dependant cursor; in software mode, the cursor reflects the current keyboard state. The hardware cursor is a blinking block; the character is visible “under” the cursor. The software cursor resembles a lowercase “v”; the character under the cursor is invisible. At system cold start, the system sets the cursor to hardware mode.
BiosGetCursorMode calls BIOS interrupt A1h, function 87h. Returns The BiosGetCursorMode function returns the hardware or software cursor mode, where:
Value Meaning
0 Hardware (blinking block, character visible)
1 Software (“v” cursor, character invisible) See Also BiosSetCursorMode
3-44 BIOS Library Functions
BiosGetCursorPos Purpose Use BiosGetCursorPos to get the current cursor position. Syntax #include <3000\bios.h>
extern void_far BiosGetCursorPos(unsigned char_far * row, ⇒ unsigned char_far * col);
Description The BiosGetCursorPos function returns the current cursor position.
BiosGetCursorPos calls BIOS interrupt A1h, function 03h. Returns The two function parameters, row and column, are pointers to the return values. The values are the row and column numbers, respectively, starting at 0,0. See Also BiosSetCursorPos
3-45 Series 3000 Application Programmer’s Reference Manual
BiosGetCursorSize Purpose Use BiosGetCursorSize to get the size of the hardware cursor. Syntax #include <3000\bios.h>
extern void_far BiosGetCursorSize(unsigned char_far * start, ⇒ unsigned char_far * end);
Description The BiosGetCursorSize function returns the current cursor size of the display's hardware cursor on CRT-type LCD controllers.
BiosGetCursorSize calls BIOS interrupt A1h, function 03h. Returns The two function parameters, start and end, are pointers to the return values. See Also BiosSetCursorSize
3-46 BIOS Library Functions
BiosGetDate Purpose Use BiosGetDate to retrieve the current system date. Syntax #include <3000\bios.h> extern void_far BiosGetDate(unsigned char_far * dayofweek, ⇒ unsigned char_far * day, ⇒ unsigned char_far * month, ⇒ unsigned char_far * year, ⇒ unsigned char_far * century);
Description The BiosGetDate function returns the current system date. The function expects far pointers in order to return the day of the week, day, month, year, and century. BiosGetDate calls BIOS interrupt AAh, function 04h. Returns Returns the day of the week to the variable dayofweek, returns the day to the variable day, returns the month to the variable month, returns the year to the variable year, and returns the century to the variable century. Day of week values are:
Value Day
0Sunday 1Monday 2Tuesday 3Wednesday 4Thursday 5Friday 6Saturday Note: All of the return values are in Packed BCD format. See Also BiosSetDate
3-47 Series 3000 Application Programmer’s Reference Manual
BiosGetDisplayPage Purpose Use BiosGetDisplayPage to get the current active display page. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetDisplayPage(void);
Description The BiosGetDisplayPage function returns the active display page.
BiosGetDisplayPage calls BIOS interrupt A1h, function 0fh. Returns None See Also BiosSetDisplayPage
3-48 BIOS Library Functions
BiosGetEMSConfig Purpose Use BiosGetEMSConfig to get the current EMS page frame configuration. Syntax #include <3000\bios.h>
extern void_far BiosGetEMSConfig(EMS_INFOP ems_info_ptr);
Description The BiosGetEMSConfig function returns the EMS page frame configuration. This function expects a pointer to a buffer to save the return values.
BiosGetEMSConfig calls BIOS interrupt ABh, function 05h. Returns Returns a pointer to the segment address of the page frame, the number of physical pages, and the required size of the context buffer. See Also BiosGetGlobalWrtProt
3-49 Series 3000 Application Programmer’s Reference Manual
BiosGetEquipList Purpose Use BiosGetEquipList to retrieve a list of installed equipment. Syntax #include <3000\bios.h>
extern unsigned int_far BiosGetEquipList(void);
Description The BiosGetEquipList function returns the standard IBM PC equipment list.
BiosGetEquipList calls BIOS interrupt A2h. Returns BiosGetEquipList returns the standard IBM PC equipment list, as follows: Bits Meaning
9 14 12 10 6 4 2 15 13 11 8 7 5 3 1 0
Disk Drive (1 = present) Math coprocessor (1 = present) System RAM size Initial video mode (bit 4=0, bit 5=1) (80x25 color) Number of disk drives DMA status (0 = present) Number of serial ports Reserved Number of printers
3-50 BIOS Library Functions
BiosGetFont Purpose Use BiosGetFont to get the current font mode. Syntax #include <3000\bios.h>
extern void_far BiosGetFont(unsigned char_far * font_mode, ⇒ unsigned char_far * font_ptr, ⇒ unsigned char_far * dbl_high, ⇒ unsigned char_far * dbl_wide);
Description The BiosGetFont function returns the current font mode. The function expects font_mode to be a pointer to the current font mode, font_ptr to be a pointer to a font definition table, dbl_high to be a pointer to a double high dimension flag (0 = normal, 1 = double high), and dbl_wide to be a double wide dimension flag (0 = normal, 1 = double wide). BiosGetFont calls BIOS interrupt A1h, function 8Dh. Returns The function itself returns void. Via pointer, the function returns the font mode to the variable font_mode, returns the pointer to the font definition table to the variable font_ptr, returns double high and double wide values to the variables dbl_high and dbl_wide. Font modes are:
Value Font Mode
0 Hard Font (Internal) 1Soft Font 2 Hard Font (External) See Also BiosSelectFont
3-51 Series 3000 Application Programmer’s Reference Manual
BiosGetGlobalWrtProt Purpose Use BiosGetGlobalWrtProt to determine whether global write protection is enabled or disabled. Syntax #include <3000\bios.h>
extern char_far BiosGetGlobalWrtProt(char flag);
Description The BiosGetGlobalWrtProt function returns the global write protection status for the 1 MByte memory space.
BiosGetGlobalWrtProt calls BIOS interrupt ABh, function 10h.
Note: Always set the char flag to zero when calling this function. Returns BiosGetGlobalWrtProt returns the current status of the write protection as follows:
Value Status
1Enabled 0 Disabled See Also BiosSetGlobalWrtProt
3-52 BIOS Library Functions
BiosGetGrantStatus Purpose Use BiosGetGrantStatus to obtain the grant status of the modem in the cradle. Syntax #include <3000\bios.h>
unsigned char _far BiosGetGrantStatus( void );
Example Call unsigned char Status; Status = BiosGetGrantStatus();
Description BiosGetGrantStatus gets the modem grant status for the modem in the cradle. This service is only available with system EPROM 2.0 and higher.
BiosGetGrantStatus call BIOS interrupt B8h, function 03h. Returns Status Value Description Define name
0 Modem not granted _SYM_NOT_GRANTED 1Modem granted_SYM_GRANTED 2 Not supported by _SYM_GRNOSUPP current cradle See Also BiosRequestModem( ) BiosReleaseModem( )
3-53 Series 3000 Application Programmer’s Reference Manual
BiosGetKeyboardState Purpose Use BiosGetKeyboardState to retrieve the current keyboard state. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetKeyboardState(void);
Description The BiosGetKeyboardState function returns the current keyboard state.
BiosGetKeyboardState calls BIOS interrupt A7h, function 84h. Returns BiosGetKeyboardState returns the current keyboard state, as follows:
Bits Meaning
7 6 524 3 1 0
Right Shift Left Shift Ctrl Alt Scroll Num Lock Caps Lock Function Shift
See Also BiosSetKeyboardState
3-54 BIOS Library Functions
BiosGetKybdTimeout Purpose Use BiosGetKybdTimeout to get the powerdown timeout. Syntax #include <3000\bios.h>
extern unsigned int_far BiosGetKybdTimeout(void);
Description The BiosGetKybdTimeout function gets the time the keyboard will wait for key entry before powering down.
BiosGetKybdTimeout calls BIOS interrupt A7h, function 82h. Returns The BiosGetKybdTimeout function returns the time (in seconds). See Also BiosSetKybdTimeout
3-55 Series 3000 Application Programmer’s Reference Manual
BiosGetLogPage Purpose Use BiosGetLogPage to save EMS logical pages to a buffer. Syntax #include <3000\bios.h>
extern char_far BiosGetLogPage(unsigned int_far * buffer, ⇒ char phy_page_num,int cnt);
Description The BiosGetLogPage function saves EMS logical page numbers to a buffer. It saves the logical page numbers that are mapped to the specified physical page(s) starting with the page number in the variable phy_page_num and ending with page number reached after incrementing cnt number of pages. This function expects a pointer to a buffer to save the log page numbers, a starting physical page number, and the number of pages to save.
BiosGetLogPage calls BIOS interrupt ABh, function 11h. Returns Value Status
0If error 1Otherwise.
3-56 BIOS Library Functions
BiosGetLogPageCnt Purpose Use BiosGetLogPageCnt to get the EMS fixed logical page count and the maximum number of removable pages. Syntax #include <3000\bios.h> extern void_far BiosGetLogPageCnt(LOG_PAGE_INFOP log_page_info_ptr);
Description The BiosGetLogPageCnt function returns the EMS fixed logical page count and maximum removable logical page. This function expects a pointer to a buffer in which to save the return values.
BiosGetLogPageCnt calls BIOS interrupt ABh, function 04h. Returns Returns a pointer to the fixed logical pages and the maximum removable logical pages. See Also BiosMapLogPage
3-57 Series 3000 Application Programmer’s Reference Manual
BiosGetLogScrSize Purpose Use BiosGetLogScrSize to get the logical screen dimensions. Syntax #include <3000\bios.h>
extern void_far BiosGetLogScrSize(unsigned char_far* rows, ⇒ unsigned char_far * cols);
Description The BiosGetLogScrSize function returns pointers to the size of the logical screen. For more information, see BiosSetLogScrSize.
BiosGetLogScrSize calls BIOS interrupt A1h, function 85, subfunction 01h. Returns Returns the logical screen height to the variable rows and returns the logical screen width to the variable cols. Both are returned as the number of characters of the current font that will fit on the logical screen. See Also BiosSetLogScrSize BiosGetPhysScrSize BiosGetVirScrSize
3-58 BIOS Library Functions
BiosGetModemStatus Purpose Use BiosGetModemStatus to get the current modem status. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetModemStatus(unsigned char port_no);
Description The BiosGetModemStatus function returns the current modem status of the specified serial port. This function expects port_no, the number of the serial port whose status you are requesting.
BiosGetModemStatus calls BIOS interrupt A5h, function 03h. Returns BiosGetModemStatus returns the current modem status of the specified serial port, as follows: Bits Meaning
726 5 4 3 1 0
Delta Clear To Send (CTS) Delta Data Set Ready (DSR) Trailing Edge Ring indicator (RI) Delta Carrier Detect (CD) Clear To Send (CTS) Data Set Ready (DSR) Ring Indicator (RI) Carrier Detect (CD)
3-59 Series 3000 Application Programmer’s Reference Manual
BiosGetPhysicalPos Purpose Use BiosGetPhysicalPos to get the position of the physical display within the virtual display. Syntax #include <3000\bios.h>
extern void_far BiosGetPhysicalPos(unsigned char_far * row ⇒ unsigned char_far * col);
Description The BiosGetPhysicalPos function returns pointers to the position of the physical display within the virtual display. For more information, see BiosSetPhysicalPos.
BiosGetPhysicalPos calls BIOS interrupt A1h, function 89, subfunction 01h. Returns Returns the starting row to the variable row and returns the starting column to the variable col. See Also BiosSetPhysicalPos
3-60 BIOS Library Functions
BiosGetPhysScrSize Purpose Use BiosGetPhysScrSize to get the physical screen size. Syntax #include <3000\bios.h>
extern void_far BiosGetPhysScrSize(unsigned char_far * rows, ⇒ unsigned char_far * cols);
Description The BiosGetPhysScrSize function returns physical screen size values via pointers.
BiosGetPhysScrSize calls BIOS interrupt A1h, function 84h. Returns Returns the physical screen height to the variable rows and returns the physical screen width to the variable cols. Both are returned as the number of characters of the current font that will fit on the screen. See Also BiosGetLogScrSize BiosGetVirScrSize
3-61 Series 3000 Application Programmer’s Reference Manual
BiosGetPowerSource Purpose Use BiosGet to get the current power source. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetPowerSource(void);
Description The BiosGetPowerSource function returns the source of power for the terminal.
BiosGetPowerSource calls BIOS interrupt B1h, function 0Fh. Returns BiosGetPowerSource returns the source of power for the terminal, identified by the following values:
Value Power Source
0 Batteries 1Cradle 2Charger See Also None
3-62 BIOS Library Functions
BiosGetQueuePtr Purpose Use BiosGetQueuePtr( ) to obtain information about the addresses and sizes of the current communications queues. Syntax #include <3000\bios.h>
unsigned int _far BiosGetQueuePtr(unsigned int PortNumber, ⇒ _SYM_QUEUE _far *Queues);
Example Call unsigned int Status; _SYM_QUEUE Queues; Status = BiosGetQueuePtr(_SYM_COM1, Queues);
Description Returns the segment addresses and sizes of the FIFO communications queues.
BiosGetQueuePtr calls BIOS interrupt A5h, function 92h. Returns Status Value Description Define name
0 Data returned in pointers _SYM_SUCCESS 1 No queues are currently allocated. See Also BiosAllocQueues
3-63 Series 3000 Application Programmer’s Reference Manual
BiosGetRamSize Purpose Use BiosGetRamSize to determine the amount of RAM in the terminal. Syntax #include <3000\bios.h>
extern void_far BiosGetRamSize(int_far * sysramsize, ⇒ int_far * fixramsize, ⇒ int_far * remramsize);
Description The BiosGetRamSize function returns the total amount of system RAM, permanently installed expanded RAM and the maximum size of removable media card. All sizes are given in kilobytes. This function expects pointers to variables to save the return values.
BiosGetRamSize calls BIOS interrupt ABh, function 01h. Returns None
3-64 BIOS Library Functions
BiosGetRedLED Purpose Use BiosGetRedLED to obtain information about the Red LED on the cradle. Syntax #include <3000\bios.h>
unsigned char _far BiosGetRedLED( void );
Example Call unsigned char LEDState; LEDState = BiosGetRedLED();
Description Gets the state of the Red LED on the cradle. This service is only available with system EPROM 2.0 and higher.
BiosGetRedLED calls BIOS interrupt B8h, function 02h. Returns Status Value Description Define name
0 LED is reset (LED is On) _SYM_REDLED_ON STOP-RED 1 LED is set (LED is Off) _SYM_REDLED_OFF STOP-RED See Also BiosSetRedLED( )
3-65 Series 3000 Application Programmer’s Reference Manual
BiosGetSerialSetup Purpose Use BiosGetSerialSetup to get the current parameters for a serial port. Syntax #include <3000\bios.h>
unsigned char _far BiosGetSerialSetup(int PortNumber, ⇒ _SYM_SERIAL _far *SerialParams)
Example Call unsigned char Status; _SYM_SERIAL SerialParams; Status = BiosGetSerialSetup(_SYM_COM1, &SerialParams);
Description BiosSerialSetup returns the current configuration for the specified serial port into the _SYM_SERIAL structure.
BiosSerialSetup calls BIOS interrupt A5h, function 81h. Returns Status Value Description Define name
0 Port Parameters returned Successfully _SYM_SUCCESS 1 Error. See _ErrStatus & _ErrConfig in _SYM_FAILED _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also BiosSerialSetup( )
3-66 BIOS Library Functions
BiosGetShiftStatus Purpose Use BiosGetShiftStatus to get the current keyboard status. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetShiftStatus(void);
Description The BiosGetShiftStatus function returns the command key status.
BiosGetShiftStatus calls BIOS interrupt A7H, function 02h Returns BiosGetShiftStatus returns the current keyboard state, as follows:
Bit Keyboard State
0 Right Shift 1Left Shift 2Ctrl 3Alt 4Scroll 5Num Lock 6Caps Lock 7Insert
3-67 Series 3000 Application Programmer’s Reference Manual
BiosGetTermType Purpose Use BiosGetTermType to determine the terminal type. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetTermType(void);
Description The BiosGetTermType function returns the terminal type.
BiosGetTermType calls BIOS interrupt AFh. Returns BiosGetTermType returns the terminal type, as follows:
Value Terminal Model
0 Not assigned 1 LRT 3800/LDT 3805 2 PDT 3300/PRT 3310/VRC 3910 3 PDT 3100/PRC 3110/PDT 3500 4 WS 1000 5 PDT 6800 6 PDT 6100
3-68 BIOS Library Functions
BiosGetTicks Purpose Use BiosGetTicks to get the current Timer Tick count. Syntax #include <3000\bios.h> extern unsigned long _far BiosGetTicks(unsigned char _far * MidnightSignal);
Example Call unsigned char _far MidnightSignal; unsigned long NumTicks; NumTicks = BiosGetTicks( &MidnightSignal );
Description Reads the current Timer Tick count.
BiosGetTicks calls BIOS interrupt AAh, function 0. Returns BiosGetTicks returns a long value indicating the current tick count and the Midnight Signal Flag in the address pointed to by MidnightSignal. See Also BiosPutTicks( )
3-69 Series 3000 Application Programmer’s Reference Manual
BiosGetTime Purpose Use BiosGetTime to retrieve the time of day. Syntax #include <3000\bios.h>
extern void_far BiosGetTime(unsigned char_far *hours, ⇒ unsigned char_far *mins, ⇒ unsigned char_far *secs);
Description The BiosGetTime function gets the time of day. This function expects three far pointers in order to return the hours, minutes, and seconds.
BiosGetTime calls BIOS interrupt AAh, function 02h. Returns Returns the hours to the variable Hours, returns the minutes to the variable Mins, and returns the seconds to the variable Secs. All values should be passed in packed BCD format. See Also BiosSetTime
3-70 BIOS Library Functions
BiosGetVersions Purpose Use BiosGetVersions to obtain terminal version information. Syntax #include <3000\bios.h>
void_far BiosGetVersions( _SYM_VERSION_far *VersionInfo );
Example Call _SYM_VERSION VersionInfo; BiosGetVersions( &VersionInfo ); printf("Gate Array Rev: %u\n",VersionInfo.GateArray); printf("Terminal Type : %u\n",VersionInfo.TermType); printf("Serial Number : %s\n",VersionInfo.SerialNumber); printf("Copyright : %s\n",VersionInfo.Copyright); printf("Version String: %s\n",VersionInfo.VersionStr);
Description Returns information regarding the hardware and BIOS version of the terminal into a _SYM_VERSION structure. All strings in the structure are far pointers to the data.
BiosGetVersions calls BIOS interrupt AFh. Returns _SYM_VERSION information into a structure provided by the caller. SERIALNUMBER is returned on WS-10XX terminals only. On all other terminals, this field contains random data. See Also None
3-71 Series 3000 Application Programmer’s Reference Manual
BiosGetVideoMode Purpose Use BiosGetVideoMode to get the current video mode. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetVideoMode(void);
Description The BiosGetVideoMode function returns the current video mode.
BiosGetVideoMode calls BIOS interrupt A1h, function 0Fh. Returns Returns the current video mode, where:
Value Video Mode
2 Text mode 6 Graphics mode
3-72 BIOS Library Functions
BiosGetViewAngle Purpose Use BiosGetViewAngle to get the current LCD viewing angle/contrast setting. Syntax #include <3000\bios.h>
extern unsigned char_far BiosGetViewAngle(void);
Description The BiosGetViewAngle function returns the LCD viewing angle (contrast setting).
BiosGetViewAngle calls BIOS interrupt A1h, function 81h. Returns Returns the viewing angle, where:
Value Status
0Lowest (dimmest) 7Highest (brightest) See Also BiosSetViewAngle
3-73 Series 3000 Application Programmer’s Reference Manual
BiosGetVirScrSize Purpose Use BiosGetVirScrSize to get the size of the virtual screen. Syntax #include <3000\bios.h>
extern void_far BiosGetVirScrSize(unsigned char_far * rows, ⇒ unsigned char_far * cols, ⇒ unsigned char_far * pages);
Description The BiosGetVirScrSize function returns the size of the virtual screen. For more information, see the Series 3000 System Software Manual.
BiosGetVirScrSize calls BIOS interrupt A1h, function 83, subfunction 01h. Returns Returns pointers to virtual screen rows, virtual screen columns, and virtual screen pages. See Also BiosSetVirScrSize
3-74 BIOS Library Functions
BiosGetWrtProt Purpose Use BiosGetWrtProt to get the write protect fence for a block of memory. Syntax #include <3000\bios.h>
extern void_far BiosGetWrtProt(unsigned char sectnum, ⇒ unsigned char_far * direction, ⇒ unsigned char_far * blknum);
Description The BiosGetWrtProt function returns the write protect fence for the selected memory sector. This function expects the sector number, a pointer to save the direction, and a pointer to save the block number.
BiosGetWrtProt calls BIOS interrupt ABh, function 03h. Returns Returns pointers to the direction and the block number where:
Value Status
0Down 7Up
3-75 Series 3000 Application Programmer’s Reference Manual
BiosHideCursor Purpose Use BiosHideCursor to turn off the cursor display. Syntax #include <3000\bios.h>
extern void_far BiosHideCursor(void);
Description The BiosHideCursor function disables the display of the cursor.
BiosHideCursor calls BIOS interrupt A1h, function 01h. Returns None See Also BiosShowCursor
3-76 BIOS Library Functions
BiosInitSerialPort Purpose Use BiosInitSerialPort to initialize serial port. Syntax #include <3000\bios.h>
extern unsigned int _far BiosInitSerialPort(unsigned int Port, ⇒ unsigned char Params);
Example Call BiosInitSerialPort( _SYM_COM1, (_BIT_BAUD_9600 | _BIT_PARITY_NONE | _BIT_STOP_1 | _BIT_8BITS) );
Description Initializes Port to the parameters in Params.
You MUST use the _BIT_XXXX defines in bios.gd. DO NOT use the _SYM_ defines for this function.
BiosInitSerialPort calls BIOS interrupt A5h, function 00h. Returns Line Status Returns Bit 15 = Time-out error Bit 14 = Send shift register empty Bit 13 = Send data register empty Bit 12 = Break detected Bit 11 = Framing error Bit 10 = Parity error Bit 9 = Overrun error Bit 8 = Data ready
3-77 Series 3000 Application Programmer’s Reference Manual
Modem Status Bit 7 = Carrier detect Bit 6 = Ring indicator Bit 5 = Data-set-ready (DSR) Bit 4 = Clear-to-send (CTS) Bit 3 = Delta carrier detect Bit 2 = Trailing-edge ring detect Bit 1 = Delta data-set-ready Bit 0 = Delta clear-to-send See Also BiosSendChar( ) BiosRecvChar( )
3-78 BIOS Library Functions
BiosLED Purpose Use BiosLED to turn the Series 3000 decode LED On or Off. Syntax #include <3000\bios.h>
void _far BiosLED(unsigned char Service, unsigned int Milliseconds);
Example Call BiosLED( _SYM_LED_ON, 0 );// Turn On LED BiosLED( _SYM_LED_OFF, 0 );// Turn Off LED BiosLED( _SYM_LED_TIMED, 3000 );// Turn On LED for 3 // seconds
Description Turns the Series 3000 decode LED On or Off with Timed options for On mode. The Milliseconds parameter only has meaning when the Service is _SYM_LED_TIMED, otherwise it is ignored.
BiosLED calls BIOS interrupt B6h, function 0 (turn on), 1 (turn off), or 2 (turn on for specified time). Returns None
3-79 Series 3000 Application Programmer’s Reference Manual
BiosLineTurn Purpose Use BiosLineTurn( ) to perform a physical line turn around when using Half duplex modems. Syntax #include <3000\bios.h>
unsigned int _far BiosLineTurn(int PortNumber, ⇒ unsigned char Direction );
Example Call unsigned int Status;
Status = BiosLineTurn(_SYM_COM1, _SYM_RECEIVE_ENABLE);
Description Causes the BIOS to perform a physical line turn around when using Half Duplex modems (ignored when using Full Duplex modems). This service when _SYM_TRANSMIT_ENABLE is used will disable Receive, wait a specified time for CD to drop, raise RTS, wait modem delay time, then enable Transmit. It will wait for the transmit queue and UART to go empty, drop RTS, disable Transmit wait a specified time for CD to go active, and finally enable Receive when _SYM_RECEIVE_ENABLE is used.
BiosLineTurn calls BIOS interrupt A5h, functions 88h and 89h. Returns Status Value Description Define name
0 Line Turn Around Successful _SYM_SUCCESS
Non-Zero Error Turning Line. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions.
3-80 BIOS Library Functions
BiosMapLogPage Purpose Use BiosMapLogPage to map a logical page into a physical page. Syntax #include <3000\bios.h>
extern char_far BiosMapLogPage(char phy_page, ⇒ int log_page,int cnt);
Description The BiosMapLogPage function maps the logical page into the physical page. This function expects a physical page number, a logical page number (-1 = disable the specified physical page), and the number of pages to map.
BiosMapLogPage calls BIOS interrupt ABh, function 07h. Returns Value Meaning
1 Successful 0 Physical or logical page is out of range See Also BiosGetLogPageCnt
3-81 Series 3000 Application Programmer’s Reference Manual
BiosMemToTextRect Purpose Use BiosMemToTextRect to copy a block of text to the display. Syntax #include <3000\bios.h>
extern void_far BiosMemToTextRect(unsigned char left, ⇒unsigned char top, ⇒ unsigned char right, ⇒unsigned char bottom, ⇒unsigned char_far *buffer);
Description The BiosMemToTextRect function copies a rectangular area of text from a user supplied memory buffer to the display.
The buffer size should be at least:
(bottom - top + 1) * (right - left + 1) * 2 bytes,
and contain data in the format returned by BiosTextRectToMem. BiosMemToTextRect calls BIOS interrupt A1h, function 8Bh. Returns None See Also BiosTextRectToMem
3-82 BIOS Library Functions
BiosOpenPort Purpose Use BiosOpenPort( ) to open a serial port once set up. Syntax #include <3000\bios.h>
unsigned int _far BiosOpenPort(int PortNumber );
Example Call unsigned Status;
Status = BiosOpenPort(_SYM_COM1 );
Description BiosOpenPort opens a serial port which has been initialized using either BiosSerialSetup( ) or BiosExtSerialSetup( ), and prepares the port for communication.
BiosOpenPort calls BIOS interrupt A5h, function 82h. Returns Status Value Description Define name
0 Port Opened Successfully _SYM_SUCCESS
Non-Zero Error Opening Port. See description of _ErrStatus in _SYM_SERIAL structure. See Also BiosClosePort( )
3-83 Series 3000 Application Programmer’s Reference Manual
BiosOpticalInterface Purpose Use BiosOpticalInterface to determine if the terminal is equipped with an optical interface. Syntax #include <3000\bios.h>
unsigned char _far BiosOpticalInterface( void );
Example Call unsigned char Status; Status = BiosOpticalInterface();
Description Determines if the terminal is equipped with an optical interface. The optical interface is required for the terminal to use a cradle.
BiosOpticalInterface calls BIOS interrupt B8h, function 05h. Returns Status Value Description Define name
0 Terminal does not have _SYM_NOOPTICS an optical interface
1 Terminal has an optical interface _SYM_OPTICS
3-84 BIOS Library Functions
BiosPortStatus Purpose Use BiosPortStatus( ) to receive current Information about a specified serial port. Syntax #include <3000\bios.h>
unsigned char _far BiosPortStatus(int PortNumber, ⇒ unsigned int _far *_ErrStatus, ⇒ unsigned int _far *CurrentState);
Example Call unsigned char Status; unsigned _ErrStatus; unsigned CurrentState; Status = BiosPortStatus(_SYM_COM1, &_ErrStatus, &CurrentState );
Description Returns the _ErrStatus bit mask and CurrentState bit mask in the pointers provided. The _ErrStatus is the same bit mask which is returned into the _SYM_SERIAL structure when using BiosSerialSetup( ).
BiosPortStatus calls BIOS interrupt A5h, function 87h. Returns Status Value Description Define name
0 Port Status Successful _SYM_SUCCESS Non-Zero Error Getting Status.
3-85 Series 3000 Application Programmer’s Reference Manual
_Err_Status mask:
Bits Meaning
15 14 13 12 11 10 9 8 726 5 4 3 1 0
Channel Not Open Overrun Error Parity Error Framing Error BREAK Detected Time-out Waiting for DSR or CD Lost DSR While Receiving User Aborted CD Lost During Session CD Didn’t Go Active on Receive CD Didn’t Go Inactive on Transmit Receive Character Time-out Control Start Not Received Clear To Send (CTS) Lost Receive Queue Full Invalid Configuration/Queue
3-86 BIOS Library Functions
Current State:
Bits Meaning
6 524 3 1 0
Idle (Closed) Half Duplex Receive Enable Half Duplex Data Receive Half Duplex Transmit Enable Half Duplex Modem Delay Half Duplex Data Transmit Full Duplex Send/Receive
3-87 Series 3000 Application Programmer’s Reference Manual
BiosPowerKey Purpose Use BiosPowerKey to enable or disable the power key (On/Off). Syntax #include <3000\bios.h>
unsigned int _far BiosPowerKey( unsigned char StateFlag);
Example Call unsigned int Requests; Requests = BiosPowerKey( _SYM_KEY_DISABLE );
Description BiosPowerKey enables or disables the power On/Off key and keyboard time- out metacode. This service allows the user to temporarily prevent the terminal from powering down during critical routines.
BiosPowerKey calls BIOS interrupt B1h, function 0Ch. Returns Number of Power Key disable requests.
3-88 BIOS Library Functions
BiosPowerOff Purpose Use BiosPowerOff to power off the terminal and to report the cause when waken up again. Syntax #include <3000\bios.h>
extern unsigned char_far BiosPowerOff(void);
Description The BiosPowerOff function powers off the terminal, then, upon power on, returns the reason for the power on.
BiosPowerOff calls BIOS interrupt B1h, function 00h.
Note: It is not recommended to call this routine from a background process. Returns BiosPowerOff returns the reason for wakeup, as follows:
Code Wake-up reason
0Port 0 ring 1Port 1 ring 2Laser trigger 3Alarm 4Power key 5Other key
3-89 Series 3000 Application Programmer’s Reference Manual
BiosProgramTrigger Purpose Use BiosProgramTrigger to select the left or right side trigger button on the Series 3100. Syntax #include <3000\bios.h>
void _far BiosProgramTrigger( unsigned char Key );
Example Call BiosProgramTrigger( _SYM_TRIGGER_LEFT );
Description BiosProgramTrigger selects either the right or the left side key on a Series 3100 terminal as the scanner trigger key. The key can be set to _SYM_TRIGGER_LEFT or _SYM_TRIGGER_RIGHT. No message or beep is issued by this function. The programming can be overridden by keyboard programming.
BiosPowerOff calls BIOS interrupt A7h, function 88h. Returns None
3-90 BIOS Library Functions
BiosPurgeQueue Purpose Use BiosPurgeQueue( ) to purge the contents of the transmit or receive queue for a serial port. Syntax #include <3000\bios.h>
unsigned int _far BiosPurgeQueue(int PortNumber, ⇒ unsigned char QueueType );
Example Call unsigned int Status; Status = BiosPurgeQueue(_SYM_COM1, _SYM_INPUT_QUEUE );
Description BiosPurgeQueue reinitializes the specified queue(s), discarding any queued data to be discarded.
BiosPurgeQueue calls BIOS interrupt A5h, function 8Eh. Returns Status Value Description Define name
0 Queue(s) purged Successfully _SYM_SUCCESS
Non-Zero Error. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also None
3-91 Series 3000 Application Programmer’s Reference Manual
BiosPutCharAttr Purpose Use BiosPutCharAttr to write characters to the screen, retaining cursor position. Syntax #include <3000\bios.h>
extern void_far BiosPutCharAttr(char c, unsigned char attr, ⇒ unsigned char count);
Description The BiosPutCharAttr function writes count number of characters c with attribute attr at the current cursor position. The cursor position remains unchanged.
Valid attributes are:
Attribute Meaning
0x07 Normal Video 0x70 Reverse Video
Note: Reverse Video is supported only in soft fonts modes.
BiosPutCharAttr calls BIOS interrupt A1h, function 09h. Returns None See Also BiosGetCharAttr
3-92 BIOS Library Functions
BiosPutCharMove Purpose Use BiosPutCharMove to write a character to the screen and advance the cursor position. Syntax #include <3000\bios.h>
extern void_far BiosPutCharMove(char c);
Description The BiosPutCharMove function writes a character to the display and advances the cursor.
BiosPutCharMove calls BIOS interrupt A1h, function 0Eh. Returns None See Also BiosPutCharStay
3-93 Series 3000 Application Programmer’s Reference Manual
BiosPutCharStay Purpose Use BiosPutCharStay to write a character to the screen without advancing the cursor position. Syntax #include <3000\bios.h>
extern void_far BiosPutCharStay(char c);
Description The BiosPutCharStay function writes a character to the display without advancing the cursor.
BiosPutCharStay calls BIOS interrupt A1h, function 0Ah. Returns None
See Also BiosPutCharMove
3-94 BIOS Library Functions
BiosPutStrMove Purpose Use BiosPutStrMove to write a character string to the display and advance the cursor to the end of the string. Syntax #include <3000\bios.h>
extern void_far BiosPutStrMove(unsigned char row, ⇒ unsigned char col, ⇒unsigned int len, ⇒char_far *str, unsigned char attr);
Description The BiosPutStrMove function writes a string to the display and advances the cursor to the end of the string.
BiosPutStrMove calls BIOS interrupt A1h, function 13h, subfunction 01h. Returns None See Also BiosPutStrStay
3-95 Series 3000 Application Programmer’s Reference Manual
BiosPutStrStay Purpose Use BiosPutStrStay to write a character string to the display without advancing the cursor position. Syntax #include <3000\bios.h>
extern void_far BiosPutStrStay(unsigned char row, ⇒ unsigned char col, ⇒ unsigned int len,char_far *str, ⇒ unsigned char attr);
Description The BiosPutStrStay function writes a string to the display without advancing the cursor to the beginning or to the end of the string.
BiosPutStrStay calls BIOS interrupt A1h, function 13h, subfunction 00h. Returns None See Also BiosPutStrMove
3-96 BIOS Library Functions
BiosPutTicks Purpose Use BiosPutTicks to set the current Timer Tick count. Syntax #include <3000\bios.h>
void _far BiosGetTicks( unsigned long TickCount);
Example Call unsigned long TickCount = 4096L; BiosPutTicks( TickCount );
Description Sets the Timer Tick count.
BiosPutTicks calls BIOS interrupt AAh, function 01h. Returns None See Also BiosGetTicks( )
3-97 Series 3000 Application Programmer’s Reference Manual
BiosQueueStatus Purpose Use BiosQueueStatus( ) to receive queue status information for a serial port. Syntax #include <3000\bios.h>
unsigned int _far BiosQueueStatus(int PortNumber, ⇒ unsigned char QueueType, ⇒ unsigned int _far *CharsInQueue, ⇒ unsigned int _far *SpaceLeftInQueue);
Example Call unsigned Status;
unsigned CharsInQueue;
unsigned SpaceInQueue;
Status = BiosQueueStatus(_SYM_COM1, _SYM_INPUT_QUEUE, &CharsInQueue, &SpaceInQueue ); Description BiosQueueStatus returns the number of characters currently in the specified queue in CharsInQueue and the number of empty positions in the queue in SpaceInQueue.
BiosQueueStatus calls BIOS interrupt A5h, function 86h. Returns Status Value Description Define name 0 Queue Status Successful _SYM_SUCCESS Non-Zero Error Getting Status. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions.
3-98 BIOS Library Functions
See Also BiosSendBlock( )
3-99 Series 3000 Application Programmer’s Reference Manual
BiosRecvBlock Purpose Use BiosRecvBlock( ) to retrieve a block of data from a serial port. Syntax #include <3000\bios.h>
unsigned int _far BiosRecvBlock(int PortNumber, ⇒ char _far *DataPtr, ⇒ unsigned BufLen, ⇒ unsigned char Wait, ⇒ unsigned int _far *bytes_received);
Example Call unsigned Status;
char DataPtr[ 128 ];
unsigned bytes_recvd;
Status = BiosRecvBlock(_SYM_COM1, (char _far *)DataPtr, sizeof(DataPtr), _SYM_WAITBLOCK, &bytes_recvd );
Description The specified data block is moved from the receive queue until the queue is empty or BufLen bytes have been moved into DataPtr. Reports an error if the specified serial port is not open. If wait mode is specified and if a communications error occurs, this service may terminate before all data is moved. If in Half duplex transmit, line is automatically enabled for receive.
BiosRecvBlock calls BIOS interrupt A5h, function 85h.
3-100 BIOS Library Functions
Returns Status Value Description Define name
0 Data Received Successfully _SYM_SUCCESS
Non-Zero Error Receiving. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also BiosSendBlock( )
3-101 Series 3000 Application Programmer’s Reference Manual
BiosRecvChar Purpose Use BiosRecvChar to receive a single character from the selected serial port or to remove a character from the input FIFO. Syntax #include <3000\bios.h>
extern unsigned char _far BiosRecvChar(unsigned int Port, ⇒ unsigned char _far * Ch);
Example Call unsigned char _far Ch;
unsigned char Status;
Status = BiosRecvChar( _SYM_COM1, &Ch );
Description BiosRecvChar retrieves a single character from the selected serial port's UART, if the port has been opened using BiosOpenPort( ). If the port has not been opened, the function removes a character from the input FIFO. The character is received into the address pointed to by Ch from Port.
BiosRecvChar waits until a character is available or until a time-out error occurs before returning. The status returned is identical to that returned by BiosGetLineStatus( ).
BiosRecvChar calls BIOS interrupt A5h, function 02h. Returns Status Value Description Define name
0 Character received successfully _SYM_CHAR_RECVD
Non-Zero See BiosGetLineStatus( ) return value
3-102 BIOS Library Functions
See Also BiosSendChar( ) BiosInitSerialPort( ) BiosReleaseModem( )
3-103 Series 3000 Application Programmer’s Reference Manual
BiosReleaseModem Purpose Use BiosReleaseModem to release access rights to the cradle modem. Syntax #include <3000\bios.h>
unsigned char _far BiosReleaseModem( void );
Example Call unsigned char Status;
Status = BiosReleaseModem();
Description BiosReleaseModem releases the exclusive rights to the modem in the cradle. This service is only available with system EPROM 2.0 and higher.
BiosReleaseModem calls BIOS interrupt B8h, function 03h. Returns Status Value Description Define name
0 Modem not granted _SYM_NOT_GRANTED 1Modem granted_SYM_GRANTED 2 Not supported by current cradle _SYM_GRNOSUPP See Also BiosRequestModem( ) BiosGetGrantStatus( )
3-104 BIOS Library Functions
BiosRequestModem Purpose Use BiosRequestModem to obtain access rights to the cradle modem. Syntax #include <3000\bios.h>
unsigned char _far BiosRequestModem( void );
Example Call unsigned char Status;
Status = BiosRequestModem();
Description BiosRequestModem requests exclusive rights to use the modem in the cradle. This service is only available with system EPROM 2.0 and higher.
BiosRequestModem calls BIOS interrupt B8h, function 03h. Returns Status Value Description Define name
0 Modem not granted _SYM_NOT_GRANTED 1Modem granted_SYM_GRANTED 2 Not supported by current cradle _SYM_GRNOSUPP See Also BiosGetGrantStatus( ) BiosReleaseModem( )
3-105 Series 3000 Application Programmer’s Reference Manual
BiosResetAlarm Purpose Use BiosResetAlarm to disable the terminal real-time clock. Syntax #include <3000\bios.h>
extern void_far BiosResetAlarm(void);
Description The BiosResetAlarm function disables the real time clock alarm function.
BiosResetAlarm calls BIOS interrupt AAh, function 82h. Returns None See Also BiosGetAlarm BiosSetAlarm
3-106 BIOS Library Functions
BiosResetTimer Purpose Use BiosResetTimer to reactivate a timer that has executed. Syntax #include <3000\bios.h>
unsigned char _far BiosResetTimer(unsigned char TimerNumber);
Example Call unsigned char Status;
Status = BiosResetTimer( TimerNumber );
Description Deactivates the specified timer, clearing the timer count.
BiosResetTimer calls BIOS interrupt ACh, function 04h. Returns Status Value Description Define name
0 Timer reset successfully _SYM_TIMER_SET 1 TimerNumber is out of range _SYM_OUTOFRANGE See Also BiosUpdateTimer( ) BiosSetTimer( )
3-107 Series 3000 Application Programmer’s Reference Manual
BiosResetUART Purpose Use BiosResetUART to reset the UART for a serial port. Syntax #include <3000\bios.h>
extern unsigned int_far BiosResetUART(unsigned char port_no, ⇒ unsigned char ctrl_mask);
Description The BiosResetUART function resets the UART. This function expects port_no, the port number, and ctrl_mask, a control mask that determines the UART control options. The control mask bit values are as follows: Bits Meaning
7 6 524 3 1 0
Disable DTR Disable RTS Reserved - Always 0 Reserved - Always 0 Reserved - Always 0 Reserved - Always 0 Disable Break Reserved - Always 0
BiosResetUART calls BIOS interrupt A5h, function 8Ch. Returns Bit 15: Invalid configuration/queue Bit 14: Receive queue full Bit 13: Clear-to-send (CTS) lost Bit 12: Control Start not received
3-108 BIOS Library Functions
Bit 11: Receive character timeout Bit 10: CD did not go inactive on transmit Bit 9: CD did not go active on receive Bit 8: CD lost during transmission Bit 7: User aborted Bit 6: Lost DSR while receiving Bit 5: Timeout waiting for DSR or CD Bit 4: BREAK detected Bit 3: Framing error Bit 2: Parity error Bit 1: Overrun error Bit 0: Channel not open See Also BiosSetUART
3-109 Series 3000 Application Programmer’s Reference Manual
BiosResumeTimer Purpose Use BiosResumeTimer to resume the activity of a timer. Syntax #include <3000\bios.h>
unsigned char _far BiosResumeTimer( unsigned char TimerNumber);
Example Call unsigned char Status;
Status = BiosResumeTimer( TimerNumber );
Description Resumes the execution of a timer which has been suspended by BiosSuspendTimer, but does not clear the timer count. This service simply restarts decrementing the timer.
BiosResetTimer calls BIOS interrupt ACh, function 06h. Returns Status Value Description Define name
0 Timer Reset _SYM_TIMER_RESET 1 TimerNumber is out of range _SYM_OUTOFRANGE See Also BiosSuspendTimer( )
3-110 BIOS Library Functions
BiosScrollDown Purpose Use BiosScrollDown to scroll the virtual screen down a number of lines. Syntax #include <3000\bios.h>
extern void_far BiosScrollDown(unsigned char top, ⇒ unsigned char left, ⇒ unsigned char bottom, ⇒ unsigned char right, ⇒ unsigned char numlines, ⇒ unsigned char fillattr);
Description The BiosScrollDown function scrolls the delimited virtual screen window of the active page down by numlines, inserting blank lines at the top of the window. Blank lines have the attribute specified by fillattr. If numlines = 0, the specified window is cleared.
Valid attributes are:
Value Attribute
0x07 Normal Video 0x70 Reverse Video
Reverse Video is supported only in soft fonts modes. BiosScrollDown calls BIOS interrupt A1h, function 07h. Returns None See Also BiosScrollUp
3-111 Series 3000 Application Programmer’s Reference Manual
BiosScrollUp Purpose Use BiosScrollDown to scroll the virtual screen up a number of lines. Syntax #include <3000\bios.h>
extern void_far BiosScrollUp(unsigned char top, ⇒ unsigned char left, ⇒ unsigned char bottom, ⇒ unsigned char right, ⇒ unsigned char numlines, ⇒ unsigned char fillattr);
Description The BiosScrollUp function scrolls the delimited virtual screen window of the active page up by numlines, inserting blank lines at the bottom of the window. Blank lines have the attribute specified by fillattr. If numlines = 0, the specified window is cleared.
Valid attributes are:
Value Attribute
0x07 Normal Video 0x70 Reverse Video
Note: Reverse Video is supported only in soft fonts modes. BiosScrollUp calls BIOS interrupt A1h, function 06h. Returns None See Also BiosScrollDown
3-112 BIOS Library Functions
BiosSelectFont Purpose Use BiosSelectFont to select a soft font for the video display. Syntax #include <3000\bios.h>
extern void_far BiosSelectFont(unsigned char font_mode, ⇒ unsigned char_far *font_ptr, ⇒ unsigned char dbl_high, ⇒ unsigned char dbl_wide);
Description The BiosSelectFont function selects a user supplied soft font for the video display. As parameters, this function expects a font mode, a pointer to a font definition, a double high dimension flag (0 = normal, 1 = double high), and a double wide dimension flag (0 = normal, 1 = double wide). Font mode is defined below:
Value Font Mode
0 Hard Font (Internal) 1Soft Font 2 Hard Font (External)
BiosSelectFont calls BIOS interrupt A1h, function 8Ch. Returns None See Also BiosGetFont
3-113 Series 3000 Application Programmer’s Reference Manual
BiosSendBlock Purpose Use BiosSendBlock( ) to transmit a block of data to a serial port. Syntax #include <3000\bios.h>
unsigned int _far BiosSendBlock(int PortNumber, ⇒ char _far *DataPtr, ⇒ unsigned DataLen, ⇒ unsigned char WaitFlag, ⇒ unsigned int _far *bytes_sent );
Example Call unsigned Status;
unsigned bytes_sent;
char DataPtr[ 128 ];
Status = BiosSendBlock(_SYM_COM1, DataPtr, sizeof( DataPtr), _SYM_NOWAIT, &bytes_sent );
Description The specified data block is moved into the transmit queue until the queue is full or the entire data block is queued. Reports an error if the specified serial port is not open. If wait mode is specified and if a communications error occurs, this service may terminate before all data is queued. If in Half duplex receive, the line is automatically enabled for transmit.
BiosSendBlock calls BIOS interrupt A5h, function 84h.
3-114 BIOS Library Functions
Returns Status Value Description Define name
0 Data Sent Successfully _SYM_SUCCESS
Non-Zero Error Sending. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also BiosRecvBlock( )
3-115 Series 3000 Application Programmer’s Reference Manual
BiosSendChar Purpose Use BiosSendChar to transmit a single character to a serial port's UART or to queue a single character into the output FIFO. Syntax #include <3000\bios.h>
extern unsigned int _far BiosSendChar(unsigned int Port, ⇒ unsigned char Ch);
Example Call BiosSendChar( _SYM_COM1,'A' );
Description BiosSendChar sends a single character to the specified port. If the port has been opened using BiosOpenPort(), BiosSendChar transmits a single character to the selected serial port's UART. If not, BiosSendChar queues a single character into the output FIFO. If used in polled mode, this service waits until the UART transmit register is empty before writing the new character. If used in interrupt mode, this service waits for space in the FIFO before returning. In either case, the status returned is identical to that returned by BiosGetLineStatus(). BiosSendChar calls BIOS interrupt A5h, function 01h. Returns Status Value Description Define name
0 Character Sent Successfully _SYM_CHAR_SENT Non-Zero See BiosGetLineStatus( ) return value See Also BiosInitSerialPort( ) BiosRecvChar( )
3-116 BIOS Library Functions
BiosSerialSetup Purpose Use BiosSerialSetup to initialize the specified serial port's Channel Control Block (CCB) to a standard 3 wire interface. Syntax #include <3000\bios.h>
unsigned char _far BiosSerialSetup(int PortNumber, ⇒ unsigned char BPS, ⇒ unsigned char DataBits, ⇒ unsigned char Parity, ⇒ unsigned char StopBits, ⇒ unsigned char Duplex, ⇒ unsigned char FlowControl);
Example Call unsigned char Status;
Status = BiosSerialSetup(_SYM_COM1, _SYM_BAUD_9600, _SYM_8BITS, ⇒ _SYM_PARITY_NONE, _SYM_STOP_1, ⇒ _SYM_FULL_DUPLEX, _SYM_NO_FLOWCTL);
Description Initializes the CCB for the specified serial port to the parameters for a normal three wire interface with options for BPS, DataBits, Parity, StopBits, Duplex, and FlowControl. To initialize the serial port and customize the options, use the BiosExtSerialSetup routine.
BiosSerialSetup calls BIOS interrupt A5h, function 80h.
3-117 Series 3000 Application Programmer’s Reference Manual
Returns Status Value Description Define name
0 Port Initialized Successfully _SYM_SUCCESS 1 Error initializing _SYM_FAILED See Also BiosExtSerialSetup( )
3-118 BIOS Library Functions
BiosSetAlarm Purpose Use BiosSetAlarm to set the terminal real-time clock alarm. Syntax #include <3000\bios.h>
extern void_far BiosSetAlarm(unsigned char DOM, ⇒ unsigned char DOW, ⇒ unsigned char hours, ⇒ unsigned char mins, ⇒ unsigned char secs);
Description The BiosSetAlarm function sets real-time clock alarm in the keyboard processor. This function expects a day of the month value, DOM, a day of the week value, DOW, an hours value, hours, a minutes value, mins and a seconds value, secs. All values should be passed in packed BCD format.
Day of week values are:
Value Day
0Sunday 1Monday 2Tuesday 3Wednesday 4Thursday 5Friday 6Saturday
BiosSetAlarm calls BIOS interrupt AAh, function 80h. Returns None
3-119 Series 3000 Application Programmer’s Reference Manual
See Also BiosGetAlarm( ) BiosResetAlarm( )
3-120 BIOS Library Functions
BiosSetBackLight Purpose Use BiosSetBackLight to turn the backlight on or off. Syntax #include <3000\bios.h>
extern void_far BiosSetBackLight(unsigned char onoff);
Description The BiosSetBackLight function turns the LCD backlight on or off. Returns
Value Meaning 0 = Video Backlight Off 1 = Video Backlight On 4 = Video Backlight Toggle 5 = Keypad Backlight Off (WS1000 only) 6 = Keypad Backlight On (WS1000 only) 9 = Keypad Backlight Toggle (WSS1000 only)
BiosSetBackLight calls BIOS interrupt A1h, function 82h. Returns None See Also BiosGetBackLightTime BiosSetBackLightTime
3-121 Series 3000 Application Programmer’s Reference Manual
BiosSetBackLightTime Purpose Use BiosSetBackLightTime to set the backlight timeout. Syntax #include <3000\bios.h>
extern void_far BiosSetBackLightTime(unsigned char timeout);
Description The BiosSetBackLightTime function sets the backlight timeout. Specify the timeout value in seconds.
BiosSetBackLightTime calls BIOS interrupt A1h, function 82h, subfunction 02h. Returns None See Also BiosGetBackLightTime
3-122 BIOS Library Functions
BiosSetChargingRate Purpose Use BiosSetChargingRate to set the charging rate for the Series 3000 terminal in the cradle. Syntax #include <3000\bios.h>
unsigned char _far BiosSetChargingRate( unsigned char Rate );
Example Call unsigned char ChargingInfo;
ChargingInfo = BiosSetChargingRate( _SYM_FASTRATE );
Description BiosSetChargingRate sets the charging for the Series 3000 terminal if the terminal is in the cradle.
BiosSetChargingRate calls BIOS interrupt B8h, function 01h. Returns Status Value Description Define name
0 Terminal is not charging now _SYM_NOTCHARGING 1 Slow Charging Rate is set _SYM_SLOWRATE 2 Fast Charging Rate is requested _SYM_FASTRATE 3 Service Not Supported _SYM_NOTSUPPORT by this cradle See Also BiosGetChargingRate( )
3-123 Series 3000 Application Programmer’s Reference Manual
BiosSetContextBuf Purpose Use BiosSetContextBuf to restore a previously saved EMS context. Syntax #include <3000\bios.h>
extern char_far BiosSetContextBuf(char_far * buf_adr);
Description The BiosSetContextBuf function restores a previously saved EMS mapping context from a buffer. This function expects an address of a context save buffer.
BiosSetContextBuf calls BIOS interrupt ABh, function 09h. Returns Value Meaning
1 Successful 0 Buffer contains an invalid save image See Also BiosGetContextBuf BiosGetEMSConfig
3-124 BIOS Library Functions
BiosSetCursorMode Purpose Use BiosSetCursorMode to set the hardware/software cursor mode. Syntax #include <3000\bios.h>
extern void_far BiosSetCursorMode(unsigned char mode);
Description The BiosSetCursorMode function sets the hardware or software cursor mode. In hardware mode, the system displays a hardware dependant cursor; in software mode, the cursor reflects the current keyboard state. The hardware cursor is a blinking block; the character is visible “under” the cursor. The software cursor resembles a lowercase “v”; the character under the cursor is invisible. At system cold start, the system sets the cursor to hardware mode. The mode character specifies the cursor mode as follows:
Value Meaning
0 Hardware (blinking block, character visible) 1 Software (“v” cursor, character invisible)
BiosSetCursorMode calls BIOS interrupt A1h, function 86h. Returns None See Also BiosGetCursorMode
3-125 Series 3000 Application Programmer’s Reference Manual
BiosSetCursorPos Purpose Use BiosSetCursorPos to position the cursor. Syntax #include <3000\bios.h>
extern void_far BiosSetCursorPos(unsigned char row, ⇒ unsigned char col);
Description The BiosSetCursorPos function sets the current cursor position.
BiosSetCursorPos calls BIOS interrupt A1h, function 02h. Returns None See Also BiosGetCursorPos
3-126 BIOS Library Functions
BiosSetCursorSize Purpose Use BiosSetCursorSize to set the size of the hardware cursor. Syntax #include <3000\bios.h>
extern void_far BiosSetCursorSize(unsigned char start_scan_line, ⇒ unsigned char end_scan_line);
Description The BiosSetCursorSize function sets the cursor size of the display's hardware cursor on CRT-type LCD controllers.
BiosSetCursorSize calls to BIOS interrupt A1h, function 01h. Returns None See Also BiosGetCursorSize
Note: This function is provided for compatibility purposes only.
3-127 Series 3000 Application Programmer’s Reference Manual
BiosSetDate Purpose Use BiosSetDate to set the terminal date.
Note: The “day of week” setting is used to tell the real time clock what day of the week the date being set falls on, as the real time clock hardware does not know that information. The convention is to use “0” as Sunday. Syntax #include <3000\bios.h> extern void_far BiosSetDate(unsigned char dayofweek, ⇒ unsigned char day, ⇒ unsigned char month, ⇒ unsigned char year, ⇒ unsigned char century);
Description The BiosSetDate function sets the date. Day of week values are:
Value Day 0Sunday 1Monday 2Tuesday 3Wednesday 4Thursday 5Friday 6Saturday Note: All values should be passed in packed BCD format. BiosSetDate calls BIOS interrupt AAh, function 05h. Returns None See Also BiosGetDate
3-128 BIOS Library Functions
BiosSetDisplayPage Purpose Use BiosSetDisplayPage to select the active display page. Syntax #include <3000\bios.h>
extern void_far BiosSetDisplayPage(unsigned char page)
Description The BiosSetDisplayPage function selects the active display page, causing the contents of the selected page to be displayed. If an invalid page number is selected, page zero is used.
BiosSetDisplayPage calls BIOS interrupt A1h, function 05h. Returns None See Also BiosSetVirScrSize
3-129 Series 3000 Application Programmer’s Reference Manual
BiosSetGlobalWrtProt Purpose Use BiosSetGlobalWrtProt to enable/disable global write protection. Syntax #include <3000\bios.h>
extern void_far BiosSetGlobalWrtProt(int flag);
Description The BiosSetGlobalWrtProt function selects the global write protection status for the 1 Mbyte memory space. Write-protect is turned on by default on a system cold start. A driver that has allocated and protected memory can use this service to enable writes to protected memory without having to identify and unprotect each sector individually. This function expects a flag with one of the two following values:
Value Status
1Enabled 0Disabled
BiosSetGlobalWrtProt calls BIOS interrupt ABh, function 0Fh. Returns None
3-130 BIOS Library Functions
BiosSetKeyboardState Purpose Use BiosSetKeyboardState to set the keyboard to a keyboard state. Syntax #include <3000\bios.h>
extern void_far BiosSetKeyboardState(unsigned char state);
Description The BiosSetKeyboardState function forces the keyboard into a given state. This function expects state, a character whose bit setting determines the keyboard state, as follows: Bits Meaning
7 6 524 3 1 0
Right Shift Left Shift Ctrl Alt Scroll Num Lock Caps Lock Function Shift
BiosSetKeyboardState calls BIOS interrupt A7h, function 83h. Returns None See Also BiosGetKeyboardState
3-131 Series 3000 Application Programmer’s Reference Manual
BiosSetKybdTimeout Purpose Use BiosSetKybdTimeout to set the powerdown timeout. Syntax #include <3000\bios.h>
extern void_far BiosSetKybdTimeout(unsigned int time);
Description The BiosSetKybdTimeout function sets the time that the keyboard will wait for key entry before powering down. This function expects time, the wait time in seconds.
BiosSetKybdTimeout calls BIOS interrupt A7h, function 82h. Returns None See Also BiosGetKybdTimeout
3-132 BIOS Library Functions
BiosSetLogScrSize Purpose Use BiosSetLogScrSize to set the logical screen size. Syntax #include <3000\bios.h>
extern void_far BiosSetLogScrSize(unsigned char rows, ⇒ unsigned char cols);
Description The BiosSetLogScrSize function sets the size of the logical screen. In text modes, the logical screen size defines the screen positions where video output wraps and scrolls. Applies only to functions that support automatic generation of new lines and screen scrolling. The logical width specifies the column, starting from the left edge of the virtual screen, where automatic generation of new lines occurs. Similarly, the logical length specifies the row where automatic screen scrolling occurs. Data starts at the top edge of the virtual screen. The left column of the display is column 1; the top row is row 1. On a system cold start, the system sets the logical screen size equal to the physical screen size.
BiosSetLogScrSize calls BIOS interrupt A1h, function 85h, subfunction 00h. Returns None See Also BiosGetLogScrSize BiosGetPhysScrSize BiosGetVirScrSize
3-133 Series 3000 Application Programmer’s Reference Manual
BiosSetNotify Purpose Use BiosSetNotify( ) to set up a routine to be called when the Transmit Output queue goes empty. Syntax #include <3000\bios.h>
unsigned int _far BiosSetNotify(int PortNumber, ⇒ char _far *handler );
Example Call unsigned int Status;
void _far QueEmptyHandler( void );
Status = BiosSetNotify(_SYM_COM1, (char _far *)QueEmptyHandler );
Description Dispatches an event through a _far call when the transmit queue goes empty. The dispatch routine must be a _far procedure and must save all registers it uses. The routine is not invoked immediately; instead a flag is set when the queue goes empty. The channel background task checks every 27 ms to see if this flag is set and that the dispatch routine is enabled. If so, the routine is then dispatched. System Registers are not guaranteed upon entry to the users’ handler routine.
Passing a null pointer to BiosSetNotify( ) will remove the notification.
BiosSetNotify calls BIOS interrupt A5h, function 8Fh.
3-134 BIOS Library Functions
Returns Status Value Description Define name
0 Successful _SYM_SUCCESS
Non-Zero Error. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions. See Also None
3-135 Series 3000 Application Programmer’s Reference Manual
BiosSetPhysicalPos Purpose Use BiosSetPhysicalPos to set the position of the physical screen within the virtual display. Syntax #include <3000\bios.h>
extern void_far BiosSetPhysicalPos(unsigned char row, ⇒ unsigned char col);
Description The BiosSetPhysicalPos function sets the position of the physical display within the virtual display. Using virtual RAM, the terminal can store more data in its “video” RAM area than it can display on the physical LCD screen at one time. This service allows you to “move” the physical screen within the virtual display page. This allows you to emulate a larger display than is actually installed on the terminal.
If you specify a starting row or column position that causes the physical screen to extend past the edge of the virtual display page, the starting row or column value is adjusted to bring the edge of the physical screen to the edge of the virtual screen.
When you use the BiosSetVideoMode function, the system automatically resets the physical screen position to 0,0.
BiosSetPhysicalPos calls BIOS interrupt A1h, function 89h, subfunction 00h. Returns None See Also BiosGetPhysicalPos
3-136 BIOS Library Functions
BiosSetRedLED Purpose Use BiosSetRedLED to set the state of the Red LED on the cradle. Syntax #include <3000\bios.h>
unsigned char _far BiosSetRedLED( unsigned char NewState );
Example Call unsigned char LEDState;
LEDState = BiosSetRedLED( _SYM_REDLED_ON);
Description Sets the state of the Red LED on the cradle. This service is only available with system EPROM 2.0 and higher.
BiosSetRedLED calls BIOS interrupt B8h, function 02h. Returns Status Value Description Define name
0 RED LED is reset (LED is On) _SYM_REDLED_ON STOP 1 RED LED is set (LED is Off) _SYM_REDLED_OFF STOP
3-137 Series 3000 Application Programmer’s Reference Manual
BiosSetTime Purpose Use BiosSetTime to set the terminal time-of-day. Syntax #include <3000\bios.h>
extern void_far BiosSetTime(unsigned char hours, ⇒ unsigned char mins, ⇒ unsigned char secs);
Description The BiosSetTime function sets the time of day.
BiosSetTime calls BIOS interrupt AAh, function 03h. Returns None
Note: All values should be passed in packed BCD format. See Also BiosGetTime
3-138 BIOS Library Functions
BiosSetTimer Purpose Use BiosSetTimer to activate a timer which was allocated using BiosAllocTimer( ). Syntax #include <3000\bios.h>
unsigned char _far BiosSetTimer(unsigned char TimerNumber, ⇒ unsigned long TimeUnits);
Example Call unsigned char Status;
Status = BiosSetTimer( TimerNumber, 5000L );
Description Activates the timer TimerNumber with the specified TimeType / TimeUnits combination. No execution address is set.
BiosSetTimer calls BIOS interrupt ACh, function 02h. Returns Status Value Description Define name 0 Timer set successfully. _SYM_TIMER_SET 1 TimerNumber is out of range. _SYM_OUTOFRANGE See Also BiosUpdateTimer( ) BiosResetTimer( )
3-139 Series 3000 Application Programmer’s Reference Manual
BiosSetUART Purpose Use BiosSetUART to set UART parameters. Syntax #include <3000\bios.h>
extern unsigned int_far BiosSetUART(unsigned char port_no, ⇒ unsigned char ctrl_mask);
Description The BiosSetUART function sets parameters for the UART. This function expects port_no, the port number, and ctrl_mask, a control mask that determines the UART control options. The control mask bit values are as follows: Bits Meaning
7 6 524 3 1 0
Enable DTR Enable RTS Always 0 Always 0 Always 0 Always 0 Enable BREAK Always 0
BiosSetUART calls BIOS interrupt A5h, function 8Bh. Returns Bit 15: Invalid configuration/queue Bit 14: Receive queue full Bit 13: Clear-to-send (CTS) lost Bit 12: Control Start not received
3-140 BIOS Library Functions
Bit 11: Receive character timeout Bit 10: CD did not go inactive on transmit Bit 9: CD did not go active on receive Bit 8: CD lost during transmission Bit 7: User aborted Bit 6: Lost DSR while receiving Bit 5: Timeout waiting for DSR or CD Bit 4: BREAK detected Bit 3: Framing error Bit 2: Parity error Bit 1: Overrun error Bit 0: Channel not open See Also BiosResetUART
3-141 Series 3000 Application Programmer’s Reference Manual
BiosSetVideoMode Purpose Use BiosSetVideoMode to set the video display mode. Syntax #include <3000\bios.h>
extern void_far BiosSetVideoMode(unsigned char mode);
Description The BiosSetVideoMode function sets the video mode. This service always clears the display and causes the physical screen to be positioned at the upper left hand corner of the virtual screen. On a system cold start, a Series 3000 terminal initializes video mode to text mode. If you select an unsupported video mode, the current mode doesn't change.
The mode character specifies the type of video mode, as follows:
Mode Description
2Text mode 6 Graphics mode (not yet supported)
BiosSetVideoMode calls BIOS interrupt A1h, function 00h. Returns None See Also BiosGetVideoMode
3-142 BIOS Library Functions
BiosSetViewAngle Purpose Use BiosSetViewAngle to adjust the LCD viewing angle/contrast setting. Syntax #include <3000\bios.h>
extern unsigned char_far BiosSetViewAngle(unsigned char angle);
Description The BiosSetViewAngle function sets the LCD viewing angle (contrast setting), where:
Value Meaning
0Highest (brightest) 7Lowest (dimmest)
BiosSetViewAngle calls BIOS interrupt A1h, function 80h. Returns The BiosSetViewAngle function returns the actual viewing angle. See Also BiosGetViewAngle
3-143 Series 3000 Application Programmer’s Reference Manual
BiosSetVirScrSize Purpose Use BiosSetVirScrSize to set the virtual screen size. Syntax #include <3000\bios.h>
extern void_far BiosSetVirScrSize(unsigned char rows, ⇒ unsigned char cols, ⇒ unsigned char pages);
Description The BiosSetVirScrSize function sets the size of the virtual screen. This applies only to non-CRT emulating displays. Emulated video RAM resides within the extended BIOS work area.
This service adjusts the size of the extended BIOS work area as required to contain the desired video RAM. Allocating more video RAM removes more RAM from TPA since the extended BIOS work area is allocated from TPA.
Note: If the change in virtual screen size increases in the amount of video RAM allocated, thus decreasing TPA size, the system must be warm-booted to reconfigure for the smaller memory size.
If you specify a virtual screen dimension less than the corresponding physical screen dimension, the physical screen dimension is used. A maximum of 8 display pages, with a maximum size of 25 rows by 80 columns, can be allocated. For more information, refer to the Series 3000 System Software Manual.
BiosSetVirScrSize calls BIOS interrupt A1h, function 83h, subfunction 00h. Returns None
3-144 BIOS Library Functions
See Also BiosGetVirScrSize BiosWarmBoot
3-145 Series 3000 Application Programmer’s Reference Manual
BiosSetWakeReason Purpose Use BiosSetWakeReason to set events that will power up the terminal. Syntax #include <3000\bios.h>
extern void_far BiosSetWakeReason(unsigned char pwr_events, ⇒ unsigned char kbd_events);
Description The BiosSetWakeReason function sets which wake-up events can power up the terminal. The power key can never be disabled by use of this function. To disable the power key, it must be redefined by translating it to another key through use of the BIOS keyboard translation tables.
As parameters, this function expects two character masks that indicate: enabled events after normal power off and enabled events after keyboard timeout.
Event enable mask: Bits Meaning
4 321 0
Any Key Wake Up RTC Alarm Port 0 Ring Port 1 Ring Laser Trigger
BiosSetWakeReason calls BIOS interrupt B1h, function 01h.
3-146 BIOS Library Functions
Returns None See Also BiosWakeUpReason
3-147 Series 3000 Application Programmer’s Reference Manual
BiosShowCursor Purpose Use BiosShowCursor to enable display of the cursor. Syntax #include <3000\bios.h>
extern void_far BiosShowCursor(void);
Description The BiosShowCursor function enables the display of the cursor. Used after hiding the cursor.
BiosShowCursor calls BIOS interrupt A1h, function 01h. Returns None See Also BiosHideCursor
3-148 BIOS Library Functions
BiosSpottingBeam Purpose Use BiosSpottingBeam( ) to enable or disable power to the dual trigger laser scanner. Syntax #include <3000\bios.h>
void _far BiosSpottingBeam( unsigned char State );
Example Call BiosSpottingBeam(_SYM_SPOT_ON );
Description BiosSpottingBeam enables or disables power for the spotting beam. On a dual trigger laser scanner, the first position turns on the spotting beam and the second position activates scanning. When the spotting beam is disabled, power is removed from the scanner except during scanning.
Enabling the spotting beam draws power, and so can shorten battery charge life. Disable the spotting beam when it is not in use by using the _SYM_SPOT_OFF parameter.
BiosSpottingBeam calls BIOS interrupt B3h, function 0Eh. Returns None See Also None
3-149 Series 3000 Application Programmer’s Reference Manual
BiosSuspendTimer Purpose Use BiosSuspendTimer to set the status of a timer to “suspended.” Syntax #include <3000\bios.h>
unsigned char _far BiosSuspendTimer(unsigned char TimerNumber);
Example Call unsigned char Status;
Status = BiosSuspendTimer( TimerNumber );
Description BiosResetTimer sets the specified timer status to “suspended,” but does not clear the timer count or address. This service simply stops decrementing the timer.
BiosResetTimer calls BIOS interrupt ACh, function 05h. Returns Status Value Description Define name
0 Timer Suspended _SYM_TIMER_SUSP 1 TimerNumber is out of range _SYM_OUTOFRANGE See Also BiosResumeTimer( )
3-150 BIOS Library Functions
BiosTextRectToMem Purpose Use BiosTextRectToMem to copy text from the display to a buffer. Syntax #include <3000\bios.h>
extern void_far BiosTextRectToMem(unsigned char left, ⇒ unsigned char top, ⇒ unsigned char right, ⇒ unsigned char bottom, ⇒ unsigned char_far *buffer);
Description The BiosTextRectToMem function copies a rectangular area of text from the display to a user supplied memory buffer.
The buffer size should be at least:
(bottom - top + 1) * (right - left + 1) * 2 bytes.
It is filled with the character/attribute-byte pairs for all characters in the first row of the specified rectangle (left to right) then followed by each of the rest of the rows (top to bottom).
BiosTextRectToMem calls BIOS interrupt A1h, function 8Ah. Returns None See Also BiosMemToTextRect
3-151 Series 3000 Application Programmer’s Reference Manual
BiosTransDone Purpose Use BiosTransDone( ) to wait until the transmit queue and UART are empty. Syntax #include <3000\bios.h>
unsigned int _far BiosTransDone(int PortNumber );
Example Call unsigned int Status;
Status = BiosTransDone(_SYM_COM1);
Description Waits until the transmit queue and UART for the specified serial port are empty. Use this function after transmitting some data, and before closing the port or purging the communications queue.
BiosTransDone calls BIOS interrupt A5h, function 8Ah. Returns Status Value Description Define name
0 Transmit is Done, _SYM_SUCCESS Output Queue Empty
Non-Zero Error. See description of _ErrStatus in _SYM_SERIAL structure. Refer to function BiosPortStatus( ) for _ErrStatus bit descriptions.
3-152 BIOS Library Functions
BiosUpdateTimer Purpose Use BiosUpdateTimer to update the information about a timer that has been previously activated using BiosSetTimer. Syntax #include <3000\bios.h>
unsigned char _far BiosUpdateTimer(unsigned char TimerNumber, ⇒ unsigned long TimeUnits);
Example Call unsigned char Status;
Status = BiosUpdateTimer( TimerNumber, 10000L );
Description Updates the information about a timer which has been previously activated, but does not change the timer type or address.
BiosUpdateTimer calls BIOS interrupt ACh, function 09h. Returns Status Value Description Define name
0 Timer Information Updated _SYM_TIMER_UPDATED 1 TimerNumber is out of range _SYM_OUTOFRANGE See Also BiosSetTimer( )
3-153 Series 3000 Application Programmer’s Reference Manual
BiosWakeUpReason Purpose Use BiosWakeUpReason to get the wake-up reason for the last power up event. Syntax #include <3000\bios.h>
extern unsigned char_far BiosWakeUpReason(void);
Description The BiosWakeUpReason function returns the reason for the last time the terminal was powered on.
BiosWakeUpReason calls BIOS interrupt B1h, function 02h. Returns The BiosWakeUpReason function returns the reason for wakeup as follows:
Code Wake-up Reason
0Port 0 ring 1Port 1 ring 2Laser trigger 3Alarm 4Power key 5Other key 6 Operating system boot 7System cold start 8 Command mode entry See Also BiosSetWakeReason
3-154 BIOS Library Functions
BiosWarmBoot Purpose Use BiosWarmBoot to warm boot the terminal. Syntax #include <3000\bios.h>
extern void_far BiosWarmBoot(void);
Description The BiosWarmBoot function reboots the operating system without altering the size or contents of the RAM Disk (unless it has been explicitly changed prior to calling BiosWarmBoot).
Note: This function will not return to the caller.
BiosWarmBoot calls BIOS interrupt B4h. Returns None See Also BiosSetVirScrSize
3-155 Series 3000 Application Programmer’s Reference Manual
3-156 Chapter 4 DR DOS
Chapter Contents Introduction ...... 4-3 DOS Library Functions (Listing) ...... 4-3 DOS Library Functions (Descriptions) ...... 4-4 DosAbsDiskRead ...... 4-5 DosAbsDiskWrite ...... 4-6 DosAllocMem...... 4-7 DosClose ...... 4-8 DosCreate ...... 4-9 DosFreeMem...... 4-10 DosGetCh ...... 4-11 DosGetCurDrv ...... 4-12 DosGetDate...... 4-13 DosGetIntVector...... 4-14 DosGetTime ...... 4-15 DosIoCtrlCkInput ...... 4-16 DosIoCtrlCkOutput...... 4-17 DosIoCtrlDrvRdData...... 4-18 DosIoCtrlGetInfo ...... 4-20 DosIoCtrlRdData ...... 4-21 DosIoCtrlSetInfo...... 4-22 DosIoCtrlWrData ...... 4-23 DosOpen ...... 4-25 DosRead ...... 4-26 DosReadLine...... 4-27 DosSetDate ...... 4-28 DosSetIntVector ...... 4-29 DosSetTime ...... 4-30 DosWrite ...... 4-31 DosWriteLine ...... 4-32 Interface from Microsoft C ...... 4-33 Passing Structures to Functions...... 4-33 IOCTL Commands and Error Codes ...... 4-42 IOCTL Error Codes ...... 4-42
4-1 Series 3000 Application Programmer’s Reference Manual
Keyboard IOCTL Commands and Structures ...... 4-44 Keyboard/Scanning IOCTL Structures ...... 4-46 Communications IOCTL Commands and Structures ...... 4-73
4-2 DR DOS
Introduction The DOS function library is a collection of C interface routines for accessing DR DOS system calls on Series 3000 terminals. It is located in the DOS.LIB file on the C:\3000\LIB directory in the ADK.
The following topics are presented in this chapter: • DOS Library Functions (Listing) • DOS Library Functions (Descriptions) • Interface from Microsoft C • IOCTL Tables -Error Codes - Keyboard/Scanning commands and structures - Communication commands and structures DOS Library Functions (Listing) Table 4-1 lists the DR DOS library (DOS.LIB) functions in order of the interrupt number, the function number required in the AH register and the subfunction number required (if any) in the AL register . Descriptions of these functions in alphabetical order by function name are provided in the DOS Library Functions (Descriptions) section that follows in this chapter. Table 4-1. DR DOS C Interface Functions
Function Name Interrupt Number AH AL DosGetCh 21h 01h -- DosSetIntVector 21h 25h -- DosGetDate 21h 2Ah -- DosSetDate 21h 2Bh -- DosGetTime 21h 2Ch -- DosSetTime 21h 2Dh -- DosGetIntVector 21h 35h -- DosCreate 21h 3Ch -- DosOpen 21h 3Dh --
4-3 Series 3000 Application Programmer’s Reference Manual
Table 4-1. DR DOS C Interface Functions (Continued)
Function Name Interrupt Number AH AL DosClose 21h 3Eh -- DosRead 21h 3Fh -- DosReadLine 21h 3Fh -- DosWrite 21h 40h -- DosWriteLine 21h 40h -- DosIoCtrlCkInput 21h 44h 06h DosIoCtrlCkOutput 21h 44h 07h DosIoCtrlGetInfo 21h 44h 00h DosIoCtrlSetInfo 21h 44h 01h DosIoCtrlRdData 21h 44h 02h DosIoCtrlWrData 21h 44h 03h DosIoCtrlDrvRdData 21h 44h 04h DosGetCurDrv 21h 47h 0Eh DosAllocMem 21h 48h -- DosFreeMem 21h 49h -- DosAbsDiskRead 25h -- -- DosAbsDiskWrite 26h -- --
DOS Library Functions (Descriptions) This section provides descriptions of the DOS Library functions that are listed in Table 4-1. The descriptions begin on the next page in alphabetical order by function name.
4-4 DR DOS
DosAbsDiskRead Syntax #include <3000\dos.h>
extern unsigned int far DosAbsDiskRead(unsigned int sect_num, ⇒ unsigned int start_sect, ⇒ char far * buffer, ⇒ unsigned int disk_drv, ⇒ unsigned int far * err_code);
Description The DosAbsDiskRead function reads specific DOS disk sectors. This function expects sect_num, the number of sectors to load, start_sect, the starting sector number to load, buffer, a memory address to store data, disk_drv, a logical drive (A = 0, B = 1, etc.), and err_code, the address for an error code.
DosAbsDiskRead calls DR DOS interrupt 25h. Return Value DosAbsDiskRead returns 1 if successful, or 0 if an error occurs and err_code indicates the error condition:
err_code Meaning
01h Bad command 02h Bad address 03h Attempted write on protected diskette 04h Sector not found 10h Bad CRC on read 40h SEEK failed 80h Attachment failed to respond See Also DosAbsDiskWrite
4-5 Series 3000 Application Programmer’s Reference Manual
DosAbsDiskWrite Syntax #include <3000\dos.h>
extern unsigned int far DosAbsDiskWrite(unsigned int sect_num, ⇒ unsigned int start_sect, ⇒ char far * buffer, ⇒ unsigned int disk_drv, ⇒ unsigned int far * err_code);
Description The DosAbsDiskWrite function writes specific DOS disk sectors. This function expects sect_num, the number of sectors to load, start_sect, the starting sector number to load, buffer, a memory address to store data, disk_drv, a logical drive (A = 0, B = 1, etc.), and err_code, the address for an error code.
DosAbsDiskWrite calls DR DOS interrupt 26h. Return Value DosAbsDiskWrite returns 1 if successful, or 0 if an error occurs and err_code indicates the error condition:
err_code Meaning
01h Bad command 02h Bad address 03h Attempted write on protected diskette 04h Sector not found 08h DMA failure 10h Bad CRC on read 40h SEEK failed 80h Attachment failed to respond See Also DosAbsDiskRead
4-6 DR DOS
DosAllocMem Syntax #include <3000\dos.h>
extern char far DosAllocMem(unsigned int far * numparas, ⇒ void far * far * memptr);
Description The DosAllocMem function allocates memory from the heap area. This function expects numparas, a far pointer to an unsigned integer indicating the size (in paragraphs) of requested memory.
DosAllocMemcalls DR DOS interrupt 21h, function 48h. Return Value The DosAllocMem function returns a pointer to the allocated memory in memptr and the size of the largest available block (in paragraphs) in numparas.
The function return value is:
Value Meaning
0 Successful 7 Memory control blocks destroyed 8 Insufficient memory See Also DosFreeMem
4-7 Series 3000 Application Programmer’s Reference Manual
DosClose Syntax #include <3000\dos.h>
extern unsigned int far DosClose(unsigned int handle);
Description The DosClose function closes the DOS device or file associated with handle. This function expects a valid handle, a device or file handle returned by DosOpen or DosCreate.
DosClose calls DR DOS interrupt 21h, function 3Eh. Return Value Value Meaning
0 Successful 6 Illegal file handle See Also DosCreate, DosOpen
4-8 DR DOS
DosCreate Syntax #include <3000\dos.h>
extern unsigned int far DosCreate(char far * filename, ⇒ unsigned int far * handle);
Description The DosCreate function creates a file. This function expects filename, a far pointer to a string containing the file name.
DosCreate calls DR DOS interrupt 21h, function 3Ch. Return Value DosCreate function returns the allocated handle to the pointer handle. The function returns the following status values:
Value Meaning
0 Successful 3 Path not found 4 No file handles (too many open files) 5 Access denied See Also DosOpen DosClose
4-9 Series 3000 Application Programmer’s Reference Manual
DosFreeMem Syntax #include <3000\dos.h>
extern char far DosFreeMem(void far * memptr);
Description The DosFreeMem function frees a previously allocated block of memory. This function expects memptr, a far pointer to a previously allocated block of memory.
DosFreeMemcalls DR DOS interrupt 21h, function 49h. Return Value Value Meaning
0 Successful 7 Memory control blocks destroyed 9 Illegal memory block address See Also DosAllocMem
4-10 DR DOS
DosGetCh Syntax #include <3000\dos.h>
extern char far DosGetCh(char waitflag);
Description The DosGetCh function gets a character from the standard input device. This function expects waitflag. If waitflag is 1, DosGetCh waits for an input character; otherwise, it returns immediately. While waiting for a character, DosGetCh does not look at the timeout value set by BiosSetKybdTimeout.
DosGetCh calls DR DOS interrupt 21h, function 01h. Return Value DosGetCh function returns a character if one is present or 0xFF if a character is not present. If an extended key is pressed, a value of zero is returned and the extended key scan code is returned by the next call to DosGetCh. See Appendix A for keyboard scan codes and ASCII codes. See Also BiosGetCh
4-11 Series 3000 Application Programmer’s Reference Manual
DosGetCurDrv Syntax #include <3000\dos.h>
extern unsigned int far DosGetCurDrv(void);
Description The DosGetCurDrv function reports the current drive.
DosGetCurDrv calls DR DOS interrupt 21h, function 47h. Return Value DosGetCurDrv reports the current drive using the standard numeric drive designation:
Value Meaning
0drive A 1drive B ...... 15 Invalid drive specified
4-12 DR DOS
DosGetDate Syntax #include <3000\dos.h>
extern void far DosGetDate(DOS_DATEP date_parm);
Description The DosGetDate function returns the current date, broken down into the year (1980-2079), the month (1-12), the day (1-31), and the day of the week (0-6, Sun=0, Mon=1,...,Sat=6). It uses INT 21h, Function 2Ah to get the date. This function expects a pointer to a DOS date parameter structure, as follows:
typedef struct { unsigned char day; /* 1-31 */ unsigned char month; /* 1-12 */ unsigned int year; /* 1980-2079 */ unsigned char dayofweek;/* 0-6,0=Sunday */ } DOS_DATET; typedef DOS_DATET far *DOSDATEP;
DosGetDate calls DR DOS interrupt 21h, function 2Ah. Return Value DosGetDate returns values into the structure which is pointed to by date_parm. See Also DosSetDate, DosGetTime, DosSetTime
4-13 Series 3000 Application Programmer’s Reference Manual
DosGetIntVector Syntax #include <3000\dos.h>
extern unsigned long far DosGetIntVector(unsigned int intno);
Description The DosGetIntVector function returns the current interrupt vector associated with intno via DOS function 35h. This function expects intno, an interrupt number.
DosGetIntVector calls DR DOS interrupt 21h, function 35h. Return Value DosGetIntVector returns the interrupt vector. See Also DosSetIntVector
4-14 DR DOS
DosGetTime Syntax #include <3000\dos.h>
extern void far DosGetTime(DOS_TIMEP time_parm);
Description The DosGetTime function returns the current time, broken down into the hour (0-23), minute (0-59), second (0-59), and the hundredth of a second (0-99). It uses INT 21h, Function 2Ch to get the time. This function expects a pointer to a DOS time parameter structure, as follows:
typedef struct { unsigned char hour; /* 0-23 */ unsigned char minute; /* 0-59 */ unsigned char second; /* 0-59 */ unsigned char hsecond; /* 0-99 */ } DOS_TIMET; typedef DOS_TIMET far *DOS_TIMEP;
DosGetTime calls DR DOS interrupt 21h, function 2Ch. Return Value DosGetTime puts the time information into the structure pointed to by time_parm. See Also DosSetTime, DosGetDate, DosSetDate
4-15 Series 3000 Application Programmer’s Reference Manual
DosIoCtrlCkInput Syntax #include <3000\dos.h> extern unsigned char far DosIoCtrlCkInput( unsigned int Handle);
Description Checks device or file to determine if it is ready for input. This function expects a valid handle number.
DosIoCtrlCkInput calls DR DOS interrupt 21h, function 44h, subfunction 06h. Returns For a device:
Return Value Description
0xff Device Ready 0 Device Not Ready
For a file:
Return Value Description
0xff Ready 0Pointer at EOF See Also DosIoCtrlCkOutput
4-16 DR DOS
DosIoCtrlCkOutput Syntax #include <3000\dos.h> extern unsigned char far DosIoCtrlCkOutput( unsigned int Handle);
Description Checks the device or file to determine if it is ready for output. This function expects a valid handle number.
DosIoCtrlCkOutput calls DR DOS interrupt 21h, function 44h, subfunction 07h. Returns For a device:
Return Value Description
0xff Device Ready 0 Device Not Ready
For a file:
Return Value Description
0xff Ready 0Pointer at EOF See Also DosIoCtrlCkInput
4-17 Series 3000 Application Programmer’s Reference Manual
DosIoCtrlDrvRdData Syntax #include <3000\dos.h>
extern unsigned int far DosIoCtrlDrvRdData(unsigned int handle, ⇒ void far * bufptr);
Description The DosIoCtrlDrvRdData function either translates a sector number into a segment address and checks if the consecutive count sectors are within the same boundary, or translates a segment address into a sector number.
This function expects handle, a valid handle number and bufptr, a far pointer to a parameter block which is defined as follows:
typedef struct{ unsigned int dir; /* direction of translation */ /*0=sector to segment */ /*1=segment to sector */ unsigned int size; /* size of verified memory in bytes */ unsigned int segment; /* segment address */ unsigned int count; /* sector number count to check*/ unsigned int sector; /* starting sector Number */ unsigned int pagenum; /* EMS logical page number */ /* -1 = conventional memory */ }DRIVE_DATAT; DRIVE_DATAT DriveData; DosIoCtrlDrvRdData ( handle. (void far *) &DriveData);
If dir = 0, DosIoCtrlDrvRdData uses the starting sector number and the sector count. It returns the segment address, the sector count available to the caller (sector count within boundaries), the memory size in bytes (size of sector multiplied by sector count), and the logical page number if the sector range is in expanded memory or -1 if the sector range is in conventional memory. If the sector range is in expanded memory, the logical page must be mapped into the physical page frame before attempting access to the sectors. The segment address returned assumes physical page 0 will be used.
4-18 DR DOS
If dir = 1, DosIoCtrlDrvRdData uses the segment address and the page number. It returns the starting sector number that corresponds to the segment address.
DosIoCtrlDrvRdData calls DR DOS interrupt 21h, function 44h, sub-function 0Eh. Return Value DosIoCtrlDrvRdData returns values to the defined parameter block as described under Description.
4-19 Series 3000 Application Programmer’s Reference Manual
DosIoCtrlGetInfo Syntax #include <3000\dos.h>
extern unsigned int far DosIoCtrlGetInfo(unsigned int handle);
Description The DosIoCtrlGetInfo function gets information about a device or file referenced by handle. This function expects handle, a valid device or file handle number.
DosIoCtrlGetInfo calls DR DOS interrupt 21h, function 44h, sub-function 00h. Return Value The DosIoCtrlGetInfo return value contains device information. See Also DosIoCtrlSetInfo
4-20 DR DOS
DosIoCtrlRdData Syntax #include <3000\dos.h>
extern unsigned int far DosIoCtrlRdData(unsigned int handle, ⇒ void far * bufptr, ⇒ int buflen);
Description The DosIoCtrlRdData function reads control strings from a device driver. This function expects handle, a valid handle number, bufptr, a far pointer to a data buffer, and buflen, the number of bytes to read.
See the IOCTL Command and Error Code tables at the end of this chapter for a detailed description of the IOCTL parameters. IOCTL data structures are located in URM.GT. Defines for buflen are located in URM.GD. Include <3000\URM.H> to get these structures and be sure to pack the structures on 1- byte boundaries. To pack structures on 1-byte boundaries, use #pragma pack(1) or /Zp1.
DosIoCtrlRdData calls DR DOS interrupt 21h, function 44h, sub-function 02h. Example IoctlT iob; /* Get last char read status */ iob.funcode = ConsIoctlGetCharStatus; DosIoCtrlRdData(handle,&iob,ConsIoctlGetCharStatusLen);
Return Value DosIoCtrlRdData returns data read from the device driver to the buffer pointed to by bufptr. The function return value contains the actual number of bytes transferred. See Also DosIoCtrlWrData
4-21 Series 3000 Application Programmer’s Reference Manual
DosIoCtrlSetInfo Syntax #include <3000\dos.h>
extern void far DosIoCtrlSetInfo(unsigned int handle, ⇒ unsigned int devdata);
Description The DosIoCtrlSetInfo function sets device driver information. This function expects handle, a valid device handle number and devdata, a device data word.
Note: When using DosIoCtrlSetInfo, the value passed for devdata should always be a value returned by DosIoCtrlGetInfo, suitably modified. It is not advisable to simply pass a user- created value as the bits in this word can seriously impact the operation of the file or device.
DosIoCtrlSetInfo calls DR DOS interrupt 21h, function 44h, sub-function 01h. Return Value None See Also DosIoCtrlGetInfo
4-22 DR DOS
DosIoCtrlWrData Syntax #include <3000\dos.h>
extern unsigned int far DosIoCtrlWrData(unsigned int handle, ⇒ void far * bufptr, ⇒ int buflen);
Description The DosIoCtrlWrData function writes control strings to a device driver. This function expects handle, a valid handle number, bufptr, a far pointer to a data buffer, and buflen, the number of bytes to write.
See the IOCTL Command and Error Code tables at the end of this chapter for a detailed description of the IOCTL parameters. IOCTL data structures are located in URM.GT. Defines for buflen are located in URM.GD. Include <3000\URM.H> to get these structures and be sure to pack the structures on 1- byte boundaries. To pack structures on 1-byte boundaries, use #pragma pack(1) or /Zp1. Example IoctlT iob; /* Turn on scanning = allow scan ahead */ iob.funcode = ConsIoctlScanState; iob.data.scanstate.scan_state = 1; DosIoCtrlWrData(handle,&iob,ConsIoctlScanStateLen);
Note: In many cases, it is recommended that the buffer passed to DosIoCtrlWrData be loaded with the contents returned by DosIoCtrlRdData, suitably modified. This is most important when a Get/Set function is available for reading and writing device parameters. This will prevent invalid values in fields not set by the user.
DosIoCtrlWrData calls DR DOS interrupt 21h, function 44h, sub-function 03h.
4-23 Series 3000 Application Programmer’s Reference Manual
Return Value The DosIoCtrlWrData return value contains the actual number of bytes transferred. See Also DosIoCtrlRdData
4-24 DR DOS
DosOpen Syntax #include <3000\dos.h>
extern unsigned int far DosOpen(char far * filename, ⇒ unsigned char openmode, ⇒ unsigned int far * handle);
Description The DosOpen function opens a file or device. As parameters, the DosOpen function expects filename, a far pointer to a string containing the device or file name, and openmode, a byte indicating the I/O mode, where:
Value Meaning
0x00 Read Only 0x01 Write Only 0x02 Read/Write
DosOpen calls DR DOS interrupt 21h, function 3Dh. Return Value DosOpen returns the opened handle to the variable handle. The function return value is as follows:
Value Meaning
0 Successful 2 File not found 5 Access denied 12 Invalid access code See Also DosCreate, DosClose
4-25 Series 3000 Application Programmer’s Reference Manual
DosRead Syntax #include <3000\dos.h>
extern unsigned int far DosRead(unsigned int handle, ⇒ void far * bufptr, ⇒ unsigned int buflen, ⇒ unsigned int far * number);
Description The DosRead function reads from the file or device associated with handle. This function expects handle, a device or file handle number, bufptr, a far pointer to a data buffer, and buflen, the length of the data buffer.
DosRead calls DR DOS interrupt 21h, function 3Fh. Return Value DosRead returns the actual number of bytes read to the variable number. The function return value is as follows:
Values Meaning
0 Successful 5 Access denied 6 Illegal file handle See Also DosReadLine DosWrite
4-26 DR DOS
DosReadLine Syntax #include <3000\dos.h>
extern unsigned int far DosReadLine(unsigned int handle, ⇒ char far * bufptr, ⇒ unsigned int maxlen);
Description The DosReadLine function uses the DosRead function to read maxlen characters from the file associated with handle. If a carriage return line feed sequence is encountered or if maxlen characters are read, it null terminates the string and returns 0 (success).
DosReadLine calls DR DOS interrupt 21h, function 3Fh. Return Value If a carriage return line feed sequence is encountered or if maxlen characters are read, it null terminates the string and returns 0 (success). If the line is empty, a 1 is returned. If DosRead fails, an error code is returned:
Error Code Meaning
5 Access denied 6 Illegal file handle See Also DosWriteLine
4-27 Series 3000 Application Programmer’s Reference Manual
DosSetDate Syntax #include <3000\dos.h>
extern void far DosSetDate(DOS_DATEP date_parm);
Description The DosSetDate function sets the current date, broken down into the year (1980-2079), the month (1-12), the day (1-31), and the day of the week (0-6, Sun=0, Mon=1, ..., Sat=6). It uses INT 21h, Function 2Bh to set the date. This function expects a pointer to a DOS date parameter structure, as follows:
typedef struct { unsigned char day; /* 1-31 */ unsigned char month; /* 1-12 */ unsigned int year; /* 1980-2079 */ unsigned char dayofweek;/* 0-6,0=Sunday */ } DOS_DATET; typedef DOS_DATET far *DOSDATEP;
DosSetDate calls DR DOS interrupt 21h, function 2Bh. Return Value None See Also DosGetDate DosGetTime DosSetTime
4-28 DR DOS
DosSetIntVector Syntax #include <3000\dos.h>
extern void far DosSetIntVector(unsigned int intno, ⇒ void far * vector);
Description The DosSetIntVector function sets the interrupt vector associated with intno via DOS function 25h. This function expects intno, an interrupt number and vector, a far pointer to the interrupt handler.
DosSetIntVector calls DR DOS interrupt 21h, function 25h. Return Value None See Also DosGetIntVector
4-29 Series 3000 Application Programmer’s Reference Manual
DosSetTime Syntax #include <3000\dos.h>
extern void far DosSetTime(DOS_TIMEP time_parm);
Description The DosSetTime function sets the current time, broken down into the hour (0- 23), minute (0-59), second (0-59), and the hundredth of a second (0-99). It uses INT 21h, Function 2Dh to set the time. This function expects a pointer to a DOS time parameter structure, as follows:
typedef struct { unsigned char hour; /* 0-23 */ unsigned char minute;/* 0-59 */ unsigned char second;/* 0-59 */ unsigned char hsecond;/* 0-99 */ } DOS_TIMET; typedef DOS_TIMET far *DOS_TIMEP;
DosSetTime calls DR DOS interrupt 21h, function 2Dh. Return Value None See Also DosGetTime, DosGetDate, DosSetDate
4-30 DR DOS
DosWrite Syntax #include <3000\dos.h>
extern unsigned int far DosWrite(unsigned int handle, ⇒ void far * bufptr, ⇒ unsigned int buflen, ⇒ unsigned int far * number);
Description The DosWrite function writes to the file or device associated with handle. This function expects handle, a device or file handle number, bufptr, a far pointer to a data buffer, and buflen, the length of the data buffer.
DosWrite calls DR DOS interrupt 21h, function 40h. Return Value DosWrite returns the actual number of bytes written to the variable number. The function return values are as follow:
Value Meaning
0 Successful 5 Access denied 6 Illegal file handle See Also DosRead
4-31 Series 3000 Application Programmer’s Reference Manual
DosWriteLine Syntax #include <3000\dos.h>
extern unsigned int far DosWriteLine(unsigned int handle, ⇒ void far * bufptr);
Description The DosWriteLine function uses the DosWrite function to write the characters pointed to by bufptr to the file associated with handle. The function appends a carriage return line feed sequence to the end of the string.
DosWriteLine calls DR DOS interrupt 21h, function 40h. Return Value If DosWrite cannot write the characters pointed to by bufptr or if DosWrite cannot write a carriage return line feed sequence, DosWriteLine returns 1. If DosWrite fails, an error code is returned:
Error Code Meaning
5 Access denied 6 Illegal file handle See Also DosReadLine
4-32 DR DOS
Interface from Microsoft C This section discusses details regarding the use of the DR DOS functions from Microsoft C.
Using the DR DOS interface functions is, for the most part, straightforward. Most function calls naturally involve passing parameters. In many cases, one of those parameters is a pointer to a structure. The information in this section explains how to pass a structure pointer to a DR DOS function.
A complete list of DOS structures is provided; however, explanations for each DOS structure goes beyond the scope of this document. Two examples are provided that should cover both types of DR DOS structures that you will encounter.
The first example explains how to declare, initialize, and pass a simple data structure, the date structure, to a DR DOS function. The second example explains how to do the same for a more complex data structure, the ioctl structure. Passing Structures to Functions Structures passed to Symbol DOS library functions must be packed. The library functions will access data in the structure incorrectly if passed an unpacked structure.
To pack a structure, use the /Zp compiler option or the pack pragma. For example:
cl /AL /Zp1 sample.c or
#pragma pack(1)
Refer to section on packing structures in the Microsoft C compiler documentation.
4-33 Series 3000 Application Programmer’s Reference Manual
Example 1: Simple Data Structure This example explains how to declare, initialize, and pass a date structure to the DR DOS function: DosGetDate.
There are many similar DOS structures available. Most of these structures are declared, initialized, and passed to DOS functions in the same way as the example provided.
Date Structure Defined
The following section presents the Microsoft C declaration for the Date structure:
typedef struct { unsigned char day; /* 1-31 */ unsigned char month; /* 1-12 */ unsigned int year; /* 1980-2079 */ unsigned char dayofweek;/* 0-6, 0=Sunday */ }DOS_DATET; typedef DOS_DATET far DOS_DATEP;
Declaring the Date Structure
Use the symbol DOS_DATET to declare instances of date structures as needed to satisfy the program requirements. For example:
DOS_DATET todays_date;
Initializing the Date Structure
The date structure or any DOS structure must be initialized before it is passed to a DR DOS function. DOS_DATET todays_date = {01, /* day: the first */ 07, /* month: July */ 1990, /* year: 1990 */ 4 /* day of week: Thursday */ }
Passing the Date Structure to a Function
4-34 DR DOS
When passing a date structure or most types of DOS structures as a parameter to a DR DOS function, use the “address of” operator (&) in front of the name of the structure, for example:
DosGetDate( &todays_date );
Example 2: Complex Data Structure This example explains how to declare, initialize, and pass an I/O control (ioctl) structure to the DR DOS function: DosIoCtrlWrData.
DosIoCtrlWrData is a member of a group of functions within the DR DOS interface library with the prefix: DosIoCtrl. These are DOS input/output control functions. Two of these functions receive, as one of their parameters, a pointer to an input/output control structure (ioctl).
The ioctl structure is a complex data structure that includes a function code specification, and error code value, and a “C” union construct. The union describes various formats for use by the various function codes. The function code (funcode) value determines which format to use.
For this example, the value in funcode will cause the commonly used Communications Parameters structure to be referenced.
Communication Parameter Structure Defined
The following section presents the Microsoft C declaration for the Communication Parameter structure, and can be found in URM.GT:
struct ComParam_S { byte baudrate; byte databits; byte parity; byte stopbits; byte duplex; word modemdelay; word txcarrierwait; word rxcarrierwait; word carrierlossdetect; byte ctlstopchar;
4-35 Series 3000 Application Programmer’s Reference Manual
byte ctlstartchar; byte ctlstartwait; byte ctslossdetect; byte rxcharwait; byte dsrwait; byte cdwait; byte spacetime; byte marktime; byte linecondflags; byte flowctl; byte errmask; byte errinsch; word dtrsettle; byte connectwait; };
#define ComParamT struct ComParam_S #define ComParamP ComParamT far *
Initializing the Communications Parameters Structure The Communications Parameters structure or any DOS structure should be initialized before it is passed to a DR DOS function. The Communications Parameters structure is a subset of the generic ioctl structure, which is defined in URM.GT. Unlike other structures, the ioctl structure contains a union. The union describes various formats for use by the various function codes. In order to specify which of the various formats to use, to initialize the fields of the structure, use assignment statements (see below).
Also, using assignment statements makes it easy to conditionally select values for various fields (see the Sample Function section at the end of this chapter).
The Communications Parameters structure might be initialized as shown below:
ioctl.data.comparameters.databits= DATABITS8; ioctl.data.comparameters.parity= PARITYNONE; ioctl.data.comparameters.ctlstopchar= 0x13; ioctl.data.comparameters.ctlstartchar= 0x11; ioctl.data.comparameters.spacetime= 3;
4-36 DR DOS
ioctl.data.comparameters.marktime= 3; ioctl.data.comparameters.flowctl= NOFLOWCTL;
Passing the Communications Parameters Structure to a Function
When passing the communications parameter structure to a DR DOS function, use the “address of” operator (&) in front of the name of the structure, for example:
DosIoCtrlWrData(handle,(charfar *)&ioctl, ComIoctlComParamLen);
The function DosIoCtrlWrData receives a character pointer as a parameter rather than a structure pointer. To satisfy the C compiler, use the cast, (charfar *), in front of the “address of” operator (&). Sample Function The following sample function (configure) demonstrates how to use two of the ioctl functions, making use of the ioctl structure, specifically the pointer to the Communications Parameters structure. configure opens a device handle, checks to see if it is a device (as opposed to a disk file), and sets the device to binary mode. It then gets the currently selected parameters and sets new parameters. Finally, it writes the new parameters to the device and closes the device handle.
void configure(char *port,byte col) { /* Open the handle */ if ( DosOpen(port,READWRITE,&handle) ) terminate(1);
/* Check to see if its a device, not a disk file */ DeviceInfo = DosIoCtrlGetInfo(handle); if ( ( DeviceInfo & ISDEVICE ) == 0 ) terminate(1);
/* Set binary mode */ DosIoCtrlSetInfo(handle,DeviceInfo|RAWMODE);
/* Get currently selected parameters */ ioctl.funcode = ComIoctlComParamCmd; DosIoCtrlRdData(handle,(charfar *)&ioctl, ComIoctlComParamLen);
4-37 Series 3000 Application Programmer’s Reference Manual
/* Set new parameters that are based on protocol selected */ switch ( msi_prot )
{case MSITWOWAY: ioctl.data.comparameters.databits= DATABITS8; ioctl.data.comparameters.parity= PARITYNONE; ioctl.data.comparameters.flowctl= NOFLOWCTL; break; case MSISIMPLEX: ioctl.data.comparameters.databits = DATABITS7; ioctl.data.comparameters.parity= PARITYODD; ioctl.data.comparameters.flowctl= HARDWAREFLOWCTL; if ( send ) {ioctl.data.comparameters.marktime = 3; ioctl.data.comparameters.spacetime = 3; }else {ioctl.data.comparameters.marktime = 0; ioctl.data.comparameters.spacetime = 0; } break; case MSIXONXOFF: ioctl.data.comparameters.databits= DATABITS7; ioctl.data.comparameters.parity= PARITYODD; ioctl.data.comparameters.flowctl= SOFTWAREFLOWCTL; ioctl.data.comparameters.ctlstartchar= 0x11; ioctl.data.comparameters.ctlstopchar= 0x13; break; };
/* Set new parameters that are protocol independent */ ioctl.data.comparameters.baudrate= BAUD1200; ioctl.data.comparameters.stopbits= STOPBITS1; ioctl.data.comparameters.duplex= duplex; ioctl.data.comparameters.modemdelay= delay; ioctl.data.comparameters.dsrwait= 30; ioctl.data.comparameters.cdwait= 30; ioctl.data.comparameters.linecondflags= CTSCOND; ioctl.data.comparameters.rxcharwait= 30;
4-38 DR DOS
/* Write the new parameters */ ioctl.funcode = ComIoctlComParamCmd; DosIoCtrlWrData(handle,(charfar *)&ioctl, ComIoctlComParamLen);
/* Close the handle */ if ( DosClose(handle) ) terminate(1); };
I/O Control Structure Defined struct Ioctl_S { char funcode; char errcode; union { /* Comm */ ComParamT comparameters; ModemStatusT modemstatus; LineStatusT linestatus; ProtoCntT protocolcnt; NextProtoT protocol; SelectProtT selectprotocol; ProtParamT prot_parms; SLPParamT slp_parms; HdrTrlrT hdrtrlr; QStatusT qstat;
TwoWayParamT twoway_parms; Spect1ParamT spect1_parms;
Spect1StatsT spect1_stats SLPStatsT slp_stats; Spect1StatusT s1_status TwoWayStatusT twoway_status; TwoWay_StatsT twoway_stats; byte s1_timeout; byte s1_unsolicited;
/* LPT */ char far * terminator; LptParamT lptparm;
4-39 Series 3000 Application Programmer’s Reference Manual
LptRedirectT redirect; byte linenum; byte lptCE; LptIoctlStatusT lptstat;
/* Con */ InModeT inputmode; ScanModeT scanmode; ScanStateT scanstate; CharStatT charstatus; ReaderCharT readerchar; ReaderParamT readerparms; ScanParamT scanparms; DecoderParamT decoderparms; byte decodercount; char decodername[16]; byte index; byte wandpresent; byte readertype;
/* PDF Decoder Information */ PDFDecoderParmT pdfdecoderparms; PDFComParmT pdfcomparms; PDFContigParmT pdfcontigparms; PDFSeparatorParmT pdfseparatorparms; PDFTemplateParmT pdftemplateparms;
/* Scanning Decoder Extensions */ DecoderRedunT redundancy; DecoderChkDgt checkdigit; DecoderUPCParmT UPCparms; DecoderRetFmT retformat;
/* Scanning Decoder Extensions Catch-All */ DecoderExtensionT extensions; PDFcontrolT pdfcontrol PDFdata_statusT PDFdata_status PDFdata_accessT PDFdata_access Genesis_ParamT Genesis_Param TriggerStateT triggerstate LaserTimeOuT lasertimeout }data; };
4-40 DR DOS
#define IoctlT struct Ioctl_S #define IoctlP IoctlT far *
4-41 Series 3000 Application Programmer’s Reference Manual
IOCTL Commands and Error Codes The following tables give the following IOCTL information:
Table 4-2 IOCTL Error Codes Table 4-3 Keyboard IOCTL Commands and Structures Table 4-4 through 4-28 Keyboard/Scanning IOCTL Commands and Structures Tables 4-29through 4-49 Communications IOCTL Commands and Structures
Note that in all cases, the first two fields of an IOCTL structure are the subcommand number and the error code, respectively. IOCTL Error Codes Table 4-2 gives the IOCTL Error Codes: Table 4-2. IOCTL Error Codes
Error Code Error Name Description Number Physical layer error codes 0x00 Successful (no error) 0x01 NOTOPEN Channel not open 0x02 OVERRUN UART data overrun error 0x03 PARITY Character parity error 0x04 FRAMING Character framing error 0x05 BREAK Data Line break detected 0x06 NODSRCD CD/DSR not detected on open 0x07 DSRLOST DSR lost (line drop) 0x08 ABORTKEY Abort key pressed 0x09 CDLOST CD lost (line drop) 0x0A CDRCVERR CD error on receive 0x0B CDXMITERR CD error on transmit 0x0C RCVTIMEOUT Character receive timeout 0x0D XONNOTRCVD Control start not received
4-42 DR DOS
Table 4-2. IOCTL Error Codes (Continued)
Error Code Error Name Description Number 0x0E CTSLOST CTS lost (line drop) 0x0F FCVQFULL Receive queue full 0x10 BADCFG Invalid line configuration 0x11 NOTIMER Insufficient system resources available Comm driver only codes 0x30 BADFUNC IOCTL function not supported 0x31 BADPROT Requested protocol not attached Generic protocol errors 0x40 BADPROTPARM Invalid protocol parameter 0x41 BADSTATEFNC Invalid function for this state 0x42 BADPROTFNC Function violates protocol requirements 0x50 RCVDABORT Disconnect (abort sequence received) 0x51 RCVDEOT End of transmission (EOT received) 0x52 EOTWOETX Premature end of transmission (EOT before ETX) 0x53 RCVDRVI Remote requested line turnaround (RVI received) 0x54 SENTRVI Transmission not currently allowed (RVI was sent) 0x60 Transmit or receive timeout Two-way specific errors 0x80 MAXNAKS NAK limit exceeded 0x81 MAXWAKS WACK limit exceeded 0x82 MAXTTDS TTD limit exceeded
4-43 Series 3000 Application Programmer’s Reference Manual
Keyboard IOCTL Commands and Structures Table 4-3 lists the keyboard IOCTL commands and structures. Table 4-3. Keyboard IOCTL Commands and Structures
Keyboard IOCTL Commands Command Command Name IOCTL Structure Number from URM.GD 0 ConsIoctlInputMode inputmode ConsIoctlGetInputMode ConsIoctlSetInputMode 1 ConsIoctlScanMode scanmode ConsIoctlGetScanMode ConsIoctlSetScanMode 2 ConsIoctlScanState scanstate ConsIoctlGetScanState ConsIoctlSetScanState 3 ConsIoctlGetCharStatus charstatus ConsIoctlSoftTrigger no structure 4 ConsIoctlReaderChar readerchar ConsIoctlGetReaderChar ConsIoctlSetReaderChar 5 ConsIoctlReaderParms readerparms ConsIoctlGetReaderParms ConsIoctlSetReaderParms 6 ConsIoctlScanParms scanparms ConsIoctlGetScanParms ConsIoctlSetScanParms 7 ConsIoctlDecoderParms decoderparms ConsIoctlGetDecoderParms ConsIoctlSetDecoderParms 8 ConsIoctlGetDecodercount decodercount ConsIoctlResetSoftTrigger no structure 9 ConsIoctlGetNextDecoder decodername ConsIoctlSet Redundancy redundancy 0A ConsIoctlGetErrorCode no structure CoonsIoctlSetCheckDigits checkdigit
4-44 DR DOS
Table 4-3. Keyboard IOCTL Commands and Structures (Continued)
Keyboard IOCTL Commands Command Command Name IOCTL Structure Number from URM.GD 0B ConsIoctlGetReaderType readertype ConsIoctlWandPresent readertype ConsIoctlSetUPCParams upcparms 0C ConsIoctlGetRedundancy redundancy ConsIoctlSetReturnFmt retformat 0D ConsIoctlGetCheckDigits checkdigit ConsIoctlSetScanExtensions extensions 0E ConsIoctlGetUPCParams upcparms ConsSetScanExtensions pdfdecoderparms 0F ConsIoctlGetReturnFmt retformat ConsSetPDFDecoderParms pdfcoparms 10 ConsIoctlGetScanExtensions extensions ConsSetPDF ContigParms pdfcontigparms 11 ConsGetPDFDecoderParms pdfdecoderparms ConsSetPDFSepParms pdfseparatorparms 12 ConsGetPDFComParms pdfcomparms ConsSetPDFTemplateParms pdftemplateparms 13 ConsGetPDFContigParms pdfcontigparms ConsIoctlSetPDFcontrol pdfcontrol 14 ConsGetPDFSepParms pdfseparatorparms ConsIoctlSetPDFdata_access pdfdata_access 15 ConsGetPDFTemplateParms pdftemplateparms ConsIoctlResetPDFdata_status pdfdata_status 16 ConsIoctlGetPDFcontrol pdfcontrol 17 ConsIoctlGetPDFdata_status pdfdata_status ConsIoctlSetTriggerState triggerstate 18 ConsIoctlGetPDFdata_access pdfdata_access ConsIoctlSetLaserTimeOut lasertimeout 19 ConsIoctlGetTriggerState triggerstate 1A ConsIoctlGetLaserTimeOut lasertimeout
4-45 Series 3000 Application Programmer’s Reference Manual
Keyboard/Scanning IOCTL Structures Tables 4-4 through 4-48 give the IOCTL structures used by the keyboard and scanning IOCTL commands. All structures are defined in URM.H, which is located on the C:\3000\3000 directory in the ADK. Table 4-4. Get/Set Input Mode Command
Subcommand 0 Structure name: inputmode Field Size Parameters Parameter Names inmode byte 0 = Keys-only INMODE_KEYSONLY 1 = Keys and labels INMODE_KEYANDLABELS 2 = Labels-only INMODE_LABELSONLY labeltimeout word Label-only timeout
Table 4-5. Get/Set Scan Mode Command
Subcommand 1 Structure name: scan_mode Field Size Parameters Parameter Names scan_mode byte 0 = No scan mode SCANMODE_NONE 1 = Contact scanner SCANMODE_CONTACT 2 = Laser scanner SCANMODE_LASER 3 = CCD SCANMODE_CCD 4 =Autoselect (default) SCANMODE_AUTO
4-46 DR DOS
Table 4-6. Get/Set Scan State Command [See note below]
Subcommand 2 Structure name: scanstate Field Size Parameters Parameter Names scan_state byte 0 = Off SCANSTATE_OFF 1 = On SCANSTATE_ON scan_process byte 1 = Acquire SCANPROCESS_ACQUIRE 2 = Pulse SCANPROCESS_PULSE 3 = Stop SCANPROCESS_STOP 4 = Time expired (Klasse Eins)
Note: Get/Set Scan State is not available on PDT 35XX-P terminals.
Table 4-7. Set Soft Trigger Command
Subcommand 3 Structure name Field Size Parameters Parameter Names No parameters required
Table 4-8. Get Last Character Read Status Command
Subcommand 3 Structure name: charstatus Field Size Parameters Parameter Names source byte 0 = No character SOURCE_NOCHAR 1 = Contact Wand SOURCE_CONTACT 2 = Laser gun SOURCE_LASER 3 = Keyboard SOURCE_KEYBOARD 4 = Timeout SOURCE_TIMEOUT scancode byte PC scan code
4-47 Series 3000 Application Programmer’s Reference Manual
Table 4-8. Get Last Character Read Status Command (Continued)
Subcommand 3 Structure name: charstatus Field Size Parameters Parameter Names labeltype byte 00h = UPC E0 01h = UPC E1 02h = UPC A 03h = MSI 04h = EAN 8 05h = EAN 13 06h = Codabar 07h = Code 39 08h = Discrete 2 of 5 09h = Interleaved 2 of 5 0Ah = Code 11 0Bh = Code 93 0Ch = Code 128 0x80=system information NR=No Read NG=Data is damaged scandir byte 1 = Forward SCANDIR_FORWARD 2 = Backward SCANDIR_BACKWARD If PDT 35XX-P in PDF mode is used, then Scan Direction is defined as follows: MSB :7:unused MSB 6:unused MSB 5:unused MSB 4:unused MSB 3:unused MSB 2: 1=system information (NR or NG) 0=barcode data MSB 1: 1=not the last data frame 0=last data frame
LSB 0: 1=forward, 0=backward
labellen byte Number of characters in label charpos byte Ordinal number (position of character in label)
4-48 DR DOS
Table 4-9. Get/Set Character Reader Command
Subcommand 4 Structure name: readerchar Field Size Parameters Parameter Names trigger byte Trigger signal FALSE = 0 TRUE = 1 mult_scan byte Autoscan same FALSE = 0 label TRUE = 1 direction byte Direction signal FALSE = 0 TRUE = 1 feedback byte Decode feedback FALSE = 0 TRUE = 1 enable_used byte Wand connector FALSE = 0 enable pin used TRUE = 1
. Table 4-10. Get/Set Reader Parameters Command [See note below]
Subcommand 5 Structure name: readerparms Field Size Parameters enable_set_time word Microsecs of settling time (only if Enable Used is true). power_set_time word Microsecs of power settling time feedback_loglevel byte 0 = Low-level decoder feedback logic 1 = High-level decoder feedback logic white_data_log_level byte 0 = Low-level white data logic 1 = High-level white data logic
Note: Get/Set Reader Parameters is not available on PDT 35XX-P terminals.
4-49 Series 3000 Application Programmer’s Reference Manual
Table 4-11. Get/Set Scan Parameters Command
Subcommand 6 Structure name: scanparms Field Size Parameters Parameter Names beepondecode byte 0 = No beep 0 = FALSE 1 = Beep 1 = TRUE beeptime word Number of millisecs in beep scansperlabel* byte clkspeedtoggle* byte 0 = Not fast 0 = FALSE 1 = Fast mode 1 = TRUE transres* byte System clock/2 4,8,16, labeltermchar* byte Last character of label 0 = none inactivetime* word Number of seconds before timeout quietzoneratio* byte x;1 and 1;x label start and end ratio initscantime* byte Number of seconds in initial scan time pulsedelay* word Number of millisecs in pulse delay subsscantime* byte Number of seconds in subsequent scan time nodatatime* byte Number of seconds
postdecodeact* byte 0 = Pulse ACTION_PULSE 1 = Acquire ACTION_ACQUIRE 2 = Stop ACTION_STOP decodefailact* byte 0 = Pulse ACTION_PULSE 1 = Acquire ACTION_ACQUIRE 2 = Stop ACTION_STOP FeedbackTime byte Number of seconds to wait for feedback BeepFreq word Megahertz in beep
4-50 DR DOS
Table 4-11. Get/Set Scan Parameters Command (Continued)
Subcommand 6 Structure name: scanparms Field Size Parameters Parameter Names TimeUsed* byte Klasse Eins time used
TimeLeft* byte Klasse Eins time left Reserved3 byte Reserved for later use Reserved4 byte Reserved for later use n/a
* Not available if terminal type is PDT35XX-P
Table 4-12. Get/Set Decoder Parameters [See note below]
Subcommand 7 Structure name: decoderparms Field Size Parameters Parameter Names name 16- 16 characters, left-justified, CODABAR byte space filled CODE_11 word CODE_128 CODE_39 CODE_49 CODE_93 CODE_D25 CODE_I25 EAN_13 EAN_8 MSI PDF_417 SUPPS UPC_A UPC_E0 UPC_E1 state byte Disable/Enable decoder 0 = DISABLE 1 = ENABLE minlen byte Minimum label length 0 = No 2-char supps For UPC Supplementals 1 = Decode 2-char supps,
4-51 Series 3000 Application Programmer’s Reference Manual
Table 4-12. Get/Set Decoder Parameters (Continued) [See note below]
Subcommand 7 Structure name: decoderparms Field Size Parameters Parameter Names maxlen byte Maximum label length 0 = No 5-char supps For UPC Supplementals 1 = Decode 5-char supps, Dependent on byte decoder: e0_expand Disable/Enable UPC-E0 0 = DISABLE Expansion 1 = ENABLE e1_expand Disable/Enable UPC-E1 0 = DISABLE Expansion 1 = ENABLE supps_mode No UPC supplementals 0 = NO_SUPPS Only labels with supps 1 = SUPPS_ONLY Labels with/without supps 2 = SUPPS_Y/N full_ascii Convert to full ASCII Code 39 0 = DISABLE 1 = ENABLE chk_digits_11 Disable/Enable check digits 0 = NO_CHKS for Code 11 1 = 1_CHKS 2 = 2_CHKS chk_digits_msi Disable/Enable check digits 1 = 1_CHKS for MSI 2 = 2_CHKS
Note: The Get/Set Decoder Parameters command is not valid if using a PDT35XX-P terminal in the cradle.
Table 4-13. Get Decoder Count Command
Subcommand 8 Structure name: decodercount Field Size Parameters Parameter Names byte Number of decoders in listing
4-52 DR DOS
Table 4-14. Reset Soft Trigger Command
Subcommand 8 Structure name Field Size Parameters Parameter Names No parameters required
Table 4-15. Get Next Decoder Name Command
Subcommand 9 Structure name: decodername Field Size Parameters Parameter Names bytes 1 - 16 Name of next decoder in list
Table 4-16. Get Error Code Command
Subcommand 10 Structure name: Field Size Parameters Parameter Names No parameters required
Table 4-17. Get Reader Type Command
Subcommand 11 Structure name: wandpresent Field Size Parameters Parameter Names byte 0 = Not a contact wand 0 = FALSE 1 = Contact wand 1 = TRUE
The following Read subcommands (12 through 16) and Write subcommands (9 through 13) encompass common variables. Read subcommands 12 through 15 are subsets of Read subcommand 16. Write subcommands 9 through 12 are subsets of Write subcommand 13. The tables (4-18 through 4-23) for these subcommands are shown first; field descriptions and programming examples are provided in the subsection that follows the tables.
4-53 Series 3000 Application Programmer’s Reference Manual
Table 4-18. Get/Set Redundancy Command [See note below]
Field Size Value Subcommand Number Byte GET = 12, SET = 9 Error Code Byte See Error Chart cd25_red_enabled Byte 0 = disabled 1 = enabled ci25_red_enabled Byte 0 = disabled 1 = enabled c39_red_enabled Byte 0 = disabled 1 = enabled cbar_red_enabled Byte 0 = disabled 1 = enabled c128_red_enabled Byte 0 = disabled 1 = enabled c93_red_enabled Byte 0 = disabled 1 = enabled c11_red_enabled Byte 0 = disabled 1 = enabled cmsi_red_enabled Byte 0 = disabled 1 = enabled bidir_redundancy Byte 0 = disabled 1 = enabled
Note: The Get/Set Redundancy command is not valid if using a PDT35XX-P terminal in the cradle.
Table 4-19. Get/Set Checks Command [See note below]
Field Size Value Subcommand Number Byte GET = 13, SET = 10 Error Code Byte See Error Chart code39_chk_b Byte 0 = disabled 1 = enabled c11_chk_dgt Byte 0, 1, or 2 check digits report_c11_chk Byte 0 = disabled 1 = enabled msi_chk_dgt Byte 1 or 2 check digits report_msi_chk Byte 0 = disabled 1 = enabled upc_a_chk_b Byte 0 = disabled 1 = enabled upc_e_chk_b Byte 0 = disabled 1 = enabled upc_e1_chk_b Byte 0 = disabled 1 = enabled
4-54 DR DOS
Note: The Get/Set Checks command is not valid if using a PDT35XX-P terminal in the cradle.
Table 4-20. Get/Set UPC Parameters Command [See note below]
Field Size Value Subcommand Number Byte GET = 14, SET = 11 Error Code Byte See Error Chart upc_a_chk_b Byte 0 = disabled 1 = enabled upc_e_chk_b Byte 0 = disabled 1 = enabled upc_e1_chk_b Byte 0 = disabled 1 = enabled linear_upc_enabled Byte 0 = disabled 1 = enabled no_supp_max Byte 2 <= no_supp_max <= 10 upcean_security_level Byte 0<=upcean_security_level<=3 conv_ean8to13_b Byte 0 = disabled 1 = enabled conv_upce2a_b Byte 0 = disabled 1 = enabled conv_upce1_2a_b Byte 0 = disabled 1 = enabled upca_preamble Byte 0<=upca_preamble<=2 upce_preamble Byte 0<=upce_preamble<=2 upce1_preamble Byte 0<=upce1_preamble<=2 suppl_2 Byte 0 = disabled 1 = enabled suppl_5 Byte 0 = disabled 1 = enabled supps_autod Byte 0<=supps_autod<=2
Note: The Get/Set UPC Parameters command is not valid if using a PDT35XX-P terminal in the cradle.
4-55 Series 3000 Application Programmer’s Reference Manual
Table 4-21. Get/Set Return Format Command [See note below]
Field Size Value Subcommand Number Byte GET = 15, SET = 12 Error Code Byte See Error Chart clsi_editing Byte 0 = disabled 1 = enabled notis_editing Byte 0 = disabled 1 = enabled xmit_code_id_char Byte 0 = disabled 1 = enabled code39_full_ascii Byte 0 = disabled 1 = enabled
Note: The Get/Set Return Format command is not valid if using a PDT35XX-P terminal in the cradle.
Table 4-22. Get/Set All Decoder Parameters Command [See note below]
Field Size Value Subcommand Number Byte GET = 16, SET = 13 Error Code Byte See Error Chart cd25_red_enabled Byte 0 = disabled 1 = enabled ci25_red_enabled Byte 0 = disabled 1 = enabled c39_red_enabled Byte 0 = disabled 1 = enabled cbar_red_enabled Byte 0 = disabled 1 = enabled c128_red_enabled Byte 0 = disabled 1 = enabled c93_red_enabled Byte 0 = disabled 1 = enabled c11_red_enabled Byte 0 = disabled 1 = enabled cmsi_red_enabled Byte 0 = disabled 1 = enabled bidir_redundancy Byte 0 = disabled 1 = enabled code39_chk_b Byte 0 = disabled 1 = enabled c11_chk_dgt Byte 0, 1, or 2 check digits report_c11_chk Byte 0 = disabled 1 = enabled msi_chk_dgt Byte 1 or 2 check digits
4-56 DR DOS
Table 4-22. Get/Set All Decoder Parameters Command [See note below] (Continued) report_msi_chk Byte 0 = disabled 1 = enabled upc_a_chk_b Byte 0 = disabled 1 = enabled upc_e_chk_b Byte 0 = disabled 1 = enabled upc_e1_chk_b Byte 0 = disabled 1 = enabled linear_upc_enabled Byte 0 = disabled 1 = enabled no_supp_max Byte 2 <= no_supp_max <=10 upcean_security_level Byte 0<=upcean_security_level<=3 conv_ean8to13_b Byte 0 = disabled 1 = enabled conv_upce2a_b Byte 0 = disabled 1 = enabled conv_upce1_2a_b Byte 0 = disabled 1 = enabled upca_preamble Byte 0 = disabled 1 = enabled upce_preamble Byte 0 = disabled 1 = enabled upce1_preamble Byte 0 = disabled 1 = enabled suppl_2 Byte 0 = disabled 1 = enabled suppl_5 Byte 0 = disabled 1 = enabled supps_autod Byte 0 <= supps_autod <= 2 clsi_editing Byte 0 = disabled 1 = enabled notis_editing Byte 0 = disabled 1 = enabled xmit_code_id_char Byte 0 = disabled 1 = enabled code39_full_ascii Byte 0 = disabled 1 = enabled
Note: The Get/Set All Decoder Parameters command is not valid if using a PDT35XX-P terminal in the cradle.
4-57 Series 3000 Application Programmer’s Reference Manual
Table 4-23. Get/Set PDF Control Command [See note below]
Field Size Value Subcommand Number Byte GET = 22, SET = 19 Error Code Byte See Error Chart soft_trig_time Byte 0-5 seconds (this value defines the laser- on time for the soft trigger) systeminfo Byte 0=disable 1=enable (When enabled, the scanner driver sends an ‘NR’ message with code type 0x80 if there was no decode with the last trigger pull) pdf_trigger_mode Byte 0=Raster Mode 1=Aiming Mode
Note: The Get/Set PDF Control command is for use only with PDT35XX-P terminals. It is not valid if the terminal is seated in the cradle. Field Descriptions The following are descriptions of fields listed in Tables 4-18 through 4-23:
cd25_red_enabled ci25_red_enabled c39_red_enabled cbar_red_enabled c128_red_enabled c93_red_enabled c11_red_enabled cmsi_red_enabled If the above boolean fields are non-zero, then redundancy is enabled for the associated decoder (in order shown above: i.e, d 2 of 5, i2 of 5, code 39, codabar, code 128 code 93, code 11, msi). If the following field, bidir_redundancy, is zero, then simple redundancy is used. Simple redundancy pertains to laser scanners and requires that the bar code be decoded twice. The decodes must be from two separate laser scans. If
4-58 DR DOS bidir_redundancy is non-zero then the two separate laser scans must be in opposite directions. bidir_redundancy If this boolean field is non-zero, then the simple redundancy above has the added requirement that the two decodes of the bar code must be in opposite laser sweep directions. Bidir_redundancy being TRUE has no effect unless one of the above simple redundancy fields is true. It simply modifies the type of redundancy the above fields represent. code39_chk_b Some Code 39 bar codes contain a check digit character. If code39_chk_b is non-zero, then the decoder will require that the check digit be present and correct. If it is zero then the check digit character (or the character in the check digit position) is simply sent to the application with the other data characters. c11_chk_dgt Code 11 may have zero, one, or two check digits. Values other then these will cause unpredictable operation. The number of check digits verified (the last character is considered the first check digit and the next-to-last character the second check digit) is c11_chk_dgt. Do not include the number of check digits in the Code 11 length specification even if they are to be reported back to the application. report_c11_chk If it is desired to have the check digit(s) returned to the application, then this field is set to a non-zero value. If it is zero, the check digits are not reported. This field has no effect on the length specification. Only data characters should be accounted for in the length specification, not check digits. msi_chk_dgt MSI Code may have one, or two check digits. Values other than these will cause unpredictable operation (if zero the decoder defaults to one check digit). The number of check digits verified (the last character is considered the first check digit and the next-to-last character the second
4-59 Series 3000 Application Programmer’s Reference Manual
check digit) is msi_chk_dgt. Do not include the number of check digits in the MSI length specification even if they are to be reported back to the application.
report_msi_chk If it is desired to have the check digit(s) returned to the application then this field is set to a non-zero value. If it is zero, the check digits are not reported. This field has no effect on the length specification. Only data characters should be accounted for in the length specification, not check digits.
upc_a_chk_b upc_e_chk_b upc_e1_chk_b If the above fields are true then the check digit is reported to the application. The check digit is always verified for UPC. This simply determines whether it is reported.
linear_upc_enabled UPC labels can be divided into left and right blocks (manufacturer and item numbers). The UPC decoder has the capability to take a block from a partially decoded UPC label and combine it with a block decoded in an earlier scan (providing it matches in type and the check digit test passes) to create a decoded label. This increases the aggressiveness of the decoder. It does not usually cause a problem unless there are multiple labels in the laser field that may have potentially interchangeable blocks. If this is the case, the decoder can be forced to require that all of a labels’ blocks are decoded in the same sweep. If linear_upc_enabled is TRUE (non-zero) then the UPC blocks must be decoded this way. If it is zero, the decoder can decode the blocks in separate scans.
no_supp_max UPC labels sometimes have small bar codes called supplementals appended to the end of them. The UPC decoder can be configured to recognize the presence or absence of these supplementals and report them. If labels with and without supplementals are being returned to
4-60 DR DOS the application, then the supplemental auto discrimination mode is active. No_supp_max determines how many times the decoder will attempt to decode the UPC label before it is satisfied there are no supplementals. Range is from 2 to 10. upcean_security_level This parameter aids in decoding poor labels by preventing against misdecodes. The variable determines how stringent the decode algorithm used for UPC and EAN bar codes is. The higher the level, the more stringent, but the less aggressive the decoder is. The lower the level the less stringent but the more aggressive the decoding. A higher security level provides greater insurance against misdecodes. conv_ean8to13_b If this field is non-zero then EAN8 will be zero padded to 13 characters. This is useful when reading both EAN13 labels and EAN8 labels and the input field is fixed at 13 characters. conv_upce2a_b UPC E0 labels are zero-suppressed UPCA labels. If a UPCA label contains enough zeros then it can be condensed to a 6 character UPC label. If conv_upce2a_b is non-zero then UPC E0 labels will be expanded from 6 characters to the equivalent 12 character UPCA label. The label type indicator will also change to UPCA. conv_upce1_2a_b UPC E1 labels are derived in the same way as UPC E0 labels. The only difference is the parity pattern of the UPC characters in the label. UPC E1 is non-standard and is only used in custom applications. If this variable is non-zero then the UPC E1 labels will be expanded from 6 characters to the equivalent 12 character UPCA label. The label type indicator will also change to UPCA.
4-61 Series 3000 Application Programmer’s Reference Manual
upca_preamble upce_preamble upce1_preamble EAN13 labels have a number system and country code associated with them. UPC has no country code, but it is number system zero. If both UPC and EAN bar codes are being scanned, it may be desirable to have a UPC number system character, along with a place holder for the country code, prefix a decoded UPC label. These two characters are always reported for EAN labels. This allows compatibility with EAN input fields. If the preamble field (upca_preamble, upce_preamble or upce1_preamble) is zero, then no characters will prefix the label data. If it is one, then the number system character for the code type will prefix the data (a one for upce1 because its number system is 1, zero for all other UPC types). If it is 2, then a zero will prefix the number system character and the label data as a place holder for the country code.
suppl_2 If this value is non-zero then supplemental UPC bar codes of length 2 may be decoded if the supplemental decoding mode (supps_autod) is non-zero.
suppl_5 If this value is non-zero then supplemental UPC bar codes of length 5 may be decoded if the supplemental decoding mode (supps_autod) is non-zero.
supps_autod This field indicates the method of handling supplemental bar codes. If it is zero, supplemental bar codes are ignored. If it is one, then the UPC label must have a supplemental attached. The supplemental must match the enabled lengths. For instance, if suppl_2 and suppl_5 are TRUE then either a length 2 or length 5 supplemental bar code must be present. If suppl_5 is TRUE and suppl_2 is FALSE, then only bar codes with a length 5 supplemental are valid. If supps_autod is 2 then the decoder is in the auto discriminate mode. This means that if the decoder determines that there is a supplemental of any length, it is reported. Suppl_2 and suppl_5 have no effect in this mode.
4-62 DR DOS clsi_editing This function is used to change a 14-character codabar symbol (not including stop/start chars) into a special format. In this format, the start and stop chars are removed and spaces are added after the first, fifth and tenth digits. For example, the symbol “a12345678901234” is changed into “1 2345 67890 1234". notis_editing This function is used to remove the start and stop characters from the codabar symbol. xmit_code_id_char If this value is non-zero, then depending on the code type, one of the following ASCII characters prefixes the data characters returned to the application:
'A' UPC,UPCE,UPCE1,EAN13,EAN8 'B' Code 39 'C' Codabar 'D' Code 128 'E' Code 93 'F'' I 2 of 5 'G' D 2 of 5 'G' IATA 'H' Code 11 'J' MSI code39_full_ascii Full ASCII is a feature of Code 39 that allows full representation of the ASCII character set by combining certain pairs of Code 39 characters. When this option is active, characters that are not in the standard Code 39 set are created by TWO standard Code 39 characters being encoded in the label. In Full ASCII mode, only the character represented by this combination is returned. If Full ASCII is not selected, and the labels that are being used contain Full ASCII representations, then the two
4-63 Series 3000 Application Programmer’s Reference Manual
character combinations will be returned to the application instead. If this value is non-zero, FULL ASCII is selected.
Table 4-24. Get/Set PDF Decoder Parameters Command
Field Size Value
Subcommand byte GET = 17, SET = 14 Number
Error Code byte See error chart
mode byte 0 = PDF_MODE_1D 1 =PDF_MODE_1
scandir byte 1 = SCANDIR_FORWARD 2 = SCANDIR_BACKWARD
reader byte 1 = SOURCE_CONTACT 2 = SOURCE_LASER
datamode byte 0 = PDF_MODE_CONTIGUOUS 1 = PDF_MODE_SEPARATOR 2 = PDF_MODE_TEMPLATE
4-64 DR DOS
The following are definitions of fields listed in Table 4-24:
mode Current mode of the PDF decoders 0 = PDF off 1-D scanning with standard scanners allowed 1 = PDF mode 1 - 2-D & 1-D scanning with PDF 1000 scanner data is passed on to application based on current datamode scandir Scan direction value that is to be reported to application reader Reader type that is to be reported to application datamode Data mode for PDF mode 1
Table 4-25. Get/Set PDF Communications Parameters Command [See note below]
Field Size Value
Subcommand byte GET = 18, SET = 15 Number
Error Code byte See error chart
baud byte 1 = BAUD300 2 = BAUD600 3 = BAUD1200 5 = BAUD2400 6 = BAUD4800
data_bits byte 2 = DATABITS7 3 = DATABITS8
parity byte 0 = PARITYEVEN 1 = PARITYODD 4 = PARITYNONE
stop_bits byte 0 = STOPBITS1 1 = STOPBITS2
4-65 Series 3000 Application Programmer’s Reference Manual
Note: The Get/Set PDF Communications Parameters command is not available on PDT 35XX-P terminals.
The following are definitions of fields listed in Table 4-25: baud Baud rate for communications with PDF 1000 scanner data_bits Data bits for communications with PDF 1000 scanner parity Parity for communications with PDF 1000 scanner stop_bits Stop bits for communications with PDF 1000 scanner
Table 4-26. Get/Set PDF Contiguous Data Mode Parameters Command
Field Size Value
Subcommand byte GET = 19, SET = 16 Number
Error Code byte See error chart
labeltype byte 00h = UPC E0 01h = UPC E1 02h = UPC A 03h = MSI 04h = EAN 8 05h = EAN 13 06h = Codabar 07h = Code 39 08h = Discrete 2 of 5 09h = Interleaved 2 0f 5 0Ah = Code 11 0Bh = Code 93 0Ch = Code 128 0Dh = PDF 417
blocksize byte 1 to 251
terminate char 0 to 255 ASCII value
4-66 DR DOS
The following are definitions of fields listed in Table 4-26: labeltype Returned label type value for PDF decoded data. blocksize Size of PDF decoded data blocks that are to be returned. terminate Terminator character to signify the last PDF data block. This is sent as bar code of length 1.
Table 4-27. Get/Set PDF Separator Data Mode Parameters Command
Field Size Value
Subcommand byte GET = 20, SET = 17 Number
Error Code byte See error chart
labeltype byte 00h = UPC E0 01h = UPC E1 02h = UPC A 03h = MSI 04h = EAN 8 05h = EAN 13 06h = Codaabar 07h = Code 39 08h = Discrete 2 of 5 09h = Interleaved 2 0f 5 0Ah = Code 11 0Bh = Code 93 0Ch = Code 128 0Dh = PDF 417
blocksize byte 1 to 251
sepchar char 0 to 255 ASCII value
4-67 Series 3000 Application Programmer’s Reference Manual
The following are definitions of fields listed in Table 4-27:
labeltype Returned label type value for PDF decoded data. blocksize Maximum size of PDF decoded separator blocks. If data that is terminated by sepchar is larger than blocksize, it is broken up into data blocks with maximum length blocksize. sepchar Data separator character to signify the end of the current data block.
Table 4-28. Get/Set PDF Template Data Mode Parameters Command
Field Size Value
Subcommand byte GET = 21, SET = 18 Number
Error Code byte See error chart
active_template byte 0 = default_template 1 = template1 2 = template2 3 = template3 4 = template4 5 = template5
auto_detect byte 0 = Auto detection disabled 1 = Auto detection enabled
d_last_entry byte 0 to 255
t1_last_entry byte 0 to 255
t2_last_entry byte 0 to 255
t3_last_entry byte 0 to 255
t4_last_entry byte 0 to 255
4-68 DR DOS
Table 4-28. Get/Set PDF Template Data Mode Parameters Command (Continued)
t5_last_entry byte 0 to 255
*default_template byte far double word address
*template1 byte far double word address
*template2 byte far double word address
*template3 byte far double word address
*template4 byte far double word address
*template5 byte far double word address
The following are definitions of fields listed in Table 4-28: active_template Index of current active template that is to be used if auto_detect of templates is disabled. auto_detect Auto detection of template flag. d_last_entry Index of last entry in template pointed to by default_template. t1_last_entry Index of last entry in template pointed to by template1. t2_last_entry Index of last entry in template pointed to by template2. t3_last_entry Index of last entry in template pointed to by template3. t4_last_entry Index of last entry in template pointed to by template4. t5_last_entry Index of last entry in template pointed to by template5. *default_template Far pointer to default template. *template1 Far pointer to template 1.
4-69 Series 3000 Application Programmer’s Reference Manual
*template2 Far pointer to template 2.
*template3 Far pointer to template 3.
*template4 Far pointer to template 4.
*template5 Far pointer to template 5.
Table 4-29. Get/Set PDF Data Access Mode Command
Field Size Value Subcommand Byte GET = 24, SET = 20 Number Error Code Byte Access_type Word 0 = Get the data from keyboard queue (old style). In this case, the content of data_buffer and buffer_size are ignored. 1 = Get the data direct from decoder and the data is placed in iob.data.PDTdata_access.data_buffer and the sizer is in iob.data.PDFdata_access.data_buffer. The data is flushed out when there is a new trigger pull. In this case, data_buffer and buffer_size must be initialized. 2 = This is the same as 1, except the data is retained in the buffer until the function ConsIoctlResetPDFdata_status is called or the system is closed. In this case, data_buffer and buffer_size must be initialized. Buffer_size Word The size of data_buffer.
4-70 DR DOS
Table 4-29. Get/Set PDF Data Access Mode Command
Field Size Value Data_buffer Char far * Data_buffer is the buffer that the PDF data will be placed in. The size of data_buffer must be greater than or equal to the size of the biggest bar code in the application. If the size of data_buffer is smaller than the bar code, the error status = 3 is returned (see ConsIoctlGetPDFdata_status).
Note: ThGet/Set PDF Data Access Mode command is only available on the PDT35XX-P terminal. The PDF data process modes Contiguous, Terminator, and Separator are not supported when access_type = 1 or 2.
Table 4-30. Get/Reset PDF Data Status Command
Field Size Value Subcommand Number Byte GET = 23, SET = 21 Error Code Byte labeltype Word Returns label type value for PDF decoded data. blocksize Word The size of the decoded data. status Word 0 = No data 1 = Data is coming 2 = Data is ready 3 = Data size is larger than the data_buffer.
When access_type = 2 and status = 2, the data is kept in the buffer until the function ConsIoctlResetPDFdata_status is called.
Note: ThGet/Reset PDF Data Status command is only available on PDT35XX-P terminals with scan3500 V2.00-10 or later.
4-71 Series 3000 Application Programmer’s Reference Manual
Table 4-31. Get/Set PDF Trigger State Command
Field Size Value Subcommand Byte GET = 25, SET = 23 Number Error Code Byte Scan_ahead Byte 0 = laser cannot be fired. 1 = laser can be fired (default) Reserved5 Byte
Note: The Get/Set PDF Trigger State Command is only available in PDT35XX-P terminals with scan3500 V2.00- 10 or later.
Table 4-32. Get/Set Laset Time Out Command
Field Size Value Subcommand Byte GET = 26, SET = 24 Number Error Code Byte Lasertimeout Word Change the no decode laser on time. The valid range is between 500 to 10000 ms. The default is 3000 ms. Reserved6 Byte
Note: The Get/Set Laser Time Out command is only available in PDT68XX terminals with scan3000 V3.05 or later.
4-72 DR DOS
Communications IOCTL Commands and Structures Communications IOCTL Commands Table 4-33 lists the communications IOCTL commands. Table 4-33. Communications IOCTL Commands
Command Command Name IOCTL Structure(s) Number 00 ComIoctlComParamCmd comparameters 01 ComIoctlMdmStatCmd modemstatus 02 ComIoctlLineStatCmd linestatus 20 ComIoctlProtoCntCmd protocolcnt 21 ComIoctlNextProtoCmd protocol 22 ComIoctlSelectProtCmd selectprotocol 23 ComIoctlProtoParamCmd twoway_parms spect1_parms slp_parms 24 ComIoctlGetStatistics spect1_stats slp_stats 30 ComIoctlOpenLine No structure 31 ComIoctlCloseLine No structure 40 ComIoctlStartProtocol No structure 41 ComIoctlSetHdrTrlr hdrtrlr 42 ComIoctlSendEnd No structure 43 ComIoctlCloseProtocol No structure 44 ComIoctlAbortProtocol No structure 45 ComIoctlGetWrStatus No structure 46 ComIoctlGetRdStatus hdrtrlr 50 ComIoctlOutputQStatus qstat 51 ComIoctlFlushOutputQ No structure 52 ComIoctlInputQStatus qstat 53 ComIoctlFlushInputQ No structure 90 ComIoctlS1Status s1_status 91 ComIoctlS1Timeout s1_timeout
4-73 Series 3000 Application Programmer’s Reference Manual
Table 4-33. Communications IOCTL Commands (Continued)
Command Command Name IOCTL Structure(s) Number 92 ComIoctlS1Unsolicited s1_unsolicited
Communications IOCTL Structures Tables 4-34 through 4-40 give the IOCTL structures used by each keyboard command: Table 4-34. comparameters Structure
Subcommand 0 Structure name: comparameters Get/Set Serial Port Interrupt A5, Function 80 Parameters Field Size Parameters Parameter Names Passed/Returned baudrate byte 0 = 150 bps BAUD150 1 = 300 BAUD300 2 = 600 BAUD600 3 = 1200 BAUD1200 4 = 1350 BAUD1350 5 = 2400 BAUD2400 6 = 4800 BAUD4800 7 = 9600 BAUD9600 8 = 19200 BAUD19200 9 = 38400 BAUD38400 databits byte 2 = 7 DATABITS7 3 = 8 DATABITS8 parity byte 0 = Even PARITYEVEN 1 = Odd PARITYODD 3 = Space PARITYSPACE 4 = None PARITYNONE stopbits byte 0 = 1 Bits STOPBITS1 1 = 2 STOPBITS2 duplex byte 0= Full-Duplex DUPLEXFULL 1=Half-Duplex DUPLEXHALF 2=Multi-Access See the Extended Serial I/O Services section in the ROM BIOS chapter of the Series 3000 System Software Manual for more information on the duplex control parameters.
4-74 DR DOS
Table 4-34. comparameters Structure (Continued)
Subcommand 0 Structure name: comparameters Get/Set Serial Port Interrupt A5, Function 80 Parameters Field Size Parameters Parameter Names Passed/Returned modemdelay word Delay in milliseconds between the raising of RTS and the start of transmission txcarrierwait word Transmit carrier wait time in milliseconds. If high order bit set, error occurs if the time specified elapses, else transmit proceeds once time elapses. rxcarrierwait word Receive carrier wait time in milliseconds. If high order bit set, error occurs if the time specified elapses. carrierlossdetect word Carrier loss detect time in milliseconds ctlstopchar byte Used in software flow control mode. This character is sent when the receive queue reaches 80% of its capacity. If received, transmit is disabled until a control start character is received. If used, all control stop characters are filtered from the received data. ctlstartchar byte Used in software flow control mode. This character is sent, if a control stop character was sent, when the receive queue drops to 60% of its capacity. If received after a previous contsrol stop, transmit is re-enabled. If used, all control start characters are filtered from the received data. ctlstartwait byte Time in seconds before reporting an error whenever a control stop character is received and a control start character isn't subsequently received. ctslossdetect byte Time, in seconds, that the BIOS waits for CTS to go active before reporting a timeout error. Used only if linecondflags = 4 (CTSCOND). If = 0, then waits forever (use with caution).
4-75 Series 3000 Application Programmer’s Reference Manual
Table 4-34. comparameters Structure (Continued)
Subcommand 0 Structure name: comparameters Get/Set Serial Port Interrupt A5, Function 80 Parameters Field Size Parameters Parameter Names Passed/Returned linecondflags byte 1 = DSR DSRCOND 2 = CD CDCOND 4 = CTS CTSCOND
More than one value If CTSCOND is set, will wait can be supplied by ctslossdetect seconds before error adding these together, if CTS is lost. i.e.: DRSCOND+ CTSCOND flowctl byte 0 = None NOFLOWCTL 1 = Software SOFTWAREFLOWCTL 2 = Hardware HARDWAREFLOWCTL errmask byte 1 = Overrun 2 = Parity 4 = Framing 8 = Break Detect
More than one value can be supplied by adding these together errinsch byte Error Insertion Character dtrsettle byte DTR Settling Time connectwait byte Connect Time
4-76 DR DOS
Table 4-35. modemstatus Structure
Subcommand 1 Structure name: modemstatus Get Modem Status Field Size Parameters Parameter Names Passed/Returned CTS byte 0 = CTS Off FALSE 1 = CTS On TRUE DSR byte 0 = DSR Off FALSE 1 = DSR On TRUE RI byte 0 = RI Off FALSE 1 = RI On TRUE CD byte 0 = CD Off FALSE 1 = CD On TRUE
Table 4-36. linestatus Structure
Subcommand 2 Structure name: linestatus Get Line Status Field Size Parameters Parameter Names Passed/Returned overrun_err byte 0 = No Error FALSE 1 = Overrun Error TRUE parity_err byte 0 = No Error FALSE 1 = Parity Error TRUE framing_err byte 0 = No Error FALSE 1 = Framing Error TRUE break_err byte 0 = No Error FALSE 1 = Break Error TRUE Note: the appropriate bits must be set in the errmask field in the comparameters structure before these errors become effective. See Get/Set Serial Port Parameters.
4-77 Series 3000 Application Programmer’s Reference Manual
Table 4-37. protocolcnt Structure
Subcommand 20h Structure name: protocolcnt Get Attached Protocol Count Size Parameters Passed/Returned byte Number of protocols currently attached to the Comm Driver
Table 4-38. protocol Structure
Subcommand 21h Structure name: protocol Get Next Attached Protocol Entry Field Size Parameters Passed/Returned id word ID Number name 8 bytes Protocol Name Use subcommand 20h to get the number of attached protocols. Then use subcommand 21h to get the ID number of all protocols installed in the terminal.
Table 4-39. selectprotocol Structure
Subcommand 22h Structure name: selectprotocol Get/Select Protocol Field Size Parameters Parameter Names Passed/Returned Protocol ID word 0x0030 MSISTD 0X0031 TWOWAY 0X0037 MAPLP 0X0038 SLP 0X0039 SPECTRUM1 0X003F MSIMDM More protocols may be added at a later date.
4-78 DR DOS
Table 4-40. twoway_parms Structure
Subcommand 23h Structure name: twoway_parms Get/Set Protocol Parameters Field Size Parameters Passed/Returned max_wak_cnt byte Maximum number of Wait after positive ACKnowledgement (WACK) signals the sending station will accept before aborting the comm session. Default = 0 (indefinite) max_nak_cnt byte Maximum number of Negative ACKnowledgement (NACK) signals the sending station will accept before aborting the comm session. Default = 7 (0 = indefinite) max_ttd_cnt byte Maximum number of Temporary Text Delay (TTD) signals the receiving station will accept before aborting the comm session. Default = 0 (indefinite) max_enq_cnt byte Maximum number of ENQiry (ENQ) signals the sending station will transmit 1) when attempting to establish a comm session, or 2) when making a request for last positive reply. Default = 10 wak_ttd_time word Maximum time the receiving station will wait before sending a WACK, or the maximum time a sending station will wait before sending a TTD. Default = 2 seconds enq_time word Maximum time, in milliseconds, sending station will wait for a response after sending an ENQ, before retrying. Default = 3 seconds no_data_time word Maximum time, in milliseconds, receiving station will wait for data (BID) before timing out. Default = 20 seconds
4-79 Series 3000 Application Programmer’s Reference Manual
Table 4-41. spect1_parms Structure
Subcommand 23h Structure name: spect1_parms Get/Select Protocol Parameters Field Size Parameters Passed/Returned config_status byte Configuration valid flag (read only) (1=valid) handle_number word Current unit ID number (read only) active_freq byte Current active radio channel (read only) cnctd_2_base byte Current status of remote to base connection (read only) transporter byte Current status of the transporter (read only) time_out word Current DAS command timeout delay, in seconds unslctd_msgs byte Unsolicited message exchange rate (1 = fast)
Table 4-42. slp_parms Structure
Subcommand 23h Structure name: slp_parms Get/Select Protocol Parameters Field Size Parameters Passed/Requested link_layer_proto word Link layer Protocol ID# mode byte Session Direction 0 = Alternating (transmit) 1 = Simultaneous 2 = Alternating (receive) reserved 1 word reserved 2 word
4-80 DR DOS
Table 4-43. spect1_stats Structure
Subcommand 24h Structure name: spect1_stats Get Spectrum1 Statistics Field Size Parameters Passed/Returned byte_count_in ulong Number of data bytes received packet_count_in word Number of data packets received message_count_in word Number of datagrams received byte_count_out ulong Number of datagrams transmitted packet_count_out word Number of data packets transmitted message_count_out word Number of datagrams transmitted naks_recvd word Number of NAKs received by remote naks_sent word Number of NAKs sent by remote packet_retrys word Number of packet retransmissions bad_packets word Number of undecodable packets bad_checksums word Number of bad checksums bad_unit_ids word Number of packets with wrong handles bad_hdr_scans word Number of complete (header scan) fails good_exchanges word Number of good exchanges since IOCTL 44
4-81 Series 3000 Application Programmer’s Reference Manual
Table 4-44. slp_stats Structure
Subcommand 24h Structure name: slp_stats Get Statistics Field Size Parameters Passed/Returned tx_cnt long Total number of transmit chars tx_blk_cnt word Total number of transmit blocks tx_hb_count word Total number of header blocks sent tx_db_count word Total number of data blocks sent tx_lb_count word Total number of last blocks sent tx_hlb_cnt word Total number of header/last blocks rx_cnt long Total number of received chars rx_blk_count word Total number of received blocks rx_hb_count word Total number of header blocks rcvd rx_db_count word Total number of data blocks rcvd rx_lb_count word Total number of last blocks rcvd rx_hlb_cnt word Total number of header/last blocks
Table 4-45. hdrtrlr Structure
Subcommands 41, 46h Structure name: hdrtrlr Set Header/Trailer Get Read Status Field Size Parameters Passed/Returned header byte Header record flag trailer byte Trailer record flag
4-82 DR DOS
Table 4-46. qstat Structure
Subcommands 50, 52h Structure name: qstat Get Output Queue Status Get Input Queue Status Field Size Parameters Passed/Returned charsinq word Number of queued characters spaceleft word Space left in queue
Table 4-47. s1_status Structure
Subcommand 90h Structure name: s1_status Get Spectrum1 Status Field Size Parameters Passed/Returned Config_status byte Configuration valid flag (read only) (1 = valid) handle_number word Current unit ID number (read only) active_freq byte Current active radio channel (read only) cnctd_2_base byte Current status of remote to base connection (read only) transponder byte Current state of the transporter (read only) status byte Background status flag (TRUE, FALSE)
4-83 Series 3000 Application Programmer’s Reference Manual
Table 4-48. s1_timeout Structure
Subcommand 91h Structure name: s1_timeout Set S1 Timeout Field Size Parameters Passed/Returned set_timeout byte Time the protocol driver waits for the Read, Write, Send End, Start Protocol, and Select Control Packet IOCTL functions to complete before aborting with error.
Table 4-49. s1_unsolicited Structure
Subcommand 92h Structure name: s1_unsolicited Set Unsolicited Messages Flag Field Size Parameters Passed/Returned set_unsolictited byte Unsolicited message receive rate
4-84 Chapter 5 UBASIC Record Manager
Chapter Contents Introduction ...... 5-3 Basic URM Capabilities...... 5-3 Interface from Various Languages ...... 5-5 Interface from Microsoft C ...... 5-5 Loading the URM...... 5-8 UBASIC File Manager ...... 5-9 Interfacing with Low-Level Features ...... 5-10 Memory Manager ...... 5-11 UBASIC Variables ...... 5-12 URM Function Descriptions...... 5-13 blk_alloc...... 5-14 blk_delete ...... 5-15 blk_free ...... 5-16 blk_insert...... 5-17 blk_search ...... 5-18 blk_traverse...... 5-19 mclose ...... 5-20 mcreate ...... 5-21 mcrunch...... 5-23 mdelete ...... 5-24 merase ...... 5-25 mfree ...... 5-26 minit...... 5-27 minput ...... 5-28 minsert...... 5-29 mopen ...... 5-30 mprint ...... 5-31 msearch ...... 5-32 mterminate ...... 5-34 UrmOpen ...... 5-35 UrmReadField ...... 5-37 UrmWriteField ...... 5-39 UrmClose ...... 5-41
5-1 Series 3000 Application Programmer’s Reference Manual
UrmPresent ...... 5-42 URM Structure Definitions...... 5-43 File Control Block (FCB) ...... 5-43 Device Name Translation Table (XlatPtrT) ...... 5-47 Separator Character Structure ...... 5-50 Modem Control Structure...... 5-55 URM Pointer Structure (UrmPtrT) ...... 5-61 FMGR Data Block Link ...... 5-69 File Information Block...... 5-69 File Directory Block ...... 5-70 DOS File Directory...... 5-72 Bios Parameter Block...... 5-72 DOS FAT Entries ...... 5-73 Free Block ...... 5-74 Segment Table Entry ...... 5-74 RAM Disk Driver Parameter Block ...... 5-75 File Manager First Data Segment ...... 5-76 Header of Cluster Variant Files ...... 5-77 Block Traverse Return Parameter Block ...... 5-78 File Manager Work Buffer ...... 5-78 MCREATE Parameter Blocks...... 5-82 URM Global Prototypes ...... 5-83 Error Codes (Record Manager/File Manager) ...... 5-85
5-2 UBASIC Record Manager
Introduction The UBASIC Record Manager (URM), File Manager, and Memory Manager form a file I/O system providing access to UBASIC data files using the Microsoft Visual C++ calling convention.
The URM is a file system that provides a consistent access interface to files and devices for record input and output. The URM handles the logical blocking and unblocking of records for block-oriented devices and the prefix and postfix characters often used for stream-oriented devices. Regardless of the type of device in use, URM handles transfers in units called records and fields.
The File Manager provides access methods for storing fixed length and variable length records and for retrieving them as a linked list or as a cluster. Applications may build on these facilities, adding the semantics of data base management.
The Memory Manager consists of the interface routines between the File Manager and the RAM Disk Driver. All of the Memory Manager functions are block-oriented, which means they either require a block pointer as the input or return a block pointer as output.
The UBASIC language, which is the native programming language on Symbol Technologies 8-bit terminals, makes extensive use of the UBASIC Record Manager, even though it is transparent to the programmer. The URM, File Manager and Record Manager are provided primarily for purposes of porting applications to the 16-bit, DOS based, Series 3000 terminals. The URM can be used transparently from UBASIC or as a full featured C interface package. When used for porting applications, the managers must be used in conjunction with the UBASIC Bridging Kit. Basic URM Capabilities Although the primary purpose of the URM is to provide file access capabilities to the UBASIC Plus interpreter for the 3000 Series 16-bit terminal, the URM also comprises a complete file access package usable by a C language program to perform device or file independent record I/O. The URM allows access to logical devices such as COM1 and LPT1, as well as to files. Files may be accessed via the DOS file system or the UBASIC Plus file system.
5-3 Series 3000 Application Programmer’s Reference Manual
It must be understood that the URM is not a stand-alone package, but rather relies heavily on the DOS file management system and/or on the UBASIC Plus file manager package. The URM may be configured to support only DOS files or only UBASIC Plus file manager files as circumstances may later require.
The URM consists of the following functions which are generally available for all files and devices:
• Open a file or device • Read a field from an open file or device • Write a field to an open file or device • Close an open file or device The URM also supports some functions whose purpose is to allow access to operations available only for File Manager files:
• Insert a record to a file • Delete a record from a file • Mark a file for deletion • Search a file for a specified search pattern • Initialize
5-4 UBASIC Record Manager
Interface from Various Languages When calling URM functions directly from a user application, the language being used will have an impact on the ease of use. The simplest way to access these functions is to use the Microsoft Visual C++ Optimizing Compiler. Using Microsoft Visual C++, simply include the supplied header file (URM.H) which provides all the necessary declarations for calling these functions.
When using a language other than Microsoft C or Visual C++, you must provide your own declarations to the compiler to describe the calling conventions. In such cases, refer to URM.H as a model for the calling conventions used. For example, when using Microsoft Pascal, you can use the EXTERN FAR C declaration to inform the Pascal compiler that the C parameter passing method is to be used. The definitions of the structures, pointers, etc., defined in URM.H must also be translated, though this is normally quite straightforward.
Note that all structures are packed to be byte-aligned, which may require a special indication to some compilers. For Microsoft C and Visual C++, this can be accomplished using the /Zp switch on the command line or by using the #pragma pack(1) instruction in the source code.
Also, note that all strings passed to URM functions are null-terminated in the C fashion, rather than length prefixed as used by Pascal and other languages. Interface from Microsoft C This section discusses details regarding the use of the URM functions from Microsoft C and Visual C++. Memory Model All URM functions were compiled using the Microsoft C and Visual C++ LARGE memory model. This means that all pointers are FAR and all functions are FAR. The URM.H file explicitly declares all functions and parameters accordingly. This means that an application program of any model up to LARGE can use the URM. Programs of model HUGE can be used only if all variables to be used as parameters to URM are explicitly declared as FAR in the application program.
5-5 Series 3000 Application Programmer’s Reference Manual
When a model other than LARGE is used for the application program, Microsoft C and Visual C++ will automatically convert any NEAR pointers to FAR pointers when making calls to URM functions. Pointers vs. Values You will note that some of the parameters passed to URM are passed as pointers and some are passed by value. There are some basic rules governing the passing of parameters which should be understood:
1. All string parameters are passed as pointers (standard C language method). 2. All structure parameters are passed as pointers (standard C does not allow structures to be passed by value, even though Microsoft C and Visual C++ do). 3. All parameters which are output parameters (i.e. are modified by the function) or are both input and output parameters are passed as pointers (since parameters passed by value cannot be modified in the C language). 4. Except in the special circumstances described in rule 5, below, all parameters which are strictly input parameters, are passed by value. 5. Where two functions have parameter lists which are nearly the same, a special rule may apply. 6. If the difference between two functions lies in one function having a parameter passed as a pointer (since it is an output parameter) and the other function having the parameter passed by value (since it is strictly an input parameter), the functions will both pass that parameter by pointer to make the application program's use of these functions consistent. Structure Pointers and Initialization When passing pointers to structures to URM functions some precautions must be followed:
1. All structures should be declared as instances rather than as pointers. For example, choose the declaration: FCBT myfcb; /* Correct */
rather than either of the declarations:
5-6 UBASIC Record Manager
FCBP myfcb; /*Incorrect */
or
FCBT *myfcb; /* Also Incorrect */
The instance declaration defines space for the structure, whereas the pointer declarations simply define space for a pointer to a structure of that type.
When passing structures to URM functions, the “address of” operator (&) should be used. For example:
UrmErase(&myfcb,&urmrec);
1. All structures passed as parameters to URM functions should be initialized by the caller BEFORE the call to the URM function is made unless the purpose of the call is to initialize the structure (e.g., UrmOpen initializes the FCB whose pointer is passed). For initializing structures defined with AUTO storage class (i.e., inside functions and not explicitly declared STATIC), explicit assignment statements should be used to assign values to the fields of the structures or initialization functions such as memset should be used to initialize the structures.
For initializing structures defined with STATIC storage class (i.e., outside of functions or with explicit STATIC declaration), the standard C structure initializer format may be used as part of the structure declaration.
2. Beware of “lost” structures when using AUTO storage class. If a structure, such as an FCB is declared with AUTO storage class and then a file is opened using that FCB (via UrmOpen), the information stored in the FCB is important until the file is closed (via UrmClose).
If the function which declared the FCB using AUTO storage class should terminate after a call to UrmOpen, but before a call to UrmClose, then the information in the FCB is lost (since it is on the stack) and further access to that file is not possible.
5-7 Series 3000 Application Programmer’s Reference Manual
Passing Structures to Functions If you pass a pointer to a structure to a Symbol library function, that structure must be packed.
If you pass a pointer to an unpacked structure, the library function will access data in the structure incorrectly.
Therefore: all structures passed to a Symbol library function must be packed.
You must pack structure members with the /Zp compiler option or with the pack pragma. For example:
cl /AL /Zp sample.c
or
#pragma pack(1)
Refer to the Microsoft Optimizing Compiler for details on packing structures on 1-byte boundaries. Stack Space Many of the functions in the URM library (and in other subsidiary packages such as the UBASIC Plus file manager or DOS) rely on being able to push substantial amounts of data onto the application stack when they are called. This makes the standard 2K of stack space allocated by the C runtime library inadequate. An application program which intends to use URM functions should plan on allocating at least 8K worth of stack. This is done using the /STACK:nnn switch to the Microsoft LINK utility. Loading the URM There are two ways to link the URM to an application:
• link the URM functions with your application • link only interface routines and load the URM functions as a resident library. For many applications, the easiest way to use the URM functions is to include the URM.H file in the C source code and link the URM.LIB library with the application. This provides everything necessary to access the URM functions.
5-8 UBASIC Record Manager
An alternative is to use the URM as a resident library. This allows you to link small interface routines that call the URM resident library. This method keeps the size of your application small and allows several applications to share a single copy of the URM library. To do this, include URMRES.H in the source instead of URM.H and load the URM libraries resident.
The URM package may be made resident either in NVM using the User Configuration Tool or in RAM via a TSR version of the URM package. In either case, the functions of the URM package become available as soon as the package is made resident. UBASIC File Manager For every application that requests its services, the File Manager creates a read- only DOS file named UBASIC.FMG to store control information for its own use. There is at least one cluster assigned to UBASIC in the DOS FAT. All spaces used by the File Manager to store information, the FCB, and the data blocks for a UBASIC data file are allocated to UBASIC.FMG. A DOS directory entry is made for UBASIC.FMG with the file attribute hidden to protect UBASIC data files from any DOS operation.
Unlike any other DOS file, the space allocated to UBASIC.FMG starts from the end of the FAT and grows towards the center. This is accomplished by checking the FAT starting from the end and looking for the desired number of consecutive free FAT entries. If found, a call is made to the RAM disk driver to ensure that the block of memory is contained within a page boundary and to obtain an address pointing to the beginning of the block of memory. The offset part of the address is always 0. The segment part is saved in the segment table. (See FMGR Segment Table in the glossary of terms given earlier under FMGR Data Structure).
The first data segment allocated to UBASIC.FMG is loaded with the File Manager First Data Segment structure FIRSTSEGT. The remainder of the first segment can be used for file manager data storage and FDBs. As the space in one segment is used up, more data segments can be allocated through the RAM Disk Driver.
5-9 Series 3000 Application Programmer’s Reference Manual
Interfacing with Low-Level Features RAM Disk Interface All data files created by File Manager reside in the RAM disk. In order to reduce the time required to write to the RAM disk, File Manager disables the RAM disk write protection upon entry of every file manager operation and writes directly to the RAM disk instead of through the RAM disk driver. Upon exit of every file manager operation, regardless of whether there is an error, the write protection is re-enabled.
File Manager makes a call to the RAM Disk Driver when it finds the desired number of FAT entries to allocate to UBASIC.FMG. The RAM Disk Driver translates the sector number into a segment address and checks that all the desired sectors are in the same page boundary. EMS Interface On a PDT 3xxx terminal, expanded memory is accessed through a bank switching scheme called Expanded Memory Specification. Each bank of expanded memory is divided into a maximum of 128, 16KByte logical pages. In order to access data in expanded memory, a logical page has to be mapped into one of four physical pages (numbered 0 to 3).
The EMS context is the same as the current status of the logical page that is mapped. In order to perform operations on a data file dependent on the current state, the File Manager software adds a context buffer to the File Directory Block expressly to save the EMS context for every data file. In the beginning of every file manager operation the context is loaded, and at the end, the context is saved to the FDB.
Because the information contained in the first data segment allocated to UBASIC.FMG is accessed most frequently, the logical page which contains the first data segment allocated to File Manager is always mapped into physical page 3 for efficiency. Hence all File Manager operations have only three physical pages to work with.
5-10 UBASIC Record Manager
Memory Manager The routines that serve as the interface between the File Manager and the RAM Disk Driver comprise the Memory Manager. All of the Memory Manager functions are block-oriented, which means they either require a block pointer as the input or return a block pointer as output. Some of the functions require that the block is built with a special format while others do not.
A special formatted block is composed of a three-byte link in the beginning of the block followed by user data. The link is used to traverse the data linked list built by the Memory Manager. The link is set up when blk_insert is called, and it is used by blk_delete, blk_search, and blk_traverse. As long as the Memory Manager is used to manipulate the user linked list, this link is maintained automatically.
However, for blk_alloc and blk_free, the Memory Manager does not set up nor use any link in the block. If these functions are used, the user is responsible for maintaining the link-if he wishes to use a linked list.
When the Memory Manager allocates memory from the RAM Disk, it uses the minimum segment size specified to the minit function to allocate a segment each time. If blk_alloc or blk_insert is called to allocate or insert a block, the Memory Manager will try to allocate the space from the segment first. If a large enough block is not found in the segment, then a request will be made to the RAM Disk driver to allocate another segment.
Any unused or fragmented memory blocks caused by random deletion and insertion by the application in the segment, are maintained in the free linked list. The block returned by blk_free is also inserted into the free linked list.
5-11 Series 3000 Application Programmer’s Reference Manual
UBASIC Variables Some of the input parameters to the FMGR functions are functionally the same as some UBASIC Interface Variables. Table 5-1 lists the parameters with the corresponding variables. For more details on how to use these input parameters, refer to the UBASIC Bridging Kit. Table 5-1. UBASIC Interface Variables/FMGR Input Parameters
Parameters UBASIC Variable cparmp.cluster_size ClusterSize
cparmp.fixed_rec_len FixedRecLen
cparmp.recs_per_cluster RecsPerCluster
cparmp.rec_info RecInfo$
cparmp.type_table_addr TypeTableAddr
cparmp.type_table_size TypeTableSize
filename FileName$
filetype FileType%
reclen RecLen recnum RecNum
rectype RecType%
searchstart SearchStart
searchend SearchEnd
5-12 UBASIC Record Manager
URM Function Descriptions This section contains detailed descriptions of UBASIC Record Manager functions. The descriptions begin at the top of the next page and are in alphabetical order by function name.
5-13 Series 3000 Application Programmer’s Reference Manual
blk_alloc Syntax N/A
Description Allocate a block from the RAM Disk. Input blklen Block length. Since exactly blklen bytes are allocated, the user should include the BLKLINKSIZE bytes if desired.
desired_phy_page_num Desired physical page number to map to if the allocated memory is in EMS. If you have no preference, pass -1; then physical page 0 will be used. Output POINTER TO ALLOCATED BLOCK if successful; NULL if failure. Returns None See Also N/A
5-14 UBASIC Record Manager blk_delete Syntax N/A
Description Delete a block from the data block linked list. Input linkptr Pointer to a block link blknum Block number to traverse before deleting the block (must be > = 1). blklen Block length to delete (not including the BLKLINKSIZE bytes) Output TRUE if successful, FALSE if failure. Returns None See Also N/A
5-15 Series 3000 Application Programmer’s Reference Manual
blk_free Syntax N/A Description Return a block of memory to the free linked list. Input linkptr Pointer to returning block
blklen Block length to free. Since exactly blklen bytes are freed, the user should include the BLKLINKSIZE bytes if desired. Output TRUE if successful, FALSE if failure. Returns None See Also N/A
Note: The 2 bytes for block length in the new free block will be updated.
5-16 UBASIC Record Manager blk_insert Syntax N/A
Description Allocate and insert a block into the data linked list. Input linkptr Pointer to starting block blknum Block number to traverse before insert (must be > = 1) blklen Block length (not including the BLKLINKSIZE bytes). desired_phy_page_num Desired physical page number to map to if the allocated memory is in EMS. If you have no preference, pass -1; then physical page 0 will be used. Output POINTER TO INSERTED BLOCK if successful, NULL if failure. Returns None See Also N/A
Note: Function blk_insert( ) actually inserts a block of blklen + BLKLINKSIZE bytes.
5-17 Series 3000 Application Programmer’s Reference Manual
blk_search Syntax N/A Description Search a linked list for a matching record, or for the next highest value compared to search key.
You should specify the type of search to be performed: either SEARCHFOR or SEARCHFORNEXT.
• SEARCHFOR starts searching from the (linkptr + srchindex) record and searches until exact match is found, or when end of the linked list is encountered. • SEARCHFORNEXT starts searching from the (linkptr + srchindex) record and searches until exact match is found, or when the end of the linked list is encountered. Also, keep track of the next higher value. If exact match is not found, start searching from the beginning of the linked list and look for the next highest value until the record that meets (linkptr + srchindex) is reached. Input linkptr Pointer to starting block srchindex Offset from linkptr to start searching srchtype 0 = For, 1 = ForNext fieldoffset Offset into the record to check key Points to key to search for keylen Length of key to match Output Record number, either an exact match or the smallest value that is greater than the search key. NULL if not found. See Also N/A
5-18 UBASIC Record Manager blk_traverse Syntax N/A Description Traverse a linked list to the desired block number. Input linkptr Pointer to start traversing block blknum Block number to traverse (must be > = 1) t_ptr Pointer to a structure of two BLKLINKT pointers. This structure holds the return value. Output 1 Success Current block pointer and previous block
pointer are updated in t_ptr.
2 End of list The end was encountered and the required block is one beyond the last block. Current block and previous block pointers both point to the current last block in the linked list.
NULL Failure Returns None See Also N/A
5-19 Series 3000 Application Programmer’s Reference Manual
mclose Syntax N/A Description Close a file manager data file. Input FcbPtr Pointer to file control block
closebit bit 0 set = close input side
bit 1 set = close print side
An application may also use the following macros, defined in fmgr.gm:
mclose_for_input(Fcbptr)
mclose_for_print(Fcbptr)
mclose_for_both(Fcbptr) Output Returns 0 if successful, otherwise error code. Error code is also saved in FcbPtr->result. Returns None See Also N/A
5-20 UBASIC Record Manager mcreate Syntax N/A Description Create a file manager data file.
The mcreate function allows you to create a file manager data file by creating a File Directory Block and linking it to the FDB link list. Input filetype Type of file to be created, all file types are defined in fmgr.gd.
0x00 = LinkedFixed
0x10 = LinkedVariant
0x20 = ClusterVariant filename Name of file to be created; the maximum size is 16 characters.
When declared in C, 17 bytes should be allocated to include the null string terminator. May use the macro “CFileNameSize” in fmgr.gd. cparmp Pointer to a CREATE_PARM_S union structure depending on the file type, one of the structures should be initialized. fixed_rec_len Record length. Requires file type Linked Fixed. type_table_addr Address of rec type tab. Requires file type Linked Variant. type_table_size Size of rec type tab. Applies to file type Linked Variant only.
5-21 Series 3000 Application Programmer’s Reference Manual
rec_info Record information string. Applies to file type Linked Variant only.
recs_per_cluster Number of records in each clusters. Applies to file type Cluster Fixed only.
rec_info Record information string. Applies to file type Cluster Variant only.
cluster_size Number of bytes in each cluster. Applies to file type Cluster Variant only. Output Returns 0 if successful, otherwise error code. Returns None See Also N/A
5-22 UBASIC Record Manager mcrunch Syntax N/A Description Compress free space out of a Cluster Variant file. Input filename Name of file to crunch Output Returns 0 if successful, else error code. mcrunch may generate errors if the file is not found or is not of type Cluster Variant. Returns None See Also N/A
5-23 Series 3000 Application Programmer’s Reference Manual
mdelete Syntax N/A Description Delete a record from a data file.
If recnum is the last record in the file, FcbPtr->printside.lastrec is decremented by 1. This prevents the next file manager operation from accessing a non- existent record. Input FcbPtr Pointer to the file control block
reclen Pointer to desired record length (Set by the file manager)
recnum Pointer to the desired insert record number
rectype Pointer to desired record type (File type need not be fixed) Output Returns 0 if successful, otherwise returns an error code. The error code is saved in FcbPtr->result. Returns None See Also N/A
5-24 UBASIC Record Manager merase Syntax N/A Description The merase function marks a data file as erased. All data blocks will be freed when the file is closed. Input FcbPtr Pointer to file control block Output Returns 0 if successful, otherwise returns an error code. The error code is saved in FcbPtr->result. Returns None See Also N/A
5-25 Series 3000 Application Programmer’s Reference Manual
mfree Syntax N/A Description Check the available free space in the file manager file area. Since mfree allocates a lot of space from the stack, the following switch must be added to your link response file to increase the stack size if mfree is called by your application: /ST:0x1000
Mfree requires information such as record type and cluster size to calculate the number of free records. This information is contained in the file control block and is identified by the filename string. Hence the filename pointer should be set to point to the file name of a data file containing the specific record type and/ or cluster size that you are checking. The filename data file must be opened before mfree is called. Input recsize 0 = check for total number of free bytes N = check for number of available N-sized records
total Pointer to an unsigned long variable to save the return value
filename Pointer to a null terminated file name string. Output Returns 0 if successful, or error 11 status 13 (File Not Found error) if filename file is not opened. Returns None See Also N/A
5-26 UBASIC Record Manager minit Syntax N/A Description Initialize the file manager working variables
The minit function puts the work buffer address in the interrupt vector and sets up the first data segment and segment table and creates UBASIC.FMG. Refer to the next section for more details on UBASIC.FMG. Input wrkbufp Pointer to the file manager work buffer min_seg_size The minimum segment size allocated by the application Output Returns 0 if successful, otherwise error code. Returns None See Also N/A
5-27 Series 3000 Application Programmer’s Reference Manual
minput Syntax N/A Description Read a record from a data file.
If the record number is 0FFFFh and the file type is variant, then inputs the next record with the specified record type. If the record number is 0h, then input the next sequential record for all file types. Input FcbPtr Pointer to the file control block
reclen Pointer to desired record length (Set by the file manager)
recnum Pointer to the desired insert record number
rectype Pointer to desired record type (Don't care if file type is fixed) Output Returns 0 if successful, otherwise returns an error code. The error code is also saved in FcbPtr->result.
Other returned values are:
*reclen Length of record
*rectype Record type
*FcbPtr-inputside.bufadr Record data
FcbPtr-inputside.bufcnt Record length See Also N/A
5-28 UBASIC Record Manager minsert Syntax N/A Description Insert a record into a file manager data file. Input FcbPtr Pointer to the file control block reclen Pointer to desired record length (Set by the file manager) recnum Pointer to the desired insert record number rectype Pointer to desired record type (Don't care if file type is fixed) Output Returns 0 if successful, otherwise returns an error code. The error code is saved in FcbPtr->result. Returns None See Also N/A
5-29 Series 3000 Application Programmer’s Reference Manual
mopen Syntax N/A Description Open a file manager data file. Input FcbPtr Pointer to the file control block
openbit Bit 0 set = open for input Bit 1 set = open for print
You may also use the following macros defined in fmgr.gm:
mopen_for_input(Fcbptr) mopen_for_print(Fcbptr) mopen_for_both(Fcbptr) Output Returns 0 if successful, else error code. Error code is also saved in FcbPtr->result.
Returns None See Also N/A
5-30 UBASIC Record Manager mprint Syntax N/A Description Write a record to a data file.
If the record number is 0FFFFh and the file type is variant, then print to the next record with the specified record type. If the record number is 0, then prints the next sequential record for all file typed. If the file is variant, print only to the record with the same record type as specified in *rectype. Input FcbPtr Pointer to the file control block reclen Pointer to desired record length (Set by the file manager) recnum Pointer to the desired insert record number rectype Pointer to desired record type (Don't care if file type is fixed) Output Returns 0 if successful, otherwise returns an error code. The error code is saved in FcbPtr->result.
FcbPtr->printside.bufcnt Bytes of data printed
FcbPtr-> printside.devblk.lastrec recnum
*reclen Bytes of data printed. Returns None See Also N/A
5-31 Series 3000 Application Programmer’s Reference Manual
msearch Syntax N/A Description Search for a record from a data file. Input FcbPtr Pointer to File Control Block
srchindex First record number to start search at
srchtype 0 = SearchFor 0x80 = SearchForNext (defined in fmgr.gd)
searchstart Start record number of bounded search
searchend End record number of bounded search
reclen Pointer to found record length (Set by the file manager)
recnum Pointer to the found insert record number (Set by the file manager)
rectype Pointer to found record type (Don't care if file type is fixed) Output Returns 0 if successful, otherwise returns an error code. The error code is saved in FcbPtr->result.
Other values are returned as follows:
*reclen Length of record found
*recnum Record number found
5-32 UBASIC Record Manager
*rectype Record type found
*srchindex Record number found Returns None See Also N/A
5-33 Series 3000 Application Programmer’s Reference Manual
mterminate Syntax N/A Description Set the status flag in all the File Directory Blocks to ’close’.
This function should be called if an application is aborted in the middle of execution. Input None
Output None Returns None See Also N/A
5-34 UBASIC Record Manager
UrmOpen Syntax #include <3000\urm.h>
extern int far UrmOpen(FCBP fcbptr,XlatPtrP xlatptr, ⇒ char far nameaddr,WORD namelen, ⇒ char far buffaddr, WORD bufflen, ⇒ BYTE openmode,MODEMCTLP modemctl, ⇒ SEPCHARP outseparators);
Description The UrmOpen function establishes a link to a file or device. The first parameter is the File Control Block (FCB). If the open is successful, then the FCB is initialized to contain information applicable to that file or device. Subsequent operations on that file or device are performed by passing a pointer to the same FCB. Input fcbptr Pointer to the FCB to initialize. xlatptr Pointer to the device name translation table. nameaddr Pointer to the name of the file or device to open. namelen Length of the file name pointed to by nameaddr. buffaddr Pointer to the buffer holding records to read or write. bufflen Buffer length. The length must be sufficient
to hold the largest possible record to be read or
written for the file or device. This may include prefix
and/or suffix characters.
5-35 Series 3000 Application Programmer’s Reference Manual
openmode Mode in which to open the file or device: 1 = Input only 2 = Print only 3 = Input and Print
modemctl Modem control parameters structure.
Refer to the structure definition later in this chapter. If a null pointer is passed, no modem control is attempted.
outseparators Output separator character list. Contains the same items as described for the UrmWriteField function. Output None Returns Error Number Symbolic Name Description
0 Successful No error
6 AlreadyOpen File is already opened
8 InvalidDevice Invalid device for this operation
9 CantExecute Operation illegal or unknown
13 FileNotFound Can't find requested file
115 RamDiskErr Error generated by the RAM disk driver
See Also N/A
5-36 UBASIC Record Manager
UrmReadField Syntax #include <3000\urm.h>
extern int far UrmReadField(FCBP fcbptr,char far fieldbuffer, ⇒ int fieldsize,int far fieldlength, ⇒ UrmPtrP urmp);
Description UrmReadField reads the next field of the current record. If insufficient data is available in the current record, then additional records are read as needed until the field is satisfied. It is possible to read an entire record or to skip a field using this function.
A zero in the record length field parameter means: move zero bytes from the record to the field. Setting the ENDOFREC flag to TRUE combined with the zero length record in UrmReadField causes every call to UrmReadField to read an entire record into the buffer supplied to the UrmOpen function rather than causing fields to be read from that buffer into the field buffer.
The UrmPtrT structure contains two data conversion fields, called RecvCvt and XmitCvt. RecvCvt contains either a NULL value or a far pointer to a conversion routine. If it points to a conversion routine, the routine is called for each record read to convert the data into the desired format. An example of such a routine is EbcdicToAscii. XmitCvt points to a conversion routine that converts data before transmission.
Both of these conversions take place in the buffer supplied to the UrmOpen function just before a transmission or reception. See the description of the URM pointer structure for more details. Input fcbptr Pointer to the FCB. The FCB must have been prepared for I/O using the UrmOpen function.
5-37 Series 3000 Application Programmer’s Reference Manual
fieldbuffer Pointer to the buffer for the field to be read. The buffer should be at least as large as the size specified by the fieldsize parameter.
fieldsize Maximum length of the field to be read.
fieldlength Pointer to an integer to return the actual length of the field read. If this pointer is NULL, then the length is not returned.
urmp Pointer to a URM detail structure containing information about the record to be processed. Output None Returns Error Number Symbolic Name Definition 0 Successful No error 1 NoDataTimeout No data within RCVTIME 2 MaxRetryCount Max retries failed 3 LineDrop Communication line lost 4 ReceiveAbort Received a request to abort 7 NotYetOpen File is not yet opened 8 InvalidDevice Invalid device for this operation 9 CantExecute Operation illegal or unknown 10 ReceiveRvi Received an RVI from remote 11 EndOfFile End of file reached 12 NoSuchRecord Can't find requested record 15 DeviceOutputErr Can't output to device 17 ReceiveEot Received an end of transmit 18 DataOverRun Data buffer too small See Also UrmWriteField, UrmOpen
5-38 UBASIC Record Manager
UrmWriteField Syntax #include <3000\urm.h>
extern int far UrmWriteField(FCBP fcbptr,char far fieldbuffer, ⇒ int fieldsize, int far fieldlength, ⇒ UrmPtrP urmp);
Description The UrmWriteField function writes a field to an open file or device. This function is analogous to the read function, except the direction of transfer is reversed. The meanings of the parameters are also reversed in some cases.
The UrmPtrT structure contains a field called XmitCvt. This field has a NULL value or a far pointer to a conversion routine. The conversion routine is called for each record transmitted to convert the data into the desired format. A common example of such a routine is AsciiToEbcdic. See the description of the URM pointer structure for more details. Input Fcbptr Pointer to the FCB associated with the file to be used.
The FCB must have been prepared for I/O using the UrmOpen function. fieldbuffer Pointer to the field that is written to the file or device. fieldsize Length of the field to be written. fieldlength Pointer to an integer that will contain the length of the field that was written.
If this pointer is NULL, then the length is not returned. urmp Pointer to a URM detail structure containing information about the record to be processed.
5-39 Series 3000 Application Programmer’s Reference Manual
Output None Returns Number Symbolic Name Definition
0 Successful No error
9 CantExecute Operation illegal or unknown
15 DeviceOutputErr Can't output to device See Also UrmReadField, UrmOpen
5-40 UBASIC Record Manager
UrmClose Syntax #include <3000\urm.h>
extern int far UrmClose(FCBP fcbptr,UrmPtrP urmp);
Description The UrmClose function terminates a link to a file or device which was established via a call to UrmOpen. Input fcbptr Pointer to the FCB associated with the file to be closed.
The FCB must have been opened using the UrmOpen function. urmp Pointer to a URM detail structure containing information about the record to be processed. Output None Returns Number Symbolic Name Definition
0 Successful No error
9 CantExecute Operation illegal or unknown
15 DeviceOutputErr Can't output to device See Also UrmOpen
5-41 Series 3000 Application Programmer’s Reference Manual
UrmPresent Syntax #include <3000\urm.h>
external boolean UrmPresent(void);
Description UrmPresent tests for the presence of the URM functions in NVM or RAM. This function should be used at the beginning of an application before any other URM functions are called. If an application tries to call other URM functions when the functions are not present, unpredictable results may occur. The UrmPresent function must be linked into the application to ensure that the function is available. Input None Output None Returns UrmPresent returns TRUE if the URM functions are available, otherwise it returns FALSE. See Also N/A
5-42 UBASIC Record Manager
URM Structure Definitions The functions described in this section use several common structures. The following pages describe these structures. File Control Block (FCB) The File Control Block structure is used by the UBASIC Record Manager and File Manager to keep track of information concerning a file while it is open. The following is the Microsoft C declaration of the FCB structure, preceded by substructure declarations.
struct FCBDEV_S /* device dependent block,MEM:*/ { WORD lastrec; /* Last record accessed */ BLKLINKT fdbptr; /* Fdb pointer */ BYTE filler[7];/* not used */ WORD handle; /* file handle */ };
#define FCBDEVT struct FCBDEV_S #define FCBDEVP FCBDEVT far * #define FCBDEVSIZE sizeof (FCBDEVT); struct FCBSIDE_S { char name[CFileNameSize]/* data file name */ char device[CDevNameSize];/* COM:,LPT:, or MEM: */ BYTE devnum; /* device number*/ BYTE redirect; /* redirection requested */ BYTE protocol; /* protocol selected */ char far *bufadr; /* data buffer address*/ WORD bufsiz; /* data buffer size */ char far *bufptr; /* current ptr to buffer */ WORD bufcnt; /*count of data in buffer */ WORD recnum; /* current record number */ char far *recptr; WORD reccnt; int firstrec; int startrec; FCBDEVT devblk; /* device dependent block */ };
5-43 Series 3000 Application Programmer’s Reference Manual
#define FCBSIDET struct FCBSIDE_S #define FCBSIDEP FCBSIDET far * #define FCBSIDESIZE sizeof(FCBSIDET); struct FCB_S { BYTE openmode; /* Modes file is open for*/ BYTE result; /* Result of last operation */ /* == 0 No Error */ /* == 0 Error code */ BYTE lastop; /* Last operation for this */ /* channel */ /* == 0 - Open */ /* == 1 - Input */ /* == 2 - Print */ /* == 3 - Close */ /* == 4 - Erase */ /* == 5 - Insert */ /* == 6 - Delete */ /* == 7 - Search */ WORD offset; /* Offset to search pattern*/ char far *keyadr; /* Address of search key*/ WORD keylen; /* Length of search key*/ FCBSIDET inputside; /* Input operation specific info */ FCBSIDET printside; /* Print operation specific info */ }; #define FCBT struct FCB_S #define FCBP FCBT far * #define FCBSIZE sizeof(FCBT)
Declaring an FCB An application program should use the symbol FCBT to declare instances of FCBs as needed to satisfy the program requirements. As a general rule, an application needs to declare as many FCBs as it will have files open simultaneously. The application may define the FCBs with individual names, or as an array depending on what is most convenient for the application use.
The following are examples how to declare a FCB.
Declaring individual FCBs:
5-44 UBASIC Record Manager
FCBT customer_file; FCBT product file;
Declaring an array of FCBs:
#define MAXIMUM_CUSTOMERS 8 FCBT files[MAXIMUM_CUSTOMERS];
Initializing an FCB A FCB must be initialized prior to first use. To initialize a FCB, set the openmode field to zero. This prevents UrmOpen returning an “already open” error.
The structure initializer affects only the first use of a structure. Later uses of the same structure retain previous values. However, if the UrmClose function is used, the openmode field will be set to zero once all opens have been matched with closes for a given FCB.
The following are examples of how to initialize a FCB.
Initializing an individual FCB:
customer_file.openmode = 0; product_file.openmode = 0;
If the FCBs were declared STATIC, the standard C structure initializer could be used, such as:
FCBT customer_file = {} FCBT product_file = {}
Initializing a static structure is not necessary, since STATIC variables are automatically initialized to zero. However, this is a good practice since some structures will require initial values other than zero.
5-45 Series 3000 Application Programmer’s Reference Manual
Initializing an array of FCBs:
files[0].openmode = 0; . . . files[n].openmode = 0;
Initializing an array of FCBs using a for loop:
for(i=0;i Initializing an array of FCBs using a C library initialization routine: memset(files,MAXIMUM_CUSTOMERS *FCBSIZE,0); Initializing an array of FCBs using an initializer for a STATIC variable: FCBT files[MAXIMUM_CUSTOMERS] = {0}{}...,{}; Passing an FCB as a Parameter When passing an FCB as a parameter to a URM function, use the “address of” operator (&) in front of either the individual FCB name or in front of the array element selector. Passing an individual FCB: UrmErase(&customer_file,&outseps); Passing an FCB array element: UrmErase(&files[i],&outseps); 5-46 UBASIC Record Manager Device Name Translation Table (XlatPtrT) The device name translation table (XlatPtrT) is a lookup table that translates UBASIC Plus logical device names to URM device names. A device code is included in the table and can be used in various device dependent operations. When UrmOpen is called, a device name translation table must be supplied to allow URM to correctly interpret the UBASIC Plus device names within the file specification supplied. The following is the Microsoft C declaration for the device name translation table structure. struct XlatPtr_S { char far *SrcTable; /* Ptr to UBASIC device names*/ char far *DestTable; /* Ptr to replace device names*/ BYTE far *IndexTable; /* Ptr to UBASIC device codes*/ }; #define XlatPtrT struct XlatPtr_S #define XlatPtrP XlatPtrT far * In normal use, an application program should have only one device name translation table. This table should associate each UBASIC device name used by the application with its corresponding URM device name. Refer to the UBASIC Plus reference manual for more information on UBASIC device names. Table 5-2 shows the standard UBASIC Plus device name translation table. The special device name “AUTO” causes URM to automatically select either COM1 or COM2 based on hardware availability and state. 5-47 Series 3000 Application Programmer’s Reference Manual Table 5-2. Stanfard UBASIC Plus Device Names UBASIC URM Device Name Name Code Description COM AUTO 2 Auto select port, comm COM:1 0 Error Comm via parallel COM:2 COM1 2 DB25 port, comm COM:3 0 Error, no comm via wand COM:4 COM2 2+0x20 Internal modem, comm COM:5 COM2 2+0x10 Acoustic modem LPT: LPT1 3 Parallel port, print LPT:1 LPT1 3 Parallel port, print LPT:2 LPT1 3 + 0x10 DB25 port, print LPT:3 0 Error, no print to wand LPT:4 COM2 3 + 0x20 Internal modem, print The device code is used to communicate the device type and redirection. The device types are: Number Symbolic Name Description 0 MEMDEV Mem (File Manager) 1 DOSDEV DOS (DOS Files) 2 COMDEV COM (Serial communications) 3 LPTDEV LPT (Printer output) 4 OTHERDEV Other (Any DOS character devices) Redirection applies only to LPT (3) or COM (2), and is added to the device code. The redirection values are: Number Symbolic Name Description 0x10 TOCOM1 Redirect LPT to COM1 0x20 TOCOM2 Redirect LPT to COM2 0x10 TOSPKR Redirect COM to speaker/mike 0x20 TOMDM Redirect COM to internal modem 5-48 UBASIC Record Manager Declaring a Device Name Translation Table In normal use, a C application should declare one device name translation table and use it for all calls to UrmOpen. This table is declared using an instance of the structure name XlatPtrT as follows: XlatPtrT devtab; The pointer to this table would be passed to the UrmOpen function by using the address operator (&): UrmOpen(&myfcb,&devtab,...); Initializing a Device Name Translation Table The device name translation table must be initialized before it is passed to UrmOpen. To simplify initialization, the table should be defined as STATIC. The entire definition of the initial contents of the device name table can be performed in one step using standard C structure and array initialization constructs. An example table could be initialized as follows: XlatPtrT devtab = { "COM:\0 COM:2\0 COM:4\0 COM:5\0", "AUTO\0 COM1\0 COM2\0 COM2\0", {COMDEV, COMDEV, COMDEV+TOMDM, COMDEV+TOSPKR} }; Note: The device code constants COMDEV, LPTDEV, TOCOM1, and TOCOM2 are used to define the device code portion of the table. These constants are defined by the URM.H file. 5-49 Series 3000 Application Programmer’s Reference Manual Separator Character Structure The separator character structure defines a series of characters to be used by the URM functions stream I/O operations. The separator characters structure is only used for device types 1(DOS files), 2 (COM), and 4 (Other). The following is the Microsoft C declaration for the separator character structure: struct SEPCHAR_S { char FieldSep; /* Field separator character*/ char SessionPre; /* Session pre character*/ char SessionPost; /* Session post character*/ char HeaderPre; /* Header pre character*/ char NonHeaderPre; /* Non-header pre character*/ char TrailerPost; /* Trailer post character*/ char NonTrailerPost;/* Non-trailer post character*/ } #define SEPCHART struct SEPCHAR_S #define SEPCHARP SEPCHART far * URM input and output operations use separate versions of this structure. The individual items of the structure, along with the meaning for input and output are described in the following table. Declaring a Separator Character Structure An application program should use the symbol SEPCHART to declare instances of separator character structures. For example: SEPCHART dos_text_file_sep; SEPCHART one_way_com_sep; In general, an application needs as many separator character structures as it has different stream file styles. For example, if one stream file uses carriage return/line feed record separators and another uses commas, two structures should be allocated. Also, if the input and output characteristics are different, then a structure for each should be allocated. 5-50 UBASIC Record Manager When passing a separator character structure as a parameter to an URM function, use the address operator (&) in front of the name of the structure, for example: UrmOpen(&myfcb,..,&dos_text_file_sep); Initializing a Separator Character Structure The separator character structure must be initialized before it is passed to an URM function. In most cases the structure is best defined as STATIC and the entire structure can be initialized in one step using standard C structure initialization constructs. Some examples follow: SEPCHART dos_text_file_sep = {0x00, /* No field separator char*/ 0x0D, /* CR session start char*/ 0x00, /* No session end char*/ 0x00, /* No header prefix*/ 0x0A, /* LF non header prefix*/ 0x00, /* No trailer postfix*/ 0x0D /* CR non trailer postfix*/ }; SEPCHART one_way_com_sep = {0x00, /* No field separator char*/ 0x02, /* STX session start char*/ 0x03, /* ETX session end char*/ 0x00, /* No header prefix*/ 0x00, /* No non header prefix*/ 0x00, /* No trailer postfix*/ '+' /* + non trailer postfix*/ }; When the separator characters change frequently or vary depending on protocol, then assignment statements can be used to initialize this structure so that the values assigned can be changed dynamically. 5-51 Series 3000 Application Programmer’s Reference Manual Parameters FieldSep A field separator character. No field separator precedes the first field or follows the last field of a record. Input: Terminates reading a field before the maximum field size has been read. Also causes early termination for all not yet read fields when the end of record is encountered. Output: Writes the field separator character following the field data unless the field is the last field of the record. SessionPre The session prefix character begins a session and separates the actual session data from any pre-session data. Input: All data received prior to the session prefix character is ignored and the prefix character is discarded. The next character read is the first character of the session. Output: The session prefix character is written prior to the first session character. SessionPost The session postfix character. When this item is set to a non-zero value, then its operation is enabled. Input: The session postfix character generates a logical end-of-file condition. Further characters are ignored until a new session is started. Output: The session postfix character is written following the last character of the session prior to physically closing the files or starting a new session. 5-52 UBASIC Record Manager HeaderPre A character used to mark the beginning of a logical header record. Some communication protocols use the header/non-header information to control protocol specific handling (e.g. Symbol MSI Two-way uses SOH for headers and STX for non-headers). Input: Begins reading data as a header record. Characters preceding the first record or between records are ignored. Output: The header prefix character is written prior to the first character of header data. NonHeaderPre A character used to mark the beginning of a logical non-header record. Some communication protocols use the header/non-header information to control protocol specific handling (e.g. Symbol MSI Two-way uses SOH for headers and STX for non-headers). Input: Causes the recognition of the start of a record. Reports a non-header record type. Characters preceding the first record or between records are ignored. Output: When writing a non-header record, causes the non header prefix character to be sent or stored prior to the first character of the record. TrailerPost A character used to mark the end of a logical trailer record. Some communication protocols use the trailer/non-trailer information to control protocol-specific handling (e.g. Symbol Two-way uses ETX for trailers and ETB for non-trailers). 5-53 Series 3000 Application Programmer’s Reference Manual Input: Causes the recognition of the end of a record. Reports a trailer record type. Characters following the last record or between records are ignored. Output: When writing a trailer record, causes the trailer postfix character to be sent or stored following the last character of the record. NonTrailerPost A character used to mark the end of a logical non trailer record. Some communication protocols use the trailer/non-trailer information to control protocol-specific handling (e.g. Symbol Two-way uses ETX for trailers and ETB for non-trailers). When this item is set to a non-zero value, then its operation is enabled. Input: Causes the recognition of the end of a record. Reports a non trailer record type. Characters following the last record or between records are ignored. Output: When writing a non trailer record, causes the non trailer postfix character to be sent or stored following the last character of the record. 5-54 UBASIC Record Manager Modem Control Structure The modem control structure defines a series of values to be used by the UrmOpen function to control modems. The parameters set in this structure are related to specific hardware characteristics of the modem being used. When a value that is not compatible with the capabilities of the modem is passed to UrmOpen via this structure, no error is generated. The UrmOpen function attempts to perform the closest approximation supported by the modem. This is the declaration for the modem control information structure. struct MODEMCTL_S { BYTE dial; /* Type of dialing selected*/ char tel[UbTelLen]; /* Telephone number to dial*/ BYTE adcnt; /* # of retries when dialing*/ WORD adrty; /* Time between retries (ms.)*/ BYTE modemtype; /* modem technology*/ BYTE dtdbnc; /* Debounce time for dial tone*/ BYTE dtwait; /* Wait time for dial tone*/ BYTE country; /* Country Type Code*/ BYTE europhone /* USA/Europe phone flag*/ BYTE monitor; /* Audio call progress monitoring */ /* enable/disable) */ BYTE mkboost /* loudness of acoustic mark*/; BYTE spboost; /* loudness of acoustic space*/; void (far *callprog)(int);/ * call progress routine*/ /*pointer */ }; #define MODEMCTLT struct MODEMCTL_S #define MODEMCTLP MODEMCTLT far * 5-55 Series 3000 Application Programmer’s Reference Manual Declaring a Modem Control Structure Use the symbol MODEMCTLT to declare instances of modem control structures as needed to satisfy the program requirements. For example: MODEMCTLT adaptive_modem; MODEMCTLT half_duplex_modem; MODEMCTLT smart_modem; When passing a modem control structure as a parameter to a URM function, use the address of operator (&) in front of the name of the structure, for example: UrmOpen(&myfcb,..,&smart_modem,...); Initializing a Modem Control Structure The modem control structure must be initialized completely before it is passed to a URM function. In most cases, this structure is best defined to be STATIC so it can be initialized using the structure initialization constructs. Example: MODEMCTLT hayes_modem = {TONEDIAL, /* use DTMF DIALING */ {'9', '1', '2',....}/* must be 40 chars*/ 5, /* retry count */ 10, /* Retry delay */ ModemV22, /* V.22 modem */ 2, /* DT debounce time */ 10, /* DT wait time */ 0, /* FCC Mode */ 0, /* USA Flag */ 0, /* No monitoring */ 0, /* No mark boost */ 0, /* No space boost */ NULL /* No call progress routine */ }; If the modem characteristics change dynamically, for example as a result of a user menu, then assignment statements can be used to initialize this structure. 5-56 UBASIC Record Manager Full and Half-Duplex Modems V.23 and Bell 202 are half-duplex modems. They use the same carrier frequency for transmit and receive and can only transmit or receive in one direction at a time. You must use an alternating protocol (e.g., TWOWAY) with a half-duplex modem, and you must set the “duplex” field in the “comparameters” IOCTL structure to DUPLEXHALF. Half-duplex modems should also have a modem delay set in the “modemdelay” field, especially for the older modems. This allows the carrier to stabilize after doing a Line Turn Around. The V.21, V.22, (V.22 bis), Bell 103, and Bell 212 modems are all full-duplex. Because they use different carrier frequencies for transmit and receive, they can transmit and receive at the same time. Set the “duplex” field to DUPLEXFULL for full-duplex modems. A modem delay is not needed, because a Line Turn Around is not required. 5-57 Series 3000 Application Programmer’s Reference Manual Modem Configuration Parameters The following parameters are set in the modem control structure. dial Type of dialing to be performed. This item specifies the type of dialing to be used, provided that the modem is capable of performing the requested type of dialing. Symbol Technologies IM3 and IM4 modems support Auto dial selection via the ATD command. For the IM5 and external Hayes-compatible modems, use either DTMF or Pulse dialing. Value Symbolic Name Description 0NODIALNo dialing 1 TONEDIAL DTMF (tone) dialing 2 PULSEDIAL Pulsedialing 3AUTODIALAuto (DTMF, then pulse) tel Telephone dial string. Depending upon the modem in use, this string may include several control characters in addition to digits. Refer to the Chapter 7, Internal Modem Command Set for control characters. adcnt Auto dial retry count. Number of times to attempt redialing before giving up. adrty Auto dial retry delay time. Time (in milliseconds) between redial attempts. 5-58 UBASIC Record Manager modemtype The type of modem. Value Symbolic Name Description 0ModemV.23 1 Modem 103 Bell 103 2 Modem V21 V.21 3 Modem212 Bell 212 4ModemV22V.22 5 Modem 202 Bell202 dtdbnc Dial tone debounce time. Specifies the time, in 25 ms increments, that energy (dial tone) from the modem must be present before it is assumed to be stable. This eliminates noise on the line which could be mistaken for dial tone. dtwait Duration, in 1 second increments, before the lack of energy (dial tone) from the modem results in a failure to connect. This controls the time allowed for dial tone to come up. Can be reduced to speed up auto-select if the line is known to respond with dial tone quickly after going off hook. country Country type code. Refer to Chapter 7, Internal Modem Command Set for a complete list. Value Symbolic Name Description 0 Country USA USA 1 CountryUK0 European europhone European Phone flag. This item controls whether the transformer is turned off during pulse dialing on European phones. 5-59 Series 3000 Application Programmer’s Reference Manual monitor This item controls audible call progress monitoring to the internal speaker. The series 3000 does not have Audio Call Progress Monitoring. A similar capability is provided by software Call Progress Monitoring (described below). Value Symbolic Name Description 0 OFFMONITOR Speaker off entire session 1 SEMIMONITOR Speaker on until answer tone 2 ONMONITOR Speaker on entire session mkboost Gain (volume) used for acoustic mark tones (0-8). spboost Gain (volume) used for acoustic space tones (0-8). callprog Address of software call progress routine to be called during modem control as the state of the call changes. Value Symbolic Name 0x00 ModemOK 0x01 ModemConnect 0x02 ModemLocalRing 0x03 ModemNoCarrier 0x04 ModemCommandError 0x05 ModemConnect120 0x06 ModemNoDialTone 0x07 ModemRemoteBusy 0x08 ModemNoAnswer 0x09 ModemConnect600 0x0A ModemConnect2400 0x0B ModemConnectV23 0x91 ModemLocalOffHook 0x92 ModemDialTone 0x93 ModemDialingPulse 0x94 ModemRemoteRing 0x95 ModemEndRing 0x96 ModemAnswerTone 5-60 UBASIC Record Manager URM Pointer Structure (UrmPtrT) The URM pointer structure, UrmPtrT, holds pointers to various pieces of control information needed by many of the URM functions. Rather than pass a long list of pointers to these functions, the pointers are grouped together into a single structure whose pointer is passed to the URM functions. The following is the Microsoft C declaration for the URM pointer structure. struct SEPCHAR_S {SEPCHARP OutSeparators; /* Ptr to output separator */ /* characters structure */ SEPCHARP InSeparators; /* Ptr to input separator */ /* characters structure */ int far *RecordNumber; /* Ptr to desired/actual */ /* record #*/ WORD far *RecordLength; /* Ptr to desired/actual */ /* record length*/ BYTE far *recordtype; /* Ptr to desired/actual */ /* record type*/ BYTE far *RecordFlags; /* Ptr to desired/actual */ /* record flag*/ CvtFuncP XmitCvt; /* Ptr to transmit*/ /* conversion function*/ CvtFuncP RecvCvt; /* Ptr to receive */ /* conversion function*/ }; #define UrmPtrT struct UrmPtr_S #define UrmPtrP UrmPtrT far * Except for the separator character structure pointers, most of the fields of the URM pointer structure pertain only to File Manager files. When accessing multiple file manager files simultaneously it is often convenient to have one URM pointer structure per file to allow the files to have independent record lengths, types, etc. 5-61 Series 3000 Application Programmer’s Reference Manual Declaring a URM Pointer Structure In normal use, the application program should use the symbol UrmPtrT to declare instances of URM pointer structures as needed to satisfy program requirements. As a general rule, an application would have several URM pointer structures for the various file I/O and device I/O activities being performed. Some example URM pointer structure declarations are: UrmPtrT dos_file_io UrmPtrt comm; UrmPtrT ubasic_file_io; An application will typically declare as many URM Pointer structures as it has file I/O categories. However, it is seldom necessary to declare a URM pointer structure for each pair of separator character structures. Some pairs are never used together and some situations allow otherwise identical structures to be modified at runtime to change the separator character structure pointers. Initializing a URM Pointer Structure The URM pointer structure MUST be initialized completely before it is passed to a URM function. In most cases, this function should be declared as STATIC so the initialization can be performed using the structure initialization construct. For example: SEPCHART out_seps; SEPCHART in_seps; int rec_num; WORD rec_len; BYTE rec_typ; BYTE rec_flg; UrmPtrT urmp1 = { &out_seps, &in_seps, &rec_num, &rec_len, 5-62 UBASIC Record Manager &rec_typ, &rec_flg, NULL, NULL }; extern void far AsciiToEbcdic(char far *buffer, unsigned int buflen); extern void far EbcdicToAscii(char far *buffer, unsigned int buflen); UrmPtrT urmp2 = { &out_seps, &in_seps, &rec_num, &rec_len, &rec_typ, &rec_flg, AsciiToEbcdic, EbcdicToAscii }; Header and Trailer Flags The header and trailer flags indicate whether that record is a header record, trailer record, both, or neither. Some blocked protocols, such as the 2-way protocol, recognize a distinction between header records, data records, and trailer records. When a record is read, the URM sets the header and trailer flags to indicate the type of record received. The meaning of the header/trailer information is determined by the application. Generally, a header record indicates the beginning of a data sequence or gives information about the data to follow. This is typically followed by data records. A trailer block (which is not also a header block) is usually sent to indicate the end of data. 5-63 Series 3000 Application Programmer’s Reference Manual Refer to the Communication Device Driver chapter in the Series 3000 System Software Manual for information on setting the header and trailer bits for the Communications Driver. Parameters OutSeparators The pointer to the separator character structure used for output operations. This pointer resides within the URM Pointer Structure which is passed to other URM functions. InSeparators The pointer to the separator character structure to be used for input operations. This pointer resides within the URM Pointer Structure which is passed to other URM functions. RecordNumber (This field can be ignored at this time.) The pointer to the integer value which represents the record number (of a File Manager file) to be read or written. If a value less than or equal to zero is used, the File Manager may do a sequential read or write, in which case the record number will be altered to reflect the record number actually read or written. RecordLength (This field can be ignored at this time.) The pointer to the word value which represents the number of bytes actually read or written for the current record. This is modified only when a record is actually read or written (which may not happen every time UrmReadField or UrmWriteField are called). recordtype (This field can be ignored at this time.) The pointer to the byte value which represents the type of record read or the type of record to be written. This is applicable only to the File Manager files of type Linked Variant and Cluster Variant. RecordFlags A pointer to the byte value containing record and field flags for the current UrmReadField or UrmWriteField operation. The byte is a bit map representing six flags. 5-64 UBASIC Record Manager Set the corresponding bit for TRUE and reset it for FALSE. Full descriptions of each flag are given below. The value of each flag is: Value Name 0x80 ENDOFREC 0x40 BLOCKPROT 0x20 TWOWAYEMUL 0x1 CEOTFLAG 0x02 TRAILERPOST 0x01 HEADERPRE XmitCvt The pointer to the function used to convert a buffer from one format to another before transmission. This is used only for files whose device type is COMDEV. Prior to sending any record, the buffer pointer and size are passed to the function whose pointer is in this field. If this field contains NULL, then the call is not made. The conversion is performed in place (i.e. the buffer is modified). An example prototype for a function that could be used for this purpose is given below: void far AsciiToEbcdic(char far *buffer, ⇒ unsigned int buflen); RecvCvt The pointer to the function used to convert a buffer from one format to another after reception. This is used only for files whose device type is COMDEV. After receiving any record, the buffer pointer and size are passed to the function whose pointer is in this field. If this field contains NULL, then the call is not made. The conversion is performed in place (i.e. the buffer is modified). An example prototype for a function that could be used for this purpose is given below: 5-65 Series 3000 Application Programmer’s Reference Manual void far EbcdicToAscii(char far *buffer, unsigned int buflen); Record Flag Descriptions ENDOFREC On a write, ENDOFREC indicates the last field in a record. After this field is written, the data output buffer will be flushed. On a read, ENDOFREC indicates the last field of a record. You can set ENDOFREC to skip the rest of the fields in a record. This discards any unread portion of the buffer and forces the next field to come from the beginning of the next record. BLOCKPROT Setting this flag indicates that the protocol to be used is a block protocol. A block protocol preserves: • The identity of the data blocks. The block length received is the same as the block length transmitted. URM assumes that there is exactly one record per block and allows the protocol to control record delimiting. • The data. The data received is exactly the same as the data transmitted. • The data sequence. The data is received in the same order as it was transmitted. A stream protocol preserves data and the data sequence, but not block information. There is no way on the receiving end to distinguish between the end of one block and the beginning of the next. The last character of one block is immediately followed by the first character of the next block. 5-66 UBASIC Record Manager If the BLOCKPROT flag is set, all separator characters except FieldSep are ignored. Session and record delimiting are handled by the protocol. If the BLOCKPROT flag is cleared, all non-zero separator characters are inserted into the data stream. These can be used by a stream protocol to emulate blocking. If the field separator is non-zero, the fields may be shorter than their maximum length. A field read ends when: Its maximum length is reached, or The field separator character is detected, or End-of-record is reached. TWOWAYEMUL This flag provides UBASIC header/trailer compatibility. If BLOCKPROT and TWOWAYEMUL are set, the following actions are taken. On a write, URM will set the header flag if the header prefix character is SOH, and will clear the header flag if the header prefix character is STX. URM will set the trailer flag if the trailer postfix character is ETX, and will clear the trailer flag if the trailer postfix character is ETB. The behavior of URM when TWOWAYEMUL is used and characters other than SOH, STX, ETX, AND ETB are used is undefined. On a read, URM will set the header prefix character to SOH if the header flag is set on an incoming record and will set the header prefix character to STX if the header flag is clear. URM will set the trailer postfix character to ETX if the trailer 5-67 Series 3000 Application Programmer’s Reference Manual flag is set on an incoming record and will set the trailer postfix character to ETB if the trailer flag is clear. This method of specifying and detecting header and trailer flags is not generally recommended. Direct access to the header and trailer flags via recflg is preferred. CEOTFLAG This flag is used to trigger a special MSITWOWAY session that was possible in previous generations of Symbol terminals. Setting or clearing this flag, along with the proper sequence of Close In and Close Out operations, controlled the terminal sequence sent. The following shows the result of each type of close sequence. Close Sequence Result Clear CEOTFLAGDLE EOT (Standard) Close In Close Out Clear CEOTFLAG EOT DLE EOT (Normally considered invalid) Close Out Close In Set CEOTFLAG EOT (Normally considered invalid) Close Out Close In HEADERPRE This flag indicates that the current record is a header record. Refer to “Header and Trailer Flags” earlier in this section. TRAILERPOST This flag indicates that the current record is a trailer record. Refer to “Header and Trailer Flags” earlier in this section. 5-68 UBASIC Record Manager FMGR Data Block Link A FMGR Data Block Link is the pointer to the next data block in the file. It is stored in the first three bytes of every data block. The index part can be translated into a segment address through the segment table. When combined with the offset part of this structure, it makes a four-byte pointer. struct BLKLINK_S {BYTE index; /* index into the segment table */ WORD offset; /* offset part of a pointer */ }; #define BLKLINKT struct BLKLINK_S #define BLKLINKP BLKLINKT far * #define BLKLINKSIZE sizeof(BLKLINKT) File Information Block A File Information Block is used to store record-related information for variant files. It is the first block in the linked list of the file. It is created when the variant file is created and will remain until the file is erased and closed. struct FIB_S {BLKLINKT firstblkptr; /*pointer to first data block */ WORD length; /*length of this block */ TYPETABT rectyptable; /*copy of the user specified */ /* type table */ }; #define FIBT struct FIB_S #define FIBP FIBT far * #define FIBSIZE sizeof(FIBT) 5-69 Series 3000 Application Programmer’s Reference Manual File Directory Block A file directory block contains all the necessary file information which will be retained even when the file is closed. It is created when the file is created and will remain until the file is erased and closed. union DEPBLK_U { struct /*Linked Fixed */ { WORD reclen; /*Length of all */ }linked_fixed; /* records in file */ struct /*†Cluster Fixed */ { WORD clustersize; /* Length of all blocks*/ WORD reccnt; /* records per cluster*/ WORD recsiz; /* size of each record */ char far *currentptr; /* current record pointer*/ }cluster_fixed; struct /* Cluster Variant*/ { WORD clustersize; /* Length of all clusters */ WORD clscnt; /* total number of clusters */ WORD curclsnum; /* current cluster number*/ }cluster_variant; }; #define DEPBLKT union DEPBLK_U #define DEPBLKP DEPBLKT far * #define DEPBLKSIZE sizeof(DEPBLKT); struct FDB_S { BLKLINKT nextlink; /* Link to next Fdb */ BLKLINKT prevlink; /* Link to prev Fdb */ char filename[CFileNameSize]; /* Name of this file MUST be the */ /* first field after the links.*/ 5-70 UBASIC Record Manager /* See putfdb() in fmgr.lm.*/ BYTE openstatus; /* Open status of the file */ /* 7 6 5 4 3 2 1 0*/ /* | | | | | | | |*/ /* | | | | | | | |*/ /* | | | | | | | \- 1 Open for Input*/ /* | | | | | | \ - 1 Open for Print*/ /* | | | | | \ -- 0/1 Seq/Rnd*/ /* | | | | \-future 0/1 Rn/Key*/ /* | | | \ ---- 0/1 Fixed/Variant*/ /* | | \ ----- 0/1 Linked/Cluster*/ /* | \ ---future 1 ISAM*/ /* \ ------1 Erase*/ BLKLINKT firstptr; /* Pointer to first record*/ /* Note:If file is LinkedVariant,*/ /* then it has a Fib which is the*/ /* first block of data. The format*/ /* of the Fib is shown above*/ WORD reccnt; /* Number of records in this*/ /* file*/ BLKLINKP currentptr; /* Pointer to current record*/ WORD currecnum; /* Number of current record*/ /* First rec # in cls for CV*/ /* only*/ char context_buf[CONTEXT_BUF_SIZE]; /* EMS context buf*/ /* CONTEXT_BUF_SIZE = 20 in */ /* fmgr.gd */ DEPBLKT dependent; }; #define FDBT struct FDB_S #define FDBP FDBT far * #define FDBSIZE sizeof(FDBT) 5-71 Series 3000 Application Programmer’s Reference Manual DOS File Directory The DOS File Directory structure is used by FMGR to set up the UBASIC.FMG DOS file which stores the data files for the file manager. The attribute is set to Hidden so that the UBASIC.FMG file would not be tampered by any DOS operation. struct DOS_FD_S { char filename[DOSFileNameSize]; /* DOSFileNameSize= 8 */ /* in fmgr.gd */ char fileext[ExtNameSize]; /* ExtNameSize = 3 */ /* in fmgr.gd */ BYTE attribute; char reserved[10]; WORD time; WORD date; WORD start_fat_entry; unsigned long filesize; }; #define DOS_FDT struct DOS_FD_S #define DOS_FDP DOS_FDT far * #define DOS_FDSIZE sizeof(DOS_FDT) Bios Parameter Block The Bios Parameter Block contains the RAM Disk information needed by File Manager to perform memory allocation in the RAM disk. The information is maintained in the first sector in the RAM disk. struct BPB_S { char version[8]; /* 8 bytes for OEM name and ver*/ WORD bytes_per_sect; BYTE sect_per_cluster; WORD reserved_sect; BYTE fat_num; WORD root_entry_num; WORD sect_in_log_image; 5-72 UBASIC Record Manager BYTE media_descriptor; WORD sect_per_fat; WORD sect_per_track; WORD head_num; WORD hidden_sect_num; }; #define BPBT struct BPB_S #define BPBP BPBT far * #define BPBSIZE sizeof(BPBT) DOS FAT Entries The following structure actually contains two DOS File Allocation Table entries. Each of them occupies one and a half bytes. This structure is used by the File Manager during the chaining and unchaining of UBASIC.FMG FAT entries. struct FAT_ENTRY_S { byte fat1; byte fat2; byte fat3; }; #define FAT_ENTRYT struct FAT_ENTRY_S #define FAT_ENTRYP FAT_ENTRYT far * #define FAT_ENTRYPP FAT_ENTRYP far * #define FAT_ENTRYSIZE sizeof(FAT_ENTRYT) 5-73 Series 3000 Application Programmer’s Reference Manual Free Block A file manager free block is a block of memory available for allocation to the application, but still in possession of UBASIC.FMG. Other than the link, it also contains the size of the block at the beginning of the block. struct FREE_S { BLKLINKT link; WORD size; }; #define FREET struct FREE_S #define FREEP FREET far * #define FREESIZE sizeof(FREET) Segment Table Entry A Segment Table Entry contains the information File Manager needs, namely pagenum and seg, to translate a one-byte index into a two-byte segment address. It also contains the data segment size which is filled in by the segment_alloc( ) routine. This size is needed when the segment is returned to DOS. struct SEG_INFO_S { BYTE pagenum; /* lower 8 bits of EMS logical page number */ /* -1 = not EMS */ BYTE size; /* segment size in sector */ WORD seg; /* segment address */ }; #define SEG_INFOT struct SEG_INFO_S #define SEG_INFOP SEG_INFOT far * #define SEG_INFOSIZE sizeof(SEG_INFOT) 5-74 UBASIC Record Manager RAM Disk Driver Parameter Block The RAM Disk Parameter Block is the interface structure File Manager uses to communicate with the RAM Disk Driver. /* refer to the RAM DISK driver documentation for */ /* more information on the RAM DISK Parameter Block */ struct RD_PARM_S { WORD dir; /* xlate sect to seg, or seg to sect */ WORD size; /* number of consecutive sectors */ WORD segment; /* segment address*/ WORD count; /* count of bytes to check boundary */ /* if outp count!= inp count, only */ /* outp count bytes are within same */ /* boundary */ WORD sector; /* sector number */ WORD pagenum; /* EMS logical page number, */ /* = -1 if not EMS */ }; #define RD_PARMT struct RD_PARM_S #define RD_PARMP RD_PARMT far* #define RD_PARMSIZE sizeof(RD_PARMT) 5-75 Series 3000 Application Programmer’s Reference Manual File Manager First Data Segment struct FIRSTSEG_S { int overhead; /* reser sect # + fat sect # + */ /* dos dir sect #**/ /* NOTE: MUST be the first word in */ /* first sect since a faked first seg */ /* was set up in minit */ int dos_cluster_size; /*size of a dos cluster = */ /* bytes/sect*sect/clus*/ BYTE min_seg_size; /* min segment size,in # of */ /* dos clusters */ BLKLINKT fdbhead; /* NOTE: fdb head and tail */ /* must be together */ BLKLINKT fdbtail; /* since they are initialized */ /* together */ WORD seg_total; /* total num of segments used */ /* in table */ SEG_INFOT seg_table[MaxSegNum]; /* ea entry cnvt's */ /* 2 bytes seg adr to one byte */ BPBT bpbbuf; /* save a copy of the bpb */ BLKLINKT freehead; /* NOTE:freehead & freetail */ /* MUST be the last */ BLKLINKT freetail; /* 2 fields in this struct for */ /* initialization*/ }; #define FIRSTSEGT struct FIRSTSEG_S #define FIRSTSEGP FIRSTSEGT far * #define FIRSTSEGSIZE sizeof(FIRSTSEGT) struct FIRSTSEG_S_N { int overhead; /* reser sect # + fat sect # + */ /* dos dir sect # */ /* NOTE: MUST be the first word in */ /* first sect since a faked first seg */ /* was set up in minit */ int dos_cluster_size; /* size of a dos cluster = */ /* bytes/sect*sect/clus */ BYTE min_seg_size; /* user specified minimum DOS */ /* data segment size */ 5-76 UBASIC Record Manager BLKLINKT fdbhead; /* NOTE: fdb head and tail */ /* must be together */ BLKLINKT fdbtail; /* since they are initialized */ /* together */ WORD seg_total; /* total num of segments used */ /* in table */ SEG_INFOT seg_table[1]; /* ea entry cnvt's 2 bytes */ /* seg adr to one byte*/ }; #define FIRSTSEGT_N struct FIRSTSEG_S_N #define FIRSTSEGSIZE_N sizeof(FIRSTSEGT_N) Header of Cluster Variant Files This structure contains the information needed by all the file manager operations for a cluster variant file. struct CVHEADER_S { WORD blklen; /* length of CV cluster */ BYTE rectypcnt; /* # of rec types in this cluster */ BYTE reccnt; /* # of rec in this cluster */ BYTE rectype[CVHeaderBufSize-4]; }; #define CVHEADERT struct CVHEADER_S #define CVHEADERP CVHEADERT far * #define CVHEADERSIZE sizeof(CVHEADERT) #define FIRSTRECTYP 4 /* offset of first record type */ 5-77 Series 3000 Application Programmer’s Reference Manual Block Traverse Return Parameter Block This structure is mainly used by the blk_traverse( ) routine. It contains two pointers that may be useful for the caller of the blk_traverse( ) routine. struct TRAVERSE_S { BLKLINKP curblkptr; BLKLINKP prevblkptr; }; #define TRAVERSET struct TRAVERSE_S #define TRAVERSEP TRAVERSET far * #define TRAVERSESIZE sizeof(TRAVERSET) File Manager Work Buffer Instead of passing returning parameters on the stack, the Work Buffer is a more efficient way to communicate information among the file manager subroutines. struct WORKBUF_S { long sav_stk_ptr; /* save ss:sp for deeply nested */ /* error return*/ /*** MUST be the first var in ***/ /*** workbuf ***/ WORD ds; /* save user ds so that the ds can */ /* be used to address the workbuf */ /* with a near ptr */ /*** MUST be the second var in ***/ /*** workbuf ***/ WORD ftype_offset; /* linked/variant fixed/cluster, */ /* for dispatcher*/ BYTE sav_write_protect; /* save global write protect */ /* flag */ /* these variables are parameters passed to the fmgr */ /* routines from the application (C or Pcode */ /* interpreter). They are saved here for easy access */ 5-78 UBASIC Record Manager WORD fixed_rec_len; WORD recs_per_cluster; char far *type_table_addr; WORD type_table_size; WORD cluster_size; char far *filename; BYTE filetype; WORD far *recnum; WORD far *reclen; BYTE far *rectype; WORD searchstart; WORD searchend; char far *rec_info; /* ramdisk related work var's */ BPBP bpb_ptr; /* pt to bpb in ramdisk */ FAT_ENTRYP fat_ptr; /* pt to a fat entry */ BYTE next_largest; /* next larger num of */ /* allocatable FAT */ FIRSTSEGP first_seg_ptr; /* pt to first seg */ /* allocated to UBASIC.FMG */ WORD first_seg_pagenum; /* EMS log page num of */ /* first seg */ FAT_ENTRYP fat_tail_ptr; /* pt to tail of */ /* UBASIC.FMG fat chain */ WORD fat_tail_num; /* fat number of tail of */ /* UBASIC.FMG */ char far *sector_0_adr; /* pt to first byte in */ /* ramdisk */ DOS_FDP ubs_dirptr; /* pt to UBASIC.FMG DOS */ /* file dir entry */ WORD last_fat_entry_num; /* last fat ent num in */ /* fat, start counting frm 2 */ FAT_ENTRYP last_fat_entry_ptr;/* ptr to one byte */ /* after last fat entry */ /* EMS related work var's */ char context_buf[CONTEXT_BUF_SIZE]; /* context buf */ /* of page frame info */ BOOLEAN EMS_flag; /* TRUE if EMS is present */ WORD fix_rem_byte; /* upper byte of logical */ 5-79 Series 3000 Application Programmer’s Reference Manual /* page # to indicate fixed */ /* or removable EMS */ WORD pageframe[PhyPageCnt];/* rec which logical */ /* EMS page is mapped */ BYTE phy_page_num; /* next phy page to map */ /* to (set by fmgr) */ BYTE desired_phy_page_num; /* desired phy page to */ /* map to (set by appl) */ BYTE max_phy_page_num; /* largest phy page num */ /* to map to b4 wrap around */ /* miscellaneous */ BYTE closebit; /* for files open 4 both,close */ /* input/output flg */ BYTE user_rectyp; /* save user specified rec type */ /* for var file */ WORD user_reclen; /* save user specified rec len */ /* for var file */ BYTE seq_rectyp_flg; /* search sequentially for */ /* next rec type flag*/ FCBP fcbptr; /* pt to user fcb, used in */ /* posterror() */ FCBSIDEP sideptr; /* pt to req (input or print) */ /* side of FCB */ BYTE lastop; /* save last operation mode from */ /* fcb in wrk buf */ BLKLINKP curblkptr; /* current block ptr in a */ /* linked list */ BLKLINKP prevblkptr; /* previous block ptr in a */ /* linked list */ /* note: the order of curblkptr and */ /* prevblkptr must be the same as */ /* TRAVERSET */ WORD blkoffset; /* block number to traverse */ WORD recoffset; /* record number to traverse */ BLKLINKT curfib; /* 3-byte ptr to current FIB */ BLKLINKT curfib_firstblkptr; /* ptr in curfib to */ /* the first data block */ WORD curfib_length;/ /* length of curfib */ WORD curfib_pagenum; /* index part of the 3-byte */ /* ptr to current FIB */ 5-80 UBASIC Record Manager BLKLINKT curfdb; /* ptr to current FDB in RAMDISK */ FDBT fdbbuf; WORD ramdisk_drv; /* the ramdisk drive # */ BLKLINKT null_blklink; /* for fast assignments */ /* work var's for cluster variant files */ CVHEADERT CVheaderbuf; /* save header info for */ /* CV file */ WORD CVfirstrecnumnxt; /* first rec number of next */ /* CV cluster */ char far *CVfirstrecptr; /* pt to first rec in a */ /* CV cluster */ byte far *CVcurtypptr; /* pt to cur rec type in a */ /* CV cluster */ char far *CVcurrecptr; /* pt to cur rec in a CV */ /* cluster */ WORD CVcurrecnum; /* current rec num in a CV */ /* cluster */ WORD CVreccnt; /* rec cnt remaining in a CV */ /* cluster */ WORD CVrectypcnt; /* rec type cnt remaining in */ /* a CV cluster */ BYTE CVfreerec_flg; /* 1 = cur record is free */ WORD CVfreespace; /* amt of free space in a */ /* cluster */ WORD CVxferrectypcnt; /* # of record types to */ /* xfer to new cluster*/ WORD CVxferreccnt; /* # of records to xfer to */ /* new cluster */ WORD CVxferreclen; /* len of data to xfer to */ /*new cluster */ char far *CVsaveptr; char far *CVfirstdatabyteptr; }; #define WORKBUFT struct WORKBUF_S #define WORKBUFP WORKBUFT far * #define WORKBUFP_N WORKBUFT near * #define WORKBUFSIZE sizeof(WORKBUFT) 5-81 Series 3000 Application Programmer’s Reference Manual MCREATE Parameter Blocks The MCREATE Parameter Blocks contain file creation information required by the file manager mcreate() routine. Based on the file type, the appropriate structure should be initialized and the address of the structure passed to mcreate( ). Functionally, they are equivalent to the UBASIC Interface Variables. union CREATE_PARM_U { struct { WORD fixed_rec_len; }linked_fixed; struct { char far *type_table_addr; WORD type_table_size; char far *rec_info; }linked_variant; struct { WORD fixed_rec_len; WORD recs_per_cluster; }cluster_fixed; struct { char far *type_table_addr; WORD type_table_size; char far *rec_info; WORD cluster_size; }cluster_variant; }; #define CREATE_PARMT union CREATE_PARM_U #define CREATE_PARMP CREATE_PARMT far * #define CREATE_PARMSIZE sizeof(CREATE_PARMT) 5-82 UBASIC Record Manager URM Global Prototypes Memory Manager Functions extern void far * far blk_alloc(WORD blklen, ⇒ BYTE desired_phy_page_num); extern BOOLEAN far blk_delete(BLKLINKP linkptr, ⇒ WORD blknum, ⇒ WORD blklen); extern BOOLEAN far blk_free(void far *linkptr, ⇒ WORD blklen); extern BLKLINKP far blk_insert(BLKLINKP linkptr, ⇒ WORD blknum, ⇒ WORD blklen, ⇒ BYTE desired_phy_page_num); extern WORD far blk_search(BLKLINKP linkptr, ⇒ WORD srchindex, ⇒ BYTE srchtype, ⇒ WORD fieldoffset, ⇒ char far *key, ⇒ WORD keylen); extern BYTE far blk_traverse(BLKLINKP linkptr, ⇒ int blknum, ⇒ TRAVERSEP t_ptr); 5-83 Series 3000 Application Programmer’s Reference Manual File Manager Functions extern int far mclose(FCBP fcbptr, BYTE closebit); extern int far mcreate(BYTE filetype,char far *filename, ⇒ CREATE_PARMP cparmp); extern int far mcrunch(char far *filename); extern int far mdelete(FCBP fcbptr,WORD far *reclen, ⇒ WORD far *recnum, BYTE far *rectype); extern int far merase(FCBP fcbptr); int mfree(WORD recsize,ULONG *total,char *filename); extern int far minit(WORKBUFP wrkbufp, WORD min_seg_size); extern int far minput(FCBP fcbptr, WORD far *reclen, ⇒ WORD far *recnum, ⇒ BYTE far *rectype); extern int far minsert(FCBP fcbptr, WORD far *reclen, ⇒ WORD far *recnum, ⇒ BYTE far *rectype); extern int far mopen(FCBP fcbptr, BYTE openbit); extern int far mprint(FCBP fcbptr, WORD far *reclen, ⇒ WORD far *recnum, ⇒ BYTE far *rectype); extern int far msearch(FCBP fcbptr, ⇒ WORD far *srchindex, ⇒ BYTE srchtype, ⇒ int searchstart, ⇒ int searchend, ⇒ WORD far *reclen, ⇒ WORD far *recnum, ⇒ BYTE far *rectype); extern void far mterminate(void); 5-84 UBASIC Record Manager Error Codes (Record Manager/File Manager) Table 5-3 lists the possible error conditions returned by the UBASIC Record Manager . Each error code is accompanied by its symbolic name and definition. Table 5-3. UBASIC Record Manager Error Codes Error Code Symbolic Name Description 0Successful No error 1 NoDataTimeout No data within RCVTIME 2 MaxRetryCount Max retries failed 3 LineDrop Communication line lost 4 ReceiveAbort Received a request to abort 5 InvalidFileNo Channel number illegal 6 AlreadyOpen File is already opened 7 NotYetOpen File is not yet opened 8 InvalidDevice Invalid device for this operation 9 CantExecute Operation illegal or unknown 10 ReceiveRvi Received an RVI from remote 11 EndOfFile End of file reached 12 NoSuchRecord Can't find requested record 13 FileNotFound Can't find requested file 14 DeviceInUse Device is already open 15 DeviceOutputErr Can't output to device 16 PackedIndexErr Packed index not word aligned 17 ReceiveEot Received an end of transmit 18 DataOverRun Data buffer too small 115 RamDiskErr Error generated by the RAM disk driver 5-85 Series 3000 Application Programmer’s Reference Manual Table 5-4 lists the possible error conditions returned by the UBASIC File Manager . Each error code is accompanied by its symbolic name and definition. Table 5-4. File Manager Error Codes Error Code Symbolic Name Description -1 NotRequired minit not required 0Successful No error 1 NoDataTimeout No data within RCVTIME 2 MaxRetryCount Max retries failed 3 LineDrop Communication line lost 4 ReceiveAbort Received a request to abort 5 InvalidFileNo Channel number illegal 6 AlreadyOpen File is already opened 7 NotYetOpen File is not yet opened 8 InvalidDevice Invalid device for this operation 9 CantExecute Operation illegal or unknown 10 ReceiveRvi Received an RVI from remote 11 EndOfFile End of file reached 12 NoSuchRecord Cant find requested record 13 FileNotFound Can't find requested file 14 DeviceInUse Device is already open 15 DeviceOutputErr Can't output to device 16 PackedIndexErr Packed index not word aligned 17 ReceiveEot Received an end of transmit 18 DataOverRun Data buffer too small 112 WriteProtect Attempt to write to protected memory 113 EndofSegTab Search beyond end of segment table 114 NoDirError No space for UBASIC.FMG in DOS file directory 115 RamDiskErr Error generated by the ramdisk driver 116 DefaultDrv Default drive must be >= C: 5-86 UBASIC Record Manager Table 5-4. File Manager Error Codes (Continued) Error Code Symbolic Name Description 117 SegSizeErr Min seg size or alloc size bigger than max 118 FmgrNoMemory FMGR failed to allocated from RamDisk 119 WrongFileType Filename bit doesn't match type 120 AlreadyExists File already exists 121 Unimplemented Routine not implemented 122 NoSuchRoutine Access out of dispatch table 123 RecTypNotMatch Record type for Print different 124 BadCreateParm Create parameter is invalid 125 RecordTooBig Rec too big for cluster 126 ContextSizeErr EMS context buf size not match 127 EMSContextErr Starting phy page # or page cnt out of range 128 EMSMapErr Fail to map a logical page 5-87 Series 3000 Application Programmer’s Reference Manual 5-88 Chapter 6 Miscellaneous Libraries and Functions Chapter Contents Introduction ...... 6-3 Batch RF Interface Library ...... 6-4 BRFEnable ...... 6-5 BRFDisable ...... 6-6 BRFLoadConfig ...... 6-7 BRFGetStats ...... 6-8 Calculator Library ...... 6-9 CalcPresent ...... 6-10 Calculate ...... 6-11 Floating Point Calculation Library ...... 6-15 Error Codes...... 6-16 Sample Program...... 6-16 FppAdd ...... 6-17 FppConvert...... 6-18 FppDiv...... 6-19 FppFloatToStr...... 6-20 FppMath ...... 6-21 FppMul ...... 6-22 FppPresent ...... 6-23 FppStrToFloat...... 6-24 FppSub...... 6-25 Graphics Library ...... 6-26 SFArc ...... 6-27 SFClearArea ...... 6-28 SFClearScreen ...... 6-29 SFDisplayFile ...... 6-30 SFDrawLine ...... 6-31 SFEllipse ...... 6-32 SFEndGraphics...... 6-33 SFGetImage...... 6-34 SFGetPixel ...... 6-35 SFGetPosition ...... 6-36 SFImageSize ...... 6-37 6-1 Series 3000 Application Programmer’s Reference Manual SFInitGraphics ...... 6-38 SFMoveTo ...... 6-39 SFPutCharText ...... 6-40 SFPutImage...... 6-41 SFPutStrText ...... 6-42 SFRectangle...... 6-43 SFSetPixel ...... 6-44 Macro Processing Manager (MPM3000.EXE) ...... 6-45 MPMLoadFile...... 6-48 Printer Interface Library (PS1Kx.LIB) ...... 6-49 Error Codes...... 6-49 Wireless Printing ...... 6-51 Application Programming Interface (API)...... 6-52 Symbol Utility Library (SYMUTILx.LIB) ...... 6-77 KBD3000 Interface Functions ...... 6-78 KBDRestore...... 6-79 KBDLoadFile ...... 6-80 KBD3000 Error Codes ...... 6-81 Miscellaneous Functions...... 6-82 TSRLoaded ...... 6-83 TSRRegistrationCheck...... 6-84 _STORDS...... 6-85 _RESTORDS ...... 6-86 6-2 Miscellaneous Library Functions Introduction This chapter provides reference descriptions of functions provided in a variety of small, special purpose libraries included in the ADK. The libraries are: • Batch RF Interface library (BATCHRFx.LIB) • Calculator Library (CALCTSR) • Floating Point Calculation Library (FPPRES or FPPTSR) • Graphics Library (SFGRAPHx.LIB) • Macro Processing Manager (MPM3000.EXE) • Printer Interface Library (PS1Kx.LIB) • Symbol Utility Library (SYMUTILx.LIB) - KBD3000 Interface Functions - MPM3000 Interface Functions - Miscellaneous Functions (TSRLoaded , TSRRegistrationCheck, _STORDS, and _RESTORDS) 6-3 Series 3000 Application Programmer’s Reference Manual Batch RF Interface Library Table 6-1 lists the functions contained in the Batch RF Interface Library in the ADK along with short descriptions of each. Detailed descriptions of each finction in the same order they are listed in the table are provided on the pages that follow. Table 6-1. Batch RF Interface Library Functions Function Description BRFEnable Activates the BATCHRF utility abd begins data transmission as a background process BRFDisable Ends data trans mission by the BATCHRF utility BRFLoadConfig Loads a BATCHRF initialization (.INI) file BRFGetStats Reads current BATCHRF statistics 6-4 Miscellaneous Library Functions BRFEnable Purpose Use BRFEnable in a batch data collection program to activate BATCHRF, beginning data transmission as a background process. Syntax #include <3000\batchrf.h> int BRFEnable( void ) Description BRFEnable activates the BATCHRF TSR, to start it transmitting collected data over the Spectrum One network. The application program collects batch data, writing that data to a specified file. As records become available, BATCHRF transmits them to the host. To use BRFEnable, the application must be linked with BATCHRFx.LIB, where x is either s (small model), m (medium model), or l (large model). Return Values 1 = successful 0 = failure See Also Description of Batchrf.exe in Chapter 1, Utilities. 6-5 Series 3000 Application Programmer’s Reference Manual BRFDisable Purpose Use BRFDisable to end data transmission by BATCHRF. Syntax #include <3000\batchrf.h> int BRFDisable( void ) Description BRFDisable deactivates the BATCHRF TSR, ending transmission of data to the Spectrum One host. To use BRFDisable, the application must be linked with BATCHRFx.LIB, where x is either s (small model), m (medium model), or l (large model). After using BRFDisable, the collection data file should be purged by the application before issuing another BRFEnable( ). Return Values 1 = successful 0 = failure See Also Description of Batchrf.exe in Chapter 1, Utilities. BRFEnable( ) 6-6 Miscellaneous Library Functions BRFLoadConfig Purpose Use BRFLoadConfig to load another BATCHRF initialization file. Syntax #include <3000\batchrf.h> int BRFLoadConfig( unsigned char _far *fname) Description BRFLoadConfig loads a new BATCHRF initialization file, changing the data and timing characteristics. To use BRFLoadConfig, the application must be linked with BATCHRFx.LIB, where x is either s (small model), m (medium model), or l (large model). Return Values 0 Successful load 1 No timers available 2 Config file not found 3 Error opening config file 4 Config file syntax error 5 Config file does not contain the proper number of parameters See Also N/A 6-7 Series 3000 Application Programmer’s Reference Manual BRFGetStats Purpose Use BRFGetStats to read the current BATCHRF statistics. Syntax #include <3000\batchrf.h> void BRFGetStats( STATUS_TYPE *statbuf) Description BRFGetStats returns a status report on BATCHRF activity. The status types are defined in STATS_TYPE structure in batchrf.h (see below). To use BRFGetStats, the application must be linked with BATCHRFx.LIB, where x is either s (small model), m (medium model), or l (large model). Return Value The STATS_TYPE structure provides the following data. Each field is defined as an unsigned long integer. Define Name Description NumTx Number of records transmitted NumAck Number of records acknowledged NumTs Number of records tombstoned RetryDOS Number of retries caused in DOS RetryOOR Number of retries caused by Out Of Range error RetryNAK Number of retries caused by NAK RetryTMO Number of retries caused by timeout NumEof Number of retries caused by End Of File See Also N/A 6-8 Miscellaneous Library Functions Calculator Library The Calculator Library provides a full set of arithmetic functions that you can easily incorporate into your applications. Calculator is a TSR (CALCTSR.EXE) that remains in memory and services software interrupts. This TSR must be loaded before the Calculator function can be called. For C programming, a ready-to-use function lets you call the Calculator. The Calculator function is described in detail on the pages that follow. 6-9 Series 3000 Application Programmer’s Reference Manual CalcPresent Purpose Use CalcPresent to check whether or not the calculator is loaded. Syntax #include <3000\calc.h> extern int far CalcPresent(void); Description The CalcPresent function calls software interrupt C8H to check the calculator’s registration. Returns CalcPresent returns a non-zero number if the calculator is loaded. Example #include<3000\calc.h> If(!calcPresent( )) { printf(“Calculator not loaded.\n”); exit(0)); }; 6-10 Miscellaneous Library Functions Calculate Purpose Use Calculate to perform a full set of arithmetic functions within an application. Syntax #include char far * far Calculate(unsigned int fielddesc, ⇒ unsigned char fieldlen, ⇒ unsigned char datatype, ⇒ unsigned char row,unsigned char col, ⇒ char far *str, unsigned char * key); Description The Calculate function provides a full set of arithmetic functions from within an application. The calculator is invoked via a call from the application. The application programmer might also allow the terminal operator to press a key which invokes the calculator function. Once entered, the calculator function takes control until a result is returned to the application. The Calculate function contains seven input parameters which have the following values: Parameter Value fielddesc Field descriptor informing the calculator of the data entry characteristics being used. The bit values of this one word field are: 15 = Alpha shift enabled 14 = Left to right entry 13 = Right to left entry 12 = Update allowed 11 = Wandable 10 = Skip field 9 = Prompt field 6-11 Series 3000 Application Programmer’s Reference Manual 8 = Fill character present 7 = Unused 6 = Unused 5 = Zero filled field 4 = Calculator enabled 3 = Must press fieldlen Field Length. Informs the calculator of the size of the field being entered. datatype Data Type of Target. Inform the calculator of the type of data being entered as follows. 0 = Byte Integer 1 = Word Integer 2 = BCD 3 = Packed String 4 = String 5 = Floating Point row Field Start Row. Sets the screen location where data entry is to be performed. col Field Start Column. Sets the screen location where data entry is to be performed. str Pointer to null-terminated data string containing the initial value of the field. Use this parameter to supply a value from the current data entry field. If no value is supplied, a pointer to a null terminator must be passed as this parameter. key Key that causes the calculator to exit. Causes the key that invoked the calculator to also be the key that exits the calculator. 6-12 Miscellaneous Library Functions Return Value The Calculate function returns a pointer to a null terminated data string containing the new value of the field or NULL, if no new value was calculated. It is up to the application to replace the original value with the newly calculated value if desired. Example /* Program: calctest.c */ #include “calc.h” #include char *newval; if ( !CalcPresent() ) { BiosBeep(100L); printf("Calculator not loaded\n"); exit(0); }; BiosClrScr(7); BiosSetCursorPos(5,0); printf("Starting string: '%s'\n",buffer); newval = Calculate(0,6,WORDINTEGER,0,0,buffer,ESCAPE); BiosSetCursorPos(6,0); if ( newval != NULL ) printf("New value '%s'\n",newval); else printf("Value unchanged\n"); }; 6-13 Series 3000 Application Programmer’s Reference Manual See Also N/A 6-14 Miscellaneous Library Functions Floating Point Calculation Library Table 6-2 lists the functions contained in the Floating Point Calculation Library provided in the ADK. These functions can be invoked in an application to perform floating point calculations. Detailed descriptions (in the same order the functions are listed in the table) are provided on the pages that follow. Table 6-2. Floating Point Calculation Library Functions Function Description FppAdd Adds two floating point numbers FppConvert Performs the specifies operation on a source and outputs the result to a destination FppDiv Divides one floating point number by another FppFloatToStr Converts a floating point number to a string FppMath Performs the indicated operation on two floating point numbers FppMul Multiplies one floating point number by another FppPresent Checks on whether or not the floating point library is loaded. FppStrToFloat Converts a string to a floating point number FppSub Subtracts one floating point number from another One of the following resident libraries must be loaded before executing these functions: FPPRES.EXE FPPTSR.EXE 6-15 Series 3000 Application Programmer’s Reference Manual Error Codes The following error conditions may be returned by the floating point functions. Return Value Meaning 0 Success (No error) 7 Overflow/Underflow 8 Conversion size error (String too small) 9 Conversion type error (Invalid format) 10 Divide by zero Sample Program The FPPTEST.C program is included in the C:\3000\SAMPLE directory of the ADK to illustrate floating point functions. 6-16 Miscellaneous Library Functions FppAdd Purpose Adds two floating point numbers and outputs the result to the destination. Syntax #include <3000\fpp.h> extern int far FppAdd(char far *dest,char far *scr1, ⇒ char far *src2); Description The FppAdd function adds two floating point numbers (src1 and src2) and outputs the result to dest. One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 7 Overflow/Underflow See Also FppSub, FppMul, FppDiv, FppRes, FppTsr 6-17 Series 3000 Application Programmer’s Reference Manual FppConvert Purpose Performs specified operation on the source and outputs the result to the destination. Syntax #include <3000\fpp.h> extern int far FppConvert(int operation,char far *dest, ⇒ int destlen,char far *src); Description The FppConvert function is the base function that is used by two higher level functions: FppFloattostr and FppStrtofloat. FppConvert performs the operation specified (conversion from a string to a floating point number or vice versa) on the source (src) and outputs the result to dest (destination). One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 8 Conversion size error (String too small) 9 Conversion type error (Invalid format) See Also FppFloatToStr, FppStrToFloat, FppRes, FppTrs 6-18 Miscellaneous Library Functions FppDiv Purpose Divides two floating point numbers and outputs the result to destination. Syntax #include <3000\fpp.h> extern int far FppDiv(char far *dest,char far *scr1, ⇒ char far *src2); Description The FppDiv function divides two floating point numbers (src1 by src2) and outputs the result to dest. One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 7 Overflow/Underflow 10 Divide by zero See Also FppMul, FppAdd, FppSub 6-19 Series 3000 Application Programmer’s Reference Manual FppFloatToStr Purpose Converts a floating point number to a string. Syntax #include <3000\fpp.h> extern int far FppFloatToStr(char far *dest,int destlen, ⇒ char far *src2); Description The FppFloatToStr function converts a floating point number (src2) to a string (dest). destlen determines the string length. The format of the string depends on the value of the floating point (src2) and the length of the string. If the value can be placed into the string in unscaled notation without any loss of significant digits, then it will be stored in unscaled notation. Otherwise, scaled notation is used resulting in a loss of significant digits, but a preservation of magnitude. One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 8 Conversion size error (String too small) See Also FppStrToFloat 6-20 Miscellaneous Library Functions FppMath Purpose Performs the specified operation on two floating point numbers and reports the result. Syntax #include <3000\fpp.h> extern int far FppMath(int operation,char far *dest, ⇒ char far *src1,char far *src2); Description The FppMath function is the base function that is used by four higher level macros: FppAdd, FppSub, FppMul, and FppDiv. FppMath performs the operation specified (addition, subtraction, multiplication, or division) on two floating point numbers (src1 and src2) and outputs the result to dest (destination). One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 7Overflow/Underflow 10 Divide by zero See Also FppAdd, FppSub, FppMul, FppDiv, FppRes, FppTsr 6-21 Series 3000 Application Programmer’s Reference Manual FppMul Purpose Multiplies two floating point numbers and outputs the result to the destination. Syntax #include <3000\fpp.h> extern int far FppMul(char far *dest,char far *scr1, ⇒ char far *src2); Description The FppMul function multiplies two floating point numbers (src1 and src2) and outputs the result to dest. One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 7Overflow/Underflow See Also FppDiv, FppAdd, FppSub 6-22 Miscellaneous Library Functions FppPresent Purpose Use FppPresent to check on whether or not the floating point library is loaded. Syntax #include <3000\fpp.h> extern int far FppPresent(void); Description The FppPresent function calls software interrupt C8H to check the registration of the floating point library. Returns FppPresent returns a non-zero number if the library is loaded. Example #include <3000\fpp.h> if(!FppPresent( )) { printf(“Floating library not loaded.\n”); exit(0); }; 6-23 Series 3000 Application Programmer’s Reference Manual FppStrToFloat Purpose Converts a string to a floating point number. Syntax #include <3000\fpp.h> extern int far FppStrToFloat(char far *dest,char far *scr); Description The FppStrToFloat function converts a string (src2) to a floating point number (dest). One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 9 Conversion type error (Invalid format) See Also FppFloatToStr 6-24 Miscellaneous Library Functions FppSub Purpose Subtracts two floating point numbers and outputs the result to the destination. Syntax #include <3000\fpp.h> extern int far FppSub(char far *dest,char far *scr1, ⇒ char far *src2); Description The FppSub function subtracts two floating point numbers (src2 from src1) and outputs the result to dest. One of the following resident libraries must be loaded before executing this function: FPPRES.EXE FPPTSR.EXE Return Value Value Meaning 0 Success (No error) 7Overflow/Underflow See Also FppAdd, FppMul, FppDiv, FppRes, FppTsr 6-25 Series 3000 Application Programmer’s Reference Manual Graphics Library The graphics functions, for which descriptions begin on the next page, provide basic line drawing and fill capabilities for including graphics in the application display. All of the drawing routines use logical coordinates as a parameter passing convention. The drawing routines which create geometric shapes and lines use the Fill Mask and Line Type settings when drawing, and are optional on some routines. The rectangle, ellipse, arc, and wedge (called the “pie”) are the four basic shapes supported by these functions. 6-26 Miscellaneous Library Functions SFArc Purpose Use SFArc to draw an elliptical arc within a bounding rectangle. Syntax #include <3000\sfgraph.h> int SFArc(int x1, int y1, int x2, int y2, ⇒ int StartVecX, int StartVecY, int EndVecX, ⇒ int EndVecY) Description SFArc draws an elliptical arc within the bounding rectangle. The arc is clipped from the center of the ellipse to the start and end vectors supplied. The points given by (x1,y1) (x2,y2) form the bounding rectangle for the ellipse. StartVec and EndVec represent the portion of the ellipse which will be drawn for the arc. Example Call int SFRectangle(59, 0, 179, 62, 59, 0, 119, 63); Returns Values Meaning 0 Successful. 1Invalid. x2 is less than x1. 2Invalid. y2 is less than y1. See Also N/A 6-27 Series 3000 Application Programmer’s Reference Manual SFClearArea Purpose Use SFClearArea to clear the area within a bounding rectangle. Syntax #include <3000\sfgraph.h> void SFClearArea(int x1, int y1, int x2, int y2, color); Description SFClearArea clears the space within the rectangle determined by (x1, y1) (x2, y2), and fills the area with the specified color. Color options are _SFWHITE and _SFBLACK. Example Call SFClearArea(0, 0, 119, 63, _SFWHITE); Returns None See Also N/A 6-28 Miscellaneous Library Functions SFClearScreen Purpose Use SFClearScreen to clear the entire graphics screen. Syntax #include <3000\sfgraph.h> void SFClearScreen( void ); Description SFClearScreen clears the entire graphics screen area without regard to logical coordinates. Example Call SFClearScreen(); Returns None See Also SFClearArea( ) See Also N/A 6-29 Series 3000 Application Programmer’s Reference Manual SFDisplayFile Purpose Use SFDisplayFile to display a .BMP or .SFF file. Syntax #include <3000\sfgraph.h> int SFDisplayFile(char *fname, int x1, int y1) Description Displays a one-bit, one-plane, monochrome device independent bitmap file, as specified by Microsoft (R) Windows (TM) 3.0. SFDisplayFile can also display an SFF as converted by the BMP2SFF.EXE utility program. Displaying an SFF file is faster than a BMP. Example Call SFDisplayFile("D:\\LOGO.BMP", 0, 0); Returns Values Meaning 0 BMP or SFF file displayed. Success. 2 Invalid file type. See Also N/A 6-30 Miscellaneous Library Functions SFDrawLine Purpose Use SFDrawLine to draw a line to a specified point. Syntax #include <3000\sfgraph.h> int SFDrawLine(int x1, int y1); Description SFDrawLine draws a line from the current position to the specified target (x1,y1), using the current color. The current position is updated to the target (x1,y1). Example Call int SFDrawLine(10, 60); Returns Always returns Success: Values Meaning 0 Successful See Also SFMoveTo See Also N/A 6-31 Series 3000 Application Programmer’s Reference Manual SFEllipse Purpose Use SFEllipse to draw an ellipse within a bounding rectangle. Syntax #include <3000\sfgraph.h> int SFEllipse(int fillmask, int x1, int y1, int x2, int y2); Description SFEllipse draws an ellipse within the bounding rectangle determined by (x1, y1) (x2,y2). The fill option is specified by fillmask, which can be either _SFGBORDER or _SFFILLINTERIOR. Example Call SFEllipse(_SFGBORDER, 5, 5, 119, 60); Returns Values Meaning 0 Successful. 1 Invalid. x2 is less than x1. 2 Invalid. y2 is less than y1. See Also N/A 6-32 Miscellaneous Library Functions SFEndGraphics Purpose Use SFEndGraphics to end the graphics session and restore the original text softfonts. Syntax #include <3000\sfgraph.h> void SFEndGraphics( void ); Description SFEndGraphics ends the graphics session, restoring the original mode and fonts. Example Call SFEndGraphics(); Returns None See Also SFInitGraphics( ) See Also N/A 6-33 Series 3000 Application Programmer’s Reference Manual SFGetImage Purpose Use SFGetImage to copy the contents of a rectangular area specified from the screen into a buffer. Syntax #include <3000\sfgraph.h> void SFGetImage(int x1, int y1,int x2, int y2, void _far *bufptr) Description SFGetImage performs the same function as BiosTextRectToMem( ), except using graphical coordinates. The amount of space required in bufptr can be computed by the same methods applied to BiosTextRectToMem( ), then dividing the x value by 6 and adding 1, and the y value by 8 then adding 1. Example: x = (119 - 0) / 6 + 1; Entire Top Row Note: width of screen in pixels y = (63 - 0) / 8 + 1; Entire Columns Note: height of screen in pixels bufsize = x * y; 20 * 8 == 160 Clips to the borders if coordinates are out of range. Example Call void SFGetImage( 0, 0, 119, 63, bufptr); Returns None See Also SFPutImage 6-34 Miscellaneous Library Functions SFGetPixel Purpose Use SFGetPixel to get the color of a single pixel. Syntax #include <3000\sfgraph.h> COLOR SFGetPixel( int x, int y ); Description SFGetPixel gets the color of the pixel at (x,y). Example Call COLOR color; color = SFGetPixel( 63, 31); Returns Color: Values Meaning -1 BIX_XOR 0 BIT_CLEAR 1 BIT_SET See Also SFSetPixel( ) 6-35 Series 3000 Application Programmer’s Reference Manual SFGetPosition Purpose Use SFGetPosition to get the current virtual port coordinate position. Syntax #include <3000\sfgraph.h> COORD_PAIR *SFGetPosition( void ); Description SFGetPosition returns a pointer to a COORD_PAIR structure which contains the virtual port coordinate position in logical units. Example Call COORD_PAIR *coords; coords = SFGetPosition(); x = coords -> x_coord; y = coords -> y_coord; Returns Pointer to COORD_PAIR structure See Also SFMoveTo 6-36 Miscellaneous Library Functions SFImageSize Purpose Use SFImageSize to calculate the buffer size required to store an image grabbed using SFGetImage. Syntax #include <3000\sfgraph.h> int SFImageSize(int x1, int y1, int x2, int y2 ); Description SFImageSize calculates the size of the buffer required to store an image captured using SFGetImage. Example Call int ISize; ISize = SFImageSize(0, 0, 119, 63 ); Returns Always 0 (zero). See Also SFGetImage SFPutImage 6-37 Series 3000 Application Programmer’s Reference Manual SFInitGraphics Purpose Use SFInitGraphics to initialize the graphics environment. Syntax #include <3000\sfgraph.h> int SFInitGraphics( void ); Description SFInitGraphics initializes the entire screen for the graphics environment and clears the screen. The old font table is saved for restoration using SFEndGraphics. Example Call SFInitGraphics(); Returns Always 0 See Also N/A 6-38 Miscellaneous Library Functions SFMoveTo Purpose Use SFMoveTo to move the current graphics cursor position within the virtual window. Syntax #include <3000\sfgraph.h> void SFMoveTo(int x1, int y1) Description SFMoveTo moves the current graphics cursor within the virtual window to the position specified by (x1,y1). Example Call SFMoveTo(0, 0); Returns None See Also N/A 6-39 Series 3000 Application Programmer’s Reference Manual SFPutCharText Purpose Use SFPutCharText to place a character on the screen at a text mode coordinate. Syntax #include <3000\sfgraph.h> void SFPutCharText( int x, int y, unsigned char c, char mode); Description SFPutCharText places a character at the specified text coordinate (x,y). The character is displayed in the specified character mode, either _SFNORMAL or _SFREVERSE. SFPutCharText is faster than SFPutCharGraphic. Example Call SFPutCharText( 5, 3, 'A', _SFNORMAL); Returns None See Also SFPutCharGraphic SFPutStrText See Also N/A 6-40 Miscellaneous Library Functions SFPutImage Purpose Use SFPutImage to copy the contents of a buffer to the screen. Syntax #include <3000\sfgraph.h> void SFPutImage(int x1,int y1, int x2, int y2,void _far *bufptr) Description SFPutImage performs the same function as BiosMemToTextRect( ) except using graphical coordinates. (See SFGetImage for buffer size calculation.) SFPutImage clips the image to the borders if the coordinates specified are out of range. Example Call void SFPutImage( 0, 0, 119, 63, bufptr); Returns None See Also SFGetImage SFImageSize See Also N/A 6-41 Series 3000 Application Programmer’s Reference Manual SFPutStrText Purpose Use SFPutStrText to place a character string on the screen at a text coordinate. Syntax #include <3000\sfgraph.h> void SFPutStrText(int x, int y, unsigned char *str, ⇒ char mode); Description SFPutStrText places the null terminated string at the specified text coordinate (x,y). The string is displayed in the specified character mode, either _SFNORMAL or _SFREVERSE. SFPutStrText is faster than SFPutStrGraphic. Example Call SFPutStrText( 3, 5, "ABCDEFG", _SFNORMAL); Returns None See Also SFPutCharText SFPutStrGraphic See Also N/A 6-42 Miscellaneous Library Functions SFRectangle Purpose Use SFRectangle to draw a rectangle on the screen. Syntax #include <3000\sfgraph.h> int SFRectangle(int fillmask, int lx1, int ly1, int lx2, ⇒ int ly2); Description SFRectangle draws a rectangle within the bounding coordinates. An optional fillmask may be specified as either _SFBORDER or _SFFILLINTERIOR. Example Call int SFRectangle(_SFGBORDER, 0, 0, 119, 63); Returns Values Meaning 0 Successful See Also N/A 6-43 Series 3000 Application Programmer’s Reference Manual SFSetPixel Purpose Use SFSetPixel to set a single pixel to the current color. Syntax #include <3000\sfgraph.h> void SFSetPixel( int x, int y ); Description SFSetPixel sets the specified pixel at coordinate (x,y) to the current color. Example Call SFSetPixel( 63, 31); Returns None See Also SFGetPixel( ) See Also N/A 6-44 Miscellaneous Library Functions Macro Processing Manager (MPM3000.EXE) MPM3000 (Macro Processing Manager) is a series 3000 TSR that can record, store, and execute keyboard macros for use on Series 3000 terminals. Note: MPM3000 requires system EPROM 3.02 or above. Macros are saved on the terminal’s RAM disk and can be loaded from any disk device. Usage MPM3000 [-L Filename] [-H xxyy] [-C] where the command line options are: -L (LOAD) Filename can be any valid DOS filename and path. This option loads the file specified by Filename as a keyboard macro file, making all macros in that file active. -H (HOTKEY) This option requires a scan code/ASCII code pair in the HEX form xxyy, where xx is the two-digit scan code for the Record HOTKEY and yy is the two-digit ASCII code for the HOTKEY. The default Record HOTKEY is CTRL-R. See the Recording Macros section below. -C This option disables the macro chaining function, so that key which would branch to another macro will be treated as regular trees. See the Chaining Macros section below. Recording Macros To Record a macro press the Record HOTKEY (CTRL-R) by default. A dual- tone sound will indicate that the user has entered record mode. All keystokes recorded while in record mode will be indicated by a "blip" tone at the keyboard. If the number of keystrokes pressed has exceeded the maximum allowed (63 keys), the "blip" sound will stop. To stop recording, press the Record HOTKEY again. 6-45 Series 3000 Application Programmer’s Reference Manual The Macro Processing Manager will present the SAVE MACRO screen on which you can assign a HOTKEY to the newly-created macro by pressing the desired keystroke. Note: It is recommended that you do not use the Record HOTKEY, CLEAR, or ENTER as HOTKEY assignments. The Macro Processing Manager will indicate that the hot key was saved. Then enter the name of the desired file where the macros in memory will be stored. The default macro file name is D:\CURRENT.KMF. Pressing the CLEAR key will abort the record, and the new macro is lost. Pressing ENTER will save the macro to the file and make it active in memory. When the file is written to the RAM disk, a quick triple beep will sound. The SAVE MACRO screen is removed and the user’s original screen restored. All macros which were currently loaded are saved to the file. To Remove a macro from the set of macros, press the Record HOTKEY twice. When the macro is saved, the space it occupied will be made available for future use, and the HOTKEY assigned is no longer a macro HOTKEY. A maximum of 32 macros can be created, with 63 keystrokes each. If there is no more macro space available to save the current macro, the following message is displayed for 2 seconds: OUT OF SPACE! Chaining Macros One macro can chain to another macro by simply including its HOTKEY in the calling macro. Execution is passed to the new macro, and control is not returned to the original macro. Therefore, any keys pressed after the chaining HOTKEY are not executed. Chaining can be used to increase the number of keystrokes per macro or to create an infinite looping macro. Chaining can be disabled by passing the -C command line switch. The default is chaining enabled. 6-46 Miscellaneous Library Functions Running Macros To run a macro you have created, simply press its HOTKEY. During macro execution, all keystrokes pressed at the keyboard are ignored except the CLEAR key. If the CLEAR key is pressed during macro execution, macro execution stops. MPM3000 and STG3000.EXE MPM3000 can not execute a soft trigger key through STG3000. It is OK to have MPM3000 executing while STG3000 is executing, but MPM3000 can not execute a soft trigger key. It is recommended that you load the STG3000 TSR before loading MPM3000. For a description of the STG3000 TSR, refer to the STG3000.EXE section of the Utilities chapter in this manual. Macro Files Each macro file can contain 32 macros of 64 bytes each. The file occupies 4160 bytes of space. Load the file using the -L command line option. If the TSR is already loaded you can replace the current file by starting the TSR again and passing the -L option with the new file name. 6-47 Series 3000 Application Programmer’s Reference Manual MPMLoadFile This function is in the SYMUTILx.LIB, where x= S (small), M (medium) or L (large). Description Loads a Macro Processing Manager file from disk into memory and makes it the current macro set. Syntax #include <3000\symutil.h> int MPMLoadFile(char _far *fname); Parameter fname is a far pointer to the full path and name of the file, including the extension. Returns Values Meaning 0 Success -1 Failure 6-48 Miscellaneous Library Functions Printer Interface Library (PS1Kx.LIB) There are three models of the Printer Interface Library provided in the C:\3000\LIB directory of the ADK as follows: PS1KL.LIB the large model PS1KM.LIB the medium model PS1KS.LIB the small model The PS1Kx libraries provide C language interface support for the PS1000 bar code printers. Make certain the PS10XX printer being used is compatible with the Symbol terminal to which it is connected. Refer to your PS1000 Series Product Reference Guide. Using the wrong configuration can result in skipped labels or a damaged Printer Interface Module (PIM). Two sample programs are provided with the printer library. The two programs are: PS1K.C Prints some simple labels to the printer. PDF.C Prints two PDF-417 labels to the printer. Requires the PDF1.DAT and PDF2.DAT files on the terminal. They are located on the C:\3000\SAMPLE directory of the ADK. Error Codes When one of the PS1K library functions returns an error code and its status reflects an internal system error, the upper nibble of the status word indicates where the error occurred. 0x2000 Series COM Driver Errors If the upper nibble of the status word is 2h, the lower byte contains a communication driver error code. Communication driver errors are listed in Chapter 2 of the Series 3000 Application Programmer’s Guide. 6-49 Series 3000 Application Programmer’s Reference Manual Example Error: 0x2052==Premature end of transmission. The 52 is the error from the Communication Driver. 4000h - Parallel Services Errors If the upper nibble of the status word is 4h, the lower byte is 01h, indicating that printing was aborted. Either the printer became not ready or the Printer Interface Module (PIM) became disconnected. Example Error: 0x4001==Error While Printing. 8000h - DOS Errors If the upper nibble of the status word is 8h, the lower byte contains a DOS error code. DR DOS errors are described in the DR DOS section of this manual (Chapter 4). Example Error: 0x8006==Illegal File Handle. The 06 hex is the error from DR-DOS. 6-50 Miscellaneous Library Functions Wireless Printing RF Printing Design The RF Wireless Printer feature allows easy, wearable printing without cumbersome cables. The printer and terminal communicate regardless of orientation and alignment with each other. The system works as follows: • There is a master/slave relationship between the terminal (master) and printer (slave). The terminal initiates all communication. • A terminal and printer are linked together using unique addresses and can only communicate with each other when linked, which avoids crosstalk between nearby users. • To link a terminal to a printer, both addresses must be known and set up in the terminal. The user application initiates a link using the library functions provided. Unlinking is not required because the printer is always ready to receive a new link packet. • The PS1K Library supports the Comtec series of Short Range (SRRF) wireless printers. RF Addresses For Comtec printers, the RF address is embedded in the Comtec serial number. The application should ideally be able to key in or scan the serial number directly from this label. The printer’s serial number must be sent as the parameter to the PSComputeComtecID function. The value returned by this function must be used as the input parameter to PSLink. The wireless printing network designer ensures that each terminal in the network has a unique address. This can be done several ways, such as: • Manual entry of known unique addresses • Scanned entry of known unique addresses • Derived from S24 MAC address • Derived from pseudo-random number Creating a Link Use PSLink() to form a link with the specified addresses. Printing can start when a successful link is established. If a linked terminal and printer separate, create a new link by setting up new addresses and linking. 6-51 Series 3000 Application Programmer’s Reference Manual Application Programming Interface (API) The following table lists API functions and their descriptions. Table 6-3. API Functions Function Description PSGetPorts() Lists ports which are suitable for printing. PSStartSession() Sets up a port for printing (any connection is suitable). PSSelectPrinter() Selects one of the supported printer types. PSNewLabel() Discards an old label and begins building a new label. PSBuildLabel() Builds a portion of a label. PSEndLabel() Ends the building of a label, now ready to send. PSSendLabel() Sends the finished label to the port. PSEndSession() Ends the printing session on the port. PSPrinterReady() Checks if the port is ready for printing. PSCatLabel() Concatenates a buffer to the label. PSPrinterStat() Returns status bits of the printer port. PSConnectType() Returns the connection type (Serial or Parallel). PSSetDeliveryMode() Sets the delivery mode to DELIVERY_WAIT or DELIVERY_QUICK. PSSetParameter() Sets communication parameters. Functions that support Comtec SRRF wireless printing: PSLink() Links with the SRRF printer. 6-52 Miscellaneous Library Functions PSGetPorts() Description Lists ports which are suitable for printing. Syntax #include <3000/ps1k.h> void PSGetPorts(PSPORTSLIST *PSPortsList ); Parameters • PSPortsList Specifies a pointer to a PSPORTSLIST structure. This structure has a list of Booleans which represent ports which can be used for printing. Remarks The PSGetPorts function provides information about the terminal communication ports and indicates which ports are suitable as printer ports. The LRT 3800, LDT 3805, PDT 6800, and VRC 3910 always report FALSE for COM2. Older PDT 3300 terminals report COM2 as FALSE when there is a communication adapter board installed. The WWC 1040 and WWC 1049 terminals report TRUE for COM2, even though only the WWC 1049 has the port. To check if your PDT3300 recognizes the adapter board, run the Self Test - Config Screen 1 in the terminal's COMMAND MODE. If COM2 reports S1, the PDT 3300 can recognize the installed adapter board. If the system reports S0, either no board is installed, or it can't recognize the installed board. If you know there is a board installed you may use the port for printing even if PSGetPorts() reports the presence of the port as FALSE. Return Value Fills the structure pointed to by PSPortsList. Example #include <3000/ps1k.h> PSPORTSLIST PSPortsList; PSGetPorts(&PSPortsList ); /* See what ports are available */ if (PSPortsList.Com1 == TRUE) 6-53 Series 3000 Application Programmer’s Reference Manual PSStartSession( COM1); else if (PSPortsList.Com2 == TRUE) PSStartSession(COM2); else { puts("Can't find a suitable port for printing."); exit( 1 ); } 6-54 Miscellaneous Library Functions PSStartSession() Description Sets up a port for printing (any connection is suitable). Syntax #include <3000/ps1k.h> int PSStartSession(unsigned int PSPort ); Parameters • PSPort Specifies a port to begin the session on. Currently, the only two ports are COM1 and COM2 (0 and 1 respectively). Remarks PSStartSession verifies the port is valid, and attempts to open the port through either the LPT driver or the COM driver depending on the detected connection. If the port can't be opened, a Status returns. For wireless printing with the Comtec SRRF printer (WWC 1049), select COM2. Return Value 0 Session Start Successful -4 Unable to allocate SRRF protocol timers Other Error Example #include <3000/ps1k.h> if (PSStartSession( COM1) != 0) puts("Can't open COM1 for printing"); 6-55 Series 3000 Application Programmer’s Reference Manual PSSelectPrinter() Description Selects the printer type. Syntax #include <3000/ps1k.h> void PSSelectPrinter(unsigned int PSPrinterType ); Parameters PSPrinterType Specifies the type of printer to be used during the session. Currently the supported printers are PS1000, PS1001, PS1004, PDDUMB, Monarch RASCAL 9450 model and Pathfinder, and COMTEC MP5020, MP5022 model and the Comtec SRRF wireless printers. Remarks The PSSelectPrinter sets a flag which triggers pre- and post-processing required by each type of printer, performed automatically when building and printing labels. This special processing is: • PS1004: Wake Up Sequence before each print. Uses Hardware Flow Control Protocol. • PDDUMB: PDDUMB may be selected in place any PS10XX series printer when the application does not require printing multiple copies of a label in quick succession. This eliminates wait times when printing one or two labels at a time. • COMTECRF: Default baud rate is 19.2 Kbps. Use PSSetParameters() to set alternate baud rates. The default printer type is PS1000. Return Value None Passing an invalid printer type defaults the printer to PS1000. Example #include <3000/ps1k.h> PSSelectPrinter( PS1004); 6-56 Miscellaneous Library Functions PSNewLabel() Description Starts a build of a new label. Disregards any previously built labels. Syntax #include <3000/ps1k.h> void PSNewLabel( void ); Remarks PSNewLabel disregards any old label built using PSBuildLabel() and starts a new label buffer. Return Value None Example #include <3000/ps1k.h> PSNewLabel(); 6-57 Series 3000 Application Programmer’s Reference Manual PSBuildLabel() Description Adds a line to the current label. Syntax #include <3000/ps1k.h> int PSBuildLabel( const char *format_string,... ); Parameters • format_string Character string that describes the format to be used. The format strings which are valid are the same as printf. • ... Variable number of arguments depending on the number of items described in the format_string. Remarks The PSBuildLabel parameters are the same as those for printf. Refer to the ANSI standard printf documentation. A Carriage Return / Line Feed Pair is not required at the end of the print command. If one does not exist, PSBuildLabel() appends it. Return Value Returns the number of characters added to the label. Returns a 0 for an error. Example #include <3000/ps1k.h> PSStartSession( COM1 ); PSNewLabel(); PSBuildLabel("! 0 100 250 1" ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel( "STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); for (ii = 0; ii < 10; ii++) PSSendLabel(); PSEndSession(); 6-58 Miscellaneous Library Functions PSEndLabel() Description Ends the build of the label and appends any post-processing for specific printer types to the end of the label. Syntax #include void PSEndLabel( void ); Remarks Performs the post-processing for a label. Appends INDEX and END to the label command packet. Only applicable for PS1000, PS 1001, PS 1004, COMTECPS, and CODECOVR printer types. Return Value None Example #include <3000/ps1k.h> int ret; PSStartSession( COM1 ); PSNewLabel(); PSBuildLabel("! 0 100 250 1" ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel( "STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); for (ii = 0; ii < 10; ii++) if ( (ret = PSSendLabel()) ) { printf("Print Error %04x\n", ret); break; } PSEndSession(); 6-59 Series 3000 Application Programmer’s Reference Manual PSSendLabel() Description Outputs the built label to the printer. Syntax #include <3000/ps1k.h> int PSSendLabel( void ); Remarks Sends the current label to the printer through the port which was previously opened. Sends a CLEAR command to the printer before the data is sent to overcome printer lockups. The CLEAR command is NOT sent to the printer if the printer type is LINEPRN, COMTEC, MONARCH, RASCAL or PDDUMB. Return Value 0 Label printed successfully. Positive Non-Zero Error -1 User Abort Key pressed while printer was not ready. The code 0x8008 may also be returned if the abort key was pressed. -2 PSStartSession() has not been called to init the port. -3 Send Block protocol timeout for SRRF printers. -4 Blocksize too big for SRRF printers. -5 Last ACK was not received from SRRF printer (user should check to see if label printed). -10 RF Channel not clear. Label was not sent to the SRRF printer. Example #include <3000/ps1k.h> int ret; 6-60 Miscellaneous Library Functions PSStartSession( COM1 ); PSNewLabel(); PSBuildLabel("! 0 100 250 1" ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel("STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); for (ii = 0; ii < 10; ii++) { rc = PSSendLabel(); if ( rc ) { printf("Printer Error %04x\n", ret); break; } } PSEndSession(); 6-61 Series 3000 Application Programmer’s Reference Manual PSEndSession() Description Frees any label which may be current, closes the port and ends the session. Syntax #include <3000/ps1k.h> int PSEndSession( void ); Remarks Frees any label which may be current, closes the port and ends the session. Return Value 0 Session ended successfully Non-Zero Error Example #include <3000/ps1k.h> PSStartSession( COM1 ); PSNewLabel(); PSBuildLabel("! 0 100 250 1" ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel( "STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); for (ii = 0; ii < 10; ii++) PSSendLabel(); PSEndSession(); 6-62 Miscellaneous Library Functions PSPrinterReady() Description Checks the condition of the port for an indication that a character can be printed without blocking. When a serial connection is used, CTS is raised. When a parallel connection is used, the printer ready bit is raised. Syntax #include <3000/ps1k.h> int PSPrinterReady(void); Remarks Caution Implemented as a MACRO. Side effects may occur. PSPrinterReady() always returns 1 if the printer type is PDDUMB. Because the MONARCH Pathfinder printer cable only uses tx, rx, power and ground, you can not check the printer connection status through CTS or DSR. The Pathfinder, however, echos the Bell character (Hex 7). The following description does not apply to COMTEC cable version 5. For the printer type COMTEC, PSPrinterReady() returns 1 if CTS and DSR are both high. For COMTEC printer version 1.12: If CTS or RI is low, PS1K sends out the Wakeup sequence to COMTEC. If CTS or RI is high, PSPrinterReady() returns 1. If CTS or RI is still low, PS1K sends out the printer status request command to the printer. If the return status byte reports the printer is ready, PSPrinterReady() returns 1; otherwise it returns 0. For COMTEC SRRF printers, a wakeup packet is sent to the printer. If the printer is ready, a 1 returns, otherwise 0. Return Value 0 Printer port not ready 1 Printer port ready 6-63 Series 3000 Application Programmer’s Reference Manual Example #include <3000/ps1k.h> PSStartSession( COM1 ); PSNewLabel(); PSBuildLabel("! 0 100 250 1" ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel( "STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); if (PSPrinterReady() != 1){ puts("Printer Not Ready!"); BiosGetChar(); } for (ii = 0; ii < 10; ii++) if ( (ret = PSSendLabel()) != 0 ) { if (ret < 0) /* The user pressed Abort */ printf("\nUser Abort.[%04x]\n", ret); else /* Some other error occurred */ printf("\nPrinter error %04X\n",ret); break; } PSEndSession(); 6-64 Miscellaneous Library Functions PSCatLabel() Description Adds the contents of a buffer to the current label. Syntax #include <3000/ps1k.h> int PSCatLabel( const void *bufptr, unsigned buflen ); Parameters • bufptr pointer to a buffer of characters. • buflen The length of the data at bufptr. Remarks The PSCatLabel contatenates the buffer to the current label. It does not modify the contents or concatenate the carriage return and line feed to the label. Return Value Returns the number of characters added to the label. Returns a zero for an error. Example #include char bufx[20]; PSStartSession( COM1 ); PSNewLabel(); sprintf(bufx,"! 0 100 250 1"); PSCatLabel(bufx,strlen(bufx) ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel( "STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); for (ii = 0; ii < 10; ii++) PSSendLabel(); PSEndSession(); 6-65 Series 3000 Application Programmer’s Reference Manual PSPrinterStat() Description Returns the current status of the printer port. Information may vary based on the connection. Syntax #include <3000/ps1k.h> int PSPrinterType( void ); Remarks Returns the LPT Printer Status or the BiosModemStatus bits to the caller. Return Value Bit value based on the connection type. The common bit values are: • _SER_NOCABLE_IN_TERMINAL_ 0x00 (Serial Connection Only) • _PAR_PRINTER_NOT_CONNECTED_ 0xC0 (Parallel Connection Only) • _SER_PRINTER_NOT_READY_ 0x20 (Serial Connection Only) • _PAR_PRINTER_BUSY_ 0x10 (Parallel Connection Only) • _SER_PRINTER_READY_ 0x30 (Serial Connection Only) • _PAR_PRINTER_READY_ 0x90 (Parallel Connection Only) • _RF_PRINTER_PROTOCOL_TIMEOUT_ 0x40 (RF Connection Only) • _RF_PRINTER_NOT_LINKED_ 0x80 (RF Connection Only) • _RF_PRINTER_READY_ 0x30 (RF Connection Only) • _RF_PRINTER_NOT_READY_ 0xf0 (RF Connection Only) • _RF_CHANNEL_NOT_CLEAR_Ox60 (RF Connection Only) For serial connections the values may be any legal value returned by the BiosGetModemStatus() function. Refer to the ADK documentation. The low order nibble from BiosGetModemStatus() is masked off to remove the delta values. On RF connections, a wakeup packet is sent to the printer and the status returns with the ready packet. -1 Port is not open for printing. 6-66 Miscellaneous Library Functions Example #include <3000/ps1k.h> PSStartSession( COM1 ); PSNewLabel(); PSBuildLabel("! 0 100 250 1" ); for (jj = 1, kk = 40; jj < 7; jj++,kk+=30) PSBuildLabel( "STRING 16(%d,%d,1,1) 0 %d SALE PRICE",jj,jj,kk); PSEndLabel(); switch((char) PSPrinterStat()) { case _SER_NOCABLE_IN_TERMINAL_: puts("Connect Cable to Terminal."); break; case _PAR_PRINTER_NOT_CONNECTED_: puts("Connect Cable to Terminal, or Turn Printer Power On."); break; case _SER_PRINTER_NOT_READY_: puts("The printer is busy or not connected."); break; case _PAR_PRINTER_BUSY_: puts("The printer is busy."); break; case _SER_PRINTER_READY_: case _PAR_PRINTER_READY_: puts("The printer is ready."); break; } puts("Press any key"); BiosGetChar(); for (ii = 0; ii < 10; ii++) PSSendLabel(); PSEndSession(); 6-67 Series 3000 Application Programmer’s Reference Manual PSConnectType() Description Returns the type of connection currently used to communicate to the printer. Syntax #include <3000/ps1k.h> int PSConnectType( void ); Remarks Returns the physical connection type used to communicate to the printer. It can filter return types from PSPrinterStat() which do not apply to the connection type being used. Return Value PARALLEL Parallel connection (LPT) SERIAL Serial connection (COM) Example #include <3000/ps1k.h> PSStartSession( COM1 ); if (PSConnectType() == PARALLEL puts("LPT Connection"); else if (PSConnectType == SERIAL) puts("COM Connection"); PSEndSession(); 6-68 Miscellaneous Library Functions PSSetDeliveryMode() Description Sets the delivery mode used when labels are sent to the printer. Syntax #include <3000/ps1k.h> int PSSetDeliveryMode( unsigned char Mode ); Remarks Sets the delivery mode to DELIVER_WAIT or DELIVER_QUICK. The default setting without calling this function is DELIVER_WAIT. If DELIVER_WAIT is set, the PSSendLabel() function does not return until all characters have been sent to the printer, or an error occurs. DELIVER_QUICK sends the block to the printer and returns immediately. If DELIVER_QUICK is set, the status of the printer does not change until the buffer is passed to the printer, so calling PSPrinterReady() may show the printer ready. DELIVER_WAIT is recommended. Return Value PSSetDeliveryMode() is implemented as a macro. Example #include <3000/ps1k.h> PSSetDeliveryMode( DELIVER_WAIT ); PSStartSession( COM1 ); if (PSConnectType() == PARALLEL) puts("LPT Connection"); else if (PSConnectType == SERIAL) puts("COM Connection"); PSEndSession(); 6-69 Series 3000 Application Programmer’s Reference Manual PSLink() Description Sends a Force Link Packet to the current Printer ID and waits for a Link Accept Packet. Syntax #include <3000\ps1k.h> int PSLink(unsigned long printer_id, unsigned long terminal_id, unsigned char retry_count, unsigned int PSPort); Remarks Attempts to link with an SRRF printer. Return Value 0 Link successful -1 PSStartSession() was not successfully completed -2 Protocol Time-out other Error Example #include<3000\ps1k.h> PSSelectPrinter( COMTECRF ); ret = PSLink( printer_id, terminal_id, retry_count, COM2); if(ret!=0) { printf (“PSLink error\n”); } 6-70 Miscellaneous Library Functions PSComputeComtecID() Description Computes the unique Comtec SRRF radio ID based on the Comtec 14-character Serial Number and returns the ID to the caller. Syntax #include <3000\ps1k.h> unsigned long PSComputeComtecID(unsigned char *comtec_serial_no_ptr); Remarks Returns the Comtec Printer’s SRRF ID to be used by PSSetPrinterID(). Return Value -1 Invalid Comtec Serial Number else Valid 32 bit Comtec printer ID Example #include<3000\ps1k.h> printer_id = PSComputeComtecID( comtec_serial_no_ptr ); if(printer_id == -1) { printf(“Invalid Comtec serial number”); } 6-71 Series 3000 Application Programmer’s Reference Manual PSGetParameter() Description Gets communication parameters: baud rate, data bits, parity bits, stop bits, flow control, control start character wait timeout value, and ready flag. These communication parameters have been set according to the printer type in the PSSelectPrinter(). This function should be called after the printer type has been selected. Syntax #include<3000\ps1k.h> void PSGetParameter(unsigned char *Baud, unsigned char *Data, unsigned char *Parity, unsigned char *Stop, unsigned char *Flow, unsigned char *Wait, unsigned char *Ready); where: Baud is a pointer to a variable to receive the current baud rate. Data is a pointer to a variable to receive the current number of data bits. Parity is a pointer to a variable to receive the current parity. Stop is a pointer to a variable to receive the current number of stop bits. Flow is a pointer to a variable to receive the current flow control mode. Wait is a pointer to a variable to receive the current control character timeout value. Ready is a pointer to a variable to receive the current ready flag. Return Value None Example #include <3000\urm.h> #include <3000\ps1k.h> /* Change connection baud rate only*/ 6-72 Miscellaneous Library Functions PSSelectPrinter( printer_type ); PSGetParameter( &baud, &databits, &parity, &stopbits, &flowctrl, &wait, &ready); PSSetParameter( BAUD19200, databits, parity,stopbits, flowctrl, wait, ready ); 6-73 Series 3000 Application Programmer’s Reference Manual PSGetVersion() Description Gets the PS1K Library major and minor version. Syntax #include<3000\ps1k.h> unsigned int PSGetVersion(); Return Value Library version. Major version in high byte, minor version in low byte. For example, a library verison of 3.02 would be returned as 0x0302. Example #include<3000\ps1k.h> library_version = PSGetVersion(); major = (library_version >> 8) & 0x00FF; minor = library_version & 0x00FF; printf(“The PS1K Library version is %d.%02d\n”, major, minor); 6-74 Miscellaneous Library Functions PSSetParameter() Description Sets communication parameters: baud rate, data bits, parity bits, stop bits, flow control, control start character wait timeout value, and ready flag. The above communication parameters are set according to the printer type in the PSSelectPrinter(). This function should be called after the printer type has been selected. Refer to URM.GD for communication parameters definitions. Syntax #include <3000/ps1k.h> void PSSetParameter(unsigned char Baud, unsigned char Data, unsigned char Parity, unsigned char Stop, unsigned char Flow, unsigned char Wait, unsigned char ready); Parameters The PSSetParameter changes the default communication parameters value. The table below indicates default values for each printer type. Table 6-1. Printer Defaults PS1000/1001 MONARCH PS1004/LINEPRN PDDUMB PATHFINDER PS1004/LINEPRN COMTEC COMTEC RF DataBits 87888 Parity NONE ODD NONE NONE NONE StopBits 22221 BaudRate 9600 9600 9600 19200 19200 FlowControl SOFTWARE SOFTWARE HARDWARE NONE 255 CtlStartWait 0 sec 255 sec 0 sec 255 sec Return Value None 6-75 Series 3000 Application Programmer’s Reference Manual Example #include <3000\urm.h> #include <3000\ps1k.h> /* Use software flow control xon/xoff and the control character wait time is 10 seconds. */ PSSelectPrinter(printer_type); PSSetParameter( BAUD9600, DATABITS8, PARITYNONE, STOPBITS2, SOFTWAREFLOWCTL, 10,1 ); 6-76 Miscellaneous Library Functions Symbol Utility Library (SYMUTILx.LIB) This section contains subsections that describe: • commands available for use in a C program for accessing the keyboard definitions (KBD3000 interface functions) • routines for determining whether or not a specified TSR is loaded in memory (TSRLoaded and TSRRegistrationCheck) • functions that are useful when a program (like a TSR) needs to retrieve its Data Segment inside an interrupt service routine (_STORDS and _RESTORDS) These commands are in the Symbol Utilities library. There are three models of this library: SYMUTILL.LIB the large model SYMUTILM.LIB the medium model SYMUTILS.LIB the small model All three models are in the C:\3000\LIB directory in the ADK. Note: The MPM3000 interface function, MPMLoadFile, which is also in SYMUTILx.LIB, is described in the section on the Macro Processing Manager (MPM3000.EXE) in this chapter. 6-77 Series 3000 Application Programmer’s Reference Manual KBD3000 Interface Functions The following pages describe two commands (KBDRestore and KBDLoadFile)available for use in a C program for accessing the keyboard definitions and errors returned to the DOS shell upon loading the KBD3000 TSR. For a description of the keyboard redefinition program that runs on Series 3000 terminals as a TSR, refer to the KBD3000.EXE section of the Utilities chapter in this manual. 6-78 Miscellaneous Library Functions KBDRestore Purpose Restore a keyboard to the original definition table which existed when KBD3000 was loaded into memory. Syntax #include <3000\symutil.h> int KBDRestore(unsigned char KBType); Parameters KBDType can be either STD or AUX. See the #defines in the file symutil.h. Note: Calling this routine when the KBD3000 TSR is not loaded can cause unpredictable results. Returns Values Meaning 0 Successful -1 Failed See Also N/A 6-79 Series 3000 Application Programmer’s Reference Manual KBDLoadFile Purpose Loads a keyboard definition file from disk and sets the definition active. Syntax #include <\3000\symutil.h> int KBDLoadFile(unsigned char far *fname,unsigned char KBType); Parameters fname is a far pointer to the name of the definition file. The full path and file name must be given, including the .KBD extension. KBDType can be either “STD” or “AUX”. See #defines in the file symutil.h. Note: Calling this routine when the KBD3000 TSR is not loaded can cause unpredictable results. Returns Values Meaning 0 File was Loaded -1 File was NOT Loaded See Also N/A 6-80 Miscellaneous Library Functions KBD3000 Error Codes Errors returned to the DOS shell upon loading the TSR are reported in two ways: 1. The KBD3000 version string will be followed by the error code in the format: KBD3000 V X.XX-XX:# where # will be the error code number. 2. The same error code is returned to the DOS shell, which can be detected by a batch file errorlevel statement. Errors Meaning 0 Successful 1 Invalid Argument Supplied 2 Standard Keyboard was NOT Restored 3 Auxiliary Keyboard was NOT Restored 4 Standard Keyboard File was not Loaded 5 Auxiliary Keyboard File was not Loaded 6 TSRREG.EXE (TSR registration program) is not running load TSRREG.EXE prior to KBD3000 6-81 Series 3000 Application Programmer’s Reference Manual Miscellaneous Functions This section describes two C interface functions in the SYMUTILx.LIB that can be used in applications to check whether or not specified TSRs are currently installed on a terminal. These are: TSRLoaded TSRRegistrationCheck Detailed descriptions of these functions are provided on the pages that follow. TSRLoaded calls TSRRegistrationCheck to verify that a specific TSR is currently loaded. The TSR Registration utility (TSRREG.EXE) calls TSRRegistrationCheck to determine whether or not aTSR that an application is attempting to install is already loaded on the terminal. If the TSR is not currently installed, TSRREG will take the ID (TsrId) of the installing TSR and put it in a table of installed TSRs. If the TSR is currently installed, TSRREG will return a boolean value (1) to indicate that condition. This subsection also contains descriptions of two functions in the SYMUTILx.LIB that are useful when a program (like a TSR) needs to retrieve its Data Segment inside an interrupt service routine. They are: _STORDS _RESTORDS Detailed descriptions of these two routines are provided at the end of this section. 6-82 Miscellaneous Library Functions TSRLoaded This function is in the SYMUTILx.LIB, where x= S (small), M (medium) or L (large). Purpose Determines whether or not the specified TSR is currently loaded in memory. Syntax #include <3000\TSRIDS.h> #include <3000\symutil.h> int TSRLoaded( unsigned int TsrId ) Description TSRLoaded calls TSRRegistrationCheck to determine whether or not the TSR identified by TsrId is currently loaded in memory. TSR ID numbers (TsrId) are defined in TSRIDS.H on the C:\3000\3000 directory in the ADK. TSRREG.EXE must be loaded (see the TSRREG.EXE section of the Utilities chapter in this manual). To install the specified TSR that is not currently installed, an application can use TSRRegistrationCheck (TsrID, INSTALL_TSR). Returns Values Meaning 0TSR is NOT Loaded 1TSR is Loaded See Also TSRRegistrationCheck 6-83 Series 3000 Application Programmer’s Reference Manual TSRRegistrationCheck This function is in the SYMUTILx.LIB, where x= S (small), M (medium) or L (large). Purpose Determines whether or not a specified TSR is currently installed in memory. Syntax #include <3000\TSRIDS.h> #include <3000\symutil.h> int TSRRegistrationCheck(unsigned int TsrId, ⇒ unsigned int FuncId); Description TSRRegistrationCheck calls the TSRREG utility through an interrupt vector for TsrId to perform FuncId. TSR ID numbers (TSRId) are defined in TSRIDS.H on the C:\3000\3000 directory in the ADK. FuncId can be CHECK_INSTALLED or INSTALL_TSR, which are also defined in TSRIDS.H. For a description of the TSR Registration utility (TSRREG.EXE), refer to the Utilities chapter in this manual. Returns Values Meaning 0 The TSR has not been installed 1 The TSR is currently installed See Also TSRLoaded 6-84 Miscellaneous Library Functions _STORDS This function is in the SYMUTILx.LIB, where x= S (small), M (medium) or L (large). Description Stores the current value in the DS register into a predefined location in the code segment. This function is useful when a program (like a TSR) needs to retrieve its Data Segment inside an interrupt service routine. Syntax #include <3000\symutil.h> void _STORDS(void); Returns None See Also _RESTORDS 6-85 Series 3000 Application Programmer’s Reference Manual _RESTORDS This function is in the SYMUTILx.LIB, where x= S (small), M (medium) or L (large). Description Retrieves the value stored in a predefined location in the code segment which contains the DS register value stored using the _STORDS function. Syntax #include <3000\symutil.h> void _RESTORDS(void); Returns None See Also _STORDS 6-86 Chapter 7 Internal Modem Command Set Chapter Contents Introduction ...... 7-3 Programming Considerations ...... 7-3 Modem Communications Port...... 7-3 Modem Capabilities...... 7-3 DTR Line and Power ...... 7-4 Sending AT Commands ...... 7-5 Opening the Communications Line ...... 7-6 Repeat Dialing ...... 7-6 Australia ...... 7-6 Europe ...... 7-6 USA and Canada ...... 7-7 Descriptions of AT Commands ...... 7-8 IM3/4 Commands ...... 7-9 IM5/IM5S Commands ...... 7-16 IM6 Commands ...... 7-35 IM7 Commands ...... 7-46 Result Codes ...... 7-49 S Register Descriptions ...... 7-51 IM8/IM8S Modems ...... 7-66 DTE Speeds...... 7-66 DTR Line and Power ...... 7-66 IM 8 Notes...... 7-87 Differences Between IM5/5S and IM8/8S ...... 7-87 Register S14 bitmap ...... 7-96 Register S16 bitmap ...... 7-97 Register S21 bitmap ...... 7-98 Register S22 bitmap ...... 7-99 Register S23 bitmap ...... 7-100 Register S27 bitmap ...... 7-101 Register S28 bitmap ...... 7-102 Register S31 bitmap ...... 7-103 Register S37 bitmap ...... 7-104 Register S39 bitmap ...... 7-105 7-1 Series 3000 Application Programmer’s Reference Manual Register S40 bitmap ...... 7-106 Register S41 bitmap ...... 7-107 Register S80 bitmap ...... 7-108 7-2 Internal Modem Command Set 7-3 Series 3000 Application Programmer’s Reference Manual 7-4 Internal Modem Command Set Introduction The Symbol Technologies internal modems (IM3, IM4, IM5, IM5S, IM6, IM7 and IM8) support the Hayes Smartmodem 2400 AT command set. This chapter describes the basic commands, result codes, and S-registers for these modems. Programming Considerations There are a number of special considerations to keep in mind when programming the internal modem. Modem Communications Port The PDT 3300 internal modem is always configured as COM2. Internal modems in cradles are always configured as COM1. Modem Capabilities The IM3, IM4, IM5, IM6, IM7 and IM8 modems have different capabilities, as shown in the following chart: V.21 V.2 2 V.22 bis V.2 3 V.32 V.32bis B103 B212 V.42 V.42bis B202 HDX IM3 XX X IM4 XXX X X IM5/ XXX X X X X IM5S IM6 XX X X IM7 XX X X IM8 XXXXXXXXXX 7-5 Series 3000 Application Programmer’s Reference Manual Note: The IM5 and the IM5S have virtually the same capabilities. The main difference between the two modems is that the IM5S is used inside the PDT 3100. The following chart indicates where each of the modems can be used: MODEM TERMINAL CRADLE IM3/4 PDT 3300 3365 IM5 PDT 3300 CRD 3100 3365 3865 IM5S PDT 3100 None IM6 PDT 3300 CRD 3100 3365 3865 IM7 PDT 3100 None IM8 PDT 3100 CRD 3100 38/6865 6100 DTR Line and Power Power to the internal modem is controlled by the DTR line. When DTR is lowered, the modem is powered down. When DTR is raised, the modem goes through its boot process, which takes some time. The application must include a minimum delay of 500ms between raising DTR and sending data. In IM3/4 modems, default parameters are set each time the modem powers up, and so non-default parameters must be specified each time DTR is raised. In the IM5, non-default parameters may be set in non-volatile memory, eliminating the need to reset them each time DTR is raised. Also, observe these two additional guidelines: • Do NOT set DSR_Wait or CD_Wait. DSR and CD are not present until the proper commands are sent and the connection is established. • Wait at least one second between dropping DTR and raising it again, to assure a full reset of the modem. Otherwise, the modem may not fully 7-6 Internal Modem Command Set reset, resulting in unpredictable behavior. Sending AT Commands To ensure a successful execution of the AT commands, do the following: 1. Do a separate DOS WRITE for each character of the command, rather than for the entire command. 2. Use the SEND END IOCTL command once the whole command has been written. 3. Wait for a response from the modem, using 5 seconds for a Receive Character wait time (DOS IOCTL Write, function code 00h). 4. Responses to AT commands come as either numeric or text result codes, as determined by the AT command. To get the result codes, an application program must perform a DOS READ on the appropriate Comm line. 5. Read the result code by looping on a DOS READ until either a Carriage Return (for numeric result code) or a Carriage Return/Line Feed (text result code) is received. Note that if the modem is set to ECHO ON, you must check for both the Carriage Return/Line Feed and Carriage Return. For instance, if the modem is set to ECHO ON and you send the ATE0 command, the return string is ATE0 0, echoing the command and returning the result code. It is now safe to send the next AT command. 7-7 Series 3000 Application Programmer’s Reference Manual Opening the Communications Line When using the MSI 2-WAY communications driver, two line opens are required to begin a communication session. This is necessary to configure the line for the data transfer. When using other communications drivers, two line opens may not be required. The first open establishes the line to make the phone connection. The following AT commands can then be used to set the modem online: • Make modem connection, using: ATD - to originate the call ATA - to answer the call • ATJ7 - to shut off the modem, establishing a direct connect link on the RJ41 (IM5 in PDT 3300 only) Once the modem is set online, wait for DSR and/or CD. Then reset the serial parameters and do another open line to establish the parameters for the session. Since two opens are used, two closes are required before closing the line. The first close can be issued immediately following the second open, since the parameters remain unchanged. Repeat Dialing Repeat dialing is permitted providing the controlling application software complies with the following: Australia A minimum of 2 seconds off line shall be provided between attempts. A maximum of three automated attempts is allowed, then if unsuccessful, no further automatic attempt shall be made untili after 30 minutes from initiating the first attempt. This may be reduced to 5 minutes if a handshake procedure is used to ensure the correct party has answered. Europe A minimum of 5 seconds off line shall be provided between attempts. 7-8 Internal Modem Command Set A maximum of fifteen automated attempts is allowed, then if unsuccessful, no further automatic attempts are made. USA and Canada A minimum of 5 seconds off line shall be provided between attempts. 7-9 Series 3000 Application Programmer’s Reference Manual Descriptions of AT Commands The commands are listed by modem, in alphabetical order, with brief descriptions. Commands may be entered in either upper or lower case. The term “n” indicates a numeric digit. If the digit is omitted, the value is assumed to be 0. All command lines except A/ must begin with AT. More than one command may be entered at a time, up to a maximum of 40 characters, not including the AT and Carriage Return. Command lines are not executed until a Carriage Return (0Dh) is entered (except when A/ is used). Commands entered may be deleted by the BACKSPACE character (08h). The escape command switches the modem from the on-line state to the command state. The default escape character is “+” and must be entered three consecutive times. A Carriage Return character (0Dh) is not permitted. Note that responses to AT commands are received by performing a DOS READ on the comm port. 7-10 Internal Modem Command Set IM3/4 Commands A/ Repeat last command Repeat the last command. This command does not use the AT prefix or Carriage Return terminator. AT Attention code The prefix for all command lines except A/. A Immediate answer Answer the telephone immediately, transmit the answer tone and enter the appropriate connect sequence. This must be the final command in the line. Bn Select Bell or CCITT mode dependent on DTE B or B0 at 300 Select v.21 B(0) at 600 Select v.22 B(0) at 1200 Select v.22 B(0) at 2400 Select v.22bis B1 at 300 Select Bell 103 B1 at 1200 Select Bell 212A B2 not supported, same result as B(0) B3 at 1200 Select half duplex v.23 If the requested capability is not available in the installed modem, the ERROR message is sent. Default is B0. \Bn Break Break length in 100ms units. Default is 3. 7-11 Series 3000 Application Programmer’s Reference Manual $Cn Country code The IM3/4 modems support country codes 0-6 in the following chart: Code Country Code Country 0 USA (Bell enable) 12 not used 1 Great Britain 13 not used 2France 14not used 3 Germany 15 not used 4Italy 16not used 5 Netherlands 17 not used 6 Denmark 18 not used 7 not used 19 not used 8 not used 20 not used 9 not used 21 not used 10 not used 22 not used 11 not used 23 not used In IM3/4 modems, the country code sets bell shunt enable, pulse dial ratio, call progress monitoring, and calling tone enable. Other parameters must be individually set. Default is $C0 (USA). Dstr Dial string (phone number) D is followed by the phone number to be dialed. T (Tone dialing), P (Pulse dialing), or A (Autoselect, IM3/4 only) modifiers may follow. Default is Tone mode. Invalid characters may cause errors on the IM3 and IM4 modems. The following characters may be included in the dial string. If the A, P, or T characters are used, they must immediately follow the D character. The other characters may occur anywhere in the string. 7-12 Internal Modem Command Set A Autoselect dialing mode (IM3, IM4) Supported on the IM3 and IM4 modems only. Automatically selects pulse dialing if tone dialing is not available. Autoselect is disabled if either the T (tone dialing) or the P (pulse dialing) command is used. Use the A command to re-enable automatic selection following a P or T command. P Pulse dialing Force pulse dialing. The dialing make/break ratio is set using either the &Pn or Nn commands. R Reverse mode for calling originate- only modems Reverses the frequencies so that the modem makes a call using “answer” tones. This command is used when calling an “originate only” modem. An example command line would be: ATDT123-4567R. T DTMF dialing Force DTMF (tone) dialing. In the IM3/4, tone duration and spacing are set in register S11. W Wait Wait for a dial tone for the period specified by S6, before continuing the dial sequence. If no dial tone is found, a NO DIALTONE message is sent. If a busy condition is detected, the modem hangs up and a BUSY message is sent. For instance, if a system requires that the numeral 9 be dialed to obtain an outside line, the dial string could be ATDT9W123- 4567. , Pause Pause between characters (0 - 255 seconds) set by register S8. Default is 1 second. ; Return to command state Return to the command state after dialing. This may be used to dial numbers with greater than 40 digits, or to access data bases that require tone identification. 7-13 Series 3000 Application Programmer’s Reference Manual ! Flash hook Go on hook. In the IM3/4 the duration is 0.5 seconds (0.75 in UK). En Command echo E or E0 Disable character echo in the command mode. E1 Enable character echo in the command mode. Default is E1. %Fn V.23 control %F or %F0 V.23 disabled (default). %F1 75 bps transmit, 1200 bps receive. %F2 1200 bps transmit, 75 bps receive. %F3 1200 bps half duplex (Default for B3 command.) G Modem capability code The modem returns a two byte, bit-mapped code indicating the features that it supports. The code mapping is shown in the following figure. For example, the capability code for the K322 modem chip is 185h (110000101 = V.22/1200, V22/600, V.21, V.23), and the capability code for the K224 modem chip is 39Eh (1110011110 = V.22/2400, V.22/1200, V.22/600, Bell 212/1200, (V.21, Bell 103). *Gn Transmit calling tone Transmit a 0.5-second on/ 1.5 second off 1300-Hz calling tone in the originate mode. *G or *G0 Disable the tone (default). *G1 Enable the tone. &Gn Guard tone generation &G or &G0 Disable the guard tone. &G1 Transmit 550-Hz guard tone in V.22 answer mode (IM3/4 only). &G2 Transmit 1800-Hz guard tone in V.22 answer mode (default). 7-14 Internal Modem Command Set Hn Telephone switch hook control H or H0 On hook (disconnect) (default). H1 Off hook (connect). In Product information or check sum I or I0 “Symbol Technologies, Inc.” I1 Copyright date (and version in IM3/4). I2 Reports “OK” (IM3/4). I3 Firmware revision. Jn Direct connect or COM2 data redirect J or J0 Direct phone line connect (default). J3 Autoselect COM2 port (phone line or RJ-41). J7 Redirect COM2 communication to the RJ-41 port, then power off modem. J3 checks for a dial tone on the phone line. If there is none, communication is redirected to the RJ-41 port and the modem is powered off. Note that, since J3 and J7 power off the modem, they must be the final commands in the command string. Nn Pulse dial ratio Controls ratio of off-hook (make) to on-hook (break) interval used for pulse dialing. Same as &Pn, which is preferred. N or N0 Selects make=39%, break=61% for use in US. N1 Selects make=33%, break=67% for use Europe. On Go to on-line state O or O0 Return to on-line state. &Pn Pulse dial make/break ratio Controls the ratio of the off-hook (make) to on-hook (break) interval used for pulse dialing. Same command as Nn. &P or&P0 39/61 for USA, Canada (default). &P1 33/67 for UK, Hong Kong, Sweden, Norway, and Japan. 7-15 Series 3000 Application Programmer’s Reference Manual Qn Result codes enable/disable The Qn command enables/disables the return of result codes. Q or Q0 Modem returns result codes (default). Q1 Modem does not return result codes. $Rn Receive boost $R or $R0 Disable receiver gain (default). $R1 Enable 12dB receiver gain. Sr? Read register value Reads the content of S Register ’r’ and sends its value as a decimal value within the range of 0 to 255. Sr=n Assigns register value Assigns S register ’r’ with the decimal value ’n’. The decimal value must be 0 to 255. Some registers have limited ranges and S1 is a read-only register. \Sn Status display Display operating status or registers. \S(0) Display S registers. $Sn Bell shunt control Permits setting the bell (anti-tinkle) shunt for unattended answering. The shunt (if installed and set) is released after dialing or answering and will be restored upon completion of the call. $S(0) Disables the shunt (default). $S1 Enables the shunt. Vn Result code language V or V0 Send result codes in digits. V1 Send result codes in words (default). See Result Codes below for a listing of the codes. 7-16 Internal Modem Command Set Xn Select result code set Selects which subset of the result messages are to be used by the modem to inform the terminal of command results. Dial tone detection may be forced by placing a W in the dial string. Extended Connect Report Call Wait for n Message Progress Dial Tone 0No No No 1 Yes No No 2Yes No Yes 3Yes Yes No 4 Yes Yes Yes 5 Not supported 6 Yes Extended call No progress report 7 Yes Extended call Yes progress report See the result code table for a description of the extended call progress messages. Default is X3. IM3/4 extended call progress messages are 0-11 and 144-150. Zn Reset modem, restore profile Clear the command line buffer and reset the modem. Z or Z0 Return all programmable options to the default state. Z1 Clear only the command buffer. 7-17 Series 3000 Application Programmer’s Reference Manual IM5/IM5S Commands A/ Repeat last command Repeat the last command. This command does not use the AT prefix or Carriage Return terminator. AT Attention code The prefix for all command lines except A/. AT=x Write to current S register The current register is determined by the last Sr? command. Some registers are subject to country-specific limitations. Other registers are read-only. Refer to the S register descriptions later in this chapter for details. AT? Read selected S register Returns the contents of the S register selected by the last Sr? command. A Immediate answer Answer the telephone immediately, transmit the answer tone and enter the appropriate connect sequence. This must be the final command in the line. \An Select maximum MNP block size \A or \A0 64 characters \A1 128 characters (default) \A2 192 characters \A3 256 characters Bn Select Bell or CCITT mode dependent on DTE B or B0 CCITT B1 Bell B2 Permits generation of the Bell answer tone in FSK modes subject to country fil limitations. 7-18 Internal Modem Command Set B3 Select V.23 half duplex.(same as %F3) B4 Permits generation of Bell answer tone in v.23 mode (for Bell 202 compatibility) If the requested capability is not available in the installed modem, the ERROR message is sent. Default is B0. \Bn Break Under non-error corrected link operation, the modem will transmit a break signal to the remote modem. Under error corrected link operation, the modem will signal break through the active error correction protocol, giving no indication of the length. An ERROR response will be generated if either not connected, or if the parameter is 0. 1-9 break length in 100ms units (default is 3 in non-error corrected links only. *B Return blacklisted numbers Blacklisted numbers are subject to dialing restrictions. Dialing restrictions are controlled by the country files. $Bn Bell answer tone detect For compatibility only, performs no function. Cn Carrier control Provided for command compatibility purposes, but performs no function. The only valid parameter is 1. %Cn Enable/disable data compression %C or %C0 Disable data compression (default for &F1). %C1 Enable MNP5 data compression negotiation. %C2 Enable V.42bis data compression. %C3 Enable V.42bis and MNP5 compression (default for &F0). 7-19 Series 3000 Application Programmer’s Reference Manual &Cn DCD option &C or &C0 DCD remains ON at all times. &C1 DCD follows carrier on the line (default). *C Remote configuration password Used only on MNP connections. The password is an alphanumeric string, 6 to 12 characters long. The default password is “QWERTY”. See also AT*E and AT*R. $Cn Country code The IM5 modem supports country codes 0-23 in the following chart: Code Country Code Country 0 USA (Bell enable) 12 Finland 1 Great Britain 13 Ireland 2France 14Japan 3Germany 15Luxembourg 4Italy 16Mexico 5 Netherlands 17 New Zealand 6Denmark 18Norway 7 USA (CCITT only) 19 Portugal 8 Belgium 20 Singapore 9 Austria 21 Spain 10 Australia 22 Sweden 11 Canada 23 Switzerland In IM5 modems, the country code sets call progress parameters, dialing parameters (DTMF and pulse), blacklisting, blind dialing, guard tone generation, S register defaults, and range limitations. The $C command automatically saves the S register profile in NVM. An ATZ command must follow the $C to make sure the new parameters become effective. Default is $C0 (USA). 7-20 Internal Modem Command Set Dstr Dial string (phone number) D is followed by the phone number to be dialed. T (Tone dialing), P (Pulse dialing) modifiers may follow. Default is Tone mode. Invalid characters are ignored by the IM5 modem. The following characters may be included in the dial string. If the A, P, or T characters are used, they must immediately follow the D character. The other characters may occur anywhere in the string. 0-9 Digits 0 to 9 Digits for the phone number when dialing. * Asterisk (star) symbol Available in tone dialing only. # Pound symbol Available in tone dialing only. ( ) Dial string punctuation Available for formatting only, otherwise ignored. — Dial string punctuation Available for formatting only, otherwise ignored. 7-21 Series 3000 Application Programmer’s Reference Manual S=n Dial the stored number Dials the stored phone number specified by n. See &Z for storing numbers. T DTMF dialing Force DTMF (tone) dialing. In the IM5, DTMF dialing is controlled by the country file. W Wait Wait for a dial tone for the period specified by S6, before continuing the dial sequence. If no dial tone is found, a NO DIALTONE message is sent. If a busy condition is detected, the modem hangs up and a BUSY message is sent. For instance, if a system requires that the numeral 9 be dialed to obtain an outside line, the dial string could be ATDT9W123-4567. @Wait for silence Forces the modem to wait for at least 5 seconds of silence in the call progress frequency band before continuing with the next dial string parameter. , Pause Pause between characters (0 - 255 seconds) set by register S8. In the IM5, the default is set by the country code. ; Return to command state Return to the command state after dialing. This may be used to dial numbers with greater than 40 digits, or to access data bases that require tone identification. ! Flash hook Go on hook. In the IM5, the duration is set in the S29 register and subject to country limitations. ^ Disable calling tone transmission Disables the calling tone transmission for the current call only. 7-22 Internal Modem Command Set &Dn DTR option Supported for compatibility only, performs no function. Accepts values 0-3. *D Return delayed numbers Returns a list of delayed telephone numbers. Calling limitations are set in the country files. En Command echo E or E0 Disable character echo in the command mode. E1 Enable character echo in the command mode. Default is E1. %En Auto retrain in non-reliable V.22bis modes When enabled, the line is dropped after three consecutive unsuccessful retrain attempts. %E or %E0 Disable auto-retrain (default). %E1 Enable auto-retrain. *E Exit remote configuration mode See the *R command. Fn Select line modulation Line modulation is fixed unless auto mode is selected. Interacts with the AT$N command. F or F0 Auto mode detection, line speeds from 2400bps (V.22bis) to 300bps (V.21). Default on IM5. F1 V.21/Bell 103 (according to ATB command) at 300bps. F2 Not supported. Error is returned. F3 V.23 75TX/1200RX originate or 1200TX/75RX answer. F4 V.22 A/B or Bell 212A (according to ATB command) at 1200bps. F5V.22bis only. 7-23 Series 3000 Application Programmer’s Reference Manual %Fn V.23 control %F or %F0 V.23 disabled (default). %F1 75 bps transmit, 1200 bps receive. %F2 1200 bps transmit, 75 bps receive. %F3 1200 bps half duplex. &Fn Restore factory configuration &F or &F0 V.42bis/V.42 and MNP5/MNP4 operation. Set terminal speed at 9600 or 19200 to maximize throughput. &F1 Emulate IM3/IM4 modems. No data compression support (default). \F Display telephone directory Displays numbers stored with the AT&Z command. G Modem capability code The modem returns a two byte, bit-mapped code indicating the features that it supports. The code mapping is shown in the following figure. For example, the capability code for the K322 modem chip is 185h (110000101 = V.22/1200, V22/600, V.21, V.23), and the capability code for the K224 modem chip is 39Eh (1110011110 = V.22/2400, V.22/1200, V.22/ 600, Bell 212/1200, (V.21, Bell 103). The code for the IM5 is 0FFFh (111111111111). 15 14 13 12 11 10 9 8 7 6 5 432 1 0 V23 Bell 103 V21 (same as Bell 103) Bell 212 @ 1200 baud (same as V22 BIS) Bell 202 V22 @ 600 baud V22 @ 1200 baud V22 @ 2400 baud (V22 BIS) MNP 4/5 V42/V42 BIS 7-24 Internal Modem Command Set *Gn Transmit calling tone Transmit a 0.5-second on/ 1.5 second off 1300-Hz calling tone in the originate mode. *G or *G0 Disable the tone (default). *G1 Enable the tone. In the IM5, the calling tone may be forced by the country code. If not forced by the country code, *G can enable it. &Gn Guard tone generation &G or &G0 Disable the guard tone (default). &G1 Transmit 1800-Hz guard tone in V.22 answer mode. &G2 Transmit 1800-Hz guard tone in V.22 answer mode. The guard tone is controlled by the country file. If not forced, &G can be used to control it. \Gn Modem to modem flow control in non-reliable modes (XON/XOFF) Enables/disables use of software flow control. \G or \G0 Disable flow control (default). \G1 Enable flow control. $GN Transmitter Gain Set modem transmit gain in 1db steps within the country limitations. Parameter is in -db. The default transmit level is set in the country files. Hn Telephone switch hook control H or H0 On hook (disconnect) (default). H1 Off hook (connect). In the IM5, ATH1 is subject to country limitations and the duration is determined by S7. 7-25 Series 3000 Application Programmer’s Reference Manual *H Link negotiation speed *H or H0 Link negotiation occurs at the highest supported speed (default). *H1 Link negotiation occurs at 1200bps. Controls the connection speed for the link negotiations before upshift occurs between two MNP Class 10 modems. In Product information or check sum I or I0 “Symbol Technologies, Inc.” I1 Copyright date. I2 Reports “OK”. I3 Firmware revision. I4 Capability code (same as ATG). I5 Country code parameter (IM5). I6–I8 Undefined. Reports error. I9 Bell shunt test (IM5). $I Initialize the NVRAM On the IM5, when S80 bit 7 is clear, $I reinitializes the contents of the NVRAM to the default parameters. Jn Direct connect or COM2 data redirect J or J0 Direct phone line connect (default). J3 Autoselect COM2 port (phone line or RJ-41). J7 Redirect COM2 communication to the RJ-41 port, then power off modem. J3 checks for a dial tone on the phone line. If there is none, communication is redirected to the RJ-41 port and the modem is powered off. Note that, since J3 and J7 power off the modem, they must be the final commands in the command string. &Jn Telephone jack control For compatibility only, performs no function. Accepts values of 0 or 1. 7-26 Internal Modem Command Set &Kn Flow control &K or &K0 Disable flow control. &K3 Enable RTS/CTS flow control (default). &K4 Enable XON/XOFF flow control. &K5 Enable transparent XON/XOFF flow control. &K6 Enable both RTS/CTS and XON/XOFF flow control. Ln Speaker volume Adjusts the speaker volume control according to the parameter supplied. 0 Speaker always off. 1Low volume. 2 Medium volume (default). 3 High volume. %L Line signal level Direct indication of the receive level attenuation at the data pump. Returns a value which indicates the received signal level in dBm. \Ln MNP block/stream mode select Selects whether an MNP link will use block or stream mode. \L or \L0 Use stream mode for MNP connections (default). \L1 Use block mode for MNP connections. *L Display secure access directory Entries are generated using the AT*P command. &Ln Line Type Provided for compatibility only since leased line operation is not supported. Mn Speaker control Supported for compatibility only since the modems do not have speakers. 7-27 Series 3000 Application Programmer’s Reference Manual M or M0 Speaker disabled. M1 Speaker disabled during reception of carrier (default). M2 Speaker always enabled. M3 Speaker disabled during reception of carrier and during dialing. On during answering phase. &Mn Synchronous mode select &M or &M0 Direct async (default). &M1 Sync on-line, async off-line. &M2 Not supported. &M3 Not supported. Nn Pulse dial ratio Controls the ratio of the off-hook (make) to on-hook (break) interval used for pulse dialing. N or N0 Selects make=39%, break=61% @ 10pps N1 Selects make=33%, break=67% @ 10pps N2 Selects make=39%, break=61% @ 20pps N3 Selects make=33%, break=67% @ 20pps $Nn Auto detect enable $N or $N0 Force connection according to ATF (S37). $N1 Enable auto speed detection. *NCnn Country select Same as AT$Cnn. \Nn Error correction operating mode \N or \N0 Disable error correction. Speed buffering on (force AT&Q6). \N1 Direct mode (AT&Q0). \N2 Force LAP-M of MNP4 error correction. Failure to connect in reliable mode results 7-28 Internal Modem Command Set in the modem hanging up. (AT&Q5, S36=4, S48=7). \N3 Enable auto-reliable mode: V.42 LAP-M or MNP4 error corrected links preferred non-error corrected links as fallback. (AT&Q5, S36=7, S48=7) (default). \N4 Force V.42 LAMP error correction. (AT&Q5, S48=0). \N5 Force MNP4 error correction. (AT&Q5, S36=4, S48=128). On Go to on-line state O or O0 Return to on-line state. O1 Return with retrain (V.22bis only). P Force pulse dialing Force all subsequent dialing in pulse mode. As soon as a dial command is executed which explicitly specifies the dialing mode for that particular call (i.e., ATDT...) this command is overridden, so that all future dialing will be tone dialed. See ATT command. This command may not be permitted in some countries. &Pn Pulse dial make/break ratio Controls the ratio of the off-hook (make) to on-hook (break) interval used for pulse dialing. Same command as Nn. In IM5, subject to country limitations. &P or&P0 39/61 make/break ratio at 10 pulses per second. &P1 33/67 make/break ratio at 10 pulses per second. &P2 40/60 at 20 pulses per second. &P3 33/67 at 20 pulses per second. 7-29 Series 3000 Application Programmer’s Reference Manual *Pn:password:number Store/delete a password/phone number pair For use in secure callback applications. n0 to 19 password 6 to 12 characters number Phone number to be dialed. Use AT*L to view the directory. $P Display remote password Requires S80 bit 7 clear. Qn Result codes enable/disable The Qn command enables/disables the return of result codes. Q or Q0 Modem returns result codes (default). Q1 Modem does not return result codes. %Q Line signal quality Value Meaning 000 to 007 Good signal quality. 008 to 127 Poor signal quality. If the value rises over 007, a retrain occurs if retraining is enabled by AT%E1. &Qn Sync/async mode This is an extension of the AT&M command used to control the connection modes permitted. Used in conjunction with the S36 and S48 registers. See also AT\N. 7-30 Internal Modem Command Set &Q or &Q0 Direct async. Same as AT&M0. &Q1 Sync connect, async off-line. Same as AT&M1. &Q2 Not supported &Q3 Not supported &Q4 Same at AT&Q1 &Q5 Try to negotiate an error correcting link. Use S36 to determine whether a failure will result in aborting or reverting to a normal asynchronous connection (default). &Q6 Connect in asynchronous normal mode. $Qn Ring result code enable/disable The $Q command controls generation of RING result code (2). $Q or $Q0 Disable RING result code reporting (default). $Q1 Enable RING result code reporting. In the IM3/4 following a modem cold boot, ring qualification is enabled only after reception of the first AT command. Once ring qualification is enabled, reporting the RING result is enabled using $Q1. &Rn RTS/CTS option Controls how the modem will control CTS. Operation of CTS will be modified if hardware control is selected. See AT&K command. &R or &R0 CTS is per V.25bis specification (default). &R1 RTS transitions are ignored. CTS drop only as required by flow control. *R Request remote configuration mode (MNP only) The password is inserted in a remote configuration request, a special MNP frame, and sent to the remote modem. The password is a string of 6 to 12 characters. Following a successful request, indicated by the return of the !AT prompt, the terminal may send commands to the remote modem. These commands, which are a subset of the normal commands, should be sent without the 'AT' header. To exit the remote 7-31 Series 3000 Application Programmer’s Reference Manual configuration mode, *E must be sent. The default password is QWERTY. See also AT*C and AT*E. This command is only known to be compatible with other modems using the Rockwell chip set and code. $Rn Receive boost $R or $R0 Disable receiver gain. $R1 Enable 9dB receiver gain (default). For the IM5 to be able to receive up to 0dBm, use $R0. Sr? Read register value Read the contents of register r and report it as a decimal value in the range 0 to 255. Sn=x Assign register value Sets the register “n” to value “x”. The decimal value must be 0 to 255. Some registers may have limited ranges, and others are read only. \Sn Status display Displays configuration information and limited S register information. Scrolling may be stopped using CTRL-Q and started using CTRL-S. /S0 Verbose form. /S1 Concise form. &Sn DSR selection &S or &S0 DSR always on. &S1 DSR active after answer tone has been detected and inactive after carrier has been lost (default). $Sn Bell shunt control Set the bell (anti-tinkle) shunt for unattended answering (the modem must be in auto-answer mode), and pulse dialing on three-wire phone systems. The shunt is enabled in the country files. 7-32 Internal Modem Command Set $S0 Disable the shunt (default). $S1 Enable the shunt. T Force tone dialing &Tn Test and diagnostics &T or &T0 End test in progress. &T1 Initiate local analog loopback V.54, L3. &T3 Initiate digital loopback V.54, L2 locally. &T4 Allow remote request for remote digital loopback. &T6 Request a remote digital loopback V.54, L2. &T7 Request and RDL V.54, L2 with self test. &T8 Initiate local analog loopback V.54, L3 with self test. Vn Result code language V or V0 Send result codes in digits. V1 Send result codes in words (default). See Result Codes below for a listing of the codes. &V Display configuration Display the active configuration, stored profiles 0 and 1, and the first four stored telephone numbers. Wn Error correction message control W or W0 The Connect message indicates the terminal speed. W1 Upon connection, report line speed, error correction and compression protocols, and the terminal speed, in that order. W2 The Connect message indicates the line speed (&F1). 7-33 Series 3000 Application Programmer’s Reference Manual \Wn Split speed operation \W or \W0 Disable split speed mode (default). \W1 Enable split speed mode. V.23 operation (ATF3) is also forced. &Wn Store current configuration &W or &W0 Save settings in profile 0 (default). &W1 Save settings in profile 1. Xn Select result code set Selects which subset of the result messages are to be used by the modem to inform the terminal of command results. Dial tone detection may be forced by placing a W in the dial string. Valid values for n are given in the following chart: Extended n Connect Busy Report Wait for Allow Blind Message Dial Tone Dialing 0NoNoNoYes 1 Yes No No Yes 2YesNoYesNo 3 Yes Yes No Yes 4 Yes Yes Yes No 5 Not supported 6 Yes Extended call No Yes progress report 7 Yes Extended call Yes No progress report See the result code table for a description of the extended call progress messages. Default is X4. 7-34 Internal Modem Command Set Yn Long space disconnect Y or Y0 Disable long space disconnect (default). Y1 Enable long space disconnect. &Yn Designate default reset profile &Y or &Y0 Use profile 0 on power-up reset (default). &Y1 Use profile 1 on power-up reset. Zn Reset modem, restore profile Clear the command line buffer and reset the modem. Z or Z0 Reset and initialize with profile 0 parameters (default). Z1 Reset and initialize with profile 1 parameters. &Zn = string Store telephone number IM5: Stores telephone numbers in a directory. Up to 20 numbers can be stored (0 – 19). n Position in the directory, 0 – 19 string Telephone number string +++ Escape code sequence Forces the modem to the command state from the online state. Consists of a three character escape code sequence surrounded by escape guard times. The delay between issuance of each escape character must not exceed the escape guard time. The escape guard time is defined as the time delay between the last character transmitted and the first character of the escape code. The default guard time is 1 second and the default character sequence is “+++”. The escape character must be entered three consecutive times. To enter the escape code sequence using the default values: WAIT AT LEAST 1 SECOND (After the last character has been transmitted) Enter +++ (Delay less than one second between characters) 7-35 Series 3000 Application Programmer’s Reference Manual WAIT AT LEAST 1 MORE SECOND (BEFORE transmitting another character) The modem returns to the local command state and sends the OK result code. The modem will not release the telephone line until it receives an ATH or ATZ command, or it detects the loss of the carrier. Use the S2 command to change the escape code or the S12 command to change the escape guard time. 7-36 Internal Modem Command Set IM6 Commands A/ Repeat last command Repeat the last command. This command does not use the AT prefix or Carriage Return terminator. AT Attention code The prefix for all command lines except +++ and A/. A Immediate answer Answer the telephone immediately, transmit the answer tone and enter the appropriate connect sequence. This must be the final command in the line. Bn Select Bell or CCITT mode dependent on DTE B or B0 V.22 2100Hz answer tone is selected B1 Bell 212A 2225Hz answer tone selected (default) Cn Carrier control Provided for command compatibility purposes, but performs no function. The only valid parameter is 1. N=0 returns ERROR. &Cn DCD option &C or &C0 DCD remains ON at all times (default). &C1 DCD follows carrier on the line. Dstr Dial string (phone number) D is followed by the phone number to be dialed. T (Tone dialing), P (Pulse dialing) modifiers may follow. Default is Tone mode. The following characters may be included in the dial string. If the A, P, or T characters are used, they must immediately follow the D character. The other characters may occur anywhere in the string. 7-37 Series 3000 Application Programmer’s Reference Manual 0-9 Digits 0 to 9 Digits for the phone number when dialing. * Asterisk (star) symbol Available in tone dialing only. # Pound symbol Available in tone dialing only. A - D DTMF digits P Pulse dialing Force pulse dialing. The dialing make/break ratio is set using either the &Pn or Nn commands. R Reverse mode for calling originate- only modems Reverses the frequencies so that the modem makes a call using “answer” tones. This command is used when calling an “originate only” modem. An example command line would be: ATDT123-4567R. S=n Dial the stored number Dials the stored phone number specified by n. See &Z for storing numbers. T DTMF dialing Force DTMF (tone) dialing. W Wait Wait for a dial tone for the period specified by S6, before continuing the dial sequence. If no dial tone is found, a NO DIALTONE message is sent. If a busy condition is detected, the modem hangs up and a BUSY message is sent. For instance, if a system requires that the numeral 9 be dialed to obtain an outside line, the dial string could be ATDT9W123-4567. 7-38 Internal Modem Command Set @ Wait for silence Forces the modem to wait for at least 5 seconds of silence in the call progress frequency band before continuing with the next dial string parameter. , Pause Pause between characters (0 - 255 seconds) set by register S8. ; Return to command state Return to the command state after dialing. This may be used to dial numbers with greater than 40 digits, or to access data bases that require tone identification. ! Flash hook Go on hook. &Dn DTR option 0Modem ignores DTR (default). 1 Modem assumes command state when on-to-off transition is detected on DTR. 2 Modem hangs up, assumes command state, and disables auto-answer upon detecting on-to-off transition on DTR. 3 Modem assumes initialization state upon detecting on-to-off transition on DTR. 7-39 Series 3000 Application Programmer’s Reference Manual %Dn DTMF attenuation Sets the DTMF transmit level attenuation. n=0 0dB (default) n=1 2dB n=2 4dB n=3 6dB n=4 8dB n=5 10dB n=6 12dB n=7 14dB En Command echo E or E0 Disable character echo in the command mode. E1 Enable character echo in the command mode. Default is E1. Fn On-line Echo Character Option Fn determines whether characters are echoed to the host from the modem in the on-line state. This command is reserved for echoing of characters in the on-line state. The RC224ATL does not echo characters in the on-line state. n=0 Returns ERROR result code. n=1 Returns OK result code (default). &F Load factory configuration Sets S registers and commands to the Rockwell factory default values. The Rockwell defaults are as follows: S Registers: S0=0, S1=0, S2=43, S3=13, S4=10, S5=8, S6=0, S7=30, S8=2, S9=6, S10=14, S11=95, S12=50, S18=0, S25=5, S26=1, S28=0. Commands: B1, C1, E1, F1, L2, M1, P, Q0, V1, Y0, X4, &C0, &D0, &G0, &J0, &M0/&G0, &P0, &R0, &S0, &T4, and &X0. 7-40 Internal Modem Command Set &Gn Guard tone generation &G or &G0 Disable the guard tone (default). &G2 Transmit 1800-Hz guard tone in V.22 answer mode. Hn Telephone switch hook control H or H0 On hook (disconnect) (default). H1 Off hook (connect). In Product information or check sum I or I0 “242” I1 Copyright date I2 Reports “OK” (IM6 checksum). I3 Firmware revision. %J Secondary defaults Resets all S Registers and commands to the &F defaults with the following exceptions: S Register/Command % J Defaults S6 3 seconds; range:3-255. S11 95 ms; range: 60-255. %Ln 6dB; (%L3). %Dn 2dB; (%D1). &Jn Auxiliary Relay Control Determines how the auxiliary relay is controlled. n=0 The auxiliary telco relay is commanded to stay open. Suitable for JR-11, RJ-41S, or RJ-45S type phone jack (default). n=1 The auxiliary telco relay is controlled by off-hook/on- hook. If the modem is off-hook, the relay is commanded to close (connecting A to A1); if the modem is on-hook, the relay is commanded to open (disconnecting A from A1). Suitable for RJ-12 or RJ-13 type phone jack. 7-41 Series 3000 Application Programmer’s Reference Manual Ln Speaker volume For compatibility only since the modems do not have speakers. Accepts values of 0 - 3. %L Line signal level Direct indication of the receive level attenuation at the data pump. n=0 0dB (default) n=1 2dB n=2 4dB n=3 6dB n=4 8dB n=5 10dB n=6 12dB n=7 14dB &Ln Line type Provided for compatibility only since leased line operation is not supported. Mn Speaker control Supported for compatibility only since the modems do not have speakers. M or M0 Speaker disabled. M1Speaker disabled during reception of carrier (default). M2 Speaker always enabled. M3 Speaker disabled during reception of carrier and during dialing. On during answering phase. &Mn Synchronous mode select &M or &M0 Direct async (default). &M1 Not supported. &M2 Not supported. &M3 Not supported. 7-42 Internal Modem Command Set On Go to on-line state O or O0 Return to on-line state. O1 Return with retrain (V.22bis only). &Pn Pulse dial make/break ratio Controls the ratio of the off-hook (make) to on-hook (break) interval used for pulse dialing. Same command as Nn. &P or &P0 39/61 for USA, Canada, Austria, Italy, the Netherlands, Denmark (default). At 10 pulses/sec. &P1 33/67 for UK, Belgium, France, Germany. At 10 pulses/ sec. &P2 39/61 at 20 pulses per second. &P3 33/67 at 20 pulses per second. Qn Result codes enable/disable The Qn command enables/disables the return of result codes. Q or Q0 Modem returns result codes (default). Q1 Modem does not return result codes. &Qn Sync/async mode This is an extension of the AT&M command used to control the connection modes permitted. Used in conjunction with the S36 and S48 registers. See also AT\N. &Q or &Q0 Direct async. Same as AT&M0. &Q1 Not supported. &Q2 Not supported &Q3 Not supported Use S36 to determine whether a failure will result in aborting or reverting to a normal asynchronous connection (default). 7-43 Series 3000 Application Programmer’s Reference Manual Sr? Read register value Read the contents of register r and report it as a decimal value in the range 0 to 27. Sn=x Assign register value Sets the register “n” to value “x”. The decimal value must be 0 to 27. Some registers may have limited ranges, and others are read only. Sn Select an S register Sn sets the pointer to a particular S Register, where “n” is the number of the register. Until another register is specified, the value “n” can be read with AT? and changed with AT=. Range: n=0-27. &Sn DSR selection &S or &S0 DSR always on (default). &S1 DSR active after answer tone has been detected and inactive after carrier has been lost. &Tn Test and diagnostics &T or &T0 End test in progress. &T1 Initiate local analog loopback V.54, L3. &T3 Initiate digital loopback V.54, L2 locally. &T4 Allow remote request for remote digital loopback. &T6 Request a remote digital loopback V.54, L2. &T7 Request and RDL V.54, L2 with self test. &T8 Initiate local analog loopback V.54, L3 with self test. Vn Result code language V or V0 Send result codes in digits. V1 Send result codes in words (default). See Result Codes below for a listing of the codes. 7-44 Internal Modem Command Set &V Display configuration Display the active configuration, stored profiles 0 and 1, and the first four stored telephone numbers. &Wn Store current configuration &W or &W0 Save settings in profile 0 (default). &W1 Save settings in profile 1. &Xn Asynchronous Data Transmission Selects the source of the transmit clock. n=0 Modem sources transmit clock (default). n=1 Reserved n=2 Reserved Xn Select result code set Selects which subset of the result messages are to be used by the modem to inform the terminal of command results. Dial tone detection may be forced by placing a W in the dial string. The following chart lists the valid values for n. Extended n Connect Busy Report Wait for Message Dial Tone 0NoNoNo 1 Yes No No 2YesNoYes 3YesYesNo 4 Yes Yes Yes See the result code table for a description of the extended call progress messages. Default is X4. For IM6 modems, the valid parameters are 0-4. 7-45 Series 3000 Application Programmer’s Reference Manual Yn Long space disconnect Y or Y0 Disable long space disconnect (default). Y1 Enable long space disconnect. &Yn Designate default reset profile &Y or &Y0 Use profile 0 on power-up reset (default). &Y1 Use profile 1 on power-up reset. Zn Reset modem, restore profile Clear the command line buffer and reset the modem. Z or Z0 Reset and initialize with profile 0 parameters (default). Z1 Reset and initialize with profile 1 parameters. &Zn = string Store telephone number n Position in the directory, 0 – 19 string Telephone number string IM6: Stores up to 4 strings for later recall by DS dial stored number command. Parameters: 0-3 Command Format: &Z 7-46 Internal Modem Command Set WAIT AT LEAST 1 SECOND (After the last character has been transmitted) Enter +++ (Delay less than one second between characters) WAIT AT LEASE 1 MORE SECOND (Between transmitting another character) The modem returns to the local command state and sends the OK result code. The modem will not release the telephone line until it receives an ATH or ATZ command, or it detects the loss of the carrier. Use the S2 command to change the escape code or the S12 command to change the escape guard time. 7-47 Series 3000 Application Programmer’s Reference Manual IM7 Commands Bn Select Bell or CCITT mode dependent on DTE B or B0 CCITT(default) B1 Bell B2 Selects V.23. B3 Selects Bell 202. Dstr Dial string (phone number) Will ignore the dialing string (’str’), however, the driver will go into ’On- line’ mode and return the proper ’CONNECT’ string. En Command echo E or E0 Disable character echo in the command mode. E1 Enable character echo in the command mode. G Modem capability code The modem returns a two byte, bit-mapped code indicating the features that it supports. The code mapping is shown in the following figure. On the IM7, this command returns a 4-digit string. This string is 004FH. . 5 14 13 12 11 10 9 8 7 6 5 432 1 0 V23 Bell 103 V21 (same as Bell 103) Bell 212 @ 1200 baud (same as V22 BIS) Bell 202 V22 @ 600 baud V22 @ 1200 baud V22 @ 2400 baud (V22 BIS) MNP 4/5 V42/V42 BIS Jn Direct connect or COM2 data redirect Performs no function. J0, J3, & J7 return ’OK’. 7-48 Internal Modem Command Set Ln Mark and space boost This command handles the Mark and space boost. The low nibble contains the Space boost value. The low nibble contains the Space boost value (from 0-15) and the upper nibble contains the Mark boost value (0- 15). If the two values are equal, a Flat signal (no boost) will be selected with the minimum gain (-15dBm). If the two values are not equal, the largest value will determine whether the Mark or Space boost is used. The absolute difference between the values divided by four will determine the gain. Mn Speaker control Performs no function, returns ’OK’. Nn Pulse dial ratio Performs no function, for compatibility purposes only. Returns ’OK’. P Force pulse dialing Performs no function, for compatibility purposes only. Returns ’OK’. Sr? Read register value Allows for any value of ’r’, and except for S26, will always return ’0000’ as a value. S26 returns the RTS/CTS Delay Time. Sn=x Assign register value Allows any value for n and except for s26, ignores the supplied value. Always returns ’OK’. T Force tone dialing Performs no function, returns ’OK’. Vn Result code language V or V0 Send result codes in digits. V1 Send result codes in words (default). See Result Codes below for a listing of the codes. 7-49 Series 3000 Application Programmer’s Reference Manual Xn Select result code set Selects which subset of the result messages are to be used by the modem to inform the terminal of command results. Dial tone detection may be forced by placing a W in the dial string. The following chart lists the valid values for n. Extended n Connect Busy Report Wait for Message Dial Tone 0NoNoNo 1 Yes No No 2YesNoYes 3YesYesNo 4 Yes Yes Yes Zn Reset modem, restore profile Clear the command line buffer and reset the modem. 7-50 Internal Modem Command Set Result Codes Result codes are responses from the modem to user commands. They are returned as either words (V1) or digits (V0). Returning result codes can be disabled (Q1) or enabled (Q0). If result codes are enabled, the Ring Detect result code (2) can be disabled ($Q0) or enabled ($Q1). The result codes are shown in Table 7-1. Codes 16–80 apply to the IM5 only. Result codes 0-8, 10, +F4, and 13 are the only result codes which apply to the IM6 modem. 0, 1, 4, and 9 are the only result codes which apply to the IM7 modem. Table 7-1. Result Codes # Verbal 0123467 0 OK XXXXXXX 1 CONNECT XXXXXXX 2 RING XXXXXXX 3 NO CARRIER XXXXXXX 4 ERROR XXXXXXX 5 CONNECT 1200 (1)XXXXXX 6NO DIAL TONE XXX 7 BUSY XXXX 8 NO ANSWER (IM5, IM6 only) XXXXXXX 9 CONNECT 600 (NOT IM6) (1)XXXXXX 10CONNECT 2400 (1)XXXXXX 11CONNECT V.23 (1)XXXXXX 12V.23 T1200/R75 (IM3/4) XXXXXXX CONNECT 4800 (IM5) (1)XXXXXX 13V.23 T75/R1200 (IM3/4) XXXXXXX CONNECT 9600 (IM5) (1)XXXXXX DATA (IM6) 16CONNECT 19200 (1)XXXXXX 22CONNECT 1200TX/75RX (1)XXXXXX 7-51 Series 3000 Application Programmer’s Reference Manual Table 7-1. Result Codes (Continued) # Verbal 0123467 23CONNECT 75TX/1200TX (1)XXXXXX 24 DELAYED (4) (4) (4) (4) (4) X X 32 BLACKLISTED (4) (4) (4) (4) (4) X X 40 CARRIER 300 X X 44 CARRIER 1200/75 X X 45 CARRIER 75/1200 X X 46 CARRIER 1200 X X 47 CARRIER 2400 X X 66 COMPRESSION: CLASS 5 X X 67 COMPRESSION: V.42bis X X 69 COMPRESSION: NONE X X 76 PROTOCOL: NONE X X 77 PROTOCOL: LAPM X X 80 PROTOCOL: ALT X X +F4 +FCERROR (IM6 only) The following are software hyperextended progress messages: 144 OFF HOOK-L X X 145 DIAL TONE X X 146 DIALING T X X 147 DIALING P X X 148 RINGING X X 149 OFF HOOK-R X X 150 ANSWER TONE X X 151 INCOMING CALL* (4) (4) (4) (4) (4) X X X = numeric or verbal response is generated (n) = verbal or numeric response is replaced by response (n) * This message is generated if the phone is ringing or has rung with the last eight seconds, provided power is not removed. 7-52 Internal Modem Command Set S Register Descriptions Table 7-2 summarizes the S registers used by the internal modems. The IM6 modem uses only S Registers S1-S28. The specific contents of several bit mapped registers are shown in tables 7-3 through 7-21. The default values for the bit mapped registers are shown in bold type. Table 7-2. S Register Summary Reg. Type Value Units Defaults Description S0 WSC 0-255 rings 0, disable Number of rings before modem answers S1 R 0-255 rings 0 Count rings S2 WS 0-127 ASCII 43, “+” Escape character S3 W 0-127 ASCII 13, “CR” Carriage Return S4 W 0-127 ASCII 10, “LF” Line Feed S5 W 0-32, ASCII 8, “BS” Backspace 127 (IM6) 0-127 (IM5) S6 WSC 2-255 seconds 5(IM5), Wait for dial tone 2(IM6) S7 WSC 1-60 seconds 30 Wait for carrier (IM5) 1-255 (IM6) S8 WSC 0-255 seconds 1 (IM5), Pause for comma 2(IM6) S9 WSC 1-255 0.1 sec 8 on IM3/4 Carrier detect time 6 on IM5/6 S10 WSC 1-255 0.1 sec 7 on IM3/4 Delay for loss of carrier 14 on IM5/6 S11 50-255 millisec 95 Duration and spacing of Touch Tones Not Used on IM5 S12 WS 0-255 20 millisec 50 Escape code guard time 7-53 Series 3000 Application Programmer’s Reference Manual Table 7-2. S Register Summary (Continued) Reg. Type Value Units Defaults Description S13 Not Used S14 RS Bit Mapped 138 E, Q, V, D S15 R Not Used 0IM5 autoselect 0: direct connect 3: autoselect com2 7: redirect I/0 S16 R Bit Mapped (IM5) 0 &T test commands S17 R 0-250 4ms 0 Fax mode Null Byte Timer (IM6) increments S18 WS 0-255 seconds 0 Test Timer S19 0-1 NONE 0 Rockwell Protocol Interface (RPI) Speed (IM6) S20 0-127 seconds 0 Fax Mode Inactivity Timer S21 RS Bit Mapped 96 (IM5) &J, &R, &D, &C, &S, Y 2 (IM3/4) Bit Mapped Options Register 0 (IM6) S22 WCRS Bit Mapped 117 (IM5) L, M, X 96 (IM3/4) Bit Mapped Options Register 76hex (IM6) S23 RS Bit Mapped 182 (IM5) &G 150 (IM3/4) Bit Mapped Options Register 7(IM6) S24 WS Bit Mapped 128 (IM3/4) $C, %F, X 0-255 (IM6) 0 (IM5) Sleep Mode Inactivity Timer 0 (IM6) S25 W 0-255 0.1 or 1 sec 5 (IM6) Delay to DTR S26 W 0-255 10ms 20 RTS - CTS Delay 1 (IM6) S27 RS Bit Mapped 10 (IM5) *G, B 128 (IM3/4) Bit Mapped Options Register 40hex (IM6) S28 RS Bit Mapped 0 \W, %F, &P,%M Bit Mapped Options Register 7-54 Internal Modem Command Set Table 7-2. S Register Summary (Continued) Reg. Type Value Units Defaults Description S29 WC 0-255 10ms 255 Flash dial modifier S30 W 0-255 seconds 0 Inactivity timer S31 RS Bit Mapped 10 N, W S32 W 0-255 ASCII 17 XON character S33 W 0-255 ASCII 19 XOFF character S34 Not Used S35 Not Used S36 WS 0-7 7 LAP-M failure code S37 WS Bit Mapped 0 F S38 W 0-255 seconds 15 Delay before forced hang-up (EC modes) S39 RS Bit Mapped 3 &K S40 RS Bit Mapped 169 -K, \K, \A S41 RS Bit Mapped 4 %C, %E, \G, \L, \J S42 - Not Used S45 S46 WS 136, 136 V.42bis data compression 138 136 - no compression 138 - compression S47 Not Used S48 WS 0,7,128 7 V.42 negotiation control 0 - force LAP-M 7 - enable negotiation 128 - force to S36 S49 - Not Used S79 S80 W Bit Mapped 82 S81 Not Used S82 W 3,7,128 128 128, Break options, LAP-M 3 - expedited 7 - 128 - 7-55 Series 3000 Application Programmer’s Reference Manual Table 7-2. S Register Summary (Continued) Reg. Type Value Units Defaults Description S83 - Not Used S85 S86 R 0-255 0 Call failure indications S87 - Not Used S90 S91 WCP 0-15 10 PSTN transmit level S92 WCP 0-15 10 FAX transmit level S93 - Not Used S94 S95 WS Bit Mapped 0 S96 - Not Used S98 S99 WP 0-15 10 Leased line level Type code: R - Read only W - Writable S - Saved in EEPROM (IM5 only) C - Subject to country limitations and override (IM5 only) P - May require S80 bit 7 clear to save (IM5 only) Notes: Registers S28 - S99 are IM5 only registers. Defaults listed for IM5 are IM3/4 compatible using &F0 Table 7-3. Register S14 Bit Map, IM3/4/5 (Default: 138, 8AH) Bit Description 0 0 Bell shunt disabled $S command 1 Bell shunt enabled 10Local echo disabled E command 1 Local echo enabled 2 0 Result codes enabled Q command 1 Result codes disabled 30Result codes sent as digits V command 1 Result codes sent as words 7-56 Internal Modem Command Set Bit Description 4 0 Enable command recognition Not used on IM5 1 Not Used 5 0 Tone Dial T modifier to D command 1 Pulse Dial P modifier to D command 6 0 Disable ring messages $Q command 1 Enable ring messages 70Answer 1 Originate Table 7-4. Register S16 Bit Map, IM5 Only (Default: 0) Bit Description 0 0 Local analog loopback off &T1 command 1 Local analog loopback on 1Not Used 2 0 Local digital loopback off &T3 command 1 Local digital loopback on 3 0 RDL (remote initiated) off &T4, &T5 commands 1 RDL in progress 4 0 Remote digital loopback off &T6 command 1 Remote digital loopback on 5 0 RDL with self test off &T7 command 1 RDL with self test on 6 0 LAL with self test off &T8 command 1 LAL with self test on 7 Reserved Table 7-5. Register S21 Bit Map, IM5 (Default: 96, 60h) Bit Description 0 0 Direct connect &J command 1 Not supported 1Not Used 2 0 AT&R0 &R command (IM5) 1 AT&R1 7-57 Series 3000 Application Programmer’s Reference Manual Bit Description 4,3 00 AT&D0 &D command (IM5) 01 AT&D1 DTR behavior 10 AT&D2 Not supported 11 AT&D3 50DCD always on &C command (IM5) 1 DCD follows carrier DCD behavior 60DSR always on &S command (IM5) 1 Modem controls DSR DSR behavior 7 0 Long space disconnect off Y command 1 Long space disconnect on Table 7-6. Register S21 Bit Map, IM3/4 (Default: 2, 02h) Bit Description 0 0 Direct connect J command 1 Not Supported Default J command 10Autoselect disabled A modifier to D commands 1 Autoselect enabled 2Not Used 3Not Used 4Not Used 5Not Used 6Not Used 7 0 Long space disconnect off Y command 1 Long space disconnect on Not Supported Table 7-7. Register S22 Bit Map, IM5 (Default: 117, 75h) Bit Description 1 0 00 Volume off L command 01 Volume low Modem audio monitor volume. 10 Volume medium 11 Volume high 7-58 Internal Modem Command Set Bit Description 3,2 00 Speaker disabled M command 01 On until carrier Speaker disable. 10 Always on On after dial, off at carrier 11 6–4 000 ATX0 selected X command 100 ATX1 selected Limit result codes 101 ATX2 selected 110 ATX3 selected 111 ATX4 selected 010 ATX6 selected 011 ATX7 selected 7Not Used Table 7-8. Register S22 Bit Map, IM3/4 (Default: 96, 60h) Bit Description 1,0 00 Volume low Modem audio monitor volume 01 Volume low Not Used 10 Volume medium 11 Volume high 3,2 00 Speaker disabled Not Used 01 on until carrier 10 always on 11 on after dial, off at carrier 4 0 Dial tone wait off - 1 Dial tone wait on X2, X4, X7 50Busy detect off - 1 Busy detect on X3, X4, X6, X7 60Extended response off - 1 Extended response on X1 - X4, X6, X7 7 0 39/61% make/break ratio (US/ N, &P commands Canada) 1 33/67% make/break ratio (UK) - 7-59 Series 3000 Application Programmer’s Reference Manual Table 7-9. Register S23 Bit Map, IM5 (Default: 182, 6Bh) Bit Description 00RDL denied &T4, &T5 commands 1 RDL accepted 3–1 000 0–300 bps Data Rate 001 600 bps 010 1200 bps 011 2400 bps 100 4800 bps 101 9600 bps 110 19200 bps 5400 Even Parity 01 Space/none 10 Odd 11 Mark/none 7600 Off Guard Tone 01 550 Hz &G command 10 1800 Hz 11 Not Used Note: This register value is saved in EEPROM and reflects the last operating value. 7-60 Internal Modem Command Set Table 7-10. Register S23 Bit Map, IM3/4 (Default: 150, 96h) Bit Description 0 0 RDL Denied Not Supported 1 RDL accepted 2,1 Data Rate 00 0-300 bps 01 600 bps 10 1200 bps 11 2400 bps 3Not Used 5,4 Parity 00 Even 01 Space/none 10 Odd 11 Mark/none 7,6 Guard Tone 00 Off 01 550 Hz &G command 10 1800 Hz - 11 Not Used - - 7-61 Series 3000 Application Programmer’s Reference Manual Table 7-11. Register S24 Bit Map, IM3/4 only (Default: 128, 80h) Bit Description 4–0 00000 USA Country Codes 00001 Great Britain $C command 00010 France 00011 Germany 00100 Italy 00101 Netherlands 00110 Denmark 00111 USA (CCITT answer tone only) 01000 Belgium 01001 Austria 01010 Not Used through 11111 6,5 00 V. 2 3 mo d e o ff V. 23 Mo d e 01 75 bps transmit, 1200 bps receive %F command 10 1200 bps transmit, 75 bps receive 11 1200 bps transmit/receive (half duplex) 70 Software call progress off X6, X7 1 Software call progress on Note: S24 on the IM5 modem is the sleep inactivity timer and is not used because the terminal controls power. To set the country selection on the IM5 , use the $C command. 7-62 Internal Modem Command Set Table 7-12. Register S27 Bit Map, IM5 (Default 10, 0Ah) Bit Description 0,1,3 0,0 AT&M0 or AT&Q0 Sync/Async selection 1,0 AT&M1 or AT&Q1 &M and &Q commands 2,0 AT&M2 or AT&Q2 3,0 AT&M3 or AT&Q3 0,1 AT&Q4 1,1 AT&Q5 2,1 AT&Q6 2 Leased line flag &L command 4, 5 0 Internal sync clock Synchronous clock select, 1 External sync clock (not supported) &X command* Slave sync clock (not supported) 2 6 0 CCITT protocol B command 1 Bell protocol 7Not Used * Command not supported. Do not modify these bits. Table 7-13. Register S27 Bit Map, IN3/4 (Default: 128, 80H) Bit Description 0Not Used 1Not Used 2Not Used 3 0 Calling tone disabled *G command 1 Calling tone enabled 4Not Used 5Not Used 6 0 CCITT protocol B command 1 Bell protocol 70Half duplex B3 command 1 Full duplex %F command 7-63 Series 3000 Application Programmer’s Reference Manual Table 7-14. Register S28 Bit Map, IM5 only (Default 0) Bit Description 0 0 Viewdata disabled \W command 1 Viewdata enabled 1 0 75bps transmit %F command 1 1200bps transmit 2 0 Disabled %F3, B3 commands 1 Enabled V. 23 ha lf d u p l e x 3,4 0 60/40 at 10pps &P, N commands 1 67/33 at 10pps Pulse dialing rate 2 60/40 at 20pps 3 67/33 at 20pps 5 Auxiliary port control %M command* Not used 6 0 Calling tone disabled *G command 1 Calling tone enabled Calling tone 7Not Used * Command not supported. Do not modify this bit. Table 7-15. Register S31 Bit Map, IM5 only (Default 10, 0Ah) Bit Description 0 Reserved 10Automode off Auto line speed detection 1 Automode on N command 3,2 00 Report terminal speed only Error correction messages 01 Report terminal speed, correction W command and line speed 10 Report line speed only 4-7 Not Used 7-64 Internal Modem Command Set Table 7-16. Register S37 Bit Map, IM5 only (Default 0) Bit Description 0-2 0 Auto mode Select line modulation 1-3 V.21 or Bell mode F command 5 V.22 or Bell 212a mode 6 V. 22 bi s m o de 7 V. 23 m o de 3-7 Not Used Table 7-17. RegisterS39 Bit Map, IM5 only (Default 3) Bit Description 0-2 0 No flow control Flow control 3 RTS/CTS flow control &K command 4 XON/XOFF flow control 5 Transparent XON flow control RTS/CTS and XON/XOFF flow 6 control 3-7 Not Used Table 7-18. Register S40 Bit Map, IM5 only (Default 169, A9h) Bit Description 00Disable conversion V.42 to MNP10 conversion, MNP10 1 Enable conversion extended services -K command* 1 0 Disable power adjustment Power adjust for cellular MNP10 1 Enable power adjustment during )M command* MNP10 negotiation 20Negotiate link at highest speed MNP link negotiation speed *H command* 1 Negotiate link at 1200bps 3-5 Break handling \K command* 7,6 0 64 characters MNP block size 1 128 characters \A command 2 192 characters 3 256 characters * Command not supported. Do not modify these bits. 7-65 Series 3000 Application Programmer’s Reference Manual Table 7-19. Register S41 Bit Map, IM5 only (Default 4) Bit Description 0,1 0 Disabled Compression selection 1 MNP5 %C command 2 V. 42 bi s 3 MNP5 or V.42bis 20Retrains disabled Auto-retrain control 1 Retrains enabled %E command 3 0 Disabled Modem to modem flow control 1 Enabled \G command 4 0 Stream mode MNP Block mode control 1 Block mode \L command 5 0 DTE speed to match line \J 1Enabled command 6Not Used 7 Reserved Table 7-20. Register S80 Bit Map, IM5 only (Default 130, 82h) Bit Description 0 0 AT set selected V.25/AT command set select 1 V.25bis set selected 10Disabled Remote configuration enable 1 Enabled 2 0 Disabled Secure access (callback) enforcement 1 Enabled 3 0 Originate selected Originate/answer selection 1 Answer selected 4-6 Reserved 70Enables $I and $P commands; Test mode enable, subject to country enables saving S91, S92 and S99 limitations 1 Disables special commands; prevents saving S91, S92 & S99 7-66 Internal Modem Command Set Table 7-21. Register S95 Bit Map, IM5 only (Default 0) Bit Description 0 CONNECT message reports line speed instead of terminal speed 1 Appends /ARQ to connect message if an error corrected link is established 2 CARRIER message enable (messages 40-47) 3 PROTOCOL message enable (messages 70-80) 4Not Used 5 COMPRESSION message enable (messages 65-69) 6Not Used 7Not Used 7-67 Series 3000 Application Programmer’s Reference Manual IM8/IM8S Modems The IM8 and IM8S modems support the Hayes AT-command set. This section describes the basic commands, result codes, and S-registers for these modems. Many AT-commands and S-registers are compatible with the commands of the predecessor of the IM8, the IM5. Programming Considerations There are a number of special considerations to keep in mind when programming the internal modem. Modem Capabilities These are the IM8/IM8S modem protocol capabilities: V.21, V.22, V.22bis, V.23, V.23hdx, V.32, V.32bis, Bell103, Bell212. V.42, V.42bis, MNP2-4, MNP5. Note: The IM8 and the IM8S have virtually the same capabilities. The main difference between the two modems is that the IM8S is used inside the PDT teminal, where the IM8 is used inside a cradle. DTE Speeds The IM8 and IM8S supports the 19200 DTE speed. All speeds are detected automatically. For maximum throughput during error- corrected connections a speed of 19200 bps is recommended. DTR Line and Power Power to the IM8/IM8S modems is controlled by the DTR line. When DTR is lowered, the modem is powered down. When DTR is raised, the modem goes through its boot process, which takes some time. The application must includea minimum delay of 1000ms between raising DTR and sending data.In IM8/IM8S modems, non-default parameters may be set in non-volatile memory, eliminating the need to reset them each time DTR is raised. Also, observe this additional guideline: 7-68 Internal Modem Command Set • Wait at least one second between dropping DTR and raising it again, to assure a full reset of the modem. Otherwise, the modem may not fully reset, resulting in unpredictable behavior. 7-69 Series 3000 Application Programmer’s Reference Manual IM8/IM8S AT-Commands The commands are listed in alphabetical order, with brief descriptions. Commands may be entered in either upper or lower case. The term “n” indicates a numeric digit. If the digit is omitted, the value is assumed to be 0. All command lines except A/ must begin with AT. More than one command may be entered at a time, up to a maximum of 40 characters, not including the AT and Carriage Return. Command lines are not executed until a Carriage Return (0Dh) is entered (except when A/ is used). Commands entered may be deleted by the BACKSPACE character (08h). A/ Repeat last command Repeat the last command. This command does not use the AT prefix or Carriage Return terminator. AT Attention code The prefix for all command lines except A/. AT=x Write to current S register The current register is determined by the last Sr? command. Some registers are subject to country-specific limitations. Other registers are read-only. Refer to the S-register descriptions later in this chapter for details. AT? Read selected S register Returns the contents of the S register selected by the last Sr? command. ATA Immediate answer Answer the telephone immediately, transmit the answer tone and enter the appropriate connect sequence. This must be the final command in the line. AT\An Select maximum MNP block size \A or \A0 64 characters \A1 128 characters (default) 7-70 Internal Modem Command Set \A2 192 characters \A3 256 characters ATBn Select Bell or CCITT mode dependent on DTE B or B0 CCITT (default) B1 Bell B2 Permits generation of the Bell answer tone in FSK modes subject to country limitations..B3 Select V.23 half duplex.(same as %F3) B4 Permits generation of Bell answer tone in v.23 mode (for Bell 202 compatibility) If the requested capability is not available in the installed modem, the ERROR message is sent. AT\Bn Send break Under non-error corrected link operation, the modem will transmit a break signal to the remote modem. Under error corrected link operation, the modem will signal break through the active error correction protocol, giving no indication of the length. An ERROR response will be generated if either not connected, or if the parameter is 0. 1-9 break length in 100ms units (default is 3 in non-error corrected links only. AT*B Return blacklisted numbers Blacklisted numbers are subject to dialing restrictions. Dialing restrictions are controlled by the country files. AT$Bn Bell answer tone detect For compatibility only, performs no function. ATCn Carrier control Provided for command compatibility purposes, but performs no function. The only valid parameter is 1. AT%Cn Enable/disable data compression %C0 Disable data compression 7-71 Series 3000 Application Programmer’s Reference Manual %C1 Enable MNP5 data compression negotiation. %C2 Enable V.42bis data compression. %C3 Enable V.42bis and MNP5 compression (default for &F0) AT&Cn DCD option &C0 DCD remains ON at all times. &C1 DCD follows carrier on the line (default). AT*C Remote configuration password For compatibility only, performs no function. AT$Cn Country code In IM 8 modems, the country code sets call progress parameters, dialing parameters, (DTMF and pulse), blacklisting, blind dialing, guard tone generation, S register defaults, and range limitations. To ensure that modem hardware and firmware is set for reliable operation and to maintain regulatory compliance, the following must be observed: • The AT15 command interrogates Country Code settings. • The country codes from the following table must be set using AT$Cn (where n is Code). • An ATZ command must follow the $C to make sure the new parameters become effective The IM8(S) modem supports country codes 0-23 in the following chart: Table 7-22. Country Codes when only Tone Dialing (default states, see ATD command) Code Country 0 USA, Canada 1 Austria, Belgium, Denmark, Finland, France, Germany, Greece, Iceland, Ireland, Italy, Liechtenstein, Luxembourg, Netherlands, Norway, Portugal, Spain, Sweden, Switzerland, United Kingdom 7-72 Internal Modem Command Set Table 7-23. Country Codes for use when either Tone or Pulse Dialing Code Country Code Country 0 USA, Canada (Bell 12 Finland Enable) 1 United Kingdom 13 Ireland 2 France 14 Reserved for potential use in Japan 3 Germany 15 Luxembourg 4 Italy & Greece 16 Reserved for potential use in Mexico 5 Netherlands 17 Reserved for potential use in New Zealand 6 Denmark 18 Norway, Iceland, Liechtenstein 7 USA and Canada 19 Portugal (CCITT) 8 Belgium 20 Reserved for potential use in Singapore 9 Austria 21 Spain 10 Australia 22 Sweden 11 USA & Canada 23 Switzerland In IM8 modems, the country code sets call progress parameters, dialing parameters (DTMF and pulse), blacklisting, blind dialing, guard tone generation, S register defaults, and range limitations. An ATZ command must follow the $C to make sure the new parameters become effective. Default country is USA ($C0). ATDstr Dial string (phone number) D is followed by the phone number to be dialed. T (Tone dialing), P(Pulse dialing) modifiers may follow. Default is Tone mode. Invalid characters are ignored by the modem. 7-73 Series 3000 Application Programmer’s Reference Manual The following characters may be included in the dial string: 0-9 Digits 0 to 9 Digits for the phone number when dialing. *,# Asterisk (star) and Pound symbol Available in tone dialing only. ( ),—, 7-74 Internal Modem Command Set @ Wait for silence Forces the modem to wait for at least 5 seconds of silence in the call progress frequency band before continuing with the next dial string parameter. , Pause Pause between characters (0 - 255 seconds) set by register S8. In the IM8, the default is set by the country code. ; Return to command state Return to the command state after dialing. This may be used to dial numbers with greater than 40 digits, or to access data bases that require tone identification. !Flash hook Go on hook. In the IM8, the duration is set in the S29 register and subject to country limitations. ^ Disable/Enable calling tone transmission Depending on country-settings, this dialmodifier disables or enables the calling tone transmission for the current call only. AT&Dn DTR option Supported for compatibility only, performs no function. Accepts values 0-3. AT*D Return delayed numbers Returns a list of delayed telephone numbers. Calling limitations are set in the country files. ATEn Command echo E0 Disable character echo in the command mode. E1 Enable character echo in the command mode. (Default). AT%En Auto retrain and fallback/fall forward Controls whether or not the modem will automatically monitor the line quality and request a retrain (%E1) or fall back when line quality is insufficient or fall 7-75 Series 3000 Application Programmer’s Reference Manual forward when line quality is sufficient (%E2). When enabled, the modem attempts to retrain for a maximum of 30 seconds. %E0 Disable auto-retrain (default). %E1 Enable auto-retrain. %E2 Enable fallback/fall forward. AT*E Exit remote configuration mode For compatibility only, performs no function. ATFn Select line modulation Line modulation is fixed unless auto mode (ATF0) is selected. Interacts with the AT$N command. F0 Auto mode detection, line speeds up to 14400bps F1 V.21/Bell 103 (according to ATB command) at 300bps. F2 Not supported. Error is returned. F3 V.23 75TX/1200RX originate or 1200TX/75RX answer. F4 V.22 A/B or Bell 212A (according to ATB command) at 1200bps. F5 V.22bis F6 V.32(bis) 4800 bps. F7 V.32bis 7200bps. F8 V.32(bis) 9600 bps. F9 V.32bis 12000 bps. F10 V.32bis 14400 bps. ATF6 to ATF10 work in IM8 modem only, also see ATJ8. AT%Fn V.23 control %F0 V.23 disabled (default). %F1 75 bps transmit, 1200 bps receive. %F2 1200 bps transmit, 75 bps receive. 7-76 Internal Modem Command Set %F3 1200 bps half duplex. AT&F Restore factory configuration &F0 V.42bis/V.42 and MNP5/MNP4 operation. Set terminal speed at 19200 to maximize throughput. .AT\F Display telephone directory Displays numbers stored with the AT&Z command. ATG Modem capability code The modem returns a two byte, bit-mapped code indicating the features that it supports. The code mapping is shown in the following figure. For example, the capability code for the IM8 modem unit is 7FBFh (0111111110111111). 15 14 13 12 11 10 9 8 7 6 5 43 2 1 0 V.23 Bell 103 V.21 (same as Bell 103) Bell 212 @ 1200 baud (same as V.22bis) Bell 202 V.22 @ 600 baud V.22 @ 1200 baud V.22 @ 2400 baud MNP 4/5 V.42/V.42bis V.32 @ 4800 V.32 @ 9600 V.32bis AT*Gn Transmit calling tone Transmit a 0.5-second on/ 1.5 second off 1300-Hz calling tone in the originate mode. *G0 Disable the tone (default). 7-77 Series 3000 Application Programmer’s Reference Manual *G1 Enable the tone. In the IM8, the calling tone may be forced by the country code. If not forced by the country code, *G can enable it. AT&Gn Guard tone generation &G0 Disable the guard tone (default). &G1 Transmit 1800-Hz guard tone in V.22 answer mode. &G2 Transmit 1800-Hz guard tone in V.22 answer mode. The guard tone is controlled by the country file. If not forced, &G can be used to control it. AT\Gn Modem to modem flow control in non-reliable modes Enables/disables use of modem to modem software flow control. \G0 Disable flow control (default). \G1 Enable flow control. AT$GN Transmitter Gain Set modem transmit gain in 1db steps within the country limitations. Parameter is in -dB. The default transmit level is set in the country files. ATHn Telephone switch hook control H0 On hook (disconnect) H1 Off hook (connect). In the IM8, ATH1 is subject to country limitations. For non-USA countries the maximum offhook duration is determined by S7. AT*Hn Link negotiation speed *H0 Link negotiation occurs at the highest supported speed (default). *H1 Link negotiation occurs at 1200bps. 7-78 Internal Modem Command Set Controls the connection speed for the link negotiations before upshift occurs between two MNP Class 10 modems. ATIn Product information or checksum I0 “Symbol Technologies, Inc.” I1 Copyright date. I2 Reports “OK”. I3 Firmware revision. I4 Capability code (same as ATG). I5 Country code parameter (IM5). I6–I8 Undefined. Reports error. I9 Bell shunt test (IM5). AT$I Initialize the NVRAM $I reinitializes the contents of the NVRAM to the default parameters. ATJn Direct connect , COM2 data redirect, IM5/IM8 select J0-J7 For compatibility only, performs no function. J8 Select IM8 compatibility mode, maximum DCE speed is (14400) J9 select IM5 compatibility mode (default), maximum DCE speed is V,22bis (2400) AT&Jn Telephone jack control For compatibility only, performs no function. Values of 0 or 1. AT&Kn Flow control &K0 Disable flow control. &K3 Enable RTS/CTS flow control (default). &K4 Enable XON/XOFF flow control. 7-79 Series 3000 Application Programmer’s Reference Manual &K5 Enable transparent XON/XOFF flow control. &K6 Enable both RTS/CTS and XON/XOFF flow control. ATLn Speaker volume Adjusts the speaker volume control according to the parameter supplied. Supported for compatibility only since the modems do not have a speaker. L0 Speaker always off. L1 Low volume. L2 Medium volume (default). L3 High volume. AT%L Line signal level Direct indication of the receive level attenuation at the data pump. Returns a value which indicates the received signal level in dBm. AT\Ln MNP block/stream mode select Selects whether an MNP link will use block or stream mode. \L0 Use stream mode for MNP connections (default). \L1 Use block mode for MNP connections. AT*L Display secure access directory Provided for compatibility only since secure access is not supported. AT&Ln Line Type Provided for compatibility only since leased line operation is not supported. ATMn Speaker control Supported for compatibility only since the modems do not have a speaker. M0 Speaker disabled. M1 Speaker disabled during reception of carrier (default). M2 Speaker always enabled. 7-80 Internal Modem Command Set M3 Speaker disabled during reception of carrier and during dialing. On during answering phase. AT&Mn Synchronous mode select &M0 Direct async. &M1 Sync on-line, async off-line. &M2 Not supported. &M3 Not supported. AT+MS Select Modulation (IM 8 Compatibility Mode only) This extended-format command selects the modulation and, optionally, enables or disables automode, and specifies the lowest and highest connection rates. The command format is: +MS= Note: Subparameters not entered (enter a comma only or AT+MS? Reporting Selected Options (IM 8 Compatibility Mode only) The modem can send a string of information to the DTE consisting of selected options using the following command: The response is: For example, 10,1,300,14400 (IM8 default values) 7-81 Series 3000 Application Programmer’s Reference Manual AT+MS=? Reporting Supported Options (IM 8 Compatibility Mode only) The modem can send a string of information to the DTE consisting of supported options. The IM8 response is: (0,1,2,3,9,10,64,69),(0,1),(300-14400),(300-14400) The table below lists the possible modulations: 0V.21300 1V.221200 2 V.22bis 2400 or 1200 3 V.23 1200 (1) 9 V.32 9600 or 4800 10 V.32bis 14400, 12000, 9600, 7200, or 4800 64 Bell 103 300 69 Bell 212 1200 Notes: 1. V.23 rates are always specified as 1200 bps ATNn Pulse dial ratio Supported for compatibility only since the pulse dial ratio is determined by the country setting. Values 0-3. AT$Nn Auto detect enable $N0 Force connection according to ATF setting. $N1 Enable auto speed detection. 7-82 Internal Modem Command Set AT*NCnn Country select Same as AT$Cnn. AT\Nn Error correction operating mode \N0 Disable error correction. Speed buffering on (force AT&Q6). \N1 Direct mode (AT&Q0). \N2 Force LAP-M of MNP4 error correction. Failure to connect in reliable mode results.in the modem hanging up. (AT&Q5, S36=4, S48=7). \N3 Enable auto-reliable mode: V.42 LAP-M or MNP4 error corrected links preferred non-error corrected links as fallback. (AT&Q5,S36=7, S48=7) (default). \N4 Force V.42 LAMP error correction. (AT&Q5, S48=0). \N5 Force MNP4 error correction. (AT&Q5, S36=4, S48=128). ATOn Return to On-line data mode O0 Return to on-line data mode. O1 Return with retrain (V.22bis and up only). ATP Force pulse dialing Force all subsequent dialing in pulse mode. As soon as a dial command is executed which explicitly specifies the dialing mode for that particular call (i.e., ATDT...) this command is overridden, so that all future dialing will be tone dialed. See ATT command. This command has no effect when Norway is the active country. AT&Pn Pulse dial make/break ratio Supported for compatibility only since the pulse dial ratio is determined by the country setting. Values 0-3. AT*Pn Store/delete a password/phone number pair Provided for compatibility only since secure access is not supported. 7-83 Series 3000 Application Programmer’s Reference Manual AT$P Display remote password Provided for compatibility only since remote access is not supported ATQn Result codes enable/disable The Qn command enables/disables the return of result codes. Q0 Modem returns result codes (default). Q1 Modem does not return result codes. AT%Q Line signal quality Reports the line signal quality. Based on the signal quality value, retrain or fallback/fall forward may be initiated if enabled by %E1 or %E2. Returns “ERROR” if not connected, or connected in FSK or fax modes. AT&Qn Sync/async mode This is an extension of the AT&M command used to control the connection modes permitted. Used in conjunction with the S36 and S48 registers. See also AT\N..&Q or &Q0 Direct async. Same as AT&M0. &Q1 Sync connect, async off-line. Same as AT&M1. &Q2 Not supported &Q3 Not supported &Q4 Not supported &Q5 Try to negotiate an error correcting link. Use S36 to determine whether a failure will result in aborting or reverting to a normal asynchronous connection (default). &Q6 Connect in asynchronous normal mode. AT$Qn Ring result code enable/disable The $Q command controls generation of RING result code (2). $Q0 Disable RING result code reporting (default). $Q1 Enable RING result code reporting. 7-84 Internal Modem Command Set AT&Rn RTS/CTS option Controls how the modem will control CTS during sync data mode. Operation of CTS will be modified if hardware control is selected. See AT&K command. &R0 CTS is per V.25bis specification (default). &R1 RTS transitions are ignored. CTS drop only as required by flow control. AT*R Request remote configuration mode Provided for compatibility only since remote access is not supported. AT$Rn Receive boost For compatibility only, performs no function. ATSr? Read register value Read the contents of register r and report it as a decimal value in the range 0 to 255. ATSn=x Assign register value Sets the register “n” to value “x”. The decimal value must be 0 to 255. Some registers may have limited ranges, and others are read only. AT\Sn Status display For compatibility only, performs no function. AT&Sn DSR selection &S0 DSR always on. &S1 DSR active after answer tone has been detected and inactive after carrier has been lost (default). AT$Sn Bell shunt control For compatibility only, performs no function. 7-85 Series 3000 Application Programmer’s Reference Manual ATT Force tone dialing This command forces DTMF dialing until the next P dial modifier or P command is received. ATVn Result code language V0 Send result codes in digits. V1 Send result codes in words (default). See Result Codes Table for a listing of the codes. AT&V Display configuration Display the active configuration, stored profiles 0 and 1, and the first four stored telephone numbers. ATWn Error correction message control W0 The Connect message indicates the terminal speed. W1 Upon connection, report line speed, error correction and compression protocols, and the terminal speed, in that order. W2 The Connect message indicates the line speed AT\Wn Split speed operation For compatibility only, performs no function. AT&Wn Store current configuration &W0 Save settings in profile 0. &W1 Save settings in profile 1. ATXn Select result code set Selects which subset of the result messages are to be used by the modem to inform the terminal of command results. Dial tone detection may be forced by placing a W in the dial string. Valid values for n are given in the following chart: 7-86 Internal Modem Command Set n Extended Busy Report Wait for Allow Blind Connect Dialtone Dialing Message 0NoNoNoYes 1 Yes No No Yes 2YesNoYesNo 3YesYesNoYes 4 Yes Yes Yes No 5 Not supported 6 Yes Extended call progress No Yes report 7 Yes Extended call progress Yes No report See the result code table below for a description of the extended call progress messages. (Default is X4). ATYn Long space disconnect This command enables/disables the generation and response to long space disconnect. Y0 Disable long space disconnect (default). Y1 Enable long space disconnect. In non-error correction mode, the mode will send a long space of four seconds prior to going On-hook. In error-correction mode, the modem will respond to the receipt of a long space by going On-hook. AT&Yn Designate default reset profile &Y0 Use profile 0 on power-up reset (default). &Y1 Use profile 1 on power-up reset. 7-87 Series 3000 Application Programmer’s Reference Manual ATZn Reset modem, restore profile Clear the command line buffer and reset the modem. Z or Z0 Reset and initialize with profile 0 parameters Z1 Reset and initialize with profile 1 parameters. AT&Zn = string Store telephone number Stores telephone numbers in a directory. Up to 20 numbers can be stored (0 – 19). N Position in the directory, 0 – 19 string Telephone number string See also AT\F AT”? Show IM8 serial number (IM 8 Compatibility Mode only) This command shows the serialnumber stored in the IM8. The number consist of 8 characters. +++ Escape code sequence Forces the modem to the command state from the online state. Consists of a three character escape code sequence surrounded by escape guard times. The delay between issuance of each escape character must not exceed the escape guard time. The escape guard time is defined as the time delay between the last character transmitted and the first character of the escape code. The default guard time is 1 second and the default character sequence is “+++”. The escape character must be entered three consecutive times. To enter the escape code sequence using the default values: t WAIT AT LEAST 1 SECOND (After the last character has been transmitted) t Enter +++ (Delay less than one second between characters). t WAIT AT LEAST 1 MORE SECOND (BEFORE transmitting another character) The modem returns to the local command state and sends the OK result code. The modem will not release the telephone line until it receives an ATH or ATZ command, or it detects the loss of the carrier. Use the S2 command to change the escape code or the S12 command to change the escape guard time. 7-88 Internal Modem Command Set IM 8 Notes For use in the USA or Canada, with either tone or pulse dial mode, the country code must be set to 0 or 11, which point to the same configuration. To disable Bell standards, use country code 7. For use in Australia, with either tone or pulse dial, use country code 10. For use in EEA, for tone dial, (the default setting), any of the TBR21 country configurations must be used, all of which share the same parameters, with the one exception of pulse dial. With pulse dial, specific national country code must be set. After any country code change, a reset is needed, forced by the Z command or power cycle controlled by dropping DTR momentarily. Differences Between IM5/5S and IM8/8S The following IM5/5S commands are accepted on the IM8/8S, but perform no function: • AT*L • AT*Pn • AT$P • AT*R • AT*C • AT*E • ATNn • AT&Pn • AT$Rn • AT\Sn • AT$Sn • AT\Wn 7-89 Series 3000 Application Programmer’s Reference Manual Result Codes Result codes are responses from the modem to user commands. They are returned as either words (V1) or digits (V0). Returning result codes can be disabled (Q1) or enabled (Q0). If result codes are enabled, the Ring Detect result code (2) can be disabled ($Q0) or enabled ($Q1). The result codes are shown in the table below: ATX value # Verbal 0123467 0 OK XXXXXXX 1 CONNECT XXXXXXX 2 RING XXXXXXX 3 NO CARRIER XXXXXXX 4 ERROR XXXXXXX 5 CONNECT 1200 (1)XXXXXX 6 NO DIALTONE (3) (3) X (3) X (3) X 7 BUSY (3)(3)(3)XXXX 8 NO ANSWER XXXXXXX 7-90 Internal Modem Command Set 9 CONNECT 600 (1)XXXXXX 10CONNECT 2400 (1)XXXXXX 11CONNECT V.23 (1)XXXXXX 12CONNECT 4800 (1)XXXXXX 13CONNECT 9600 (1)XXXXXX 14CONNECT 12000 (1)XXXXXX 15CONNECT 14400 (1)XXXXXX 16CONNECT 19200 (1)XXXXXX 17CONNECT 38400 (1)XXXXXX 18CONNECT 57600 (1)XXXXXX 22CONNECT 75TX/1200RX (1)XXXXXX 23CONNECT 1200TX/75RX (1)XXXXXX 24 DELAYED (4) (4) (4) (4) (4) X X 7-91 Series 3000 Application Programmer’s Reference Manual 32 BLACKLISTED (4) (4) (4) (4) (4) X X 39 CARRIER 75 X X 40 CARRIER 300 X X 42 CARRIER 600 X X 44 CARRIER 1200/75 X X 45 CARRIER 75/1200 X X 46 CARRIER 1200 X X 47 CARRIER 2400 X X 48 CARRIER 4800 X X 49 CARRIER 7200 X X 50 CARRIER 9600 X X 51 CARRIER 12000 X X 52 CARRIER 14400 X X 7-92 Internal Modem Command Set 66 COMPRESSION: CLASS 5 X X 67 COMPRESSION: V.42BIS X X 69 COMPRESSION: NONE X X 76 PROTOCOL: NONE X X 77 PROTOCOL: LAP-M X X 80 PROTOCOL: ALT X X 144 OFF HOOK-L X X 145 DIAL TONE X X 146 DIALING T X X 147 DIALING P X X 148 RINGING X X 149 OFF HOOK-R X X 150 ANSWER TONE X X 7-93 Series 3000 Application Programmer’s Reference Manual 151 INCOMING CALL * (4) (4) (4) (4) (4) X X X = numeric or verbal response is generated (n) = verbal or numeric response is replaced by response (n) * This message is generated if the phone is ringing or has rung within the last eight seconds, provided power is not removed. 7-94 Internal Modem Command Set S Register Descriptions Table 7-24. S Register Summary S-reg. Type Range Units Default Description S0 WS 0-255 rings rings before answer S1 R 0-255 rings ring count S2 WS 0-127 ASCII ESCAPE char. S3 W 0-127 ASCII Carriage return S4 W 0-127 ASCII Linefeed S5 W 0-127 ASCII Backspace S6 WSC 2-255(US), 2-5 (AUS), 5- seconds 2 (US), 3 Wait for dialtone 8(EU) (AUS), 6(EU) S7 WSC 1-255 (US), 0-255 (AUS), seconds 50 (US, AUS), Wait for carrier 0-60 (EU) 60 (EU) S8 WS 2-255 (US), 0-255 (AUS) seconds 2 (US, AUS) Pause for comma S9 WS 1-255 (US) 0.1 sec. 6 (US) Carrier detect time S10 WS 0-255 (US), 1-255 (AUS) 0.1 sec. 14 (US, AUS) Delay for loss of carrier S11 WS 50-255 (US), 70-255 msec. 95 (US), 70 DTMF on/off time (AUS), 70-150 (EU) (AUS), 85 (EU) S12 WS 0-255 20 msec. 50 Escape code guard time S14 RS Bm 138 S16 R Bm 0 S18 WS 0-255 0 Test timer S21 RS bm 112 7-95 Series 3000 Application Programmer’s Reference Manual S22 RS bm 117 S23 RS bm S24 WS 0-255 Seconds 0 S25 W 0-255 0.1 or 1 s. 5 DTR delay S26 W 0-255 0.1 sec. 1 RTS/CTS delay S27 RS bm 9 S28 RS bm 0 S29 WC 70fixed (US), 1-255 10 msec. 70 (US), 50 Flash time (AUS) (AUS) S30 W 0-255 seconds 0 Inactivity timer S31 RS bm 198 S32 W 0-255 ASCII 17 XON char S33 W 0-255 ASCII 19 XOFF char. S36 WS bm 7 S37 WS bm 0 ATF S38 W 0-255 seconds 20 Delay before forced hangup S39 RS bm 3 S40 RS bm 104 S41 RS bm 195 S46 WS bm 138 S48 WS bm 7 S80 W Compatibility only 0 Compatibility only S82 W 3,7,128 128 Break options 7-96 Internal Modem Command Set S86 R 0-255 Indications 0 Call failure ind. S91 WSC 8-15 (US), 10fxd (AUS), dBm 10 (US, AUS) PSTN transmit level 9fxd (EU) S92 WSC 8-15 (US), 10fxd (AUS), dBm 10 (US, AUS), FAX transmit level 9fxd (EU) 9 (EU) S95 WS Bm 44 Type code: R - Read only W – Writable S - Saved in NVRAM C – Subject to country limitations bm – bit mapped 7-97 Series 3000 Application Programmer’s Reference Manual Bit-mapped register summary Register S14 bitmap Bit Description S14 0 0 Not used 10Local echo disabled ATE 1 Local echo enabled 2 0 Result codes enabled ATQ 1 Result codes disabled 30Result codes sent as digits ATV 1 Result codes send as words 4 0Not used 5 0 Tone Dial T modifier 1 Pulse dial P modifier 6 0 Disable RING messages AT$Q 1 Enable RING messages 70Answer ATD 1 Originate ATA 7-98 Internal Modem Command Set Register S16 bitmap Bit Description S16 0 0 Local analog loopback off AT&T1 1 Local analog loopback off 10Not used 2 0 Local digital loopback off AT&T3 1 Local digital loopback on 3 0 RDL (remote initiated) off AT&T4, AT&T5 1 RDL in progress 4 0 Remote digital loopback off AT&T6 1 Remote digital loopback on 5 0 RDL with self test off AT&T7 1 RDL with self test on 6 0 LAL with self test off AT&T8 1 LAL with self test on 70Not used 7-99 Series 3000 Application Programmer’s Reference Manual Register S21 bitmap Bit Description S21 0 0 Direct connect AT&J 1 Not supported 10Not used 2 0 CTS tracks RTS during sync. AT&R 1 CTS always on during sync. 4,3 00 AT&D0 AT&D 01 AT&D1 Not supported 10 AT&D2 11 AT&D3 50DCD always on AT&C 1 DCD follows carrier 60DSR always on AT&S 1 Modem controls DSR 7 0 Long space disconnect off ATY 1 Long space disconnect on 7-100 Internal Modem Command Set Register S22 bitmap Bit Description S22 1,0 00 Volume low ATL 01 Volume low 10 Volume medium 11 Volume high 3,2 00 Speaker off ATM 01 On until carrier 10 Always on 11 Off during dial and carrier 6,5,4 000 ATX0 selected ATX 100 ATX1 selected 101 ATX2 selected 110 ATX3 selected 111 ATX4 selected 010 ATX5 selected 110 ATX6 selected 011 ATX7 selected 7 0 Not used 7-101 Series 3000 Application Programmer’s Reference Manual Register S23 bitmap Bit Description S23 0 0 RDL denied AT&T4, AT&T5 1 RDL accepted 3,2,1 000 0-300 bps Auto baud results 001 600 bps DTE 010 1200 bps 011 2400 bps 100 4800 bps 101 9600 bps 110 19200 bps 111 38400 bps 5,4 00 Even partity Auto parity results 01 Space / none 10 Odd 11 Mark/none 7,6 00 No guard tone AT&G 01 550 HZ guard tone 10 1800 Hz guard tone 7-102 Internal Modem Command Set Register S27 bitmap Bit Description S27 3,1,0 000 AT&M0, AT&Q0 AT&M, AT&Q 001 AT&M1, AT&Q1 010 AT&M2, AT&Q2 011 AT&M3, AT&Q3 101 AT&Q5 110 AT&Q6 2 0 Not used 5,4 00 Not used 6 0 CCITT protocol ATB 1 Bell protocol 7 0 Not used 7-103 Series 3000 Application Programmer’s Reference Manual Register S28 bitmap Bit Description S28 0 0 Not used 1 0 75 bps transmit AT%F 1 1200 bps transmit 2 0 V.23 hdx enabled AT%F3, ATB3 V.23 hdx enabled 3,4,5 000 Not used 7,6 00 Reserved 7-104 Internal Modem Command Set Register S31 bitmap Bit Description S31 0 0 Reserved 10Automode off AT$N, ATF, AT+MS 1 Automode on 3,2 00 Report terminal speed only ATW, ATX 01 Report terminal speed, error correction and line speed 10 Report line speed only 4-7 000 Reserved 7-105 Series 3000 Application Programmer’s Reference Manual Register S37 bitmap Bit Description S37 3-0 0000 Auto mode ATF, AT+MS 0001 300 bps 0010 300 bps 0011 300 bps 0101 1200 bps 0110 2400 bps 0111 1200/75 (V.23) 1000 4800 bps 1001 9600 bps 1010 12000 bps 1011 14400 bps 1100 7200 bps 4-7 0Not used 7-106 Internal Modem Command Set Register S39 bitmap Bit Description S39 2-0 000 No flow control ATF, AT+MS 011 RTS/CTS flow control 100 XON/XOFF flow control 101 Transparent XON flow control 110 RTS/CTS and XON/XOFF flow control 3-7 00000 Not used 7-107 Series 3000 Application Programmer’s Reference Manual Register S40 bitmap Bit Description S40 00Disable V.42 to MNP10 conversion AT-K 1 Enable V,42 to MNP10 conversion 10Disable power adjustment AT)M 1 Enable power adjustment 20Negotiate link at highest speed AT*H 1 Negotiate link at 1200 bps 5-3 Break handlig AT\K 7,6 00 64 characters MNP block size AT\A 01 128 characters MNP block size 10 192 characters MNP block size 11 256 characters MNP block size 7-108 Internal Modem Command Set Register S41 bitmap Bit Description S41 1,0 00 No error correction AT%C 01 MNP5 10 V.42bis 11 V.42bis or MNP5 6,2 00 Retrains disabled, FB/FF disabled AT%E 01 Retrains enabled, FB/FF disabled 10 Retrains disabled, FB/FF enabled 3 0 Modem to modem flow control disabled AT\G 1 Modem to modem flow control enabled 4 0 MNP Stream mode AT\L 1 MNP block mode 5,7 00 reserved 7-109 Series 3000 Application Programmer’s Reference Manual Register S80 bitmap Bit Description S80 7-0 00000000 This register was added for compatibility reasons ATS80 only 7-110 Appendix A Keyboard Codes Logical Unshifted Shifted Control Alt Key Codes Codes Codes Codes Sequence Scan/ASCII Scan/ASCII Scan/ASCII Scan/ASCII Hex Dec Hex Dec Hex Dec Hex Dec 1 02/31 2/49 none none 78/00 120/0 ! none 02/21 2/33 none none 2 03/32 3/50 none none 79/00 221/0 @ none 03/40 3/64 none none 3 04/33 4/51 none none 7A/00 122/0 # none 04/23 4/35 none none 4 05/34 5/52 none none 7B/00 123/0 $ none 05/24 5/36 none none 5 06/35 6/53 none none 7C/00 124/0 % none 06/25 6/37 none none 6 07/36 7/54 none none 7D/00 125/0 ^ none 07/5E 7/94 none none 7 08/37 8/55 none none 7E/00 126/0 & none 08/26 8/38 none none 8 09/38 9/56 none none 7F/00 127/0 * none 09/2A 9/42 none none 9 0A/39 10/57 none none 80/00 128/0 ( none 0A/28 10/ none none 40 0 0B/30 11/48 none none 81/00 129/0 ) none 0B/29 11/ none none 41 A-1 Series 3000 Application Programmer’s Reference Manual Logical Unshifted Shifted Control Alt Key Codes Codes Codes Codes Sequence Scan/ASCII Scan/ASCII Scan/ASCII Scan/ASCII Hex Dec Hex Dec Hex Dec Hex Dec A 1E/61 30/97 1E/41 30/65 1E/01 30/1 1E/00 30/0 B 30/62 48/98 30/42 48/66 30/02 48/2 30/00 48/0 C 2E/63 46/99 2E/43 46/67 2E/03 46/3 2E/00 46/0 D 20/64 32/100 20/44 32/68 20/04 32/4 20/00 32/0 E 12/65 18/101 12/45 18/69 12/05 18/5 12/00 18/0 F 21/66 33/102 21/46 33/70 21/06 33/6 21/00 33/0 G 22/67 34/103 22/47 34/71 22/07 34/7 22/00 34/0 H 23/68 35/104 23/48 35/72 23/08 35/8 23/00 35/0 I 17/69 23/105 17/49 23/73 17/09 23/9 17/00 23/0 J 24/6A 36/106 24/4A 36/74 24/0A 36/10 24/00 36/0 K 25/6B 37/107 25/4B 37/75 25/0B 37/11 25/00 37/0 L 26/6C 38/108 26/4C 38/76 26/0C 38/12 26/00 38/0 M 32/6D 50/109 32/4D 50/77 32/0D 50/13 32/00 50/0 N 31/6E 49/110 31/4E 49/78 31/0E 49/14 31/00 49/0 O 18/6F 24/111 18/4F 24/79 18/0F 24/15 18/00 24/0 P 19/70 25/112 19/50 25/80 19/10 25/16 19/00 25/0 Q 10/71 16/113 10/51 16/81 10/11 16/17 10/00 16/0 R 13/72 19/114 13/52 19/82 13/12 19/18 13/00 19/0 S 1F/73 31/115 1F/53 31/83 1F/13 31/19 1F/00 31/0 T 14/74 20/116 14/54 20/84 14/14 20/20 14/00 20/0 U 16/75 22/117 16/55 22/85 16/15 22/21 16/00 22/0 V 2F/76 47/118 2F/56 47/86 2F/16 47/22 2F/00 47/0 W 11/77 17/119 11/57 17/87 11/17 17/23 11/00 17/0 X 2D/78 45/120 2D/58 45/88 2D/18 45/24 2D/00 45/0 Y 15/79 21/121 15/59 21/89 15/19 21/25 15/00 21/0 Z 2C/7A 44/122 2C/5A 44/90 2C/1A 44/26 2C/00 44/0 A-2 Keyboard Codes Logical Unshifted Shifted Control Alt Key Codes Codes Codes Codes Sequence Scan/ASCII Scan/ASCII Scan/ASCII Scan/ASCII Hex Dec Hex Dec Hex Dec Hex Dec - 0C/2D 12/45 none none none _ none 0C/5F 12/95 none none = 0D/3D 13/61 none none 83/00 131/0 + none 0D/2B 13/43 none none [ 1A/5B 26/91 none none none { none 1A/7B 26/123 none none ] 1B/5D 27/93 none none none } none 1B/7D 27/125 none none ; 27/3B 39/59 none none none : none 27/3A 39/58 none none ' 28/27 40/39 none none none “ none 28/22 40/34 none none ` 29/60 41/96 none none none ~ none 29/7E 41/126 none none \ 2B/5C 43/92 none none none | none 2B/7C 43/124 none none , 33/2C 51/44 none none none < none 33/3C 51/60 none none . 34/2E 52/46 none none none > none 34/3E 52/62 none none / 35/2F 53/47 none none none ? none 35/3F 53/63 none none A-3 Series 3000 Application Programmer’s Reference Manual Logical Unshifted Shifted Control Alt Key Codes Codes Codes Codes Sequence Scan/ASCII Scan/ASCII Scan/ASCII Scan/ASCII Hex Dec Hex Dec Hex Dec Hex Dec Back Space 0E/08 14/8 none none none Enter 1C/0D 28/13 none none none Space 39/20 57/32 none none none Home 47/00 71/0 none 77/00 119/0 none End 4F/00 79/0 none 75/00 117/0 none Page Up 49/00 73/0 none 84/00 132/0 none Page Down 51/00 81/0 none 76/00 118/0 none Up Arrow 48/00 72/0 48/38 72/56 8D/00 141/0 none Down Arrow 50/00 80/0 50/32 80/50 91/00 145/0 none Right Arrow 4D/00 77/0 4D/36 77/54 74/00 116/0 none Left Arrow 4B/00 75/0 4B/34 75/52 73/00 115/0 none Insert 52/00 82/0 none none none Delete 53/00 83/0 none none none Ctrl Break none none 00/3 0/3 none F1 (Help) 3B/00 59/0 54/00 84/0 5E/00 94/0 68/00 104/0 F2 3C/00 60/0 55/00 85/0 5F/00 95/0 69/00 105/0 F3 3D/00 61/0 56/00 86/0 60/00 96/0 6A/00 106/0 F4 3E/00 62/0 57/00 87/0 61/00 97/0 6B/00 107/0 F5 3F/00 63/0 58/00 88/0 62/00 98/0 6C/00 108/0 F6 40/00 64/0 59/00 89/0 63/00 99/0 6D/00 109/0 F7 41/00 65/0 5A/00 90/0 64/00 100/0 6E/00 110/0 F8 42/00 66/0 5B/00 91/0 65/00 101/0 6F/00 111/0 F9 (Menu) 43/00 67/0 5C/00 92/0 66/00 102/0 70/00 112/0 F10 (Send) 44/00 68/0 5D/00 93/0 67/00 103/0 71/00 113/0 A-4 Appendix B The Series 3000 Keyboard Introduction The Series 3000 terminals have configurable keyboards with varying numbers of keys. By combining keystrokes, all of the keyboards can emulate the full 101- key IBM-PC AT keyboard. This appendix describes how key codes are produced on the Series 3000 terminals, and provides the standard keyboard definitions. Instructions for writing keyboard redefinition tables are covered in the Series 3000 Application Programmer’s Guide. Keyboard Operation On a PC, each key generates a scan code. The character code generated by a given key is determined by the scan code and the current keyboard state: unshifted, shifted, control, or alternate. The scan code generated by each key is constant, independent of the keyboard state. Scan code to character code mappings for these states are shown in Appendix A. The Series 3000 keyboards emulate the full PC/AT keyboard by using one or more modifier keys in sequence, followed by a character key. The modifier keys are: Shift Caps Lock (Alpha on the 35-key keyboard) Control (Ctrl) Function (Func) The remaining keys (a through z, 0 through 9, special characters) are called “character keys.” B-1 Series 3000 Application Programmer’s Reference Manual The character generated is a function of the key scan code and the keyboard state, as on a PC. The main difference is that the scan code generated by a key is also variable, determined by the keyboard state. To retrieve character and scan codes, refer to Interrupt 16h, Functions 00h and 02h in the Series 3000 System Software Manual. Scan Code Translation Scan codes are determined as shown in Figure B-1. The terminal keyboard produces its own native scan code. On the 56-key keyboard, for instance, these are 00 through 55, as reported in the terminal self test. These native scan codes are mapped by the BIOS to a subset of PC/AT scan codes, the base scan codes (refer to Table B-1). The subset is different for each keyboard. A keyboard translation table maps the base scan codes to other scan codes, based on the keyboard state. Translations can be provided for seven keyboard states: Unshifted, Shifted, CapLock, NumLock, Function, Control and Alternate. For example, the default keyboard translation table for the 56-key keyboard specifies no translation for the Unshifted, Shifted, CapLock or Alternate states. The NumLock state translates the number keys to numeric keypad keys. The Control state translates the Backspace key to Scroll Lock. The Function state translates several keys to special functions and miscellaneous PC keys. Once the scan code is determined, the character code is determined by that scan code and the keyboard state, exactly as on a PC. Meta Code Translation In addition to translating between scan codes, the translation may be to meta codes. There are six meta codes available for special terminal operations: Power 98 terminal On/Off Keyboard timeout 99 powers off the terminal Lamp 100 display back light Dark 101 increase display contrast Light 102 decrease display contrast Null 103 generates unique key value (see below) B-2 The Series 3000 Keyboard Note that meta code values are outside the range of the PC scan codes. The Null meta code is available to generate a unique code which cannot be confused with any usual scan code. The code returned is two bytes, consisting of 68h in AH and the key scan code in AL (see Interrupt 16h function 00h in the Series 3000 System Software Manual). Normal processing, which processes the scan code for a keyboard state, is bypassed, and the unique code can be trapped for special processing. Table B-1. 56-key Scan Code Translation Key Translations Legend Base No Shift Func Ctrl Alt Cap Num Code Mod Lock Lock F1/F659 846494104 F2/F760 856595105 F3/F861 866696106 F4/F962 876797107 F5/F10 63 88 68 98 108 On/Off 98 A30 B48 C46 D32 E18 F33 G34 H35 59 I23 J36 K37 L38 100 M50 67 N49 O24 B-3 Series 3000 Application Programmer’s Reference Manual Key Translations Legend Base No Shift Func Ctrl Alt Cap Num Code Mod Lock Lock P25 Q16 R19 S31 68 T20 U22 78 V47 74 W17 55 X45 53 Y21 Z44 Caps 58 69 Lock Func Ctrl 29 56 Shift 42 708 4112671 809 1312772 910 4312873 Clear 01 405 2612375 506 2712476 607 3912577 Sp/dark 57 101 uparrow 72 73 141 Bksp/ 14 102 03 light 1 2 40 120 71 2 3 51 121 80 3 4 53 122 81 B-4 The Series 3000 Keyboard Key Translations Legend Base No Shift Func Ctrl Alt Cap Num Code Mod Lock Lock left 75 71 115 arrow down 80 81 145 arrow right 77 79 116 arrow -/No 12 130 011 8212982 ./Yes 52 83 Enter/= 28 13 Keyboard States When the operator presses a modifier key or a defined sequence of modifier keys, the keyboard enters a modified keyboard state. Modifier key/sequence Keyboard state no modifier Unshifted Shift All keys shifted Caps Lock Alphabetic keys shifted Ctrl Control shifted Func Scan code translation only. Shift/control state determined by other modifiers in the sequence. Func + Ctrl Alternate (3300 and 3800) Func + Caps Lock NumLock (3300 and 3800) Func + N NumLock (3900) B-5 Series 3000 Application Programmer’s Reference Manual The Shift, Control and Alt (Func + Ctrl) states affect only the next character key pressed. The Caps Lock (Alpha) state remains in effect until Caps Lock is pressed again. On the 35-key keyboard, the Alpha key generates alphabetic characters (upper case only). While there is no As shown by the Alt sequence, the Once a keyboard state has been set, the A more complex example is the Func/Ctrl/Func sequence. The first For example, it is not possible to assign the semicolon (;) to a shifted sequence (e.g., Shift + [ ). This sequence puts the keyboard in a shifted state, but semicolon is an unshifted character on the PC/AT keyboard. B-6 The Series 3000 Keyboard Standard Keyboard Diagrams The codes and characters generated by each modifier key or sequence are shown in the following figures. Series 3100 21-key keyboard Fig B-1 through B-2 35-key keyboard Fig. B-3 through B-11 46-key keyboard Fig. B-12 through B-20 Series 3300 35-key keyboard Fig. B-21 through B-29 56-key keyboard Fig. B-30 through B-38 Series 3500 47-key keyboard Fig. B-39 through B-47 Series 3800/6800 35-key keyboard Fig. B-48 through B-56 46-key keyboard Fig. B-57 through B-65 Series 3900 54-key keyboard Fig. B-66 through B-74 WS 1000 27-key keyboard Fig. B-75 through B-86 PDT 6100 22-key keyboard Fig. B-97 through B-98 35-key keyboard Fig. B-87 through B-96 B-7 Series 3000 Application Programmer’s Reference Manual 75 00 77 00 I/0 72 00 80 00 97 00 Fn 78 43 12 45 1 27 SEND –– CLR 8 55 9 56 10 57 7 8 9 5 52 6 53 7 54 4 5 6 2 49 3 50 4 51 1 2 3 52 46 11 48 28 13 . 0 ENT Scan Code Ascii Value ss AA (decimal) c (decimal) Printable Character or Logical Key Sequence Figure B-1. Series 3100 21-key Unmodified Keyboard B-8 The Series 3000 Keyboard 100 00 lamp 102 00 101 00 lighter darker 65 00 66 00 67 00 F7 F8 F9 62 00 63 00 64 00 F4 F5 F6 59 00 60 00 61 00 F1 F2 F3 68 00 28 13 F10 ENT Scan Code Ascii Value ss AA (decimal) c (decimal) Printable Character or Logical Key Sequence Figure B-2. Series 3100 21-key Function-Modified Keyboard B-9 Series 3000 Application Programmer’s Reference Manual 58 00 57 32 42 00 ALPHA SPACE SHIFT On/Off 97 00 29 00 26 91 27 93 FUNC CTRL [] 40 39 13 61 55 42 53 47 ’ = */ 51 44 43 92 39 59 78 43 ,;/ + 75 00 77 00 72 00 80 00 8 55 9 56 10 57 1 27 7 8 9 CLEAR 552653754148 4 5 6 BKSP 2 49 3 50 4 51 28 13 12 3E N T E 12 45 11 48 52 46 R - 0 . SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-3. Series 3100 35-key Unmodified Keyboard B-10 The Series 3000 Keyboard 58 00 57 32 42 00 ALPHA SPACE SHIFT On/Off 97 00 29 00 26 123 27 125 FUNC CTRL {} 40 34 13 43 55 00 53 63 ” + Prt Scr ? 51 60 43 124 39 58 78 43 < I : + 75 52 77 54 72 56 80 50 46 82 8 38 9 42 10 40 1 27 & *(CLEAR 536637794148 $ % > BKSP 2 33 3 64 4 35 28 13 !@#E N T 12 95 11 41 52 62 E R _ )> SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-4. Series 3100 35-key Shift-Modified Keyboard B-11 Series 3000 Application Programmer’s Reference Manual 58 00 57 32 42 00 ALPHA SPACE SHIFT On/Off 97 00 29 00 30 65 48 66 FUNC CTRL AB 46 67 32 68 18 69 33 70 C DEF 34 71 35 72 23 73 36 74 GH I J 37 75 38 76 50 77 49 78 KL MN 24 79 25 80 16 81 1 27 O P Q CLEAR 19 82 31 83 20 84 14 8 R S T BKSP 22 85 47 86 17 87 28 13 UVWE N T 45 88 21 89 44 90 E R X YZ SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-5. Series 3100 35-key Alpha-Modified Keyboard B-12 The Series 3000 Keyboard 58 00 57 32 42 00 ALPHA SPACE SHIFT On/Off 97 00 29 00 30 1 48 2 FUNC CTRL Ctrl A Ctrl B 46 3 32 4 18 5 33 6 Ctrl C Ctrl D Ctrl E Ctrl F 34 7 35 8 23 9 36 10 Ctrl G Ctrl H Ctrl I Ctrl J 37 11 38 12 50 13 49 14 Ctrl K Ctrl L Ctrl M Ctrl N 24 15 25 16 16 17 1 27 Ctrl O Ctrl P Ctrl Q CLEAR 19 82 31 19 20 20 00 3 Ctrl R Ctrl S Ctrl T Ctrl Bk 22 21 47 22 17 23 28 10 Ctrl U Ctrl V Ctrl W E N T 45 24 21 25 44 26 E R Ctrl X Ctrl Y Ctrl Z SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-6. Series 3100 35-key Control-Modified Keyboard B-13 Series 3000 Application Programmer’s Reference Manual 58 00 57 9 42 00 ALPHA TAB SHIFT On/Off 97 00 56 00 82 00 41 96 FUNC ALT Ins ’ 13 61 101 102 Lamp = Darker Lighter 51 44 79 00 39 59 78 43 , End ; + 71 00 73 00 81 00 Home Lamp Pg Up Pg Dn 65 00 66 00 67 00 1 27 F7 F8 F9 CLEAR 62 00 63 00 64 00 83 00 F4 F5 F6 Del 59 00 60 00 61 00 28 13 F1 F2 F3 E N T 101 68 00 102 E R Darker F10 Lighter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-7. Series 3100 35-key Func-Modified Keyboard B-14 The Series 3000 Keyboard 58 00 15 00 42 00 ALPHA Shift Tab SHIFT On/Off 97 00 56 00 82 48 41 126 FUNC ALT 0 ~ 13 43 101 102 Lamp + Darker Lighter 51 60 79 49 39 58 78 43 <1 : + 71 55 73 57 81 51 7 Lamp 9 3 90 00 91 00 92 00 1 27 Shift F7 Shift F8 Shift F9 CLEAR 87 00 88 00 89 00 83 46 Shift F4 Shift F5 Shift F6 . 84 00 85 00 86 00 28 13 Shift F1 Shift F2 Shift F3 E. N T 101 93 00 102 E R Darker Shift F10 Lighter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-8. Series 3100 35-key Shift+Func-Modified Keyboard B-15 Series 3000 Application Programmer’s Reference Manual 58 00 57 32 42 00 ALPHA SPACE SHIFT On/Off 97 00 56 00 30 00 48 00 FUNC ALT Alt A Alt B 46 00 32 00 18 00 33 00 Alt C Alt D Alt E Alt F 34 00 35 00 23 00 36 00 Alt G Alt H Alt I Alt J 37 00 38 00 50 00 49 00 Alt K Alt L Alt M Alt N 24 00 25 00 16 00 Alt O Alt P Alt Q 19 00 31 00 20 00 Alt R Alt S Alt T 22 00 47 00 17 00 Alt U Alt V Alt W 45 00 21 00 44 00 Alt X Alt Y Alt Z SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-9. Series 3100 35-key ALT (Func+Ctrl)-Modified Keyboard B-16 The Series 3000 Keyboard 58 00 42 00 ALPHA SHIFT On/Off 97 00 56 00 FUNC ALT 101 102 LAMP Darker Lighter Ctrl End 119 00 132 00 118 00 Ctrl Ctrl Ctrl Home Lamp Pg Up Pg Dn 100 00 101 00 102 00 1 27 Ctrl F7 Ctrl F8 Ctrl F9 CLEAR 97 00 98 00 99 00 Ctrl F4 Ctrl F5 Ctrl F6 94 00 95 00 96 00 Ctrl F1 Ctrl F2 Ctrl F3 101 103 00 102 Darker Ctrl F10 Lighter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-10. Series 3100 35-key Control+Func-Modified Keyboard B-17 Series 3000 Application Programmer’s Reference Manual 58 00 42 00 ALPHA SHIFT On/Off 97 00 56 00 FUNC ALT 101 102 Lamp Darker Lighter Lamp 110 00 111 00 112 00 Alt F7 Alt F8 Alt F9 107 00 108 00 109 00 Alt F4 Alt F5 Alt F6 104 00 105 00 106 00 Alt F1 Alt F2 Alt F3 101 113 00 102 Darker Alt F10 Lighter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-11. Series 3100 35-key ALT+Func-Modified Keyboard B-18 The Series 3000 Keyboard 01 27 42 00 29 00 On Clear Func Shift Ctrl Off 30 97 48 98 46 99 32 100 18 101 abcde 33 102 34 103 35 104 23 105 36 106 fghij 37 107 38 108 50 109 49 110 24 111 klmno 25 112 16 113 19 114 31 115 20 116 pqrst 22 117 47 118 17 119 45 120 21 121 uvwxy 44 122 14 08 52 46 72 00 80 00 z bksp . 08 55 09 56 10 57 789 05 52 06 53 07 54 456 02 49 03 50 04 51 123 11 48 28 13 0 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-12. Series 3100 46-key Unmodified Keyboard B-19 Series 3000 Application Programmer’s Reference Manual Figure B-13. Series 3100 46-key Shift-Modified Keyboard B-20 The Series 3000 Keyboard 01 27 42 00 29 00 On Clear Func Shift Ctrl Off 30 65 48 66 46 67 32 68 18 69 ABCDE 33 70 34 71 35 72 23 73 36 74 FGHIJ 37 75 38 76 50 77 49 78 24 79 KLMNO 25 80 16 81 19 82 31 83 20 84 PQRST 22 85 47 86 17 87 45 88 21 89 UVWXY 44 90 14 08 52 46 72 00 80 00 Z bksp . 08 55 09 56 10 57 789 05 52 06 53 07 54 456 02 49 03 50 04 51 123 11 48 28 13 0 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-14. Series 3100 46-key Caplock-Modified Keyboard B-21 Series 3000 Application Programmer’s Reference Manual 01 27 On Clear Off 30 01 48 02 46 03 32 04 18 05 Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E 33 06 34 07 35 08 23 09 36 10 Ctrl F Ctrl G Ctrl H Ctrl I Ctrl J 37 11 38 12 50 13 49 14 24 15 Ctrl K Ctrl L Ctrl M Ctrl N Ctrl O 25 16 16 17 19 18 31 19 20 20 Ctrl P Ctrl Q Ctrl R Ctrl S Ctrl T 22 21 47 22 17 23 45 24 21 25 Ctrl U Ctrl V Ctrl W Ctrl X Ctrl Y 44 26 00 03 141 00 145 00 Ctrl Z Ctrl Brk Ctrl Ctrl 07 30 Ctrl 6 03 00 Ctrl 2 28 10 Linefeed SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-15. Series 3100 46-key Control-Modified Keyboard B-22 The Series 3000 Keyboard 01 27 58 00 56 00 ON Clear Cap Lk Alt OFF 78 43 74 45 55 42 53 47 18 101 +-” / e 33 102 34 103 41 96 13 61 43 92 fg’ = / 12 45 26 91 27 93 39 59 - Lamp [ ] ; 71 00 79 00 40 39 51 44 53 47 Home End ,,/ 22 21 47 22 17 23 45 24 21 25 Ins Del Pg Up Dark Light 44 122 57 32 81 00 75 00 77 00 z Space Pg Dn 65 00 66 00 67 00 F7 F8 F9 62 00 63 00 64 00 F4 F5 F6 59 00 60 00 61 00 F1 F2 F3 68 00 13 61 F10 = SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-16. Series 3100 46-key Func-Modified Keyboard B-23 Series 3000 Application Programmer’s Reference Manual 01 27 ON Clear OFF 78 43 74 45 53 63 18 69 +- ?E 33 70 34 71 41 126 13 43 43 124 FG ~ + ! 12 95 26 123 27 125 39 58 - Lamp { } : 71 55 79 49 40 34 51 60 53 63 71” 82 48 83 46 73 57 0 . 9 Dark Light 44 90 58 32 81 51 75 52 77 54 E Space 3 4 6 90 00 91 00 92 00 Shf F7 Shf F8 Shf F9 87 00 88 00 89 00 Shf F4 Shf F5 Shf F6 84 00 85 00 86 00 Shf F1 Shf F2 Shf F3 93 00 13 43 Shf F10 + SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-17. Series 3100 46-key Shift+Func-Modified Keyboard B-24 The Series 3000 Keyboard ON OFF 30 00 48 00 46 00 32 00 18 00 Alt A Alt B Alt C Alt D Alt E 33 00 34 00 35 00 23 00 36 00 Alt F Alt G Alt H Alt I Alt J 37 00 38 00 50 00 49 00 24 00 Alt K Alt L Alt M Alt N Alt O 25 00 16 00 19 00 31 00 20 00 Alt P Alt Q Alt R Alt S Alt T 22 00 47 00 17 00 45 00 21 00 Alt U Alt V Alt W Alt X Alt Y 44 00 Alt Z 126 00 127 00 128 00 Alt 7 Alt 8 Alt 9 123 00 124 00 125 00 Alt 4 Alt 5 Alt 6 120 00 121 00 122 00 Alt 1 Alt 2 Alt 3 129 00 Alt 0 SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-18. Series 3100 46-key ALT (Func+Control)-Modified Keyboard B-25 Series 3000 Application Programmer’s Reference Manual 01 27 ON Clear OFF 78 43 74 45 55 00 18 05 Ctrl * Ctrl E 33 06 34 07 43 28 Ctrl F Ctrl G Ctrl \ 12 31 26 27 27 29 Ctrl - Lamp Ctrl [ Ctrl ] 119 00 117 00 Ctl Hm Ctl End 132 00 Ctl Pg Up Dark Light 44 26 57 32 118 00 115 00 116 00 Ctrl Z Space Ctl Pg Dn Ctrl Ctrl 100 00 101 00 102 00 Ctrl F7 Ctrl F8 Ctrl F9 97 00 98 00 99 00 Ctrl F4 Ctrl F5 Ctrl F6 94 00 95 00 96 00 Ctrl F1 Ctrl F2 Ctrl F3 103 00 Ctrl F10 SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-19. Series 3100 46-key Control+Func Modified Keyboard B-26 The Series 3000 Keyboard ON OFF 18 00 Alt E 33 00 34 00 131 00 Alt F Alt G Alt = 130 00 Alt - Lamp Dark Light 44 00 57 32 Alt Z Space 110 00 111 00 112 00 Alt F7 Alt F8 Alt F9 107 00 108 00 109 00 Alt F4 Alt F5 Alt F6 104 00 105 00 106 00 Alt F1 Alt F2 Alt F3 113 00 131 00 Alt F10 Alt = SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-20. Series 3100 46-key ALT+Func-Modified Keyboard B-27 Series 3000 Application Programmer’s Reference Manual 57 32 58 00 42 00 29 00 SPACE ALPHA SHIFT CTRL FUNC 26 91 27 93 40 39 13 61 On []’ = Off 55 42 53 47 51 44 43 92 39 59 */,\; 75 00 77 00 72 00 80 00 78 43 + 08 55 09 56 10 57 01 27 789CLEAR 05 52 06 53 07 54 14 08 456BKSP 02 49 03 50 04 51 28 13 123E N T 52 46 11 48 12 45 E . 0 _ R SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-21. Series 3300 35-key Unmodified Keyboard B-28 The Series 3000 Keyboard 57 32 58 00 42 00 29 00 SPACE ALPHA SHIFT CTRL FUNC 26 123 27 125 40 34 13 43 On {}” + Off 55 00 53 63 51 60 43 124 39 58 Prt Scr ? < ! : 75 52 77 54 72 56 80 50 78 43 4682+ 08 38 09 42 10 40 01 27 & * ( CLEAR 05 36 06 37 07 94 14 08 < $% BKSP 02 33 03 64 04 35 28 13 !@#E N T 52 62 11 41 12 95 E > ) _ R SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-22. Series 3300 35-key Shift-Modified Keyboard B-29 Series 3000 Application Programmer’s Reference Manual 57 32 58 00 42 00 29 00 SPACE ALPHA SHIFT CTRL FUNC 30 65 48 66 46 67 32 68 ON ABC DOFF 18 69 33 70 34 71 35 72 23 73 EFGHI 36 74 37 75 38 76 50 77 49 78 JKLMN 24 79 25 80 16 81 01 27 OPQCLEAR 19 82 31 83 20 84 14 08 RSTBKSP 22 85 47 86 17 87 28 13 UVWE N T 45 88 21 89 44 90 E XYZR SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-23. Series 3300 35-key Alpha-Modified Keyboard B-30 The Series 3000 Keyboard 57 32 58 00 42 00 29 00 SPACE ALPHA SHIFT CTRL FUNC 30 01 48 02 46 03 32 04 On Ctrl A Ctrl B Ctrl C Ctrl D Off 18 05 33 06 34 07 35 08 23 09 Ctrl E Ctrl F Ctrl G Ctrl H Ctrl I 36 10 37 11 38 12 50 13 49 14 Ctrl J Ctrl K Ctrl L Ctrl M Ctrl N 24 15 25 16 16 17 01 27 Ctrl O Ctrl P Ctrl Q CLEAR 19 18 31 19 20 20 00 03 Ctrl R Ctrl S Ctrl T Ctrl Break 22 21 47 22 17 23 28 10 Ctrl U Ctrl V Ctrl W Ctrl J Line Feed 45 24 21 25 44 26 Ctrl X Ctrl Y Ctrl Z SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-24. Series 3300 35-key Control-Modified Keyboard B-31 Series 3000 Application Programmer’s Reference Manual 15 09 58 00 42 00 56 00 TAB ALPHA SHIFT ALT FUNC 82 00 41 96 13 61 On INS ’ Lamp = Off 101 102 51 44 39 59 Darker Lighter ’ Lamp ; 71 00 79 00 73 00 81 00 78 43 HOME END Pg Up Pg Dn + 65 00 66 00 67 00 01 27 F7 F8 F9 CLEAR 62 00 63 00 64 00 83 00 F4 F5 F6 DEL 59 00 60 00 61 00 28 10 F1 F2 F3 E N T 101 68 00 102 E Darker F10 Lighter R SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-25. Series 3300 35-key Func-Modified Keyboard B-32 The Series 3000 Keyboard 15 00 58 00 42 00 56 00 Shift Tab ALPHA SHIFT ALT FUNC 82 48 41 126 13 43 On 0 ~ Lamp + Off 101 102 51 60 39 58 Darker Lighter < Lamp : 71 55 79 49 73 57 81 51 78 43 7193+ 90 00 91 00 92 00 01 27 Shift F7 Shift F8 Shift F9 CLEAR 87 00 88 00 89 00 83 46 Shift F4 Shift F5 Shift F6 " 84 00 85 00 86 00 28 13 Shift F1 Shift F2 Shift F3 E N T 101 93 00 102 E Darker Shift F10 Lighter R SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-26. Series 3300 Shift+Func-Modified Keyboard B-33 Series 3000 Application Programmer’s Reference Manual 57 32 58 00 42 00 56 00 SPACE ALPHA SHIFT ALT FUNC 30 00 48 00 46 00 32 00 On Alt A Alt B Alt C Alt D Off 18 00 33 00 34 00 35 00 23 00 Alt E Alt F Alt G Alt H Alt I 36 00 37 00 38 00 50 00 49 00 Alt J Alt K Alt L Alt M Alt N 24 00 25 00 16 00 Alt O Alt P Alt Q 19 00 31 00 20 00 Alt R Alt S Alt T 22 00 47 00 20 00 Alt U Alt V Alt W E N T 45 00 21 00 44 00 E Alt X Alt Y Alt Z R SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-27. Series 3300 35-key ALT(Func+Ctrl)-Modified Keyboard B-34 The Series 3000 Keyboard 58 00 42 00 56 00 ALPHA SHIFT ALT FUNC On Lamp Off 101 102 Darker Lighter Lamp 119 00 117 00 132 00 118 00 Ctrl Home Ctrl End Ctrl PgUp Ctrl Pg Dn 100 00 101 00 102 00 01 27 Ctrl F7 Ctrl F8 Ctrl F9 CLEAR 97 00 98 00 99 00 Ctrl F4 Ctrl F5 Ctrl F6 94 00 95 00 96 00 28 10 Ctrl F1 Ctrl F2 Ctrl F3 E N T 101 103 00 102 E Darker Ctrl F10 Lighter R SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-28. Series 3300 35-key Control+Func-Modified Keyboard B-35 Series 3000 Application Programmer’s Reference Manual 58 00 42 00 56 00 Func Shift Ctrl ALT 131 00 On Lamp ALT = Off 101 102 Darker Lighter Lamp 110 00 111 00 112 00 Alt F7 Alt F8 Alt F9 107 00 108 00 109 00 Alt F4 Alt F5 Alt F6 104 00 105 00 106 00 Alt F1 Alt F2 Alt F3 101 00 113 00 102 00 Darker Alt F10 Lighter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-29. Series 3300 35-key ALT+Func-Modified Keyboard B-36 The Series 3000 Keyboard 59 0 60 0 61 0 62 0 63 0 On F1 F2 F3 F4 F5 Off 30 97 48 98 46 99 32 100 18 101 33 102 abc de f 34 103 35 104 23 105 36 106 37 107 38 108 ghijkl 50 109 49 110 24 111 25 112 16 113 19 114 mnopqr 31 115 20 116 22 117 47 118 17 119 45 120 st uvw x 21 121 44 122 58 29 42 yz 8 55 9 56 10 57 1 27 7 8 9 ESCAPE 57 32 14 8 Space BkSp 552653754 72 0 45 6 75 0 77 0 249350451 80 0 123 28 13 12 45 11 48 52 46 - 0. ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-30. Series 3300 56-key Unmodified Keyboard B-37 Series 3000 Application Programmer’s Reference Manual 84 0 85 0 86 0 87 0 88 0 On Shift F1 Shift F2 Shift F3 Shift F4 Shift F5 Off 30 65 48 66 46 67 32 68 18 69 33 70 ABCDE F 34 71 35 72 23 73 36 74 37 75 38 76 GH I J K L 50 77 49 78 24 79 25 80 16 81 19 82 MN O P Q R 31 83 20 84 22 85 47 86 17 87 45 88 ST UVWX 21 89 44 90 58 29 42 YZ 8 38 9 42 10 40 01 27 & * ( ESCAPE 57 32 14 08 Space BkSp 536637794 72 56 > $% 8 75 52 77 52 4 6 233364435 80 50 !@# 2 28 13 12 95 11 41 52 62 _ )>ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-31. Series 3300 56-key Shift-Modified Keyboard B-38 The Series 3000 Keyboard 59 0 60 0 61 0 62 0 63 0 On F1 F2 F3 F4 F5 Off 30 65 48 66 46 67 32 68 18 69 33 70 ABCDE F 34 71 35 72 23 73 36 74 37 75 38 76 GH I J K L 50 77 49 78 24 79 25 80 16 81 19 82 MN O P Q R 31 83 20 84 22 85 47 86 17 87 45 88 ST UVWX 21 89 44 90 58 29 42 YZ 8 52 9 56 10 57 1 27 789 ESCAPE 57 32 14 8 Space BkSp 552653754 456 72 0 75 0 77 0 249350451 80 0 123 28 13 12 45 11 48 52 46 _ 0. ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-32. Series 3300 56-key Caplock-Modified Keyboard B-39 Series 3000 Application Programmer’s Reference Manual 94 0 95 0 96 0 97 0 98 0 On Ctrl F1 Ctrl F2 Ctrl F3 Ctrl F4 Ctrl F5 Off 30 01 48 02 46 03 32 04 18 05 33 06 Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E Ctrl F 34 07 35 08 23 09 36 10 37 11 38 12 Ctrl G Ctrl H Ctrl I Ctrl J Ctrl K Ctrl L 50 13 49 14 24 15 25 16 16 17 19 18 Ctrl M Ctrl N Ctrl O Ctrl P Ctrl Q Ctrl R 31 19 20 20 22 21 47 22 17 23 45 24 Ctrl S Ctrl T Ctrl U Ctrl V Ctrl W Ctrl X 21 25 44 26 58 29 42 Ctrl Y Ctrl Z 01 27 ESCAPE 57 32 0 3 Space Ctrl 07 30 Brk 141 0 0 CRTL 6 * _ 115 0_ 0 116 _0 0 * * 03 00 145 0 0 CRTL 2 * _ 28 10 12 31 CTRL ENTER CRTL - (Line feed) SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-33. Series 3300 56-key Control-Modified Keyboard B-40 The Series 3000 Keyboard 64 0 65 0 66 0 67 0 68 0 On F6 F7 F8 F9 F10 Off 30 97 48 98 46 99 32 100 18 101 33 102 abcdef 34 103 59 0 23 105 36 106 37 107 g F1 i j k Lamp 67 0 49 110 24 111 25 112 16 113 19 114 F9 n o p q r 68 0 20 116 78 43 74 45 55 42 53 47 F10 t +- */ 21 121 44 122 69 56 yz 41 96 13 61 43 92 01 27 `=\ESCAPE 101 102 Dark Light 26 91 27 93 39 59 73 0 () ; Pg Up 71 0 79 0 Home End 40 39 51 44 53 47 81 0 Pg Dn ',/ 13 61 12 45 82 0 83 0 = - Ins Del SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-34. Series 3300 56-key Function-Modified Keyboard B-41 Series 3000 Application Programmer’s Reference Manual 89 0 90 0 91 0 92 0 93 0 On Shift F6 Shift F7 Shift F8 Shift F9 Shift F10 Off 30 65 48 66 46 67 32 68 18 69 33 70 ABCDEF 34 71 84 0 23 73 36 74 37 75 G Shift F1 IJKLamp 92 0 4978 2479 2580 1681 1982 Shift F9 NOPQR 930 2084 7843 7445 5363 Shift F10 T +- ? 21 89 44 90 YZ 41 126 13 43 43 124 01 27 ~+IESCAPE 101 102 Dark Light 26 123 27 125 39 58 {}:73 57 9 71 55 79 49 71 40 34 51 60 53 63 81 51 " 12 95 82 48 83 46 + -0. SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-35. Series 3300 56-key Shift+Func Modified Keyboard B-42 The Series 3000 Keyboard 104 0 105 0 106 0 107 0 108 0 On Alt F1 Alt F2 Alt F3 Alt F4 Alt F5 Off 30 0 48 0 46 0 32 0 18 0 33 0 Alt A Alt B Alt C Alt D Alt E Alt F 34 0 35 0 23 0 36 0 37 0 38 0 Alt G Alt H Alt I Alt J Alt K Alt L 50 0 49 0 24 0 25 0 16 0 19 0 Alt M Alt N Alt O Alt P Alt Q Alt R 31 0 20 0 22 0 47 0 17 0 45 0 Alt S Alt T Alt U Alt V Alt W Alt X 21 89 44 90 Alt Y Alt Z 126 0 127 0 128 0 Alt 7 Alt 8 Alt 9 57 32 Space 123 0 124 0 125 0 Alt 4 Alt 5 Alt 6 120 0 121 0 122 0 Alt 1 Alt 2 Alt 3 130 0 129 0 Alt - Alt 0 SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-36. Series 3300 56-key ALT (Func+Control)-Modified Keyboard B-43 Series 3000 Application Programmer’s Reference Manual 99 0 100 0 101 0 102 0 103 0 On Ctrl F6 Ctrl F7 Ctrl F8 Ctrl F9 Ctrl F10 Off 30 01 48 02 46 03 32 04 18 05 33 06 Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E Ctrl F 34 07 94 0 23 09 36 10 37 11 Ctrl G Ctrl F1 Ctrl I Ctrl J Ctrl K Lamp 1020 4914 2415 25161617 1918 Ctrl F9 Ctrl N Ctrl O Ctrl P Ctrl Q Ctrl R 103 0 20 20 55 00 Ctrl F10 Ctrl T Ctrl * 21 25 44 26 Ctrl Y Ctrl Z 43 28 01 27 Ctrl \ ESCAPE 101 102 Dark Light 26 27 27 29 132 0 Ctrl ( Ctrl ) * Pg Up 119 0 117 0 * Home * End 118 0 * Pg Dn 12 31 Ctrl - SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-37. Series 3300 56-key CTRL+Func-Modified Keyboard B-44 The Series 3000 Keyboard 109 0 110 0 111 0 112 0 113 0 On Alt F6 Alt F7 Alt F8 Alt F9 Alt F10 Off 30 00 48 00 46 00 32 00 18 00 33 00 Alt A Alt B Alt C Alt D Alt E Alt F 34 00 104 0 23 00 36 00 37 00 Alt G Alt F1 Alt I Alt J Alt K Lamp 1120 4900 2400 25001600 1900 Alt F9 Alt N Alt O Alt P Alt Q Alt R 113 0 20 00 Alt F10 Alt T 21 00 44 00 69 56 Alt Y Alt Z 131 0 Alt = 101 102 Dark Light 131 00 130 00 Alt - Alt = SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-38. Series 3300 56-key ALT+Func-Modified Keyboard B-45 Series 3000 Application Programmer’s Reference Manual Figure B-39. Series 3500 47-key Unmodified Keyboard B-46 The Series 3000 Keyboard 01 27 29 00 42 00 30 65 48 66 46 67 32 68 18 69 33 70 34 71 35 72 23 73 36 74 37 75 38 76 50 77 49 78 24 79 25 80 16 81 19 82 31 83 20 84 22 85 47 86 17 87 45 88 21 89 44 90 72 56 80 50 08 38 09 42 10 40 14 08 05 36 06 37 07 94 57 32 02 33 03 64 04 35 28 13 11 41 52 46 Figure B-40. Series 3500 47-key Shift-Modified Keyboard B-47 Series 3000 Application Programmer’s Reference Manual Figure B-41. Series 3500 47-key Caplock-Modified Keyboard B-48 The Series 3000 Keyboard Figure B-42. Series 3500 47-key Ctrl-Modified Keyboard B-49 Series 3000 Application Programmer’s Reference Manual Figure B-43. Series 3500 47-Key Func-Modified Keyboard B-50 The Series 3000 Keyboard Figure B-44. Series 3500 47-key Shift+Func-Modified Keyboard B-51 Series 3000 Application Programmer’s Reference Manual Figure B-45. Series 3500 47-key Alt (Func+Ctrl)-Modified Keyboard B-52 The Series 3000 Keyboard Figure B-46. Series 3500 47-key Ctrl+Func-Modified Keyboard B-53 Series 3000 Application Programmer’s Reference Manual Alt E Alt F Alt G Figure B-47. Series 3500 47-key Alt+Func-Modified Keyboard B-54 The Series 3000 Keyboard 57 32 58 00 29 00 SPACE ALPHA CTRL FUNC 14 08 01 27 42 00 BKSP PWR CLR SHF 26 91 27 93 40 39 13 61 (), = 55 42 53 47 12 45 78 43 * /-+ 52 46 51 44 43 92 39 59 ”’\ ; 75 00 77 00 72 00 80 00 08 55 09 56 10 57 789 05 52 06 53 07 54 456 02 49 03 50 04 51 123 11 48 28 13 0 Enter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-48. Series 3800 35-key Unmodified Keyboard B-55 Series 3000 Application Programmer’s Reference Manual 57 32 58 00 29 00 SPACE ALPHA CTRL FUNC 14 08 01 27 42 00 BKSP PWR CLR SHF 30 65 48 66 46 67 32 68 AB CD 18 69 33 70 34 71 35 72 EFGH 23 73 36 74 37 75 38 76 IJ KL 50 77 49 78 24 79 25 80 MNOP 16 81 19 82 31 83 QRS 20 84 22 85 47 86 TUV 17 87 45 88 21 89 WX Y 44 90 28 13 Z Enter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-49. Series 3800 35-key Alpha-Modified Keyboard B-56 The Series 3000 Keyboard 57 32 58 00 29 00 SPACE ALPHA CTRL FUNC 00 03 01 27 42 00 Ctrl Brk PWR CLR SHF 30 01 48 02 46 03 32 04 Ctrl A Ctrl B Ctrl C Ctrl D 18 05 33 06 34 07 35 08 Ctrl E Ctrl F Ctrl G Ctrl H 23 09 36 10 37 11 38 12 Ctrl I Ctrl J Ctrl K Ctrl L 50 13 49 14 24 15 25 16 Ctrl M Ctrl N Ctrl O Ctrl P 16 17 19 18 31 19 Ctrl Q Ctrl R Ctrl S 20 20 22 21 47 22 Ctrl T Ctrl U Ctrl V 17 23 45 24 21 25 Ctrl W Ctrl X Ctrl Y 44 26 28 10 Ctrl Z Ctrl J (Line Feed) SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-50. Series 3800 35-key Control-Modified Keyboard B-57 Series 3000 Application Programmer’s Reference Manual 15 09 58 00 56 00 TAB ALPHA ALT FUNC 83 00 01 27 42 00 Ctrl Brk PWR CLR SHF 82 00 41 96 40 39 13 61 INS ‘’= 12 45 78 43 Light Dark -+ 101 102 43 92 Darker Lighter \ Lamp 71 00 79 00 73 00 81 00 HOME END Pg Up Pg Dn MENU 65 00 66 00 67 00 F7 F8 F9 62 00 63 00 64 00 F4 F5 F6 59 00 60 00 61 00 F1 F2 F3 68 00 28 13 F10 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-51. Series 3800 35-key Func-Modified Keyboard B-58 The Series 3000 Keyboard 58 00 56 00 ALPHA ALT FUNC 83 46 01 27 42 00 . PWR CLR SHF 82 48 41 126 40 34 13 43 0 ~ ” + 53 63 12 95 78 43 ? _+ 101 102 43 124 Darker Lighter I Lamp 71 55 79 49 73 57 81 51 7193 90 00 91 00 92 00 Shift F7 Shift F8 Shift F9 87 00 88 00 89 00 Shift F4 Shift F5 Shift F6 84 00 85 00 86 00 Shift F1 Shift F2 Shift F3 93 00 28 13 Shift F10 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-52. Series 3800 35-key Shift+Func-Modified Keyboard B-59 Series 3000 Application Programmer’s Reference Manual 58 00 56 00 ALPHA ALT FUNC 01 27 42 00 PWR CLR SHF 55 00 12 31 Prt Scrn Ctrl - 101 102 43 28 Darker Lighter Ctrl \ Lamp 119 00 117 00 132 00 118 00 Ctrl Home Ctrl End Ctrl Pg Up Ctrl Pg Dn 100 00 101 00 102 00 Ctrl F7 Ctrl F8 Ctrl F9 97 00 98 00 99 00 Ctrl F4 Ctrl F5 Ctrl F6 94 00 95 00 96 00 Ctrl F1 Ctrl F2 Ctrl F3 103 00 28 13 Ctrl F10 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-53. Series 3800 35-key Control+Func-Modified Keyboard B-60 The Series 3000 Keyboard 57 32 58 00 29 00 SPACE ALPHA CTRL FUNC 14 08 01 27 42 00 BKSP PWR CLR SHF 26 123 27 125 40 34 13 43 {} ” + 55 00 53 63 12 95 78 43 Prt Scr ? - + 52 62 51 60 43 124 39 58 > 75 52 77 54 72 56 80 50 4682 08 38 09 42 10 40 & * ( 05 36 06 37 07 94 $% > 02 33 03 64 04 35 !@# 11 41 28 13 ) ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-54. Series 3800 35-key Shift-Modified Keyboard B-61 Series 3000 Application Programmer’s Reference Manual 58 00 56 00 ALPHA ALT FUNC 01 27 42 00 PWR CLR SHF 131 00 ALT = 130 00 ALT - 101 102 Darker Lighter Lamp 110 00 111 00 112 00 Alt F7 Alt F8 Alt F9 107 00 108 00 109 00 Alt F4 Alt F5 Alt F6 104 00 105 00 106 00 Alt F1 Alt F2 Alt F3 113 00 Alt F10 SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-55. Series 3800 35-key ALT+Func-Modified Keyboard B-62 The Series 3000 Keyboard 57 32 58 00 29 00 SPACE ALPHA CTRL FUNC 01 27 42 00 PWR CLR SHF 30 00 48 00 46 00 32 00 ALT A ALT B ALT C ALT D 18 00 33 00 34 00 35 00 ALT E ALT F ALT G ALT H 23 00 36 00 37 00 38 00 ALT I ALT J ALT K ALT L 50 00 49 00 24 00 25 00 ALT M ALT N ALT O ALT P 16 00 19 00 31 00 ALT Q ALT R ALT S 20 00 22 00 47 00 ALT T ALT U ALT V 17 00 45 00 21 00 ALT W ALT X ALT Y 44 00 ALT Z SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-56. Series 3800 35-key ALT(Func+Control)-Modified Keyboard B-63 Series 3000 Application Programmer’s Reference Manual 01 27 42 00 29 00 ON Clear Func Shift Ctrl OFF 30 97 48 98 46 99 32 100 18 101 abcde 33 102 34 103 35 104 23 105 36 106 f ghi j 37 107 38 108 50 109 49 110 24 111 klmno 25 112 16 113 19 114 31 115 20 116 pqrst 22 117 47 118 17 119 45 120 21 121 uvwxy 44 122 14 08 52 46 72 00 80 00 z bksp . 08 55 09 56 10 57 789 05 52 06 53 07 54 456 02 49 03 50 04 51 123 11 48 28 13 0 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-57. Series 3800/6800 46-key Unmodified Keyboard (CLR and FUNC are reversed on 6800) B-64 The Series 3000 Keyboard 01 27 42 00 29 00 CLR FUNC SHF CTL PWR 30 65 48 66 46 67 32 68 18 69 ABCDE 33 70 34 71 35 72 23 73 36 74 FGHIJ 37 75 38 76 50 77 49 78 24 79 KLMNO 25 80 16 81 19 82 31 83 20 84 PQRST 22 85 47 86 17 87 45 88 21 89 UVWXY 44 90 14 08 52 62 72 56 80 50 Z BKSP > 82 08 38 09 42 10 40 &*( 05 36 06 37 07 94 $% > 02 33 03 64 04 35 !@# 11 41 28 13 ) ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-58. Series 3800/6800 46-key Shift-Modified Keyboard (CLR and FUNC are reversed on 6800) B-65 Series 3000 Application Programmer’s Reference Manual 01 27 42 00 29 00 CLR FUNC SHF CTL PWR 30 65 48 66 46 67 32 68 18 69 ABCDE 33 70 34 71 35 72 23 73 36 74 FGHIJ 37 75 38 76 50 77 49 78 24 79 KLMNO 25 80 16 81 19 82 31 83 20 84 PQRST 22 85 47 86 17 87 45 88 21 89 UVWXY 44 90 14 08 52 46 72 00 80 00 Z BKSP . 08 55 09 56 10 57 789 05 52 06 53 07 54 456 02 49 03 50 04 51 123 11 48 28 13 0 ENTER SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-59. Series 3800/6800 46-key Caplock-Modified Keyboard (CLR and FUNC are reversed on 6800) B-66 The Series 3000 Keyboard 01 27 ON CLR OFF 30 01 48 02 46 03 32 04 18 05 Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E 33 06 34 07 35 08 23 09 36 10 Ctrl F Ctrl G Ctrl H Ctrl I Ctrl J 37 11 38 12 50 13 49 14 24 15 Ctrl K Ctrl L Ctrl M Ctrl N Ctrl O 25 16 16 17 19 18 31 19 20 20 Ctrl P Ctrl Q Ctrl R Ctrl S Ctrl T 22 21 47 22 17 23 45 24 21 25 Ctrl U Ctrl V Ctrl W Ctrl X Ctrl Y 44 26 00 03 141 00 145 00 Ctrl Z Ctrl Brk Ctrl Ctrl 07 30 Ctrl 6 03 00 Ctrl 2 28 10 Linefeed SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-60. Series 3800/6800 46-key Control-Modified Keyboard (CLR and FUNC are reversed on 6800) B-67 Series 3000 Application Programmer’s Reference Manual 01 27 58 00 56 00 ON Clear CapLk Alt OFF 78 43 74 45 55 42 53 47 18 101 +-” /e 33 102 34 103 41 96 13 61 43 92 fg`=\ 12 45 26 91 27 93 39 59 - Lamp [ ] ; 71 00 79 00 40 39 51 44 53 47 Home End ,, / 82 00 83 00 73 00 Ins Del Pg UpDark Light 44 122 57 32 81 00 75 00 77 00 Z Space Pg Dn 65 00 66 00 67 00 F7 F8 F9 62 00 63 00 64 00 F4 F5 F6 59 00 60 00 61 00 F1 F2 F3 68 00 13 61 F10 = SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-61. Series 3800/6800 46-key Func-Modified Keyboard B-68 The Series 3000 Keyboard 01 27 ON Clear OFF 78 43 74 45 53 63 18 69 +- ?E 33 70 34 71 41 126 13 43 43 124 FG~ +I 12 95 26 123 27 125 39 58 - Lamp { } : 71 55 79 49 40 34 51 60 53 63 71” 82 48 83 46 73 57 0 . 9 Dark Light 44 90 57 32 81 51 75 52 77 54 Z Space 3 4 6 90 00 91 00 92 00 Shf F7 Shf F8 Shf F9 87 00 88 00 89 00 Shf F4 Shf F5 Shf F6 84 00 85 00 86 00 Shf F1 Shf F2 Shf F3 93 00 13 43 Shf F10 + SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-62. Series 3800/6800 46-key Shift+Func-Modified Keyboard (CLR and FUNC are reversed on 6800) B-69 Series 3000 Application Programmer’s Reference Manual ON OFF 30 00 48 00 46 00 32 00 18 00 Alt A Alt B Alt C Alt D Alt E 33 00 34 00 35 00 23 00 36 00 Alt F Alt G Alt H Alt I Alt J 37 00 38 00 50 00 49 00 28 00 Alt K Alt L Alt M Alt N Alt O 25 00 16 00 19 00 31 00 20 00 Alt P Alt Q Alt R Alt S Alt T 22 00 47 00 17 00 45 00 21 00 Alt U Alt V Alt W Alt X Alt Y 44 00 Alt Z 126 00 127 00 128 00 Alt 7 Alt 8 Alt 9 123 00 124 00 125 00 Alt 4 Alt 5 Alt 6 120 00 121 00 122 00 Alt 1 Alt 2 Alt 3 129 00 Alt 0 SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-63. Series 3800/6800 46-key ALT (Func+Ctrl)-Modified Keyboard (CLR and FUNC are reversed on 6800) B-70 The Series 3000 Keyboard 01 27 ON Clear OFF 55 00 18 05 Ctrl ” Ctrl E 33 06 34 07 43 28 Ctrl F Ctrl G Ctrl \ 12 31 26 27 27 29 Ctrl - Lamp Ctrl [ Ctrl ] 119 00 117 00 Ctl Hm Ctl End 132 00 Ctl Pg Up Dark Light 44 26 57 32 118 00 115 00 116 00 Crtl Z Space Ctl Pg Dn Ctrl Ctrl 100 00 101 00 102 00 Ctrl F7 Ctrl F8 Ctrl F9 97 00 98 00 99 00 Ctrl F4 Ctrl F5 Ctrl F6 94 00 95 00 96 00 Ctrl F1 Ctrl F2 Ctrl F3 103 00 Ctrl F10 SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-64. Series 3800/6800 46-key Control+Func-Modified Keyboard (CLR and FUNC are reversed on 6800) B-71 Series 3000 Application Programmer’s Reference Manual ON OFF 18 00 Alt E 33 00 34 00 131 00 Alt F Alt G Alt = 130 00 Alt - Lamp Dark Light 44 00 57 32 Alt Z Space 110 00 111 00 112 00 Alt F7 Alt F8 Alt F9 107 00 108 00 109 00 Alt F4 Alt F5 Alt F6 104 00 105 00 106 00 Alt F1 Alt F2 Alt F3 113 00 131 00 Alt F10 Alt = SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-65. Series 3800/6800 46-key ALT+Func-Modified Keyboard (CLR and FUNC are reversed on 6800) B-72 The Series 3000 Keyboard 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 14 08 57 32 29 00 26 91 27 93 BKSP SPACE CTRL [ ] 40 39 13 61 55 42 53 47 12 45 ' = */_ 78 43 52 46 51 44 43 92 39 59 + .,\; 75 00 77 00 72 00 80 00 08 55 09 56 10 57 7 8 9 05 52 06 53 07 54 4 5 6 02 49 03 50 04 51 1 2 3 11 48 28 13 0 ENTER Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309001.eps Figure B-66. Series 6800 35-Key Unmodified Keyboard B-73 Series 3000 Application Programmer’s Reference Manual 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 14 08 57 32 29 00 30 65 48 66 BKSP SPACE CTRL A B 46 67 32 68 18 69 33 70 34 71 C D E F G 35 72 23 73 36 74 37 75 38 76 H I J K L 50 77 49 78 24 79 25 80 M N O P 16 81 19 82 31 83 Q R S 20 84 22 85 47 86 T U V 17 87 45 88 21 89 W X Y 44 90 28 13 Z ENTER Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309002.eps Figure B-67. Series 6800 35-key Alpha-modified Keyboard B-74 The Series 3000 Keyboard 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 00 03 57 32 29 00 30 01 48 02 CTL BK SPACE CTRL CTRL A CTRL B 46 03 32 04 18 05 33 06 34 07 CTRL C CTRL D CTRL E CTRL F CTRL G 35 08 23 09 36 10 37 11 38 12 CTRL H CTRL I CTRL J CTRL K CTRL L 50 13 49 14 24 15 25 16 CTRL M CTRL N CTRL O CTRL P 16 17 19 18 31 19 CTRL Q CTRL R CTRL S 20 20 22 21 47 22 CTRL T CTRL U CTRL V 17 23 45 24 21 25 CTRL W CTRL X CTRL Y 44 26 28 10 CTRL Z CTRL J (LINE FEED) Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309003.eps Figure B-68. Series 6800 Control-modified Keyboard B-75 Series 3000 Application Programmer’s Reference Manual 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 83 00 15 09 56 00 82 00 41 96 CTL BK TAB ALT INS ‘ 40 39 13 61 12 _ 45 ’ = LIGHT DARK 78 43 101 102 43 92 + DARKER LIGHTER \ LAMP 71 00 79 00 73 00 81 00 HOME END PG UP PG DN 65 00 66 00 67 00 F7 F8 F9 62 00 63 00 64 00 F4 F5 F6 59 00 60 00 61 00 F1 F2 F3 68 00 28 13 F10 ENTER Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309004.eps Figure B-69. Series 6800 35-key Function-modified Keyboard B-76 The Series 3000 Keyboard 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 83 46 56 00 82 48 41 126 . ALT 0 ~ 40 34 13 43 53 63 12 _ 95 " + ? 78 43 101 102 43 124 + DARKER LIGHTER | LAMP 71 55 79 49 73 57 81 51 7 1 9 3 90 00 91 00 92 00 SHIFT F7 SHIFT F8 SHIFT F9 87 00 88 00 89 00 SHIFT F4 SHIFT F5 SHIFT F6 84 00 85 00 86 00 SHIFT F1 SHIFT F2 SHIFT F3 93 00 28 13 SHIFT F10 ENTER Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309005.eps Figure B-70. Series 6800 35-key Shift+Func-modified Keyboard B-77 Series 3000 Application Programmer’s Reference Manual 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 56 00 ALT 55 00 12 31 PRT SCN CTRL - 101 102 43 28 DARKER LIGHTER CTRL \ LAMP 119 00 117 00 132 00 118 00 CTRL HOME CTRL END CTRL PG UP CTRL PG DN 100 00 101 00 102 00 CTRL F7 CTRL F8 CTRL F9 97 00 98 00 99 00 CTRL F4 CTRL F5 CTRL F6 94 00 95 00 96 00 CTRL F1 CTRL F2 CTRL F3 103 00 28 13 CTRL F10 ENTER Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309006.eps Figure B-71. Series 6800 35-key Control+Func-modified Keyboard B-78 The Series 3000 Keyboard 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 14 08 57 32 29 00 26 123 27 125 BKSP SPACE CTRL { } 40 34 13 43 55 00 53 63 12 95 " + PRT SCN ? - 78 43 52 62 51 60 43 124 39 58 + > < ! : 75 52 77 54 72 56 80 50 4 6 82 08 38 09 42 10 40 & *( 05 36 06 37 07 94 $ %^ 02 33 03 64 04 35 ! @ # 11 41 28 13 ) ENTER Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309007.eps Figure B-72. Series 6800 35-key Shift-modified Keyboard B-79 Series 3000 Application Programmer’s Reference Manual 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 56 00 ALT 131 00 130 00 ALT = ALT - 101 102 DARKER LIGHTER LAMP 110 00 111 00 112 00 ALT F7 ALT F8 ALT F9 107 00 108 00 109 00 ALT F4 ALT F5 ALT F6 104 00 105 00 106 00 ALT F1 ALT F2 ALT F3 113 00 ALT F10 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309008.eps Figure B-73. Series 6800 35-key ALT+Func-modified Keyboard B-80 The Series 3000 Keyboard 58 00 01 27 42 00 FUNC ALPHA CLEAR SHIFT PWR 57 32 29 00 30 00 48 00 SPACE CTRL ALT A ALT B 46 00 32 00 18 00 33 00 34 00 ALT C ALT D ALT E ALT F ALT G 35 00 23 00 36 00 37 00 38 00 ALT H ALT I ALT J ALT K ALT L 50 00 49 00 24 00 25 00 ALT M ALT N ALT O ALT P 16 00 19 00 31 00 ALT Q ALT R ALT S 20 00 22 00 47 00 ALT T ALT U ALT V 17 00 45 00 21 00 ALT W ALT X ALT Y 44 00 ALT Z Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309009.eps Figure B-74. Series 6800 35-key ALT (Func+CTRL)-modified Keyboard B-81 Series 3000 Application Programmer’s Reference Manual 01 27 42 00 29 00 FUNCCLR SHF CTL PWR 30 97 48 98 46 99 32 100 18 101 A B C D E 33 102 34 103 35 104 23 105 36 106 F G HIJ 37 107 38 108 50 109 49 110 24 111 K L M N O 25 112 16 113 19 114 31 115 20 116 P Q RST 22 117 47 118 17 119 45 120 21 121 U V WXY 44 122 14 08 52 46 72 00 80 00 Z BKSP ¥ 08 55 09 56 10 57 11 48 7 890 05 52 06 53 07 54 13 4 5628 ENTER 02 49 03 50 04 51 1 23 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309010.eps Figure B-75. Series 6800 46-Key Unmodified Keyboard B-82 The Series 3000 Keyboard 01 27 42 00 29 00 FUNC CLR SHF CTL PWR 30 65 48 66 46 67 32 68 18 69 A B C D E 33 70 34 71 35 72 23 73 36 74 F G HIJ 37 75 38 76 50 77 49 78 24 79 K L M N O 25 80 16 81 19 82 31 83 20 84 P Q R S T 22 85 47 86 17 87 45 88 21 89 U V W X Y 44 90 14 08 52 62 72 56 80 50 Z BKSP > 82 08 38 09 42 10 40 11 41 & * ( ) 05 36 06 37 07 94 28 13 $ % ^ ENTER 02 33 03 64 04 35 ! @ # Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309011.eps Figure B-76. Series 6800 46-Key Shift-modified Keyboard B-83 Series 3000 Application Programmer’s Reference Manual 01 27 42 00 29 00 FUNC CLR SHF CTL PWR 30 65 48 66 46 67 32 68 18 69 A B C D E 33 70 34 71 35 72 23 73 36 74 F G HIJ 37 75 38 76 50 77 49 78 24 79 K L M N O 25 80 16 81 19 82 31 83 20 84 P Q R S T 22 85 47 86 17 87 45 88 21 89 U V W X Y 44 90 14 08 52 46 72 00 80 00 Z BKSP . 08 55 09 56 10 57 11 48 7 8 9 0 05 52 06 53 07 54 28 13 4 5 6 ENTER 02 49 03 50 04 51 1 2 3 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309012.eps Figure B-77. Series 6800 46-Key Caplock-modified Keyboard B-84 The Series 3000 Keyboard 01 27 ON CLR OFF 30 01 48 02 46 03 32 04 18 05 CTRL A CTRL B CTRL C CTRL D CTRL E 33 06 34 07 35 08 23 09 36 10 CTRL F CTRL G CTRL H CTRL I CTRL J 37 11 38 12 50 13 49 14 24 15 CTRL K CTRL L CTRL M CTRL N CTRL O 25 16 16 17 19 18 31 19 20 20 CTRL P CTRL Q CTRL R CTRL S CTRL T 22 21 47 22 17 23 45 24 21 25 CTRL U CTRL V CTRL W CTRL X CTRL Y 44 26 00 03 141 00 145 00 CTRL Z CTRL BRK CTRL CTRL 07 30 28 10 CTRL 6 LINEFEED 03 00 CTRL 2 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309013.eps Figure B-78. Series 6800 46-Key Control-Modified Keyboard B-85 Series 3000 Application Programmer’s Reference Manual 01 27 58 00 56 00 ON CLR CAPLK ALT OFF 78 43 74 45 55 42 53 47 18 101 + - " / e 33 102 34 103 41 96 13 61 43 92 f g `=\ 12 45 26 91 27 93 39 59 - LAMP [ ] ; 71 00 79 00 40 39 51 44 53 47 HOME END , , / 82 00 83 00 73 00 INS DEL PG UP DARK LIGHT 44 122 57 32 81 00 75 00 77 00 z SPACE PG UP 65 00 66 00 67 00 68 00 F7 F8 F9 F10 62 00 63 00 64 00 13 61 F4 F5 F6 = 59 00 60 00 61 00 F1 F2 F3 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309014.eps Figure B-79. Series 6800 46-Key Func-Modified Keyboard B-86 The Series 3000 Keyboard 01 27 ON CLR OFF 78 43 74 45 53 63 18 69 + - ? E 33 70 34 71 41 126 13 43 43 124 F G ~+| 12 95 26 123 27 125 39 58 - LAMP { } : 71 55 79 49 40 34 51 60 53 63 71 " < ? 82 48 83 46 73 57 0 . 9 DARK LIGHT 44 90 57 32 81 51 75 52 77 54 z SPACE 3 4 6 90 00 91 00 92 00 93 00 SHF F7 SHF F8 SHF F9 SHF F10 87 00 88 00 89 00 13 43 SHF F4 SHF F5 SHF F6 + 84 00 85 00 86 00 SHF F1 SHF F2 SHF F3 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309015.eps Figure B-80. Series 6800 46-Key Shift+Func-modified Keyboard B-87 Series 3000 Application Programmer’s Reference Manual ON OFF 30 00 48 00 46 00 32 00 18 00 ALT A ALT B ALT C ALT D ALT E 33 00 34 00 35 00 23 00 36 00 ALT F ALT G ALT H ALT I ALT J 37 00 38 00 50 00 49 00 28 00 ALT K ALT L ALT M ALT N ALT O 25 00 16 00 19 00 31 00 20 00 ALT P ALT Q ALT R ALT S ALT T 22 00 47 00 17 00 45 00 21 00 ALT U ALT V ALT W ALT X ALT Y 44 00 ALT Z 126 00 127 00 128 00 129 00 ALT 7 ALT 8 ALT 9 ALT 0 123 00 124 00 125 00 ALT 4 ALT 5 ALT 6 120 00 121 00 122 00 ALT 1 ALT 2 ALT 3 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309016.eps Figure B-81. Series 6800 46-Key ALT (Func+CTRL)-modified Keyboard B-88 The Series 3000 Keyboard 01 27 ON CLR OFF 55 00 18 05 CTRL " CTRL E 33 06 34 07 43 28 CTRL F CTRL G CTRL \ 12 31 26 27 27 29 CTRL - LAMP CTRL [ CTRL ] 119 00 117 00 CTRL HM CTL END 132 00 CTL PG UP DARK LIGHT 44 26 57 32 118 00 115 00 116 00 CTRL Z SPACE CTL PG DN CTRL CTRL 100 00 101 00 102 00 103 00 CTRL F7 CTRL F8 CTRL F9 CTRL F10 97 00 98 00 99 00 CTRL F4 CTRL F5 CTRL F6 94 00 95 00 96 00 CTRL F1 CTRL F2 CTRL F3 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309017.eps Figure B-82. Series 6800 46-Key Control+Func-modified Keyboard B-89 Series 3000 Application Programmer’s Reference Manual ON OFF 18 00 ALT E 33 00 34 00 131 00 ALT F ALT G ALT = 130 00 ALT - LAMP DARK LIGHT 44 00 57 32 ALT Z SPACE 110 00 111 00 112 00 113 00 ALT F7 ALT F8 ALT F9 ALT F10 00 00 00 107 108 109 131 00 ALT F4 ALT F5 ALT F6 ALT = 104 00 105 00 106 00 ALT F1 ALT F2 ALT F3 Scan Code ASCII Value (Decimal) SS AA (Decimal) C Printable Character or Logical Key Sequence Name 16309018.eps Figure B-83. Series 6800 46-Key ALT+Func-modified Keyboard B-90 The Series 3000 Keyboard 59 00 60 00 61 00 62 00 63 00 75 00 77 00 72 00 80 00 ON F1 F2 F3 F4 F5 Func OFF 30 97 48 98 46 99 32 100 18 101 33 102 34 103 08 55 09 56 10 57 29 00 ab cde f g 7 8 9 Ctrl 35 104 23 105 36 106 37 107 38 108 50 109 49 110 05 52 06 53 07 54 01 27 hi j kl mn 4 5 6 Clear 24 111 25 112 16 113 19 114 31 115 20 116 22 117 02 49 03 50 04 51 28 13 op qrs t u 123 47 118 17 119 45 120 21 121 44 122 42 14 08 12 45 11 48 52 46 v w x y z Shift BkSp - 0 . Enter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-84. Series 3900 54-Key Unmodified Keyboard B-91 Series 3000 Application Programmer’s Reference Manual 84 00 85 00 86 00 87 00 88 00 75 52 77 54 72 56 80 50 ON Shift F1 Shift F2 Shift F3 Shift F4 Shift F5 4 6 8 2 OFF 30 65 48 66 46 67 32 68 18 69 33 70 34 71 08 38 09 42 10 40 29 00 AB CDE FG & * ( Ctrl 35 72 23 73 36 74 37 75 38 76 50 77 49 78 05 36 06 37 07 94 01 27 HI J KL MN $ %> Clear 24 79 25 80 16 81 19 82 31 83 20 84 22 85 02 33 03 64 04 35 28 13 OP QRS TU !@# 47 86 17 87 45 88 21 89 44 90 14 08 12 95 11 41 52 62 V W X Y Z BkSp - ) > Enter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-85. Series 3900 54-key Shift-Modified Keyboard B-92 The Series 3000 Keyboard 59 00 60 00 61 00 62 00 63 00 75 00 77 00 72 56 80 00 ON F1 F2 F3 F4 F5 OFF 30 65 48 66 46 67 32 68 18 69 33 70 34 71 08 55 09 56 10 57 AB CDE FG 789 35 72 23 73 36 74 37 75 38 76 50 77 49 78 05 52 06 53 07 54 01 27 HI J KL MN 4 5 6 Clear 24 79 25 80 16 81 19 82 31 83 20 84 22 85 02 49 03 50 04 51 28 13 OP QRS TU 123 47 86 17 87 45 88 21 89 44 90 14 08 12 45 11 48 52 46 V W X Y Z BkSp - 0 . Enter SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-86. Series 3900 54-key Caplock-Modified Keyboard B-93 Series 3000 Application Programmer’s Reference Manual 94 00 95 00 96 00 97 00 98 00 115 00 116 00 141 00 145 00 ON Ctrl F1 Ctrl F2 Ctrl F3 Ctrl F4 Ctrl F5 Ctrl Ctrl Ctrl Ctrl OFF 30 01 48 02 46 03 32 04 18 05 33 06 34 07 Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E Ctrl F Ctrl G 35 08 23 09 36 10 37 11 38 12 50 13 49 14 07 30 01 27 Ctrl H Ctrl I Ctrl J Ctrl K Ctrl L Ctrl M Ctrl N Ctrl 6 Clear 24 15 25 16 16 17 19 18 31 19 20 20 22 21 03 00 28 10 Ctrl O Ctrl P Ctrl Q Ctrl R Ctrl S Ctrl T Ctrl U Ctrl 2 47 22 17 23 45 24 21 25 44 26 00 03 12 31 Line Ctrl V Ctrl W Ctrl X Ctrl Y Ctrl Z Ctrl Brk Ctrl - Feed SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-87. Series 3900 54-key Control-Modified Keyboard B-94 The Series 3000 Keyboard 64 00 65 00 66 00 67 00 68 00 71 00 79 00 73 00 81 00 ON F6 F7 F8 F9 F10 Home End Pg Up Pg Dn OFF 30 97 48 98 46 99 32 100 18 101 33 102 34 103 41 96 13 61 43 92 29 00 ab cde f g ` = \ Alt 59 00 101 102 37 107 58 00 67 00 69 00 26 91 27 93 39 59 01 27 F1 Dark Light k CapLk F9 NumLk [ ] ; Clear 24 111 25 112 16 113 19 114 68 00 20 116 78 43 40 39 51 44 53 47 13 61 op qrF10t+ ’ , / 74 45 55 42 53 47 21 121 44 122 57 32 12 45 82 00 83 00 = -* / y z Space - Ins Del SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-88. Series 3900 54-key Func-Modified Keyboard B-95 Series 3000 Application Programmer’s Reference Manual 89 00 90 00 91 00 92 00 93 00 71 55 79 49 73 57 81 51 ON Shift F6 Shift F7 Shift F8 Shift F9 Shift F10 7 1 9 3 OFF 30 65 48 66 46 67 32 68 18 69 33 70 34 71 41 126 13 43 43 124 29 00 AB CDE FG ~ + ! Alt 84 00 101 102 37 75 58 00 92 00 69 00 26 123 27 125 39 58 01 27 Shift F1 Dark Light K CapLk Shift F9 NumLk { } : Clear 24 79 25 80 16 81 19 82 93 00 20 84 78 43 40 34 51 60 53 63 13 43 O P Q R Shift F10 T + ” < ? 74 45 53 63 21 89 44 90 14 08 12 95 82 48 83 46 + - ? Y Z BkSp - 0 . SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-89. Series 3900 54-key Shift+Func-Modified Keyboard B-96 The Series 3000 Keyboard 104 00 105 00 106 00 107 00 108 00 ON Alt F1 Alt F2 Alt F3 Alt F4 Alt F5 OFF 30 00 48 00 46 00 32 00 18 00 33 00 34 00 126 00 127 00 128 00 Alt A Alt B Alt C Alt D Alt E Alt F Alt G Alt 7 Alt 8 Alt 9 35 00 23 00 36 00 37 00 38 00 50 00 49 00 123 00 124 00 125 00 Alt H Alt I Alt J Alt K Alt L Alt M Alt N Alt 4 Alt 5 Alt 6 24 00 25 00 16 00 19 00 31 00 20 00 22 00 120 00 121 00 122 00 13 61 Alt O Alt P Alt Q Alt R Alt S Alt T Alt U Alt 1 Alt 2 Alt 3 47 00 17 00 45 00 21 00 44 00 130 00 129 00 Alt V Alt W Alt X Alt Y Alt Z Alt - Alt 0 = SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-90. Series 3900 54-key ALT (Func+Control)-Modified B-97 Series 3000 Application Programmer’s Reference Manual 99 00 100 00 101 00 102 00 103 00 119 00 117 00 132 00 118 00 ON Ctrl F6 Ctrl F7 Ctrl F8 Ctrl F9 Ctrl F10 Ctrl Hm Ctl End Ctl Pg Up Ctl Pg Dn OFF 30 01 48 02 46 03 32 04 18 05 33 06 34 07 43 28 Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E Ctrl F Ctrl G Ctrl \ 94 00 101 102 37 11 58 00 102 26 27 27 29 01 27 Ctrl F1 Dark Light Ctrl K Cap Lk Ctrl F9 Ctrl 4 Ctrl 5 Clear 24 15 25 16 16 17 19 18 103 00 20 20 Ctrl O Ctrl P Ctrl Q Ctrl R Ctrl F10 Ctrl T 55 00 21 25 44 26 42 00 57 32 12 31 Ctrl * Ctrl Y Ctrl Z Shift Space Ctrl - SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-91. Series 3900 54-key Control+Func Modified Keyboard B-98 The Series 3000 Keyboard 109 00 110 00 111 00 112 00 112 00 ON Alt F6 Alt F7 Alt F8 Alt F9 Alt F10 OFF 48 00 32 00 18 00 33 00 34 00 131 00 Alt B Alt D Alt E Alt F Alt G Alt = 104 00 101 00 102 00 37 00 58 00 112 00 69 00 Alt F1 Dark Light Alt K Cap Lk Alt F9 Num Lk 24 00 25 00 16 00 19 00 113 00 20 00 Alt O Alt P Alt Q Alt R Alt F10 Alt T 21 00 44 00 130 00 Alt Y Alt Z Alt - SCAN CODE ASCII VALUE SS AA (Decimal) (Decimal) C PRINTABLE CHARACTER OR LOGICAL KEY SEQUENCE NAME Figure B-92. Series 3900 54-key ALT+Func-Modified Keyboard B-99 Series 3000 Application Programmer’s Reference Manual 4D 00 → FUNC 4B 00 ← SHIFT 48 ∨ 00 CTRL 50 00 ∨ CAPS LOCK 02 31 03 32 04 33 05 34 06 35 LEFT 1 2 3 4 5 RIGHT 69 00 07 36 08 37 09 38 0A 39 0B 30 1C 0D 6 7 8 9 0 P1 39 20 01 1B 43 00 3B 00 0E 08 ENTER SPACE CLEAR MENU HELP BKSP Scan Code ASCII Value (Hexadecimal) (Hexadecimal) 02 31 1 Printable Character or Logical Key Sequence Figure B-93. WS 1000 Unmodified Keyboard B-100 The Series 3000 Keyboard 4D 00 → FUNC 4B 00 ← CAPS 48 ∨ 00 CTRL 00 50 ∨ CAPS LOCK 1E 61 2E 63 12 65 22 67 17 69 a c e g i RIGHT 0C 2D 25 6B 32 6D 18 6F 10 71 1F 73 0F 09 k m o q s 16 75 11 77 15 79 53 00 TAB - uwy LAMP DEL Figure B-94. WS 1000 Left Unmodified Keyboard 4D 00 → ALT STATE 4B 00 ← SHIFT 48 ∨ 00 NUM LOCK 50 ∨ 00 CAPS LOCK 30 62 20 64 21 66 23 68 24 6A LEFT b d f h j 34 2E 26 6C 31 6E 19 70 13 72 14 74 1C 0D l n p r t . 2F 76 2D 78 2C 7A 52 00 0E 08 ENTER vxzINSBKSP Figure B-95. WS 1000 Right Unmodified Keyboard B-101 Series 3000 Application Programmer’s Reference Manual 4D 36 6 FUNC 4B 4 34 48 38 8 CTRL 50 32 2 CAPS LOCK 02 21 03 40 04 23 05 24 06 25 LEFT ! @ # $ % RIGHT 69 00 07 5E 08 26 09 2A 0A 28 0B 29 1C 0D ^ & * ( ) 39 20 01 1B 5C 00 54 00 0E 08 ENTER SPACE CLEAR MENU HELP BKSP Figure B-96. WS 1000 Shift Modified Keyboard B-102 The Series 3000 Keyboard 4D 36 6 FUNC 4B 34 4 CAPS LOCK 48 38 8 SHIFT 50 32 2 CAPS LOCK 1E 41 2E 43 12 45 22 47 17 49 A C E G I RIGHT 0C 5F 25 4B 32 4D 18 4F 10 51 1F 53 0F 00 K M O Q S _ 16 55 11 57 15 59 53 2E UWYLAMP. Figure B-97. WS 1000 Shift Left Modified Keyboard 4D 36 6 ALT 4B 4 34 48 38 8 NUM LOCK 50 32 2 CAPS LOCK 30 42 20 44 21 46 23 48 24 4A LEFT B D F H J 34 3E 26 4C 31 4E 19 50 13 52 14 54 1C 0D L N P R T > 2F 56 2D 58 2C 5A 52 30 0E 08 ENTER V X Z0BKSP Figure B-98. WS 1000 Shift Right Modified Keyboard B-103 Series 3000 Application Programmer’s Reference Manual 4F → 00 47 00 ← SHIFT 49 ∨ 00 38 ALT 51 00 64 ∨ NUM LOCK 3B 00 3C 00 3D 00 3E 00 3F 00 LEFT F1 F2 F3 F4 F5 RIGHT 69 00 40 00 41 00 42 00 43 00 44 00 0D 3D F6 F7 F8 F9 F10 01 1B 43 00 3B 00 = DARK CLEAR MENU HELP LIGHT Figure B-99. WS 1000 Function Modified Keyboard B-104 The Series 3000 Keyboard 4F → 00 47 00 ← NUM LOCK 49 ∨ 00 FUNC 51 00 ∨ NUM LOCK 28 27 33 2C 35 2F 1A 5B 1B 5D ‘ , / [ ] RIGHT 0C 2D 27 3B 29 60 0D 3D 2B 5C 44 00 0F 09 ; ‘ = \ F10 - 4E 2B 37 2A 15 79 53 00 TAB + * y LAMP DEL Figure B-100. WS 1000 Function Left Modified Keyboard 4F 00 → ALT 47 00 ← SHIFT 49 ∨ 00 NUM LOCK 51 00 ∨ NUM LOCK 30 62 20 64 21 66 3B 00 24 6A LEFT b d f HELP j 53 00 31 6E 19 70 13 72 52 00 0D 3D LAMP n p r INS DEL 4A 2D 35 2F 2C 7A 52 00 = - / z INS LIGHT Figure B-101. WS 1000 Function Right Modified Keyboard B-105 Series 3000 Application Programmer’s Reference Manual 4F 1 31 47 7 37 49 39 9 ALT 51 33 3 NUM LOCK 54 00 55 00 56 00 57 00 58 00 LEFT SH-F1 SH-F2 SH-F3 SH-F4 SH-F5 RIGHT 69 00 59 00 5A 00 5B 00 5C 00 5D 00 0D 2B SH-F6 SH-F7 SH-F8 SH-F9 SH-F10 01 1B 5C 00 54 00 + DARK CLEAR SH-F9 SH-F1 LIGHT Figure B-102. WS 1000 Shift-Function Modified Keyboard B-106 The Series 3000 Keyboard 4F 1 31 47 7 37 NUM LOCK 49 39 9 FUNC 51 33 3 NUM LOCK 28 22 33 3C 35 3F 1A 7B 1B 7D “ < ? { } RIGHT 0C 5F 27 3A 29 7E 0D 2B 2B 7C 5D 00 0F 00 : ~ + | SH-F10 _ 4E 2B 15 59 53 2E + Y LAMP . Figure B-103. WS 1000 Shift-Function Left Modified Keyboard 4F 1 31 ALT 47 7 37 49 39 9 NUM LOCK 51 33 3 NUM LOCK 30 42 20 44 21 46 54 00 24 4A LEFT B D F SH-F1 J 53 2E 31 4E 19 50 13 52 52 30 0D 2B LAMP N P R 0 . 4A 2D 35 3F 2C 5A 52 30 + _ ? Z 0 LIGHT Figure B-104. WS 1000 Shift-Function Right Modified Keyboard B-107 Series 3000 Application Programmer’s Reference Manual B-108 The Series 3000 Keyboard Figure B-105. 35-Key PDT 6100 Keyboard B-109 Series 3000 Application Programmer’s Reference Manual 26 91 27 93 40 39 13 61 55 42 [ ] ' = * 53 47 51 44 43 92 39 59 78 43 / , \ ; + 750077 00 72 00 80 00 1 27 57 32 8 55 9 56 10 57 58 00 4200 5 52 6 53 7 54 97 00 2900 2 49 3 50 4 51 28 13 148124511485246 16311001.eps Figure B-106. 35-Key Unmodified PDT 6100 Keyboard B-110 The Series 3000 Keyboard 30 65 48 66 46 67 32 68 18 69 33 70 34 71 35 72 23 73 36 74 377538 76 50 77 49 72 1 27 57 32 24 79 25 80 16 81 58 00 4200 19 82 31 83 20 84 97 00 2900 22 85 47 86 17 87 28 13 148458821894490 16311003.eps Figure B-107. 35-Key Alpha Key Modified PDT 6100 Keyboard B-111 Series 3000 Application Programmer’s Reference Manual 26 123 27 12540 34 13 43 55 00 [ ] "+ 53 63 51 60 43 124 39 58 78 43 ? < | : + 755277 54 72 56 80 50 1 27 57 32 8 38 9 42 10 40 58 00 & * ( 4200 5 36 6 37 7 94 97 00 $ % ^ 2900 2 33 3 64 4 35 28 13 ! @ # 14 8 1295 11 41 52 62 > ) _ 16311009.eps Figure B-108. 35-Key Shift Key Modified PDT 6100 Keyboard B-112 The Series 3000 Keyboard 30 1 48 2 46 3 32 4 18 5 33 6 34 7 35 8 23 9 36 10 371138 12 50 13 99 14 1 27 57 32 24 15 25 16 16 17 58 00 4200 19 18 31 19 20 20 97 00 2900 22 21 47 22 17 23 28 13 00 38 45 24 21 25 44 26 16311002.eps Figure B-109. 35-Key Control Key PDT Modified PDT 6100 Keyboard B-113 Series 3000 Application Programmer’s Reference Manual 82 00 41 96 13 61 101 '= 102 51 44 79 00 39 59 78 43 ,;+ 710073 00 81 00 1 27 57 9 65 00 66 00 67 00 58 00 4200 62 00 63 00 64 00 97 00 5600 59 00 60 00 61 00 28 13 83 00 101 68 00 102 16311008.eps Figure B-110. 35-Key Function Key Modified PDT 6100 Keyboard B-114 The Series 3000 Keyboard 30 00 4800 46 00 32 00 18 00 33 0034 00 35 00 23 00 36 00 370038 00 50 00 49 00 57 32 2400 25 00 16 00 58 00 4200 1900 3100 20 00 97 00 2900 2200 47 00 17 00 4500 21 00 44 00 16311006.eps Figure B-111. 35-Key Alt Key Modified PDT 6100 Keyboard B-115 Series 3000 Application Programmer’s Reference Manual 82 48 41 126 13 43 101 ~+ 102 51 60 79 49 39 58 78 43 < : + 715573 57 81 51 1 27 15 00 90 00 91 00 92 00 58 00 4200 87 00 88 00 89 00 97 00 5600 84 00 85 00 86 00 28 13 14 8 101 93 00 102 . 16311007.eps Figure B-112. 35-Key Shift + Func Modified PDT 6100 Keyboard B-116 The Series 3000 Keyboard 101 102 11900132 00 118 00 1 27 100 00 101 00 102 00 58 00 4200 97 00 98 00 99 00 97 00 5600 94 00 95 00 96 00 101 103 00 102 16311005.eps Figure B-113. 35-Key Ctrl + Func Modified PDT 6100 Keyboard B-117 Series 3000 Application Programmer’s Reference Manual 101 102 127 110 00 111 00 112 00 58 00 4200 107 00 108 00 109 00 97 00 5600 104 00 105 00 106 00 28 13 101 113 00 102 16311004.eps Figure B-114. 35-Key Alt + Func PDT 6100 Keyboard B-118 The Series 3000 Keyboard 77 00 75 00 97 00 14 8 FN BK SP 78 43 12 45 1 27 72 00 SEND - CLR 8 55 9 56 10 57 80 00 7 8 9 5 52 6 53 7 54 28 13 4 5 6 E N 2 49 3 50 4 51 T 1 2 3 E 51 44 11 48 52 46 R ' 0 . Figure B-115. PDT 6100 22-Key Keyboard 100 00 LAMP 102 00 LIGHTER 65 00 66 00 67 00 101 00 F7 F8 F9 DARKER 62 00 63 00 64 00 28 13 F4 F5 F6 E N 59 00 60 00 61 00 T F1 F2 F3 E 68 00 R F10 Figure B-116. PDT 6100 22-Key Function-Modified Keyboard B-119 Series 3000 Application Programmer’s Reference Manual B-120 Index Symbols Running BATCHER.EXE ...... 1-5 .MAP ...... 1-79 Batch RF Interface functions _RESTORDS ...... 6-3, 6-77, 6-82, 6-86 BRFDisable...... 6-6 _STORDS...... 6-3, 6-77, 6-82, 6-85 BRFEnable ...... 6-5 BRFGetStats ...... 6-8 A BRFLoadConfig ...... 6-7 Listing of...... 6-4 Alt key ...... B-6 Batch RF Interface Library ...... 6-4 ALT state ...... B-1 BATCHRF TSR ANSI Compatibility Driver ...... 2-4 Accessing ...... 1-8 ANSI3000.EXE ...... 2-4 Sample data record ...... 1-12 ANSI3000.SYS...... 2-4 BatchRF TSR Command set ...... 2-7 .INI file format...... 1-9 Limitations ...... 2-5 Beep, task completion...... 1-14 Loading methods ...... 2-4 BEGDATA ...... 1-79 Parameters...... 2-6 BIOS Library Functions (Listing) ...... 3-5 Presence detection ...... 2-7 BIOS.LIB ...... 3-5 Small screen handling ...... 2-5 BiosAutoRepeat...... 3-14 ANSI3000. See ANSI Compatibility Driver. BiosBeep ...... 3-15 AT commands ...... 7-8 BiosCheckBattery ...... 3-19 Descriptions ...... 7-10 BiosCheckCursor...... 3-20 IM3/4 modem ...... 7-11 BiosCheckKey ...... 3-21 IM5/IM5S modems ...... 7-18 BiosClick...... 3-24 IM6 modems...... 7-37 BiosClrKey ...... 3-26 IM7 modems...... 7-48 BiosClrScr...... 3-27 Result codes ...... 7-51 BiosDelay ...... 3-29 Sending ...... 7-7 BiosGetAbortStatus...... 3-35 BiosGetAlarm ...... 3-36 B BiosGetBackLightTime...... 3-37 backlight ...... B-2 BiosGetCharAttr ...... 3-39 Batch file menu manager (BATCHER.EXE)1- BiosGetContextBuf ...... 3-42 4 BiosGetCursorMode ...... 3-44 .INI File Format ...... 1-4 BiosGetCursorPos ...... 3-45 Operation and navigation...... 1-6 BiosGetCursorSize ...... 3-46 Index-1 Series 3000 Application Programmer’s Reference Manual BiosGetDate ...... 3-47 BiosSetCursorPos ...... 3-126 BiosGetDisplayPage ...... 3-48 BiosSetCursorSize ...... 3-127 BiosGetEMSConfig ...... 3-49 BiosSetDate ...... 3-128 BiosGetEquipList ...... 3-50 BiosSetDisplayPage ...... 3-129 BiosGetFont...... 3-51 BiosSetGlobalWrtProt...... 3-130 BiosGetGlobalWrtProt...... 3-52 BiosSetKeyboardState...... 3-131 BiosGetKeyboardState...... 3-54 BiosSetKybdTimeout ...... 3-132 BiosGetKybdTimeout ...... 3-55 BiosSetLogScrSize ...... 3-133 BiosGetLogPage ...... 3-56 BiosSetPhysicalPos ...... 3-136 BiosGetLogPageCnt...... 3-57 BiosSetTime ...... 3-138 BiosGetLogScrSize ...... 3-58 BiosSetUART ...... 3-140 BiosGetModemStatus ...... 3-59 BiosSetVideoMode ...... 3-142 BiosGetPhysicalPos ...... 3-60 BiosSetViewAngle...... 3-143 BiosGetPhysScrSize ...... 3-61 BiosSetVirScrSize ...... 3-144 BiosGetPowerSource ...... 3-62 BiosSetWakeReason ...... 3-146 BiosGetRamSize ...... 3-64 BiosShowCursor ...... 3-148 BiosGetTermType ...... 3-68 BiosTextRectToMem...... 3-151 BiosGetTime ...... 3-70 BiosWakeUpReason ...... 3-154 BiosGetVideoMode ...... 3-72 BiosWarmBoot...... 3-155 BiosGetViewAngle...... 3-73 BLDINIT.EXE...... 2-13 BiosGetVirScrSize ...... 3-74 Borland Turbo Debugger...... 1-72 BiosGetWrtProt ...... 3-75 BiosHideCursor ...... 3-76 C BiosMapLogPage ...... 3-81 C interface functions. See C Interface rou- BiosMemToTextRect ...... 3-82 tines. BiosPowerOff ...... 3-89, 3-90 C interface routines BiosPutCharAttr...... 3-92 BIOS ...... 3-5 BiosPutCharMove ...... 3-93 DR DOS ...... 4-3, 4-33 BiosPutCharStay ...... 3-94 Calculator Library...... 6-9 BiosPutStrMove ...... 3-95 calculate function ...... 6-11 BiosPutStrStay ...... 3-96 Categories of service, ROM BIOS ...... 3-5 BiosResetAlarm ...... 3-106 character translation ...... B-2 BiosResetUART ...... 3-108 characters ...... B-1 BiosScrollDown ...... 3-111 Comm Structures ...... 4-74 BiosScrollUp ...... 3-112 command ...... 2-8, 2-9, 2-10 BiosSelectFont...... 3-113 Communication Parameter structure. . 4-35 BiosSetAlarm ...... 3-119 Communications IOCTL commands . . 4-73 BiosSetBackLight ...... 3-121 Communications IOCTL structures. See IO- BiosSetBackLightTime...... 3-122 CTL structures, communications. BiosSetContextBuf ...... 3-124 Communications port, modem ...... 7-5 BiosSetCursorMode ...... 3-125 Compatibility...... B-1 Index-2 Index CONFIG.SYS...... 1-77, 2-3 DosOpen...... 4-25 configuration and download process . . 1-77 DosRead ...... 4-26 console position report ...... 2-8 DosReadLine ...... 4-27 console position report command ...... 2-8 DosSetDate...... 4-28 contrast ...... B-2 DosSetIntVector...... 4-29 control state...... B-1 DosSetTime ...... 4-30 cursor down ...... 2-8 DosWrite...... 4-31 cursor down command ...... 2-8 DosWriteLine...... 4-32 cursor forward ...... 2-8 DR DOS library (DOS.LIB) ...... 4-3 cursor forward command...... 2-8 DR DOS system calls ...... 4-3 cursor up ...... 2-8 DSKBCHK.COM ...... 1-15 cursor up command...... 2-8 DTR (Data Terminal Ready) ...... 1-17 Custom keyboard layout ...... 1-27 DTRON.COM ...... 1-17 D E Date structure ...... 4-34 EMS Interface...... 5-10 Device drivers...... 2-3, 2-12, 2-13 enable character wrap ...... 2-9 Device Name Translation Table...... 5-47 erase display ...... 2-9 device status report command...... 2-9 erase display command ...... 2-9 disable character wrap ...... 2-9 erase line...... 2-9 Disk B check ...... 1-15 erase line command ...... 2-9 Display...... B-2 ERR3000.SYS ...... 2-12 DONEBEEP.COM ...... 1-14 ERR3000.SYS source code ...... 2-12 DOS function library ...... 4-3 Error codes DOS.LIB...... 4-3 KBD3000 loading...... 6-81 DosAbsDiskRead ...... 4-5 Printer Interface Library functions 6-49 DosAbsDiskWrite ...... 4-6 UBASIC File Manager ...... 5-86 DosAllocMem...... 4-7 UBASIC Record Manager ...... 5-85 DosClose ...... 4-8 Error codes, Floating point calculation func- DosCreate ...... 4-9 tions...... 6-16 DosFreeMem...... 4-10 Error codes, IOTCL...... 4-42 DosGetCh ...... 4-11 Error Message driver, Symbol...... 2-12 DosGetCurDrv ...... 4-12 ETA3000.SYS ...... 2-13 DosGetDate> ...... 4-13 Installation ...... 2-14 DosGetIntVector...... 4-14 Operation ...... 2-13 DosGetTime ...... 4-15 DosIoCtrlDrvRdData...... 4-18 F DosIoCtrlGetInfo ...... 4-20 File Control Block (FCB)...... 5-43 DosIoCtrlRdData ...... 4-21 File manager, UBASIC ...... 5-3 DosIoCtrlSetInfo...... 4-22 File Manager,UBASIC ...... 5-84 DosIoCtrlWrData ...... 4-23 FLASHDSK.SYS ...... 2-19 Index-3 Series 3000 Application Programmer’s Reference Manual Floating point calculation functions Get/Set Scan State...... 4-47 Error codes ...... 6-16 Global prototypes, UBASIC Record Manager fppadd ...... 6-17 File Manager functions...... 5-84 fppconvert...... 6-18 Memory Manager functions . . . . . 5-83 fppdiv ...... 6-19 Graphics functions fppfloattostr ...... 6-20 SFArc...... 6-27 fppmath ...... 6-21 SFClearArea ...... 6-28 fppmul ...... 6-22 SFClearScreen ...... 6-29 FPPRES.EXE and FPPTSR.EXE . . . 6-15 SFDisplayFile ...... 6-30 fppstrtofloat ...... 6-24 SFDrawLine ...... 6-31 fppsub ...... 6-25 SFEllipse ...... 6-32 Listing of ...... 6-15 SFEndGraphics ...... 6-33 Sample program...... 6-16 SFGetImage ...... 6-34 Floating Point Calculation Library . . . . 6-15 SFGetPixel ...... 6-35 FLSHCTL.EXE ...... 2-20 SFGetPosition ...... 6-36 FLSHFMT.EXE ...... 2-20 SFImageSize...... 6-37 Font Builder ...... 1-18 SFInitGraphics ...... 6-38 Character window commands. . . . 1-21 SFMoveTo ...... 6-39 Font window commands ...... 1-20 SFPutCharText...... 6-40 General (all window) commands . 1-19 SFPutImage ...... 6-41 Procedure ...... 1-18 SFPutStrText ...... 6-42 Screen windows ...... 1-19 SFRectangle ...... 6-43 Syntax ...... 1-18 SFSetPixel ...... 6-44 Text window commands ...... 1-23 Graphics Library ...... 6-26 Font builder...... 1-19 font window ...... 1-19 H FONTBLD.EXE. See Font Builder. Half-Duplex ...... 5-57 Func key ...... B-6 Header and Trailer Flags ...... 5-63 Func state...... B-1 horizontal and vertical position ...... 2-9 horizontal and vertical position command2- G 9 general ...... B-1 Get Last Character Read Status . . 4-47, 4-53 I Get Next Decoder Name...... 4-53 Internal Modems Get Reader Type...... 4-53 Capabilities...... 7-5 Get/Set Character Reader...... 4-49 Internal modems ...... 7-5 Get/Set Decoder Parameters ...... 4-51 Communications port...... 7-5 Get/Set Input Mode ...... 4-46 S Registers ...... 7-53 Get/Set Reader Parameters ...... 4-49 Terminal/Cradle use ...... 7-6 Get/Set Scan Mode ...... 4-46 IOCTL ...... 4-44, 4-46, 4-74 Get/Set Scan Parameters ...... 4-50 Index-4 Index IOCTL Commands...... 4-44 Get/Set PDF Decoder Parameters 4-64 IOCTL Communications Commands/Struc- Get/Set PDF Separator Data Mode Pa- tures ...... 4-73 rameters ...... 4-67 IOCTL Control Structures4-49, 4-50, 4-51, 4- Get/Set PDF Template Data Mode Pa- 53 rameters ...... 4-68 IOCTL Error Codes ...... 4-42 Get/Set Reader Parameters ...... 4-49 IOCTL Structures ...... 4-46, 4-47, 4-53 Get/Set Redundancy ...... 4-54 IOCTL structures, communications Get/Set Return Format ...... 4-56 comparameters ...... 4-74 Get/Set Scan Parameters ...... 4-50 hdrtrlr ...... 4-82 Get/Set UPC Parameters ...... 4-55 linestatus ...... 4-77 Reset Soft Trigger ...... 4-53 modemstatus ...... 4-77 IOCTL structures, keyboard/scanning com- protocol ...... 4-78 mands ...... 4-46 protocolcnt ...... 4-78 IOCTL structures. keyboard/scanning qstat ...... 4-83 Get Decoder Count ...... 4-52 s1_status ...... 4-83 IOCTL strucutures, keyboard/scanning s1_timeout...... 4-84 Get/Set Scan Mode...... 4-46 s1_unsolicited ...... 4-84 IOTCL commands/structures...... 4-44 selectprotocol ...... 4-78 slp_parms ...... 4-80 K slp_stats ...... 4-82 KBD interface functions spect1_parms ...... 4-80 KBDLoadFile ...... 6-80 spect1_stats ...... 4-81 KBDRestore ...... 6-79 twoway_parms...... 4-79 KBD3000 Error codes ...... 6-81 IOCTL structures, keyboard/scanning KBD3000 interface functions . . . . .6-77, 6-78 Field descriptions...... 4-58 KBD3000 software programming interface1- Get Error Code ...... 4-53 26, 6-78 Get Last Character Read Status . . . 4-47 Keyboad ...... B-1 Get Next Decoder Name...... 4-53 Keyboard ...... 4-44, B-1, B-2, B-6 Get Reader Type...... 4-53 keyboard...... B-1 Get Soft Trigger ...... 4-47 35-key Alpha ...... 111 Get/Set All Decoder Parameters . . 4-56 35-key Alt ...... 115 Get/Set Character Reader...... 4-49 35-key Alt+Func ...... 118 Get/Set Checks...... 4-54 35-key Control ...... 113 Get/Set Decoder Parameters . . . . . 4-51 35-key Ctrl+Func...... 117 Get/Set Input Mode ...... 4-46 35-key Function ...... 114 Get/Set PDF Communications Parame- 35-key layouts ...... 109 ters ...... 4-65 35-key Shift...... 112 Get/Set PDF Contiguous Data Mode Pa- 35-key unmodified ...... 110 rameters...... 4-66 Keyboard Commands...... 4-44 Get/Set PDF Control ...... 4-58 Keyboard Commands and Structures . 4-44 Index-5 Series 3000 Application Programmer’s Reference Manual Keyboard definition files Get/Set Redundancy ...... 4-54 KBD3000 data files...... 1-27 Get/Set Return Format ...... 4-56 Resident files...... 1-27 Get/Set Scan Parameters ...... 4-50 Keyboard definitions...... 6-78 Get/Set UPC Parameters ...... 4-55 Keyboard files, generating ...... 1-31 Reset Soft Trigger ...... 4-53 Keyboard IOCTL Commands/Structures 4- Keyboard/Scanning IOCTL Structures 4-46 44 Keyboards ...... B-1 Keyboard layout...... 1-27 Keyboard Mapper (KBDMAKE.EXE). . 1-27 L Keyboard mapping ...... 1-24, 1-27 LOADER.EXE. See NVM loader utility. Creating/Editing a keyboard layout1-28 Generating keyboard files...... 1-31 KBDMAKE.EXE program requirements M 1-27 Macro Processing Manager ...... 6-77 Starting the Keyboard Mapper . . . 1-27 Macro Processing Manager (MPM3000.EXE) Keyboard Mapping utility ...... 1-27 1-48, 6-45 Keyboard redefinition ...... 1-24 Mapping, keyboard ...... 1-24, 1-27 Keyboard Structures ...... 4-46 mdelete ...... 5-24 Keyboard/Scanning commands Memory Manager Functions, UBASIC 5-13 Get Decoder Count ...... 4-52 Memory manager, UBASIC...... 5-3, 5-11 Get Error Code ...... 4-53 Memory Transfer Analyzer (MTA) . . . 1-51 Get Last Character Read Status . . . 4-47 Sample session...... 1-52 Get Next Decoder Name...... 4-53 Memory Transfer Analyzer (MTA.EXE) Get Reader Type...... 4-53 Analyzing the data ...... 1-53 Get Soft Trigger ...... 4-47 Menu command reference ...... 1-59 Get/Set All Decoder Parameters . . 4-56 Recovering intact or corrupt Data 1-52 Get/Set Character Reader...... 4-49 Meta codes ...... B-2 Get/Set Checks...... 4-54 mfree ...... 5-26 Get/Set Decoder Parameters . . . . . 4-51 Modem communications port...... 7-5 Get/Set Input Mode ...... 4-46 Modem Control Structure ...... 5-55 Get/Set PDF Communications Parame- Modems ...... 5-57 ters ...... 4-65 MPM3000 ...... 6-45 Get/Set PDF Contiguous Data Mode Pa- MPM3000 interface function ...... 6-77 rameters...... 4-66 MPM3000.EXE. See Macro Processing Man- Get/Set PDF Control ...... 4-58 ager. Get/Set PDF Decoder Parameters. 4-64 MPMLoadFile ...... 6-48, 6-77 Get/Set PDF Separator Data Mode Pa- MSI 2-WAY communications driver . . . 7-8 rameters...... 4-67 Get/Set PDF Template Data Mode Pa- N rameters...... 4-68 Notational conventions ...... xv Get/Set Reader Parameters ...... 4-49 NVM ...... 1-77 Index-6 Index NVM image file transfer ...... 1-68 S NVM loader utility ...... 1-38 S Registers ...... 7-53 Command format, syntax, parameters1- Sample program 42 Floating pint calculation functions 6-16 Error messages ...... 1-44 Sample programs Modem priority ...... 1-42 ANSI3000 ...... 2-7 Operating modes ...... 1-38 save cursor position ...... 2-10 Program termination ...... 1-41 save cursor postition command ...... 2-10 scan code translation ...... B-2 O Scan codes ...... B-1 Operation ...... B-1 scan codes...... B-1 Scanner trigger...... 1-70 P Scanner trigger key ...... 2-18 Scanning commands. See Keyboard/Scan- packed ...... 4-33 ning commands. Packed structures...... 4-33 Screen Panning driver PAN3000.SYS ...... 2-16 Moving the screen...... 2-17 PAN3000.SYS source code ...... 2-17, 2-18 screen panning driver...... 2-16 PC Utilities ...... 1-14 SENDHEX.EXE ...... 1-68 PGM3000.SYS ...... 2-18 Sending AT commands ...... 7-7 Power On/Off ...... B-2 Separator Character structure ...... 5-50 Printer Interface Library (PS1Kx.LIB) . . 6-49 set graphics rendition ...... 2-10 Printer Interface Library functions set graphics rendition command . . . . . 2-10 Error codes ...... 6-49 shifted state ...... B-1 programming ...... B-1 Soft trigger keys...... 1-70 PS1Kx.LIB. See Printer Interface Library. Source code for ERR3000.SYS ...... 2-12 R PAN3000.SYS...... 2-17 RAM Disk Interface ...... 5-10 PGM3000.SYS ...... 2-18 RCVHEX.EXE ...... 1-66 Spectrum One ...... 1-8 Record manager, UBASIC ...... 5-3 Spectrum24 Flash Disk Redefinition, keyboard ...... 1-24 device driver ...... 2-19 Remote Debugging tool (TDREM.EXE) 1-72 utilities ...... 2-20 reset screen mode...... 2-10 states ...... B-1 reset screen mode command ...... 2-10 status report ...... 2-9 restore cursor position...... 2-10 STG3000.EXE ...... 1-70 Restore cursor position command. . . . . 2-10 Symbol DOS library functions ...... 4-33 Result codes, modem...... 7-51 Symbol Error Message driver (ERR3000.SYS) ROM BIOS services ...... 3-5 2-12 Symbol table converter tool (PDCON- VRT.EXE) ...... 1-65 Index-7 Series 3000 Application Programmer’s Reference Manual Symbol Technologies internal modems . 7-5 mdelete ...... 5-24 Symbol Utility Library (SYMUTILx.LIB)6-77 merase...... 5-25 mfree ...... 5-26 T minit ...... 5-27 minput ...... 5-28 Terminal file transfer utility (TFT3000.EXE) minsert ...... 5-29 1-74 mopen ...... 5-30 Terminal Initialization Tool ...... 2-13 mprint ...... 5-31 transient...... 2-3 msearch...... 5-32 Transient device drivers ...... 2-3 mterminate...... 5-34 translation ...... B-1 UrmClose ...... 5-41 translation restrictions...... B-6 UrmOpen ...... 5-35 translation table ...... B-2 UrmPresent ...... 5-42 Trigger key, scanner ...... 2-18 UrmReadField ...... 5-37 Trigger, scanner ...... 1-70 UrmWriteField ...... 5-39 TSR Registration utility...... 6-82 UBASIC Record Manager global prototypes TSR registration utility (TSRREG.EXE) 1-76 5-83 TSRLoaded ...... 6-3, 6-77, 6-83 UBASIC Record Manager structures . . 5-43 TSRREG.EXE...... 6-82 BIOS Parameter Block (BPBT) . . . . 5-72 TSRRegistrationCheck...... 6-3, 6-77, 6-84 Block Transverse Return Parameter Block (TraverseT) ...... 5-78 U Device Name Translation Table (XlatP- UBASI Record Manager structures trT)...... 5-47 Segment Table Entry (SEG_INFOT)5-74 DOS File Directory (DOS_FDT) . . 5-72 UBASIC memory manager...... 5-11 FAT Entries (FAT_ENTRYT). . . . . 5-73 UBASIC memory manager functions . . 5-13 File Control Block (FCBT) ...... 5-43 UBASIC Record Manager ...... 5-3 File Directory Block (FDBT)...... 5-70 Functions ...... 5-4 File Information Block (FIBT) . . . . 5-69 Language interfaces...... 5-5 File Manager First Data Segment (FIRST- Loading ...... 5-8 SEGT) ...... 5-76 UBASIC Record Manager error codes . 5-85 File Manager Work Buffer (WORK- UBASIC Record Manager functions BUFT) ...... 5-78 blk_alloc...... 5-14 FMGR Data Block Link (BLKLINKT) 5- blk_delete ...... 5-15 69 blk_free ...... 5-16 Free Block (FREET) ...... 5-74 blk_insert...... 5-17 Header of Cluster Variant Files (CV- blk_search ...... 5-18 HEADERT)...... 5-77 blk_travers...... 5-19 MCREATE Parameter Blocks . . . . 5-82 mclose ...... 5-20 Modem Control Structure (MODEM- mcreate ...... 5-21 CTLT) ...... 5-55 mcrunch...... 5-23 RAM Disk Driver Parameter Block Index-8 Index (RD_PARMT) ...... 5-75 Separator Character Structure (SEP- CHART)...... 5-50 URM Pointer Structure ...... 5-61 UBASIC Variables ...... 5-12 ubasic.fmg ...... 5-9 URM structures. See UBASIC Record Manag- er structures. URM. See UBASIC Record Manager. User Configuration Tool ...... 1-77 Interfaces supported ...... 1-77 Syntax ...... 1-77 USRCGFG command line switches1-78 USRCFG.EXE. See User Cobfiguration Tool. Index-9 Series 3000 Application Programmer’s Reference Manual Index-10 Tell Us What You Think... We’d like to know what you think about this Manual. Please take a moment to fill out this questionaire and fax this form to: (516) 738-3318, or mail to: Symbol Technologies, Inc. One Symbol Plaza M/S B-4 Holtsville, NY 11742-1300 Attn: Technical Publications Manager IMPORTANT: If you need product support, please call the appropriate customer support number provided. Unfortunately, we cannot provide customer support at the fax number above. User’s Manual Title: (please include revision level) How familiar were you with this product before using this manual? Very familiar Slightly familiar Not at all familiar Did this manual meet your needs? If not, please explain. What topics need to be added to the index?, if applicable What topics do you feel need to be better discussed? Please be specific. What can we do to further improve our manuals? Thank you for your input—We value your comments. Series 3000 Application Porgrammer’s Reference Manual