Intermec Janus 2010, Janus 2020, Janus Application Simulator User Manual
User's Manual
P/N 062778-001
®
JANUS
Application Simulator
Intermec Corporation
6001 36th Avenue West
P.O. Box 4280
Everett, WA 98203-9280
U.S. technical and service support: 1-800-755-5505
U.S. media supplies ordering information: 1-800-227-9947
Canadian technical and service support: 1-800-688-7043
Canadian media supplies ordering information: 1-800-268-6936
Outside U.S. and Canada: Contact your local Intermec service supplier.
The information contained herein is proprietary and is provided solely for the purpose of
allowing customers to operate and/or service Intermec manufactured equipment and is not to
be released, reproduced, or used for any other purpose without written permission of Intermec.
Information and specifications in this manual are subject to change without notice.
1995 by Intermec Corporation
All Rights Reserved
The word Intermec, the Intermec logo, JANUS, IRL, Duratherm, Virtual Wedge, and CrossBar
are trademarks of Intermec Corporation.
Throughout this manual, trademarked names may be used. Rather than put a trademark ()
symbol in every occurrence of a trademarked name, we state that we are using the names only
in an editorial fashion, and to the benefit of the trademark owner, with no intention of
infringement.
Contributors
Author Karen Granger Ross
Editor Craig Thompson
Technical Illustrator George Wilson
Technical Reviewers Roy Chrisop
Roy Law
Yong-Qin Lu
Contents
Contents
Before You Begin xi
Warranty Information xi
Cautions xi
About This Manual xii
Other Intermec Manuals xiv
Getting Started
1
Introduction to the JANUS Application Simulator 1-3
Hardware and Software Requirements 1-4
Installing the JANUS Application Simulator 1-5
Learning About the JANUS Application Simulator 1-6
How the JANUS Application Simulator Works 1-6
If You Are Not Using JANUS PSK Library Functions 1-8
Integrating the Simulator Into Your Development Process 1-9
Using the Simulator With Other Products 1-9
JANUS Features That Are Simulated 1-10
Text Display 1-10
Bar Code Input 1-10
Power Management 1-12
Communications Input and Output 1-12
JANUS Features That Are Not Simulated 1-13
Character Height 1-13
Viewport 1-14
Contrast Level 1-14
Special JANUS Key Sequences 1-14
Speed and Performance 1-14
v
Running and Debugging an Application
2
3
Deciding Where to Start the Simulator TSR 2-3
Starting the Simulator TSR 2-3
Running and Debugging a JANUS Application 2-4
Understanding the Limitations of the Simulator TSR 2-5
Exiting the Simulator TSR 2-6
Learning About the INI File
How to Customize the Parameters 3-3
How the Parameters Are Organized in This Chapter 3-3
Overview of Parameters 3-5
portn_read_file 3-6
portn_write_file 3-8
rx_check_status_return 3-9
protocol_ext_status_return 3-9
cancel_rx_buff_return 3-10
cancel_tx_buff_return 3-10
UART_status 3-11
expanded_keyboard_status 3-12
kb_insert_string_status 3-13
kb_insert_string_capacity 3-14
flush_exp_keyboard_status 3-15
warmboot_status 3-16
power_status_line 3-17
power_status_battery 3-18
power_status_backup 3-18
power_status_batt_life 3-19
power_status_return 3-19
display_contrast_level 3-20
vi
display_size_mode 3-21
display_video_mode 3-22
display_scroll_mode 3-23
display_viewport_lock 3-24
display_x_pos 3-25
display_y_pos 3-26
display_backlight 3-27
display_char_height 3-28
appl_break_status 3-29
follow_cursor 3-29
control_key 3-30
keyclick 3-31
numeric_keypad_switching 3-32
numeric_keypad_status 3-33
label_symbology 3-34
sim_wand_key 3-35
clear_abort_callback_return 3-36
command_return 3-36
link_comm_return 3-37
serial_protocol_control_return 3-37
standby_wait_return 3-38
unlink_comm_return 3-38
Contents
Communications Standard Return Values 3-39
Reader Wedge Standard Return Values 3-40
vii
Customizing INI Files With the Editor
4
Why Customize INI Files? 4-3
Starting the Editor 4-5
Using Online Help 4-6
Creating a New INI File 4-7
Opening an Existing INI File 4-8
Setting Parameters 4-9
Setting Communications Parameters 4-10
Naming portn_read_file and portn_write_file 4-11
Specifying a Path for portn_read_file and portn_write_file 4-11
Setting Keyboard Parameters 4-12
Setting Power Management Parameters 4-13
Setting Display Parameters 4-14
Setting Keypad Parameters 4-15
Setting Reader Wedge Parameters 4-16
Saving Changes 4-17
Discarding Changes 4-20
Restoring the Default Values 4-20
Updating the Simulator TSR With the Current INI File 4-21
Setting Up the Printer 4-22
Printing INI Files 4-22
Exiting the Editor 4-23
viii
Troubleshooting
Contents
5
I
Running an Application Without the Simulator TSR 5-3
Simulating Bar Code Input With an Intermec Wedge 5-3
Error and Status Messages for the Simulator TSR 5-3
Error and Status Messages for the Editor 5-4
Index
ix
Before You Begin
This section introduces you to standard warranty provisions, cautions,
document formatting conventions, and sources of additional product
information.
Warranty Information
To receive a copy of the standard warranty provision for this product,
contact your local Intermec sales organization. In the U.S. call (800) 7555505, and in Canada call (800) 688-7043. Otherwise, refer to the Worldwide
Sales & Service list shipped with this manual for the address and telephone
number of your Intermec sales organization.
Cautions
The cautions in this manual use the following format.
Before You Begin
CAUTION
Caution
A caution alerts you to an operating procedure, practice, condition, or
statement that must be strictly observed to prevent equipment damage or
destruction, or corruption or loss of data.
Conseil
Une précaution vous avertit d’une procédure de fonctionnement, d’une
méthode, d’un état ou d’un rapport qui doit être strictement respecté pour
empêcher l’endommagement ou la destruction de l’équipement, ou l’altération
ou la perte de données.
xi
JANUS Application Simulator User’s Manual
g
g
g
g
g
About This Manual
This manual describes how to install, customize, and use the JANUS
Application Simulator. You should see the online README file for
important information that was not available when this manual was
printed.
Use this manual in conjunction with the JANUS PSK Reference Manual,
which describes the PSK library functions and JANUS-specific system
interrupts that the JANUS Application Simulator captures and simulates.
Intended Audience
This manual is intended for experienced PC programmers who already
understand return values, know how to program in their chosen language,
and know how to use their application development and debugging
software. They have already read the JANUS PSK Reference Manual so they
understand how to create programs for the JANUS.
How This Manual Is Organized
The JANUS Application Simulator User's Manual is divided into five chapters:
xii
Chapter What you'll find
1
2
3
4
5
Gettin
Started
Introduces the JANUS Application Simulator and explains how to
install the software. Also describes which JANUS features the
Simulator can make your development PC mimic.
Runnin
Explains how to start and exit the Simulator TSR, and gives hints
for debugging a JANUS application.
Learnin
Lists the parameters in the initialization file.
Customizin
Describes how to use the Editor to customize the parameters in the
initialization file.
Troubleshootin
Describes how to recover if you run a JANUS application on your
PC without first starting the Simulator TSR. Also lists and describes
the status and error messages you may see.
and Debugging an Application
About the INI File
INI Files With the Editor
Before You Begin
Terms and Conventions
In this manual, the JANUS 2010 and JANUS 2020 are referred to as “the
JANUS” or “the reader.” Also, the Intermec-specific library functions
described in the JANUS PSK Reference Manual are referred to as “PSK
functions.”
This manual uses the following conventions to emphasize keyboard input,
screen messages, and command syntax.
Keyboard Input
Keystrokes are emphasized in bold. For example, “press Enter” means you
press the key labeled “Enter” on your keyboard.
If you must press more than one key at the same time, the keys are
connected by a dash in the text. For example, press Ctrl-Alt-Del to perform
a warm boot on a PC. When the keys are connected by a dash, it is
important that you press and hold the keys in the order they are listed in the
text.
Commands
Command syntax is shown in the text as you should type it. For example, to
see a listing of directories on the PC, type this command and press Enter:
dir
If a command line includes keywords in italics, the italics indicates that you
must enter a real value in place of the keyword. For example, this command
directs you to type the janussim command, specify the name of the INI file,
and press the Enter key:
janussim
filename
.ini Enter
xiii
JANUS Application Simulator User’s Manual
Other Intermec Manuals
You may need to refer to the JANUS manuals listed below while using the
JANUS Application Simulator. To order manuals, contact your local
Intermec representative or distributor.
Manual
JANUS Programmer's Software Kit Reference Manual
JANUS 2010 Hand-Held Data Collection Computer User's Manual
JANUS 2020 Hand-Held Data Collection Computer User's Manual
Also, you should see the online README file provided with the software.
This README file contains important information that was not available
when this manual was printed, such as operating guidelines or software
development packages that are compatible with the JANUS Application
Simulator.
Intermec
Part No.
062133
058426
059951
xiv
1
Getting Started
Getting Started
This chapter introduces the JANUS Application Simulator, explains how to install
the software, and describes how to make your PC mimic a JANUS reader.
Introduction to the JANUS Application Simulator
Applications created for JANUS readers may contain JANUS PSK library
functions and JANUS-specific system interrupts that—when run on a PC
instead of a reader—cause a PC to lock up.
With the JANUS Application Simulator, however, you can run JANUS
applications on a PC. The Simulator captures those functions and interrupts
before they can disrupt the PC. The Simulator then uses those functions and
interrupts to make the PC mimic a JANUS reader, allowing you to run and
debug any JANUS application on your PC.
The JANUS Application Simulator operates as shown in this illustration.
Briefly, while a JANUS
application is processing on
a PC, it may issue a JANUSspecific system interrupt.
INI FILE
1
The Simulator TSR captures
the interrupt, uses values
from the INI file to
assemble a response, and
then sends the response to
the JANUS application.
The JANUS application
acccepts the response and
continues processing.
For a detailed technical
description, see “How the
JANUS Application
Simulator Works” later in
this chapter.
Janus
Application
Processing
S
i
m
u
l
a
t
R
S
T
r
o
5700U-002
1-3
JANUS Application Simulator User’s Manual
With the JANUS Application Simulator, you can debug the logic and syntax
of a JANUS application, but not the user interface or performance:
• The Simulator helps you debug logic and coding errors by allowing you
to use development tools and debuggers common in the software
industry. For example, if you are using Microsoft Visual C++ to create
JANUS applications, you can use Microsoft Codeview for DOS to test
the applications. The Simulator runs in the background, transparent to
your development software.
• The Simulator does not help you test the user interface or performance of
the application. You can test those characteristics of the application far
better on a JANUS reader than on any simulation program. You should
always test your application by running it on a JANUS reader after you
have finished debugging the logic.
Because JANUS applications are DOS applications, you must use a DOSapplication debugger, not a Windows-application debugger. For example,
you can use Codeview for DOS, but not Codeview for Windows.
Use the JANUS Application Simulator and this manual in conjunction with
the programming software and documentation provided with your reader.
Hardware and Software Requirements
To run the JANUS Application Simulator, you need a PC with this
hardware:
• Intel 386 or 486 CPU
• 3.5 inch floppy disk drive
• 1.2 MB available on the hard drive
• VGA monitor
• Mouse or other pointing device
You must have already installed this software on your PC:
• MS-DOS 5.0 or higher
• MS-Windows 3.0 or higher
• Application development software, such as Microsoft Visual C++ 1.5
Professional Edition
1-4
Getting Started
Note: Because JANUS applications are DOS applications, you must use DOSapplication debugging software, such as Codeview for DOS. You cannot use
Windows-application debugging software, such as Codeview for Windows.
Installing the JANUS Application Simulator
The Simulator includes a Windows-based installation program to help you
install the software. During the installation, you choose the directory in
which to install the software.
To start the installation
1. Insert the JANUS Application Simulator disk into your floppy drive.
2. Start Windows.
3. From the Program Manager File menu, choose Run.
4. Start the installation with either of these commands:
• If the disk is in Drive A, type this command: a:setup
1
• If the disk is in Drive B, type this command: b:setup
5. Choose the OK button.
6. Follow the instructions displayed by the installation program.
The installation program
creates an Intermec group
on your Windows desktop.
The group contains the icon
for the Editor, the Editor's
help files, and the
README file.
Read the README file before you use the Simulator. The README file
may contain important information that was not available when this manual
was printed, such as operating guidelines or the names of software
development packages that are compatible with the Simulator.
For help using the Editor and its online help, see Chapter 4, “Customizing
INI Files With the Editor.”
1-5
JANUS Application Simulator User’s Manual
Learning About the JANUS Application Simulator
To learn more about the JANUS Application Simulator, read these sections:
• How the JANUS Application Simulator Works
• If You Are Not Using the JANUS PSK
• Using the Simulator During Development
• Using the Simulator With Other Products
• JANUS Features That Are Simulated
• JANUS Features That Are Not Simulated
How the JANUS Application Simulator Works
The JANUS Application Simulator consists of three parts:
Simulator TSR The Simulator terminate and stay resident (TSR) program
runs in the background on your PC. The Simulator TSR captures JANUSspecific system interrupts and makes your PC mimic a JANUS reader. For
instructions, see Chapter 2.
1-6
INI File The initialization (INI) file specifies how the Simulator TSR
simulates JANUS features such as bar code input and battery status.
JANUSSIM.INI is the default INI file. For a description of the parameters in
the file, see Chapter 3.
Editor The Editor is a Windows-based tool for setting the parameters
stored in the JANUSSIM.INI file. For instructions, see Chapter 4.
The Simulator TSR uses the parameters in the INI file as out parameters and
return values for any JANUS PSK library functions and JANUS-specific
system interrupts that a JANUS application contains.
For example, consider the JANUS battery. The status of the battery is very
important because it may be the reader’s only power source. JANUS
applications may check the battery’s status to make sure that sufficient
power is available for the application. There is no battery to check on the
PC. Therefore, the Simulator TSR must simulate the JANUS battery.
The following illustration shows how the Simulator TSR simulates a JANUS
battery when a JANUS application issues the im_power_status function.
Getting Started
1
INI File
1
JANUS Application
/*Check the status of
/* the power supply.
status = im_power_status
(&ac_line, &battery,
&backup, &fuel);
printf ("Status: %4X\n",
status);
4
2
Simulator TSR
Parameter Value
power_status_line 0
power_staus_battery 0
power_status_backup 0
power_status_batt_life 100
power_status_return 0800H
3
5700U-001
➊ When you start the Simulator TSR, it reads the parameters from the INI
file, parses the parameter names, and saves the values into variables in
memory.
➋ The JANUS application executes on the PC. To check the status of the
power supply, the JANUS application issues the im_power_status
function, which causes the INT 5EH interrupt to be sent to the Simulator
TSR.
➌ The Simulator TSR uses the variables related to the interrupt and returns
their values in the appropriate parameters.
➍ The Simulator TSR passes the values to the application. The application
accepts the information as the status and return values of the
im_power_status function call. The application continues executing.
1-7
JANUS Application Simulator User’s Manual
If You Are Not Using JANUS PSK Library Functions
If you are programming with JANUS-specific system interrupts instead of
JANUS PSK library functions, you can use the JANUS Application
Simulator and this manual. Simply ignore all mention of the PSK functions.
The Simulator TSR services all the JANUS-specific system interrupts listed
in the PSK reference manual. Some interrupts, such as INT 7CH, do not use
the values stored in the INI parameters. This table lists the interrupts that
do use the values stored in INI parameters:
Interrupt Related INI Parameters
INT 14H portn_read_file
portn_write_file
rx_check_status_return
protocol_ext_status_return
INT 16H expanded_keyboard_status
kb_insert_string_status
kb_insert_string_capacity
INT 5EH power_status_line
power_status_battery
power_status_backup
INT 79H display_contrast_level
display_size_mode
display_video_mode
display_scroll_mode
display_viewport_lock
INT 7EH appl_break_status
follow_cursor
control_key
INT 7DH label_symbology
clear_abort_callback_return
command_return
link_comm_return
serial_protocol_control_return
cancel_rx_buff_return
cancel_tx_buff_return
UART_status
flush_exp_keyboard_status
warmboot_status
power_status_batt_life
power_status_return
display_x_pos
display_y_pos
display_backlight
display_char_height
keyclick
numberpad_switching
numberpad_status
standby_wait_return
unlink_comm_return
portn_read_file
portn_write_file
See Chapter 3 to learn more about INI parameters.
1-8
Getting Started
1
Integrating the Simulator Into Your Development
Process
The JANUS Application Simulator can be an integral part of your
development process. For example, if you use Visual C++ to develop
applications, you can follow these steps:
1. From MS-DOS, start the Simulator TSR with this command:
janussim
2. Start Windows.
3. Run the Visual C++ compiler. Create or edit a JANUS application.
4. Run and debug the JANUS application.
5. Repeat Steps 3 and 4 as necessary.
6. Shut down Windows and return to MS-DOS.
7. Stop the Simulator TSR with this command:
janussim -d
Using the Simulator With Other Products
You can use the JANUS Application Simulator with other products,
including application development software such as Microsoft Visual C++
1.5 Professional Edition.
You can install an Intermec Wedge on your PC to simulate bar code input.
For help configuring a wedge, see “Bar Code Input” later in this chapter.
The Simulator TSR should not interfere with the normal operation of other
software on your PC. Therefore, you can start the Simulator TSR in your
AUTOEXEC.BAT file and leave it running if you have sufficient RAM
available.
You can use the JANUS Application Simulator to run JANUS applications
that use the JANUS PSK library functions and JANUS-specific system
interrupts, as described in Chapter 3.
You cannot use the JANUS Application Simulator to run JANUS programs
such as the configuration application (IC.EXE) and the IRL Desktop
(IRLDESK.EXE) on your PC. Those programs use low-level interrupts that
the JANUS Application Simulator does not support.
1-9
JANUS Application Simulator User’s Manual
JANUS Features That Are Simulated
The Simulator TSR can reproduce these JANUS features:
• Text display
• Bar code input
• Power management
• Communications input and output
For more information, read the following sections.
Text Display
If the application calls the im_set_input_mode function to select the
programmer input mode, the Simulator TSR limits character echoing to the
lines and columns based on the display size you specified by calling the
im_set_display_mode function or by setting the display_size_mode
parameter in the INI file.
The Simulator TSR has no control of the application’s output; however, the
JANUS reader wraps output in some display modes. See your JANUS
documentation for details.
1-10
Note: All human factors and usability analysis of your JANUS applications should
be performed on a JANUS reader, not with the Simulator TSR.
Bar Code Input
You can simulate bar code input using either of these two methods:
• By pressing a special key sequence that lets you type “bar code” data.
• By configuring an Intermec Wedge and wanding actual bar code labels.
These methods are described in the following paragraphs.
To simulate bar code input with a keyboard
You can simulate bar code input by pressing the key sequence specified by
the sim_wand_key in the INI file. After you press the key sequence, the
Simulator TSR captures all keyboard input and presents it to the JANUS
application as if it were bar code input from a wand. The simulated bar
code input is terminated when you press Enter.
Getting Started
Note: You specify the symbology of the simulated bar code label with the
label_symbology parameter in the INI file.
By default, the key sequence is Ctrl–G. You can change the key sequence by
editing the sim_wand_key parameter. The key sequence consists of one or
more control keys (Ctrl, Alt, Shift) and a character key (A to Z). Here are
sample key sequences:
• Alt–L
• Alt–Shift–B
• Ctrl–Shift–C
• Ctrl–Alt–Shift–W
Note: The INI file displays a slash in the key sequence (Ctrl/G) instead of a hyphen.
By convention, this manual uses a hyphen to indicate that you must press multiple
keys simultaneously.
To simulate bar code input with an Intermec Wedge
You can also simulate bar code input by attaching an Intermec Wedge to
your PC. After you set the first preamble characters to match the
sim_wand_key value, you can use the wedge to enter bar code data into the
JANUS application. The bar code input is terminated when you scan Enter
or have a Return in the postamble.
1
See your wedge documentation for help setting the preamble. To decide
how to scan the sim_wand_key value as the data for the preamble, consider
this example:
Your sim_wand_key is Ctrl–G, so you must set the preamble to Ctrl–G.
Because the wedge is in Set Preamble mode, you cannot scan the BEL
character, even though it represents Ctrl–G in the full ASCII chart.
Instead, you must consult the PC/Workstation Keyboard Mapping table to
learn which characters to scan for Ctrl and G. You learn that you must scan
the SO character for Ctrl and the lowercase g character for G. (If you scan
SO and uppercase G, the preamble is set to Ctrl–Shift–G.)
1-11
JANUS Application Simulator User’s Manual
Power Management
The initialization file contains parameters that help simulate the power
management features of the JANUS reader. For example, the
power_status_line parameter specifies if the simulated JANUS is connected
to an AC power source.
If your JANUS application calls the im_power_status function or the INT
5EH interrupt, the Simulator TSR passes the preset AC power status to the
JANUS application.
Communications Input and Output
The Simulator TSR can simulate input and output data through the JANUS
communications ports, COM1 to COM4.
To simulate data input to the application
1. Type sample data in an ASCII file. The format of the data in the file
depends on the function you use to receive the data. For example:
im_receive_byte The im_receive_byte function reads one byte of data
from the file each time it is called. Carriage return (CR) or line feed (LF)
characters are returned as data to the JANUS application.
1-12
im_receive_buffer The im_receive_buffer function reads a buffer of data
each time it is called. Therefore, your RCV file should contain a data
string terminated by a CR/LF character. The CR/LF indicates the end of
the buffer. If there is no CR/LF, the function reads up to 256 bytes of
data.
With each subsequent call, either function would continue reading data
where it left off until it reached an EOF. If the function was called after
reaching an EOF, it would start reading data at the top of the file again.
2. Specify the ASCII file’s path and filename in the portn_read_file
parameter in the INI file, where n is the COM port from which the
application expects to read the data.
3. Load the TSR and run the application.
4. Test if the application read the data correctly from the ASCII file.
Getting Started
To simulate data output from the application
1. Specify the ASCII file’s path and filename in the portn_write_file
parameter in the INI file, where n is the COM port to which the
application expects to write the data.
2. Load the TSR and run the application.
3. The application creates the ASCII file and writes data to it.
4. Test if the application wrote the data correctly to the ASCII file.
Note: You must test the application on a JANUS reader to make sure that the
application is handling the input and output communications protocols correctly.
1
JANUS Features That Are Not Simulated
The Simulator TSR cannot reproduce these JANUS features:
• Character height
• Viewport
• Contrast level
• Special JANUS key sequences
• Speed and performance
For more information, read the following sections.
Character Height
The Simulator TSR does not simulate the character height set for the JANUS
reader. The characters appear in the standard font and size for the PC.
You can, however, store a character height value in the display_char_height
parameter in the INI file. If your JANUS application calls the
im_get_display_mode function or the INT 79H interrupt, the Simulator
passes the preset character height to the JANUS application.
1-13
JANUS Application Simulator User’s Manual
Viewport
The JANUS viewport is not simulated in this release, but out parameters
and return values for related function calls and interrupts are supported:
• You can specify if the viewport is locked (unmoving) with the
display_viewport_lock parameter in the INI file.
• You can specify the horizontal and vertical offset for the viewport with
the display_x_pos and display_y_pos parameters in the INI file.
• You can specify if the viewport will follow the cursor with the
follow_cursor parameter in the INI file.
Contrast Level
The Simulator TSR does not simulate the level of contrast set for the reader.
The simulated display appears at the contrast level set for your PC.
You can, however, store a contrast value in the display_contrast_level
parameter in the INI file. If your JANUS application calls the
im_get_contrast function or the INT 79H interrupt, the Simulator TSR
passes the preset contrast level to the JANUS application.
1-14
Special JANUS Key Sequences
The JANUS keypad contains fewer keys than a standard PC-AT keyboard,
but you can produce all 102 PC-AT keys with the reader by pressing a
variety of key combinations. The special key sequences are listed in your
JANUS user’s manual.
When using the Simulator TSR to run JANUS applications on a PC, you do
not use special key sequences because your PC keyboard contains all 102
PC-AT keys. For example, to enter the F11 key on a reader, press
During a simulation, simply press the F11 key on the PC keyboard.
Note: The Simulator does not let you test how easily users can press the key
sequences that your JANUS application expects. You should test the application’s
user interface by running it on a reader after you finish debugging the logic.
E E L.
Speed and Performance
The Simulator TSR does not simulate the speed or performance of a JANUS
reader. Your JANUS applications runs as fast as your PC can execute them.
2
Running and Debugging an Application
Loading...