TK-Works Manual

TK-WORKS MANUAL
table of contents

(main)

OVERVIEW

 As you may have already noticed, TK-WORKS is much more than an excellent, screen-oriented routine editor. It is a fully integrated set of application development and maintenance tools which, together, provide a complete environment in which programmers can be effective regardless of the implementation of MUMPS they may be using.

Routine Editor TK-WORKS provides a comprehensive, full-screen editor designed specifically for efficiently creating and maintaining MUMPS routines. In addition to such necessary functions as find string, find line, find and replace string, and copy or move code, it also provides a library in which commonly used code can be stored and recalled when needed. Furthermore, the editor automatically keeps two backup copies of each routine that is saved providing a quick and painless mechanism for retrieving an earlier version.

When editing a routine, each programmer is provided a workspace . Since this workspace is disk based, there is no size limit and programmers can leave the editor without losing work in progress. The editor even remembers the line and column the cursor was on so that when the programmer returns to it, he or she will be immediately reminded of what they were last working on.

The editor also provides a number of programmer-specific options, such as whether menus should be HOT KEYED or require a [RETURN] and whether routines should be edited in 80 or 132 column mode (subject to the limitations of the terminal). Each programmer can also decide whether the routine should be displayed in high low intensity, and can set/clear their own TAB settings.

Version Manager In addition to a consistent and friendly editing environment, TK-WORKS also provides a comprehensive and fully integrated Release Management System. This system assists in maintaining release histories for an unlimited number of packages, including the version of each routine and in-line documentation. Furthermore, prior releases of any package can easily be restored.

Utilities TK-WORKS also provides a complete set of the utilities most often needed by programmers for use in development and maintenance activities. Included are a group of Routine Utilities which enable production of routine listings, find string, search and replace, cross reference and more. The Global Utilities contain the most versatile and powerful global editor available which cuts system maintenance times to a fraction. Finally, the Import and Export Utilities provide the means for transporting source or object code to any environment.

We believe that TK-WORKS is the most effective system of its kind available for Standard MUMPS systems and hope you will be completely satisfied with it. Should you have any questions or comments regarding TK-WORKS, or any of PG&A's TK-Products, please give us a call.

GETTING STARTED

 Welcome to TK-WORKS.

If you have several minutes we will install TK-WORKS and walk through an introduction to the system. By continuing into the Maintenance Functions chapter, you will find that the package is comprehensive, yet easy to use and maintain.

INITIALIZATION

 This manual assumes that you have already loaded the TK-WORKS programs onto your system and are ready to get started. Depending on whether you loaded the %version (for Managers UCI) or not, you will have noticed that all TK-WORKS programs begin with the letters %TKED or TKED . Both versions of the system are identical, except that the % version resides in the Manager's UCI and is available to all other UCIs, while the non-% version must be resident in the UCI in which it will be used.

To simplify the remainder of this manual, we will include both versions of the product in our discussion unless a distinction is specifically made in context.

Although TK-WORKS is distributed in program form, it does build and maintain several globals. By convention, the names of these globals also begin with the letters %TKED or TKED to make them easily distinguishable from others already on your system. However, you will also have the opportunity to change the names of many of these globals during initialization.

If you have installed the % version of TK-WORKS, you should invoke the initialization program from the Manager's UCI. However, you may create UCI specific TK-WORKS systems by invoking the program from the desired UCI. To invoke the program, execute the following instruction:

>DO ^%TKEDIN

If you installed the non-% version, you must run the initialization from each UCI in which the system is installed, by executing the following instruction:

>DO ^TKEDIN

NOTE: If this is the first time PG&A software has been run on your system, the program will first take you through the Toolkit Initialization which defines necessary operating system and terminal type parameters. Refer to Appendix A for more information on the initialization process.

The TK-WORKS Initialization Screen should now be displayed on your terminal. To assist you in following the simple setup instructions, a sample of the screen is shown below. As you can see, several questions must be answered during the initialization process.

System Global When TK-WORKS is started, it looks for a set of startup parameters in the system global. These parameters consist primarily of the names of globals the system will use for its database and are stored either in the global ^TKED, or if not found, the Manager global ^%TKED.

If you have begun the initialization from the Manager's UCI, you can toggle the system global field from ^TKED to ^%TKED by pressing the [%] key, or from ^%TKED to ^TKED by pressing the [T] key. If you began in another UCI the only system global you can create is the local global ^TKED. (NOTE: Some MUMPS implementations permit ^%TKED to be created and modified from other UCIs. In such cases, TK-WORKS permits the selection of system global regardless of the UCI from which it was called.

NOTE: If you created a local system global (^TKED) and would rather use the % global, you can kill ^TKED.

Site Name Enter the name of your company or site. This name will appear on all reports and listings.

Database Globals TK-WORKS allows you to define your own global names. The primary purpose for this is to allow you to specify the physical locations of these globals using extended global references. This is true for both the % version and the non-% version.

For example, if you wanted the TK-WORKS Code Library to be available for programming in several UCIs, you might amend the Library Global name to be ^["LIB"]TKEDL or even ^%TKEDL . For more information on extended references, refer to documentation supplied by your MUMPS vendor. The contents of these globals are as follows:

^TKEDU User-selected parameters
^TKEDE User Editing Workspace
^TKEDW Routine Workfile
^TKEDA Routine Archive
^TKEDP Package/Release Information
^TKEDL Code Library

Other than the Code Library global, it is generally recommended that these globals reside in the same UCI.

Routine Locking TK-WORKS can lock routines when they are loaded into a programmer's workspace to prevent their being loaded and edited concurrently by someone else. The routine is then released when another routine is loaded, or a new routine is created.

Accept the default global name for the Routine Lock Table or enter another name. The name cannot be left blank.

If you want Routine Locking enabled, answer by typing a [Y] and [RETURN]. Otherwise, type [N] followed by [RETURN].

Routine Header Map By convention, TK-WORKS assumes that the first line of a routine has a line tag (which is most frequently the name of the routine) and a comment (preceded by a semi-colon ";") about the routine's purpose or function. TK-WORKS extracts the comment from the first line when the routine is saved, and stores it in the routine directory.

However, when a routine is output from TK-WORKS by compilation, listing or export, TK-WORKS can insert additional information into the first line such as the date and time last modified, package name and version. To accommodate varying styles, TK-WORKS accomplishes this through the Routine Header Map as shown in the example.

Decide which of the pieces of information listed on the screen you would like included in routines on output. Then for each, indicate the line number (either the first or second line) and the piece number into which the information should be inserted, separated by a comma. Note that the delimiter used by TK-WORKS when creating a line is a semi-colon ";". If any are not desired, simply leave the field blank.

Copyright Lines TK-WORKS will insert up to four lines of standard text into routines as they are being output, immediately following the first (or first and second) lines as defined above. While this space is intended for copyright text, it can be used for any standard text.

Enter your copyright information or other notices or legends, if any. A semi-colon ";" will be automatically added at the beginning of each line prior to insertion in your program, making each line a comment. In some cases it may be desirable to use a second semi-colon to ensure that this text is included in the object code of those MUMPS implementations which have compilers.

Note that these lines will only be used until a routine has been released as part of a package. More specific copyright legends can be defined for each version of a package as part of the release management process.

During entry or subsequent editing, you may use your arrow keys, insert and delete character, and backspace (or rubout) keys. When completed, your screen may look something like the one shown below. To leave the program without saving your changes, press the EXIT key. To save your changes press [RETURN] through the last field.

APPROACH TO ROUTINES

 TK-WORKS maintains three globals in which routines are stored: the workspace in which the routine is edited, the workfile to which the routine is saved, and the archive to which the finished routine is copied for subsequent release. To understand how these globals are used, let's walk through a typical scenario.

Editing Routines All routine editing is done in a programmer's workspace. Therefore, to edit a routine, it must first be loaded into the workspace using the LOAD function. The routine can be loaded from any of three sources: (1) the workfile (current version or backup), (2) the archive, or (3) MUMPS itself. The following diagram helps to illustrate this.

In the illustration, notice the following. Normally, when loading a routine from the workfile , the most recent copy will be loaded. However, it is also possible to load either of the two backups of the routine maintained automatically by the system. This is shown graphically by the dotted lines originating from Backup No. 1 and Backup No. 2.

The routine archive is designed to maintain an unlimited number of versions of a routine as it evolves. How this is accomplished will be described further in the section related to Release Management . When loading a routine from the archive, the most recent version will be selected automatically.

A single routine can also be loaded directly from MUMPS. However, in some implementations of MUMPS, TK-WORKS is unable to determine if the routine exists before attempting to load it. Consequently, attempts to load a non-existing routine may result in a "NOPGM" or similar error.

Additional information will be provided regarding loading routines later in this manual in the section related to Routine Handling .

Saving Routines When the desired changes have been made to a routine in the workspace, it is then saved to the workfile using the Routine Editor's SAVE function.

During the save process, several important tasks are accomplished. First, TK-WORKS updates the Last Saved date. Secondly, a CRC check of the actual code in the routine is used to determine if the code was changed. If so, the routine's Modification Date is updated. Next, the system counts the number of characters of source code to estimate the size of the compiled routine. This size is displayed in the upper right corner of the Routine Editor.

Finally, the routine is copied to the workfile , while at the same time the two most recent copies of the routine are maintained as backups. This is illustrated below.

"SCREEN TKWORKS,INIT,4,1.8

Archiving Routines When work on a routine has been completed, the routine is transferred to the archive from the workfile in preparation for release. At the same time, all copies of the routine are removed from the workfile. This is accomplished using the Archive Routine Utility available from the Routine Utilities menu.

The archive maintains a version counter for each individual routine in order to be able to track a routine's evolution. When the routine is first archived, this counter is set to 1. It is very important to understand that subsequent archives of the same routine will not increment the counter unless that particular version of the routine has been released through the Release Management process discussed later.

If the previously archived version of the routine has been released, the version counter for the routine will be incremented and a new version of the routine created. The archive process is illustrated below.

Releasing Routines When all the routines to be released have been archived, the release process assists in defining a Package, establishing a Version for the package, and creating the list of routines to be included in the release. When all desired tests have been completed the release is frozen , thereby locking the individual version numbers of each of the affected routines.

The release process provides several important advantages. First, since a release is no more than a list of routine names and their archive version numbers, commonly used routines can be included in as many packages as needed. This is illustrated below.

Another important advantage is that TK-WORKS maintains each version of a package. This makes it possible to restore previous versions quickly and easily and can be of significant benefit to organizations supporting multiple versions of a package.

Compiling Routines Routine Compilation, as defined in TK-WORKS, is the process of transferring the code portion of one or more routines to MUMPS where they can be executed. Internal comments, a capability unique to TK-WORKS, including blank lines are not transferred. And in implementations of MUMPS which execute pseudocode, the implementation's compilation is also performed.

For testing purposes, TK-WORKS provides a Compile function which quickly compiles the routine currently in the programmer's workspace . However, a Routine Utility is also provided which enables multiple routines to be compiled, either from the workfile, the archive, or a released package.

STARTING TK-WORKS

Starting TK-WORKS is very simple. At the MUMPS prompt, type:

>D^%TKED

This can easily be shortened by creating a routine with a shorter name, such as ^%E which invokes ^%TKED, as in the following:

%E ;TK-WORKS STARTUP ROUTINE
GO G ^%TKED

You may even want to create upper and lower case versions of the routine so that it doesn't matter whether the CAPLOCK key on your terminal is on or off.

When TK-WORKS is started, the Routine Editor will appear as shown in the following example. Note that the first time TK-WORKS is invoked, there is no routine in the workspace and control will pass directly to the Functions menu where the LOAD function can be used to load a routine.

If a routine already exists in the workspace , the portion of the routine which was left on the screen the last time editing was done will be displayed, and the cursor placed at its location when the Routine Editor was exited.

Load & Edit For those occasions when you just need to load a routine from MUMPS, make a change or two, and save it again, TK-WORKS can also be invoked using the Xecute command. TK-WORKS then loads the current routine (i.e., the routine made current by the ZLOAD or similar command) and puts you in the Routine Editor.

When the desired changes have been made, you can Compile it and quit, or just quit. When you compile, there is no further need to save the routine to disk because TK-WORKS does this for you as well.

When invoked in this way, TK-WORKS creates a temporary workspace for the session and in this way avoids any affect on the routine you may have in your permanent workspace at the time. To use this feature, just load the routine and execute the editor like this:

>X ^%TKED

EXITING THE ROUTINE EDITOR

 To exit the TK-WORKS Routine Editor, press the function key which has been assigned to the EXIT function for your terminal. If you are uncertain which key it is, press the HELP key. For VT2xx, VT3xx terminals and their emulations, your keyboard should contain a key labeled "HELP". On most PC systems, the F1 function key is used for help. If your terminal does not fit either description, refer to the function key definitions for your terminal type in Appendix B at the back of this manual.

After pressing the HELP key, a window will appear which identifies important keys in routine editing, such as the one shown below:

If you pressed the HELP key and the function key window is still on your screen, press [RETURN] to return to the editor.

Press the EXIT key to invoke the Function menu, and select QUIT or press EXIT once more to return to MUMPS.

PROGRAMMER OPTIONS

TK-WORKS provides several options which can be quickly and easily changed to reflect each programmer's preferences. These are available under Options in the Functions menu.

Menus All of the menus in the TK-WORKS system are capable of operating in NORMAL mode (i.e, a RETURN is required to complete a selection) or in HOT KEY mode. In HOT KEY mode, menu selections can be made in most cases with a single key stroke, saving the programmer time. However, TK-WORKS will use each programmer's preferred setting when it is next used.

Width The TK-WORKS Routine Editor is capable of operating in the normal 80 column mode, or with terminals which support 132 cpi, in 132 column mode. Regardless of which mode is desired, TK-WORKS will always put the terminal back in 80 column mode when programmers exit.

Display Routine text can be displayed by the Routine Editor in either high or low intensity. This makes it possible for the programmer trying to overcome excessive screen glare to use high intensity, while another prefers low intensity. In either case, editing functions such as DEL CHAR and COPY or MOVE text, will use the alternate intensity to mark the affected regions. In addition, TK-WORKS remembers each programmer's preference the next time the system is used.

Editmode TK-WORKS provides two modes for editing routines, each of which appeals to the special interests of different programmers.

In TYPEOVER mode, which is the TK-WORKS default mode, characters typed will type over, or replace the character at the cursor with the character just typed. To insert new characters in a line, the INSERT CHARACTER key is pressed to enter a temporary insert mode. The line is broken at the cursor and text can be entered. When the new text has been entered and [RETURN] is pressed, the line into which the text is being inserted is put back together and the screen refreshed. In this mode, new lines can be inserted anywhere in the routine by pressing the INSERT LINE key.

In INSERT mode, the editor can be toggled between INSERT-ON and INSERT-OFF modes by pressing the INSERT CHARACTER key. In INSERT-ON mode, all characters typed are treated as new characters and do not replace but are added to existing characters. In addition, the [RETURN] key will break a line at the cursor, and the [BACKSPACE] or [RUBOUT] will put two lines back together again. INSERT-OFF mode works just like TYPEOVER mode, except for the function of the INS CHAR key.