Important TSX-32 concepts and practices.

This discussion of concepts will take you "under the hood" of TSX-32 and help you to learn how and why things happen in the way that they do. This discussion is very technical and specific and geared towards someone who wants to know how it works and fits together. This is not a "how-to" discussion, it is an intuitive one for teaching purposes. The User's Manual describes the specifics of what is discussed here in more of step by step fashion.

The discussion is broken into phases. The first phase discusses the important components and concepts . The second phase discusses systen generation and booting . The next phase discusses initialization and user logon .

At the end is a short quiz which will test your TSX-32 smarts.

Key concepts and files

Key Files:

  • The \TSX32SYS\ directory
    The so called "system" directory, also referred to as "SY" (pronounced ess-y) contains all the files used by TSX-32 except the OS itself, which resides in the root of C:\. The name of this directory is selected during installation, the default name is TSX32SYS.

  • C:\TSX32.SYS
    THE OS, the file which contains the operating system. After loading into memory, the file is not referenced, i.e. it is copied into memory during bootstrap. The file is always stored in the root of C:\.

  • \TSX32SYS\*.REX files
    Loadable drivers; these are read in during system initialization with the HANLOAD command. They allow a given system to pick and choose certain options (like ZMODEM capabilities or TCP/IP networking) and certain devices (like SCSI tape drivers or ethernet).

  • \TSX32SYS\TSX32.GEN
    File containing system generation info, devices, tuning parameters. Formatted in ASCII, it can be changed either with an editor or the TSGEN program. All device definition occurs through this file.

  • \TSX32SYS\TSKMON.EXP
    Command interpreter, also called 'KMON' (pronounced kay-mon with accent on first syllable), other OS's use the term 'shell' to describe this functionality.

    Accepts commands and performs system services to accomplish those commands. KMON has many 'built in' (or internal) commands like SHOW SYS or SET NODE. When KMON recognizes a command as internal it performs the necessary system services to do the operation, possibly displaying results. If the command is a program (like DIR) KMON uses the syfn_execute system service to 'launch' the program. The new program overwrites KMON. After its completion the OS automatically reloads KMON. Thus, KMON is not active for a job while another program (like DIR) is running.

    TSKMON is a pure user mode program which uses system services available to any program to do its job. Theoretically you could write your own command interpreter. It is registered with the OS as the default 'shell' program, which is how the OS knows to reload it in between program execution.

  • Commands like DIR,SEARCH,COPY,TYPE
    Many "commands" in TSX-32 are themselves programs written by the developers as utilities. DIR,SEARCH,COPY, and TYPE are a few examples of such commands. The program file \TSX32SYS\DIR.EXP is the directory command. These programs use ordinary system services to accomplish their tasks and display their output.

Key concepts:

  • Job (or Process)
    In TSX-32, a Job (or process) is the entity which performs useful work. A Job must be running a program of some sort must to do any useful work. That program may be KMON (the keyboard monitor) or a command (like DIR) or a user-written program.

    A program resides in virtual memory in an address space which starts at address 0 and goes to some maximum. The code, data, and stack all live in the address space and are presented with the illusion that only they live in the address space. One job cannot see or manipulate the address space of another job and a job cannot touch or change the code or data of the OS. This is all done through the magic of virtual memory and paging. Although each task is isolated, there are system services which allow cooperating processes to share memory areas, called "regions".

    The program communicates with the OS by the way of "system services" (also called an API in other OS's). All I/O, for instance, happens through system services; requests by the program for data to go out or in.

    A job may or may not have a "controlling terminal". If it does then the user types commands at the terminal which are then passed to KMON for processing. If there is not a controlling terminal the job is called a "detached job", discussed later.

  • Command procedures
    Command procedures are files which contain commands. DOS systems call them BAT files. Unix systems call them "shell scripts". When KMON reads a line from the user that line may be coming from the terminal or it may be coming from a command file; KMON doesn't know and can't tell.

    KMON calls the SYFN_GETLINE system service to read the next command, and the OS either gets the next line from the currently open command file or collects it from the terminal.

    When you type @filename at the prompt you are invoking a command procedure and the OS (not KMON) opens the file and begins returning the contents, a line at a time, to KMON. KMON does not itself open or process the command file. This is a subtlety which is not obvious. In practical terms it isn't an important distinction.

  • Executing programs
    To run a program, type its name or use the RUN command, both do the same thing. KMON, which processes the request to run the program, will call the syfn_execute system service to start the new program. The new program replaces KMON. Upon completion the OS reloads KMON.

  • Detached Jobs
    A job may or may not have one "controlling terminal" from which it can accept keystrokes or deliver character output. A job without a controlling terminal is called a "detached" job.

    Detached jobs are very important tools in TSX-32. TSX-32 starts life by running a detached job which performs many initialization functions. When a program has a controlling terminal it means that when KMON runs on behalf of that job it accepts commands from that terminal. Keystrokes are collected and the display is updated as typing occurs. When a job does not have a controlling terminal KMON must read its commands from a command procedure. Output may be written to a log file or it may be discarded.

    The KMON DETACH command is used to 'launch' detached jobs. When you launch a detached job you specify a command procedure to run. KMON uses the syfn_detach system service to tell the OS to create another copy of KMON and associate it with the specified command procedure. KMON reads and processes the commands from the command file. When it runs out of commands the detached job terminates.

    Another way to start a detached job is to specify a program to run, instead of a command file. In that case the OS launches the program, not KMON, and the detached job exists for as long as the program runs. This latter form is quite common in TSX-32.

    System Generation and Booting TSX-32.

    As shipped, TSX-32 cannot execute until it is told about the disk and other devices on the system. This is done in the TSX32.GEN file, discussed earlier.

    The TSGEN program is used to modify the OS to specify the devices which are defined in the system. The TSGEN program reads the ASCII file TSX32.GEN, interprets it, and uses the contents to modify the kernel file, TSX32.SYS. To use this program is to "gen" (pronounced jen) the system.

    The kernel, TSX32.SYS, contains a data area which is actually modified by the TSGEN program. When the system boots it does not consult the TSX32.GEN file, it already has the device and tuning information it needs in a form it can quickly process.

    Under DOS, the program RUNTSX loads the file C:\TSX32.SYS into memory, goes into 32 bit mode and transfers control to it.

    The OS initializes built-in device handlers and starts the very first job, which executes the command procedure sy:startup.cmd as a detached job. Thus, system initialization is broken into two phases: a phase which occurs internally to the OS and a phase which uses the same tools (KMON, detached jobs, command procedures) as any user of the system would use. As much as possible TSX-32 is designed to do as little as necessary internally. The ideal goal is to use the tools available to any developer to initialize the OS and its components.

    Functionally, the startup command procedure does the following work:

    1. Runs a program called MAKELOAD which locates any loadable handlers and creates a command procedure called sy:tsxload.cmd with a series of HANLOAD statements.

    2. Executes the TSXLOAD command procedure, which loads any loadable handlers via the execution of the HANLOAD commands. The best example of what happens in this step is the loading of networking software by loading SY:LHTCPIP.REX.

    3. Execute the command procedure SY:LSTARTUP.CMD, which contains any "local" processing which the user wants to perform during system startup.

    After system initialization is complete the OS is ready to run user jobs.

    Terminal Initialization and User Logon

    Once the system has initialized users are ready to use the system. Devices have been initialized, the network (if in use) is initialized and ready, the terminals are ready for use, and any local first time initializations have been done.

    At this point TSX-32 is ready for work, and what happens here is purely dependent on how the system is to be used. For instance, a shop with office folks who run WP and custom software will proceed differently than folks who are automating a warehouse.

    In the traditional timesharing model of computers, users would connect in, type a return, get a "Username:" or "Login:" prompt, type in a user name and password, and get a command prompt. They would then type in commands or run programs. In TSX-32 they would be interacting with the TSKMON program, or KMON.

    Resellers or developers of vertical applications would then develop a layer on top of that with custom programs and command procedures so that users would log in and automatically be placed in an application menu from which they had access to specialized programs, all layered on top of the basic TSX-32 OS. TSX-Online is such a layered and vertical application.

    So, the first question relating to customization is how to tailor system startup so that a specified program gets run when the users log in. To illustrate how this can be done we'll discuss how the system is shipped.

    The first place to look for custom start-is in the TSX32.GEN file. Without digressing, terminal devices are defined with a statement of the form

    DEVICE=TT/HANDDEF=SERIAL/CONTROLLER=A
    	UNIT=1/  ...options...
    
    Where "...options... " are a set of parameters for controlling the terminal. There are many options.

    Starting a job on a terminal

    After system initialization is complete, if nothing is done to customize the system, the terminals will do nothing until the CR key is pressed. At that point they will issue a startup message and KMON will be launched. The user will be presented with a command prompt.

    The first customization we can do is to have KMON automatically start when the line is initialized, instead of waiting on a CR. To do this, we specify the following option:

    DEVICE=TT/HANDDEF=SERIAL/CONTROLLER=A
    	UNIT=1/START
    

    This just means "start the line automatically".

    Running a command procedure on line startup

    In our discussion of command files recall we said that KMON reads and processes lines from the command files. The next thing that we can do to customize the system is to associate a "start up command procedure" with a terminal line. This is a command procedure which executes the first time a job is initialized for the line. This can be used to perform first time initialization for the line. The command procedure can run a program or simply display additional information. Here is how we specify a startup command procedure:

    DEVICE=TT/HANDDEF=SERIAL/CONTROLLER=A
    	UNIT=1/START/CMDFILE="SY:START.CMD"
    
    Now, when the system initializes the line it will start KMON and KMON will execute the file SY:START.CMD. This command file can contain anything valid for a command procedure, including execution of a program.

    User privileges

    An important concept to introduce at this point is the concept of user priveleges. These specify various things that the user can and cannot do with respect to system operation or device access and are used to allow access to a restricted and safe subset of items for a set of users. Each job has a set of "privilege bits" which enable or disable access to specified features. When the system starts in the way we have been describing a job has "all" privileges set. For developers of vertical applications it is desirable to restrict privileges on a user by user basis. Thats where the LOGON program comes in.

    The logon program, Usernames, UIC, and TSAUTH

    The LOGON program puts up a "Logon Please:" prompt and collects username and password information from the user. It then consults a file called SY:TSXUAF.TSX to see if that user exists, and if so initializes the user to a specified UIC and sets the user's privileges. A "UIC" is a set of two numbers (like 100,101) which identify the user. The UIC is used to control access to system facilities, and is part of the big picture of restricting access to privileged facilities.

    A program called TSAUTH is used to maintain the "User Authorization File", or UAF. With it you add users, modify them, and delete them.

    Running the logon program at startup

    We now have two bits of knowledge about startup: We know how to start a specific named command procedure on a specific terminal line (by modifying the TSX32.GEN file) and we have a body of knowledge that tells us of a way to restrict access to privileges through the TSAUTH and LOGON programs. Lets put them together by modifying the contents of SY:START.CMD, our startup command procedure, as follows:

    !
    ! Contents of SY:START.CMD
    ! Log on the user
    !
    r logon 
    

    The lines beginning with '!' are comments and are ignored. Now what happens? When the system starts, the terminals automatically start and execute the SY:START.CMD command procedure (because we told that line to do that in the TSX32.GEN file) and that command procedure runs the LOGON program, which prompts for a username and password and sets the initial privileges for the user. At the end of that we still drop to a KMON prompt, but now access to the system is password restricted to people who are in the UAF.

    Note that since the startup command procedure name is specified on a line by line basis you could easily have a different startup command procedure for each terminal, or have some set share the same one and others have a different one, or have them all execute the same one.

    Custom logon processing for each TSAUTH user

    The next level of customization is to allow each user who runs the logon program to have a command procedure specific to them execute when the log in. This command procedure would execute no matter which terminal they were logged in at, after they successfully logged in.

    This level of processing is now within the domain of the LOGON program/TSAUTH; the OS neither knows nor cares about the concept of logon command procedures. It is simply executing programs. There is a field in the UAF for each user which allows you to specify a logon command procedure for the user. When the user logs in successfully the LOGON program exits and lets KMON execute the specified command procedure, which may change directories, run a "cookie" program, set the prompt, or any other custom logon desired by the user.

    A conceptual point about LOGON and TSX-Online startup

    The important point about LOGON/TSAUTH user authorization is that it takes a OS job concept, the concept of UIC's and the concept of privileges, and places a layer around it by adding custom command procedures and a prompt for a username and password. The LOGON username is important, and certain things will not function without one, like network device access.

    However, you can develop applications which bypass running the LOGON program. The best example is TSX-Online. The line startup for TSX-Online is not the LOGON program which consults the TSXUAF.TSX file, it is a TPR program which consults the TSX-Online user file. This user file is much more complex than the TSAUTH user file because it contains information about file uploads and download and accounting information far beyond the scope required for a TSAUTH user.

    So, the point is that as a user of TSX-32 there is no automatic and mandatory processing which occurs as the system boots for each line. You could have line run a program which didn't have any concept of a logon but simply launched into an application. You could devise your own logon concept and have IT start up when the line started instead of the LOGON program. You could use the TSAUTH type user concept and launch custom command procedures based on TSX-32 UIC's and user ids.

    A short quiz

    Here are some questions which will test your knowledge of TSX-32 startup.

    • Which command procedure is first executed during TSX-32 system startup?

    • What is the relationship between the MAKELOAD program and the TSXLOAD command procedure?

    • Files with names "*.REX" are loaded into memory during startup. What program loads REX files?

    • What is the name of the .REX file which contains the networking code?

    • What is the command procedure which starts networking? What command procedure starts it?

    • The keyboard monitor is a program. What is the program's name?

    • (Not a question) Remember that KMON can do 3 useful things: Execute a command procedure, start programs, and execute internal, or built-in commands.

    • What is a "built-in" or "internal" KMON command? Give an example.

    • How does KMON "know" when you type "DIR" that DIR is a program and not a built in command?

    • When you type "@CMDFILE.CMD" at a prompt who opens the file? The OS or KMON?

    • When you type at a prompt KMON is the current program. When KMON starts a program like DIR the OS replaces KMON with the DIR program for the duration of the execution. What happens in your job when the DIR program is finished?

    • This is a trick question: When you are executing a command file how does KMON "know" which line to read from the command file? How does it advance through the command file?

    • What is the command to start a command procedure as a detached job? Is it a program or built-in KMON command?

    • What happens to output from a program when it is run as a detached job?

    • When you execute a command procedure as a detached job how do you tell the system to write the output to a log file?

    • When a job starts on a line, what is the name of the command procedure executed for line? How do you change this?

    • How do you set up a command procedure to be executed when a particular user logs on with a TSAUTH style username and password?