Commands
Introduction
The CMDS directory of Disk 1 in the OS-9 Level 2 Development System contains several commands to help in system operations. These commands and their functions are:
Command Function
BINEX
Convers a binary file into an S-Record file
DUMP
Displays the physical data contents of a file or device in both ASCII and hexadecimal form
EXBIN
Converts an S-Record file into its binary form
LOGIN
Provides login security on timesharing systems
MODPATCH
Modifies modules residing in memory
MONTYPE
Sets a system for the specified type of monitor
PARK
Moves the heads of a hard disk in preparation for moving the drive unit
SAVE
Creates a file and writes a copy of the specified memory module(s) into the file
SLEEP
Suspends a process for a specified time
TSMON
Supervises idle terminals and initiates login
TEE
Copies standard input to multiple devices
VERIFY
Checks module header parity and CRC values
BINEX
Syntax:
binex filename1 filename2
Function:
Converts a binary file into an S-Record file.
Parameters:
filename1
The name of the file to convert
filename2
The name of the file in which to store the converted code
Notes:
- Binex converts the specified OS-9 binary file (filename1) to an S-Record file and gives the new file the name specified by filename2. If filename1 is a non-binary load module file, OS-9 prints a warning message and asks you if binex should proceed anyway. Press Y to continue with the conversion. Pressing any other key causes binex to terminate.
-
When you run binex, the program asks you for a program name and a starting load address. It stores this information in a header record. Although OS-9 is position-independent and does not require absolute addressing, S-Record files do. The following example illustrates a binex command, its prompts, and possibly user input.
binex /d0/cmds/scanner scanner.s1 [ENTER] Enter starting address for file: $100 [ENTER] Enter name for header record: scanner [ENTER]
-
To download the scanner.s1 file to a device (such as a PROM programmer) using serial port /T1, type:
list scanner.s1 >/t1 [ENTER]
-
An S-Record is a type of text file that contains records representing binary data in hexadecimal character form. Most commercial PROM programmers, emulators, logic analyzers, and similar RS-232 devices can directly accept this Motorola standard format. You can also use S-Record files to transmit data over data links that can only handle character-type data or to convert OS-9 assembler- or compiler-generated programs to load on non-OS-9 systems.
Example:
To convert a binary file named Zap to an S-Record file named Zap.sr, type:
binex /d0/cmds/zap /d1/sr/zap.sr
DUMP
Syntax:
dump [name]
Function:
Displays the physical contents of the specified file or device in both ASCII and hexadecimal form.
Parameters:
name
Either a file pathlist or a device name
Notes:
- If you do not specify a file or device, dump displays the standard input path (the keyboard). Dump writes output to the standard output path (the video display).
- Use dump to examine the contents of non-text files.
- The dump display adjusts to the type of screen you are using. In 32- and 40-column screens, dump displays eight bytes per line. In 80-column screens, dump displays 16 bytes per line.
- Dump displays data in both hexadecimal and ASCII character format. If data bytes have non-displayable values, dump displays them as periods (.).
- The addresses displayed by dump are relative to the beginning of the file. Because memory modules are position-independent and are stored in files exactly as they exist in memory, the addresses shown on the dump correspond to the relative load addresses of memory-module files.
Examples:
To display keyboard input in hex on the screen, type the following command. Press [CTRL][BREAK] to return to the shell.
dump [ENTER]
Then, to display the contents of the diskette in Drive /D1, type:
dump @/d1 [ENTER]
The @ symbol causes OS-9 to treat the entire disk as a file.
Sample output, 32 columns:
dump SYS/password >/p [ENTER]
0 1 2 3 4 5 6 7 0 2 4 6
ADDR 8 9 A B C D E F 8 A C E
==== +-+-+-+-+-+-+-+- + + + +
0000 2C2C302C3132382C ,,0,128,
0008 2F44302F434D4453 /D0/CMDS
0010 2C2D2C5348454C4C ,.,SHELL
0018 0D55534552312C2C .USER1,,
0020 312C3132382C3E2C 1,128,.,
0028 2E2C5348454C4C0D .,SHELL.
0030 55534552322C2C32 USER2,,2
0038 2C3132382C232C23 ,128,.,.
0 1 2 3 4 5 6 7 0 2 4 6
ADDR 8 9 A B C D E F 8 A C E
==== +-+-+-+-+-+-+-+- + + + +
0040 2C5348454C4C0D55 ,SHELL.U
0048 534552332C2C332C SER3,,3,
0050 3132382C232C2E2C 128,.,.,
0058 5348454C4C0D5553 SHELL.US
0060 4552342C2C342C31 ER4,,4,1
0068 32382C2E2C2E2C53 28,.,.,S
0070 48454C4C0D HELL.
The first column indicates the starting address. The next eight columns (00-EF) display data bytes in hexadecimal format. The columns (0-E) displays data bytes in ASCII format. The display shows non-ASCII as periods in the ASCII character display section.
Sample output, 80-columns
dump SYS/password >/p [ENTER] ADDR 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 2 4 6 9 A C E * * * ---- ---- ---- ---- ---- ---- ---- ---- ---------------- 0000 2C2C 302C 3132 382C 2F44 302F 434D 4453 ,,0,128,/D0/CMDS 0010 2C2D 2C53 4845 4C4C 0D55 5345 5231 2C2C ,.,SHELL.USER1,, 0020 312C 3132 382C 3E2C 2E2C 5348 454C 4C0D 1,128,.,.,SHELL. 0030 5553 4552 322C 2C32 2C31 3238 2C23 2C23 USER2,,2,128,.,. 0040 2C53 4845 4C4C 0D55 5345 5233 2C2C 332C ,SHELL.USER3,,3, 0050 3132 382C 232C 2E2C 5348 454C 4C0D 5553 128,.,.,SHELL.US 0060 4552 342C 2C34 2C31 3238 2C2E 2C2E 2C53 ER4,,4,128,.,.,S 0070 4845 4C4C 0D HELL.
EXBIN
Syntax:
exbin filename1 filename2
Function:
Converts an S-Record file into its binary form
Parameters:
filename1
The name of the file to convert
filename2
The name of the file in which to store the converted code
Notes:
- Exbin is the inverse operation of binex. It assumes the file specified by filename1 is an S-Record format text file and converts it to a pure binary form in the file specified by filename2. The load addresses of each data record must describe contiguous data in ascending order.
- Exbin does not generate or check for the proper OS-9 module headers, the header CRC check value, or the module CRC check value required to load the binary file. Use the ident or verify commands to check the validity of the modules.
Examples:
-
To convert an S-Record file named Program.s1 to a binary file named Program and store it in the commands file of the current diskette, type:
exbin program.s1 cmds/program [ENTER]
LOGIN
Syntax:
login
Function:
Provides login security on timesharing systems. Login automatically adjusts its output for 32- or 80-column displays.
Parameters:
None
Notes:
- The timesharing monitor, tsmon, automatically calls login. You can also use login after initial login to change a terminal's user.
- Login requests your name and password, which it checks against a validation file. If the information is correct, login sets up your system priority, id, and working directories according to information stored in the file. Then, login executes the initial program (usually shell) specified in the password file.
- The login process terminates if you cannot supply a correct user name and password after three attempts.
-
The validation file is /DD/SYS/password. The file contains one or more variable-length text records, one for each user name. Each record has the following fields (the file uses commas as delimiters):
User name. The name can be a maximum of 32 characters, including spaces. If the name field is empty, any name matches.
Password. The pasword can be a maximum of 32 characters, including spaces. If the password field is blank, the system does not require the record's owner to type a password.
User index. This is the user ID number. It can be in the range 0 to 65535 (o is the superuser or system manager). Both the file security system and the system-wide user ID use this number to identity all processes initiated by the user. The system manager should assign a unique ID to each potential user.
Priority. This is the initial process (CPU time) priority. It can be in the rage 1 to 255.
Execution Directory. This is a pathlist showing the name and location of the initial execution directory (usually /DD/CMDS).
Working Directory. This is a pathlist showing the name and location of the initial data directory (the specific user's directory). The initial data directory is usually the root directory.
Execution Program. This is the name of the initial program to execute (usually shell). Do not use shell command lines, such as dir or dcheck, as initial program names.
-
Here is the system default validation file:
,,0,128,/D0/CMDS,.,SHELL USER1,,1,128,.,.,SHELL USER2,,2,128,.,.,SHELL USER3,,3,128,.,.,SHELL USER4,,4,128,.,.,SHELL
In this sample, the useruser's record, the first entry, contains no name or password. The ID number is 0, the initial process priority is 128, the execution directory is /D0/CMDS, and the root directory is the initial data directory. The initial program to execute is shell. The second entry is the same except the user's name is the default USER1.
-
To use login, type:
login [ENTER]
Prompts ask for your name and (optionally) a password. If you answer correctly, the system completes your login. Login initializes the user number, working execution directory, the working data directory, and executes a specified program. It displays the date, time, and process number. Login adjusts its output format for 80- or 32-column displays.
-
To kill the shell that called login, use ex. For example:
ex login [ENTER]
-
Use the OS-9 text editor to edit Password and add users.
- Logging off the system terminates the program specified in the password file. For most programs (including shell) logging off involves typing an end-of-file character ([CTRL][BREAK]) as the first character on a line.
- If motd exists in the SYS directory, login displays its contents (after a successful login).
Examples:
The following is possible user input and the screen display during login.
[ENTER]
OS-9 Timesharing system
Level II RS VR. 02.00.01
87/04/10 08:35:44
User name?: superuser[ENTER]
Password: secret[ENTER]
Process #07 logged on 87/04/10 08:36:01
Welcome!
Login then displays a message of the day from the motd file.
MODPATCH
Syntax:
modpatch [options] filename [options]
Function:
modifies modules residing in memory. Modpatch reads a file and executes the commands in the file to change the contents of one or more modules.
Parameters:
filename
The name of a file containing instructions for modpatch.
options
One of the following options that change modpatch's function.
Options:
-s
Silent mode, does not display patchfile command lines as they are executed.
-w
Does not display warnings, if any
-c
Compares only, does not change the module
Notes:
- Before using modpatch, you must create a patchfile to supply the data to control modpatch's operation. This file contains single-letter commands and the appropriate module addresses. The commands are:
l modulename
Links to the module specified by modulename.
c offset origval newval
Changes the byte at the offset address specified by offset from the value specified by origval to the new value specified by newval. If the original value does not match origval, modpatch displays a message.
v
Verify the module--update the module's CRC. If you plan to save the patched module to a file that the system can load, you must use this command.
m
Mask IRQ's. Turns off interrupt requests (for patching service routines).
u
Unmask IRQ's. Turns on interrupt requests (for patching service routines).
- You can use the build command or any word processing program to create patchfiles.
- Module byte addresses begin at 0. Modpatch changes values pointed to by an offset address (offset from 0) rather than an absolute memory address.
- To view the contents of a memory module, use save and dump to copy the module to a file and display its contents. Also use save to copy the patched module to a disk file.
- Changing a memory module might not produce an immediate effect. You have to duplicate the initialization procedure that module. This means, if the module loads during bootup, you have to create a new boot file that includes the changed module, then reboot using the new boot file.
- To use the patched module in future system boots, use save to store the module in the MODULES directory of your system disk. You can then use os9gen to create a new system disk using the patched module. If you are using the patched module to replace another module, rename the original module and then give the patched module the original name.
- If you patch a module that is loaded during the system boot, you can use cobbler to make a new system boot that uses the patched module.
Examples:
The following example shows the commands, the screen prompts, and the entries you make to patch the standard 40-column term window description to be an 80-column screen rather than the standard 40-column screen:
OS9: build termpatch [ENTER]
? l term [ENTER]
? c 002c 28 50 [ENTER]
? c 0030 01 02 [ENTER]
? v [ENTER]
? [ENTER]
OS9: modpatch termpatch [ENTER]
To change the size, columns, and colors of device window W1, create the following procedure file and name it W180:
l w1
c 0030 01 02
c 002C 1b 50
c 002D 0b 18
If the W1 module is not already in memory, load it from the MODULES directory of your system disk. Then, before initializing W1, run modpatch:
modpatch w180 [ENTER]
Next, initialize W1:
iniz w1 [ENTER]
shell i=/w1& [ENTER]
Press [CLEAR] to display the new window with 80 columns, 24 lines, and a white background.
MONTYPE
Syntax:
montype type
Function:
Sets your system for the type of monitor you are using
Parameters:
type
A single letter indicating the monitor type:
c for composite monitors or color televisions
r for RGB monitors
m for monochrome monitors or black and white televisions
Notes:
- Different types of color monitors display colors different. For the best results, set your system to the type of monitor you are suing.
- If you are using a monochrome monitor or black and white television, you can obtain a sharper image by setting your monitor type to monochrome.
- Include the montype command in your system's Startup file to automatically boot in the proper monitor mode.
- If you do not use montype, the system defaults to c (composite monitor).
Example:
To set your system for an RGB monitor, type:
montype r [ENTER]
To add a montype command to your existing Startup file, first use build to create a new command. For example:
build temp [ENTER]
montype r [ENTER]
[ENTER]
Next, append the file to Startup. Type:
merge startup temp > startup.new [ENTER]
Delete the temp file:
del temp [ENTER]
To enable the system to use Startup.new when booting, rename the original Startup file:
rename Startup Startup.old
Then rename Startup.new:
rename Startup.new Startup
PARK
Syntax:
park drive
Function:
Moves the heads of a hard disk to the innermost tracks in preparation for moving the drive unit.
Parameters:
drive
The hard disk drive for which you want to park the heads
Notes:
- Jarring your hard disk can cause its recording heads to bump against the highly polished surface of the recording media, destroying stored data. Such jarring can easily happen when you move your hard disk drive.
- Park moves all of your disk's recording heads onto the innermost tracks where information is not stored, and where such inadvertent bumping cannot destroy data.
- Always use park before relocating your hard disk or anytime you think it might be bumped or jiggled.
- After running park, turn off the system. Wait at least 15 seconds before turning on the power again. When you do turn your system on, the hard disk is immediately ready for use.
- Your hard disk is a precision instrument, built to extremely close tolerances. Always handle it carefully, even after parking its heads.
Example:
To park the heads of your hard disk, type:
park /h0 [ENTER]
SAVE
Syntax:
save filename modname [...]
Function:
Creates a file and writes a copy of the specified memory module(s) into the file
Parameters:
filename
The name of the file you want to create
modname
Specifies one or more modules to include in the file
Notes:
- The module name(s) must exist in the module directory when saved. Save gives the new file all access permissions except public write.
- Save's default directory is the current data directory. Generally, you should save executable modules in the default execution directory.
- You can use save to create a file of the commands you use most often so that you can load all of these commands using only one filename.
Examples:
To save a module named wcount into a newly created file called Workcount in the /D0/CMDS directory, type:
save /d0/cmds/workcount wcount [ENTER]
The following command saves four modules (add, sub, mul, and div) into the new file called /D1/math_pack.
save /d1/math_pack add sub mul div [ENTER]
SLEEP
Syntax:
sleep tickcount
Function:
Puts a process to sleep for the specified number of clock ticks
Parameters:
tickcount
Can be any number in the range 1 to 65535
Notes:
- If you give sleep a value larger than 65535, OS-9 reduces the value by mod 65535. For example, 65536, and all the multiples of 65536, become 0. A tick count of 95000 becomes an actual tick count of 29464.
In other words, if you give sleep a value higher than 65535, it reduces tickcount by subtracting the closest multiple of 65536 that is lower than your value.
* Use sleep to generate time delays or to break up jobs requiring large amounts of CPU time. The duration of a tick is 16.66 milliseconds.
* A tick count of 1 causes the process to give up its current time slice. A tick count of 0 causes the process to sleep indefinitely. (A signal sent to the process awakens it.)
Examples:
The following command puts the process to sleep for 25 ticks (416.50 milliseconds):
sleep 25 [ENTER]
The following command sequence causes list to start running as a child process invoked from the shell, and as a background task. Sleep then puts the shell to sleep indefinitely. When list attempts to find the file Nothing, which does not exist, it terminates and sends a signal (the error status), which wakes up the shell.
list startup sys/motd nothing & sleep 0
A sample screen display follows:
&004
setime
If an error does not occur, the shell continues to sleep. Use [BREAK] to wake the shell. Any keys you pressed while the shell was asleep are then displayed.
TEE
Syntax:
tee pathlist or devname [...]
Function:
Copies standard input to multiple devices
Parameters:
pathlist
One or more paths for the input data to follow
devname
One or more devices to which the system directs the input data
Options:
Tee can send output to any number of devices specified by devname.
Notes:
Tee is a filter that copies all text lines from its standard input path to the specified output paths.
Examples:
The following command line uses a pipeline and tee to send the output listing of dir simultaneously to the terminal, the printer, and a disk file:
dir e ! tee /term /p /d0/dir.listing
Here, a pipeline takes the output of dir e and sends it to tee. Tee in turn sends the output to the terminal, the printer, and to a file called /D0/dir.listing.
In the following example, the pipeline and tee send the output of an assembler listing to a file (pgm.list) and to the printer:
asm pgm.src l ! tee pgm.list /p [ENTER]
The next example broadcasts a message to the terminal.
echo WARNING SYSTEM DOWN IN 10 MINUTES ! tee /t1 ENTER
TSMON
Syntax:
tsmon [devname]
Function:
Supervises idle terminals and initiates the login sequence for timesharing applications
Parameters:
devname
The device for which you want login and supervision capabilities
Notes:
- If you specify a devname, tsmon opens standard I/O paths for that device. When you enter a carriage return, tsmon automatically calls the login command. If the login fails because the user cannot supply a valid user name or password, control returns to tsmon. The login command and its password file must be present for tsmon to work correctly. (See the login command description.)
- Logging off the system: Most programs terminate when you enter an end-of-file marker ([CTRL][BREAK]) as the first character on a command line. Pressing [CTRL][BREAK] causes your terminal to log off the system and to return to tsmon. Tsmon runs the login sequence again when you press [ENTER].
Examples:
The following command line activates /t1:
tsmon /t1 & [ENTER]
The command must run concurrently in order to keep /term active.
VERIFY
Syntax:
verify [u]
verify u </d0/cmds/edit >/d0/cmds/newedit
The next command line checks the edit module. Because the command does not specify the u option, verify only displays a summary message.
verify
A possible screen display is:
Header parity is correct
CRC is correct
In the next command line, verify checks Myprogram2, an invalid module. Because the command does not specify the u option, verify does not copy the module to standard output, but displays a message.
verify
The screen displays:
Header parity is INCORRECT!
CRC is INCORRECT!
