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 </term

    WELCOME TO COLOR COMPUTER OS-9
    -004
    ERROR #216

    OS9:

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] <filename1 [>filename2]
Function:	Checks to see if the module header parity and CRC value of one or more modules on a file are correct
Parameters:
filename1	The name of the module to be checked
filename2	The name for the verified module created with the u option
Options:
u	Copies the module(s) to a new module with the header parity and CRC values replaced with the computed values.

Notes:

• Verify reads module(s) from the standard input and sends output to the standard output. It sends messages to the standard error path.
• Verify is dependent on the input redirection command. If you fail to use the redirection symbol, verify causes the system to lock. To gain control of the system, press [BREAK]. You must always redirect the input path. If you use the u option, you must also redirect the output to the new file you want to create.
• Using the u (update) option causes verify to copy the module(s) to the standard output path with the module's header parity and CRC values replaced with the new computed values. Verify, with the update option, does not set the execute flag in the file attributes. Use attr to do this.
• If you do not use the u option, verify does not copy the module to standard output. Verify displays a message indicating whether the module's header parity and CRC match those computed by verify.

Examples:

Because the following command line uses the u option, verify copies the edit module to a new module, Newedit, with the header parity and CRC values replaced with the computed values.

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

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

The screen displays:

    Header parity is INCORRECT!
    CRC is INCORRECT!