TK-Works Manual

TK-WORKS MANUAL
table of contents

(main)

CREATING A ROUTINE

The NEW function is used to clear your workspace and create a new routine. It can be invoked from the Functions menu which is displayed at the bottom of your screen when you exit the Routine Editor.

If you have HOT KEYS turned on, typing an [N] will invoke the Create Routine function.

Otherwise, type [N] or use your [SPACE] key or [RIGHT] and [LEFT] arrow keys to move the selector to the new option and press [RETURN]. You will be asked for the name of the routine to be created as shown in the following screen.

If you want to clear your workspace, but not actually create a new routine, simply enter a [SPACE] and press [RETURN]. You will be placed in an empty Routine Editor from which you can exit.

Enter the name of the routine to be created and press [RETURN]. If a routine by that name already exists in TK-WORKS, you will be notified of its existence and asked for another name. If no such routine exists, your workspace will be cleared and the cursor will be placed at the top left corner of the editing window.

At this point it would be useful to remind you that TK-WORKS makes some assumptions regarding the format of the first line of the routine. The rules are very simple, but if not followed, can produce unpredictable results.

First, the line tag of the first line should be the name of the routine. If the routine name is also an extrinsic function, the parameter list may be included.

Second, TK-WORKS expects the rest of the line to be a description of the routine prefaced by a semi-colon ";". Note that at least one space must occur between the line tag and the semi-colon. Thus the first line of your routine might look like this:

Remember that creating a routine does not automatically save it to the workfile at the same time. A newly created routine exists only in your workspace until you explicitly save it.

Loading A Routine To edit a routine, it must first be loaded into your workspace . To do this, select LOAD from the Function menu. You will be asked for the name of the routine to be loaded. If you know the name of the routine, enter it and press [RETURN] as shown in the example below.

TK-WORKS will then identify the files from which the routine can be loaded and request that you select one. That is, if the routine is in the workfile , the list of possible sources will include WORKFILE. If the workfile has backup copies of the routine, the list will include BACKUP. And if the routine is also found in the archive, ARCHIVE will be in the list. Finally, MUMPS will be included as a possible source, and sometimes the only one.

The important thing to remember is that regardless of which files are represented in the list, the default option will always be the most current copy of the routine. So, unless you are specifically intending to load an older copy of the routine, simply press [RETURN].

Once selected, the routine will be loaded into your workspace and the cursor placed in the top left corner of the routine.

Routine Lookup If you are unsure of the exact name of the routine, enter as many characters of the name as you are sure of followed by a question mark. You will then be asked whether to search the workfile, archive or MUMPS . Select the source in which you expect to find the routine.

For example, if you know that the routine is not in development, look in the archive . However, when uncertain, it is generally wise to check the workfile first. If the routine is not there, then check the archive.

When the source has been selected, TK-WORKS will display a list of routines that begin with the characters you typed before the question mark, as shown in the following example. If you have displayed routines from the workfile or archive, the approximate size, date last modified and description will be displayed next to each routine name. If from MUMPS, the contents of the first line of the routine, if any, will be displayed.

Next to each routine will be displayed its approximate size, the date it was last modified, and its description. If the list is too long to be displayed on one page, you can use the NEXT PAGE and/or PREV PAGE keys to page back and forth throughout the list.

If the list does not contain the routine you are looking for, press the EXIT key and try again, this time with fewer characters.

If you find the routine, move the selector '="' to the line on which the desired routine is displayed using the cursor UP and DOWN keys. You can also use the [SPACE] key in place of the cursor DOWN key. Press [RETURN] and the routine will be quickly loaded and displayed for you and the cursor placed in the upper left corner of the routine.

EDITING A ROUTINE

While specific editing operations will be discussed in detail later in this manual, there are several general, but important things to know about TK-WORKS' Routine Editor which will be helpful to understand.

Code and Comments TK-WORKS provides an environment in which internal comments and white space can be used freely to assist in making the routine easy to read, understand and maintain. To do this TK-WORKS recognizes three types of line: (1) a blank line, (2) a comment line and (3) a code line. Each of these are illustrated in the sample routine shown below.

Notice that blank lines have been used liberally to make the routine easier to read. Also note that comment lines begin with the slash "/" character. TK-WORKS recognizes these lines as internal comment lines and does not include them in determining the size of the routine or whether the routine has been modified. Nor does it transfer them to MUMPS when the routine is compiled. However, they do remain an integral part of the source code.

The standard MUMPS comments (preceded by a semi-colon) are also permitted. Such comments, as well as any non-blank lines which do not begin with a slash, are considered code lines and will be transferred to MUMPS with the code when the routine is compiled.

Format Requirements TK-WORKS imposes few format restrictions on the programmer and most, if not all, are the same as other editors. The rules are as follows: First, linetags must begin at the leftmost margin and must adhere to ANSI MUMPS syntax requirements for linetags.

Second, linetags, with or without parameter lists, must be followed by at least one [SPACE] character before code begins. Pressing the [TAB] key after entering a linetag is helpful and also serves to keep left margins free from all but tags making the routine easier to read.

Further, TK-WORKS considers the maximum line length to be 255 characters, regardless of the implementation of MUMPS being used. Lines entered exceeding the maximum are broken when the routine is saved and the programmer notified of the error. When this occurs, the second half of the line will be preceded by the linetag '"LNGTH"', which is an illegal linetag and will not compile.

Cursor Movement TK-WORKS provides a full set of cursor movement functions, each of which can be invoked by a single keystroke. Further, most ASCII terminals and PC keyboards now provide keys for these purposes. The names of the keys may vary slightly, but their function and use remain constant.

Cursor UP Moves the cursor up one row.
Cursor DOWN Moves the cursor down one row.
Cursor LEFT Moves the cursor left one position. If at the first column, cursor moves to last column of previous line.
Cursor RIGHT Moves the cursor right one position. If at the last column, cursor moves to the leftmost column of the next line.
PAGE UP Causes the previous 21 lines of the routine to be displayed. Cursor remains in the same relative position.
PAGE DOWN Causes the next 21 lines of the routine to be displayed. Cursor remains in the same relative position.
FIRST PAGE Causes the first 21 lines of the routine to be displayed. Cursor is placed at first column of first row.
BEG-OF-LINE Moves the cursor to first column of the current line.
END-OF-LINE Moves the cursor to the end of the current line.
TAB Moves the cursor to the next TAB position shown on the rulers at the top and bottom of the editing window. TAB positions can be added and removed with the [SET TAB] key.

Edit Mode TK-WORKS provides two editing modes, known as INSERT mode and TYPEOVER mode, which can be selected by individual programmers to suit their needs. These modes are discussed in more detail in the section titled Programmer Options. Specific editing functions are discussed in the section titled Editing Functions.

Long Lines TK-WORKS does permit lines which are longer than can be displayed on one row of the screen. Simply move the cursor to the end of the current line and begin adding text. When the next character typed will no longer fit on the current line, a continuation line will be created and the new character placed at its beginning. Line SUMM in the illustration below is such a line. Notice that the continuation lines are indented two columns to the right of the first TAB.

SAVING A ROUTINE

 Saving a routine copies the routine in the workspace to the workfile . If prior copies of the routine already exist there, the two most recent copies are retained as backups.

To save the current routine, exit the Routine Editor and select SAVE from the Function menu at the bottom of the screen. As the screen illustrated below shows, you will be asked to confirm the routine name.

To save the routine as named, simply press [RETURN].

However, it is also possible to rename the routine when saving. To do so, enter the desired name and press [RETURN]. Notice that the routine in your workspace is also renamed at the same time.

If for any reason you wish to abort before saving, press the EXIT key at the 'Save Routine: ' prompt.

When the save is completed, you will be returned to the Function menu.

COMPILING A ROUTINE

The Compilation function strips blank lines and internal comments from a routine and exports the resulting routine to MUMPS where it can be executed. In those MUMPS implementations where compilation to pseudo-code is required, this step will be done at the same time.

To compile the current routine, exit the Routine Editor and select COMPILE. The routine will be compiled immediately and you will be returned to the Function menu.