Network Information Services

By Brian A. Lantz/KO4KS

TPALAN - Tampa Local Area Network

This is a reprint of a paper printed in the Proceedings of the 12th ARRL Digital Communications Conference, September 10-11, 1993, with some information updated


INTRODUCTION:

In the early days of packet radio, you were lucky to find a station or two that you could connect to for a digital QSO. As time has progressed, BBSs took the role of "generic information providers", with bulletins, and E-Mail as their strengths. Current BBSs are used nearly 100% for message handling.

The BBSs have a distinct weakness in the area of providing information to the user. The two main ways that BBSs provide generic information are:

  1. Requiring the user to read certain messages
  2. Requiring the user to download certain files.

Both of these provide a learning hurdle to a new user, which will probably cause the user to try to "stumble through it" without the needed information.

ROSE (and other networking tools) have taken the first steps of network information services by placing a screenful of text in the memory of the switch/node to answer a few questions the user might have. This is made simple for the user, requiring him to connect to an alias; no new actions to learn.

The average new user has limited computer experience and very probably NO experience with other E-Mail systems. Networks are a concept that scares even many long-time packeteers. An information provider should take these into account and also provide a way to be interactive, at least to a point.


TNOS NETWORK INFORMATION SERVER:

One of the new, unique features of TNOS is the Information Server. This is a Hypertext driver that allows tutorials, help systems, on-line surveys, etc. to be easily added to NOS. Sub-directories can be added easily to allow multi-level nesting with each Server.

The user connects to an alias (i.e. "INFO") and is presented with a numbered menu of available options. Each entry can be either a Service file, or a Subdirectory file. Their location and all other details are not needed by the user; he/she simply selects what he/she wishes from the menus.

The whole Information Server process is driven by standard ASCII text files. Lines that begin with a tilde ('~') are control lines. All other lines are simply text. These files can be uploaded from the BBS prompt, or can be automatically uploaded using a Request Server like the TNOS REQSVR.

TNOS supports three Information Servers, which all act alike, but have different aliases, directory structures and Service files. The three standard TNOS Information Servers are INFO, NEWS, and TUTOR. INFO is used for informational content, network access frequencies, BBSs available, etc. NEWS is reserved for Amateur Radio related news. The TUTOR Server is generally used for more interactive Service files. Samples include surveys, tutorials, databases, and much more.

The rest of this paper will (hopefully) serve to wet your appetite and also to document the file format used by the TNOS Information Server until better documentation is available.


NECESSARY COMPONENTS:

There are only two necessary components of a file that is used as either a Subdirectory File or a Service File for the TNOS Information Server, a File Name and a Title Line.

FILE NAME:

We all can probably agree that one of the worst "features" of MS-DOS is the size limitation of filenames; 8 character name with 3 character extension. This leads to VERY CRYPTIC filenames, at best. One definite design decision of the Information Server was to NOT inflict upon the user the responsibility of having to make sense out of MS-DOS file names. With the Information Server, you can use whatever filename you want. The file MUST have a ".tut" file extension, though.

Should you use descriptive filenames? Who cares! The user never sees them, they see the description from the file's title line, and a number that they use to choose the Service File.

Each file must be in the proper directory for the server desired. These are (by default) "spool/info", "spool/news", and "spool/tutor".

Those familar with NOS will note that the NEWS directory is used in all other variations of NOS for the NNTP directory. TNOS names the NNTP directory NNEWS by default.

TITLE LINE:

The first non-blank line of the Service File is special! It serves to provide the Information server with the description of this particular item. The title line can also allow you to nest into sub-directories easily. This allows sub-menus very painlessly.

The title line can start with preceeding spaces or tabs (they are ignored). This allows you to center the line, since this is the first line displayed to the user when the Service File is executed. The rest of the title line will be displayed as the file's description in the Information Server menu.

If the title line starts with a tilde ('~'), it expects a line of this format:


	~subdir description

The 'subdir' is the name of a sub-directory within that directory. This allows you to define one-line files that make nested sub-menus.

Table 1 lists the many filenames in a sample Information Server directory and their title lines. Figure 1 shows how the user sees this information.


TNOS SCRIPTING LANGUAGE - TSCRIPT:

While not a very elegant language, or one easy to read, the TScript language developed as the Information Server of TNOS developed. TScript is also used within TNOS to provide greater customization of the BBS, and to allow the SYSOP to automate many processes via TScript files, using the Command Session 'script' command.

The design goals of Tscript were:

  1. To provide a simple to use, easy to edit, way to display information files.
  2. To limit the number of 'special characters' required to a minimum.
  3. To allow a wide subset of TNOS capabilities under programatic control.
  4. To make it as portable as possible, in case other programs wished to use it for simple information formatting.

While this document was originally written to document the Information Server of TNOS, the rest of this document is actually an overview of the TScript Language. Before adding the additional uses for this language, Tscript and the Information Server were one and the same.


ANATOMY OF A TSCRIPT FILE:

The Tilde character ('~') is treated special at all times. All lines that do NOT begin with the tilde ('~') character are simply sent to the user after a few simple substitutions. All substitutions begin with the tilde character and serve as shortcuts for variable data fields. The special control sequences in text lines are listed in Table 2.

The first four sequences allow you to place the caller's callsign, host computer name, or the current date or time into the text data sent to the user.

The next 10 sequences allow you to place a string variable into the text flow. There are 10 variable strings given for the script writer's usage. Datafile text, user's responses, and other data can be stored in variable strings and displayed with the "~0" through "~9" control sequences.

The next 10 sequences allow you to output a numeric variable. As with string variables, the script writer has 10 integer variables at his/her disposal, named "~i0" through "~i9".

The next two allow you to place a bell character or a tilde character into the data stream. The following two sequences allow you to imbed a carriage return into a string, or mark a line to ignore its own carriage return at the end of the text line.

The last three sequences allow you to display the current Error variable string, the elapsed time of this script, or the file position of the current data file.

CONTROL LINES:

All lines that BEGIN with a '~' are treated as control lines by the TScript language used by the Information Server. In all of the following tables, parameters marked with an astrick ('*') can be either a literal number, an index counter (~i0 - ~i9), or a variable string (~0 - ~9).

The Basic Control Lines are shown in Table 3.

The "~<space>" control line allows you to imbed non-displayable, no operation lines that can be used to help document the script file. The "~b" control lines allow you to place a fixed number of blank lines into the data flow. When the "~~" control line is used, the "~~" is simply treated as ordinary characters at the beginning of an ordinary text line, which are interpreted as the "~~" control sequence, and substituted by a single "~".

The more control line ("~m") asks the user if he/she wants more, and if so continues. If a negative response is given, the script will do an implicit goto ("~g") the label named "exit". If the label "exit" doesn't exist, the script is complete. You can also exit the script at any time with "~x".

You can easily take a regular text file, using these few control commands, and make a decent Service File. You should pace the display so that there is a user interaction or a "more" command for every screenful of data.

The Query and Flow Control Lines are shown in Table 4.

You can use labels very much like they are used in the C programming language and assembly language. A label is any text name that makes sense to you. Spaces are not allowed in a label name. A label is defined with a "~l" control line.

You can go to any label in a script file with the goto ("~g") control line. The label can precede or follow the goto line in the script file.

Simple querying can be done with the query ("~q") control line. This command puts out a prompt string, asks for a yes or no reply, and sets the script's query variable to either 'y' or 'n'. The query variable is used for conditional gotos in the "~y" and "~n" control lines. These lines will go to the label given if the query variable matches ('y' for the "~y" command, 'n' for the "~n" command).

A different query variation exists with the "~v" (variable query) control line. The prompt is sent to the user, and their response is placed in the string variable that matches "num".

The Assignment and Comparison Control Lines are shown in Table 5.

You can assign an escape sequence or a literal string into a numbered string variable with the "~a" control line. You can append one string variable onto another with the "~ap" control line. You can place a sub-string of one numbered string variable into a second numbered string variable with the "~p" control line. The "~t" control line allows you to truncate (clip off) a string variable at a certain point.

There are two control lines that can be used to compare string variables, "~c" and "~j". The first, "~c", compares the entire string of each, while the "~j" command compares only the first part of the two strings. You can get the length of a string variable's data with the "~z" control line.

The "~i" control line handles four different functions with integer variables. The character after the 'i' (0 though 9) indicates which numbered integer variable to use. The next character is the character that determines the function. The '=' assigns a value. The '+' adds to the current value of a variable. The '-' subtracts from the current value. The '?' compares the variable to a set value and sets the query variable accordingly.

The "~h" control line is like the "~c" and "~j" commands, but allows searching for a substring within another string, and returns the offset in the string that the substring was found. The "~^" control line can convert a string variable to all lower or upper case.

The Data File Control Lines are shown in Table 6.

An I/O datafile can be opened with either the "~f" or the "~o" control lines. Both commands close any previously open I/O file, and open the desired file. If no filename is given, these commands simply close any previously opened file. They differ in that the "~f" creates a NEW file and sets the query variable to 'n' if the file couldn't be created or already existed. The "~o" command opens a old file and sets the query variable to 'n' if the file couldn't be opened or didn't already exist.

You can seek to the beginning ("~s") or end ("~se") of the data file. The "~sp" control line is used to see to a specific position within a data file. You can check for the end of file with the "~e" control line. The query variable gets set to 'y' if at the end of the file. If a label is given on the control line and it IS the end of file, then a "goto" is executed, moving to the label line.

You write to an open data file with the "~w" control line. The rest of the line is treated the same as regular text lines, with imbedded control sequences allowed. You read from an open data file with the "~r" control lines. The next line in the data file is placed into the numbered variable string.

The File Utilities Control Lines are shown in Table 7.

You can upload a separate text file with the "~u" control line. There is NO special processing of an uploaded file, so normal Information Server escape sequences are not examined, substituted, or acted upon.

You can use the "kill" command ("~k") to delete files on the host system's disk. FOR THIS REASON, you should limit only those that you can TRUST to be permitted to add Information Server files on your system.

You can send the contents of a file in a mail message to a user with the "~d" control line. The "~dr" control line does this also, but allows you to specify a 'Reply-To:' address to be used in the mail message.

Information about a user can be examined and set using the "~?" and "~!" control lines. You can use these to check the user's desire to use color. If the user came through the TNOS BBS and has ANSI color graphics mode on in the BBS, the color option will be on. Others will be initially set to off.

The username of the user is ONLY valid on starting a script if the connect was an AX25 connect, NOT a TCP/IP connect. You can find out if the user connected with IP using the "~? I" control line. If this is found to be an IP connect, you may wish to ask the user for a username and also ask them if they would like an ANSI color display (if your script uses these features).

The ANSI Color File Control Lines are shown in Table 8.

The Information Server allows you to give users (that desire it) a more colorful display. You can change the text colorset, imbed ANSI control sequences in the text flow or add pre-saved ANSI color files at a particular spot in a Service File.

The "~*" control line is used to mark the beginning and end of an imbedded ANSI sequence. The Information Server will remove KNOWN sequences from the data flow if the user has not selected ANSI graphics, but this is NOT without flaws. It is suggested that you use conditional looping based on the user's color setting (using a "~? C" control line).

A pre-saved color file is inserted into the data stream with the "~%" control line, but ONLY is displayed if the user has color set to ON. Otherwise, the file will be skipped.

The current text colorset is changed with the "~@" control line. The "colorcode" is a two digit, hexadecimal value that determines the colorset desired. The first digit determines the background color and the blink attribute. The second digit determines the foreground color and the high intensity attribute. These Color Codes are listed in Table 9.


CALLING SCRIPTS AND MAKING CONNECTIONS:

The Script and Connection Control Lines are shown in Table 10.

The "~$" control line allows you to execute another TScript file from within the present one, waiting for it to complete before continuing with this script, while the "~$$" control line executes the TScript file in the background.

The "~(" control line is used to bring up an ax25 or telnet connection, which can receive or send data. Up to 9 different simultaneous connections can be maintained. The "~)" control line disconnects an ax25 or telnet connection opened with the "~(" control line.

The "~#" control line allows you to change which connection you use for I/O. Stream 0 is the NORMAL interactive stream, opened with the script begins. The "~=" control line checks the requested connection to see if it is still valid and available to send/receive data.


IMPLEMENTATION:

While this is already implemented in TNOS, the same code could be easily integrated into other BBSs, other variants of NOS, or any other possible information provide.

Update note: This code has been added to the PC-ROSE code, and used for an enhanced INFO server in it.

There is a stand-alone application included in the TNOS distribution that allows ANY MS-DOS user to design/view Information Server files without needing to run TNOS.


SAMPLE SCRIPT:

What follows is a sample Information Server script that serves no REAL useful purpose, but does test most of the Information Server features, and serve as a syntax example.


                             First Test Tutorial

~l loop
This is the first test at '~h'.

Now we will test the MORE function....
~b 3
~m
~b 3
It's time to test the QUERY function....
~b 2
~q Loop back
~y loop
~b 3
Tired of looping, huh!
One more test of the QUERY function....
~b 2
~q Loop back
~n noloop
~g loop
~l noloop
~b 3
Really tired of looping, huh!

Time to test variables....
~b 3
~v 1 Enter variable #1 (at least 5 characters)

The variable entered was ~1!
~i9=4
~p 6 1 0 ~i9
The first four characters were '~6'. ~u
~z 1 4
The length of the string was ~i4.
~t 1 4
The truncated first four characters are '~1'.
Your call sign is ~c.
~a 4 This is variable #4
~~Variable number 4 is '~4'.

~v 2 Enter your call sign
~v 3 Enter your call sign again
~b 2
~c 2 3 equal
They were NOT equal~b
~g next
~l equal
They were equal and they were '~2'.~b
~l next
~j 2 3 2 nowokay
Even the first two characters didn't match!
~g skipit
~l nowokay
The first two characters matched!
~l skipit
~m
~f /newtest
~w Call sign is '~c' - Variable 4 is '~4'.~n
Writing the following to disk:
'Call sign is '~c' - Variable 4 is '~4'.'~n
~f
~o /newtest
~r 5
Variable 5 is '~5'.
Rewinding......
~s
~r 6
Variable 6 is '~6'.
~f
~k /newtest
~n xx1
Deleted temp file
~g xx2
~l xx1
Couldn't delete temp file~b
~l xx2
~b2
The date is ~d.~nThe time is ~t.
~m
~ now for the index counters test
~b 2
Here is the equivalent code for "for (k=1; k < 10; k++)"
~i1=
~l indexloop
The current value of index1 is ~i1.
~i1?10
~i1+
~n indexloop
~i2=~i1
The copied index from index1 to index2 is ~i2.
~m
~b2
And here is the equivalent code for "for (k=10; k; k--)"
~i1=10
~l indexloop2
The current value of index1 is ~i1.
~i1?1
~i1-
~n indexloop2
~l lasttest
~b2
~v 9 Enter in a number from 1 to 4
It was ~u
~i9=~9
~i9?1 was1
~i9?2 was2
~i9?3 was3
~i9?4 was4
~l invalid
not one of the numbers asked for! Your answer was~u
~i9?0
~n badone
either zero~nor started with a non-digit! ~u
~g reloop
~l badone
 ~i9! ~u
~l reloop
Try again~b
~g lasttest
~
~
~l was1
One!
~g through
~l was2
Two!
~g through
~l was3
Three!
~g through
~l was4
Four!
~l through
~m
Your current CONFIG.SYS file is....
~u /config.sys
~m
I'll now send CONFIG.SYS to you in a mail message
~dr nerfman@super.com
~c /config.sys
~n lastoops
Sent successfully!
~g lastout
~l lastoops
Couldn't send it!
~l lastout
~b 2
~q Ready to exit
~n loop
~b 3
~l exit
Goodbye, come back and see us!~b

Last updated: Sunday, 25-Jan-2004 14:20:54 UTC