Cande:: Enhancements To Unisys' Venerable Workhorse

CANDE:
Enhancements to Unisys’ Venerable Workhorse

Relative to SSR 41.2 by Donald J. Gregory
ANDE is a linchpin in the A-Series framework. CANDE continues to be a highly popular editor, despite
the fact that it is neither GUI nor menu driven. CANDE contains within it a command-based editor that
operates in both single-line and full-page mode. The full-page features give the CANDE user many of the
benefits of a true visual editor without any requirement for a PC.
Providing an editor is only one aspect of the CANDE product. Using the more recent vernacular, CANDE
is also a complete operating system “shell”. CANDE provides a variety of commands enabling its users to
compile and execute programs, enter a dialog with a program, run scripts, submit batch jobs, and monitor
those jobs through “control” commands. In short, CANDE is a fully featured computer system interface
that provides all of these features as a single, integrated working environment for the A-Series user.
The current version of CANDE was first developed around 1973 and shipped on the Mark 2.3 software
release. It was written by B6700 experts who knew how to squeeze incredible power out of that machine.
They gave CANDE its own memory management routines and task processing routines; they also gave it
special “hooks” into the operating system.
The greatest achievement of CANDE, in my opinion, is its multi-processing abilities. CANDE was de-
signed to handle dozens of users at once. Yet there was no way that you could run dozens of editing tasks
on a B6700 in 1973 (for an affordable price, that is) all at the same time and get any kind of decent re-
sponse.
To avoid the overhead of task processing, all CANDE users share a small set of “worker” stacks. These
stacks are called grind stacks because the internal name of the procedure in SYMBOL/CANDE that handles
them is GRIND. These stacks continually swap user activities in and out such that each user gets the illusion
that he is the only one using the system.
The authors of CANDE, in effect, developed an editor that is also a transaction processor. In fact, it is a
better transaction processor than many of the on-line systems in use today. CANDE enters a dialog with its
users, a feat that is next to impossible in your traditional COMS transaction processing environment.1
What’s even more amazing is that the authors of CANDE invented all of this back in the days when trans-
action processing was just a figment in the imagination of the most advanced computing scientists.
But that’s not all! To top off these achievements, they completely integrated the editor within the com-
mand processor (or “shell”). This was a major innovation.2 With an integrated editor, users are freed from
having to “run” an editor every time a file needs some dinky change. This greatly improves individual pro-
ductivity and significantly reduces machine overhead for everyday editing work.
The CANDE editor itself was reasonably advanced for its time. Having a standard editor meant that users
could go from one B6700 to another and not require retraining. Having a quality editor meant that there
was little incentive to write other editors — editors that would muck up the system by firing off a task each
time they were used and requiring the enormous overhead of one stack per user.3
Thus, the authors of CANDE gave the B6700 — and now the A-Series — audience a working environment
that was years ahead of its time.
To be sure, CANDE does have its limitations, such as the 255-user limit. These limitations descend from
the original partial word definitions that enabled CANDE to run in a tight memory environment. Now the
memory constraints are gone, but the partial word definitions are integrated throughout the software in so
many places that it is difficult to change them.
1
2 \ Gregory’s A-Series Technical Journal
Despite these limitations, the basic genius behind CANDE continues to shine. This makes CANDE an
extremely popular product amongst A-Series customers and a valuable resource that Unisys continues to
enhance and maintain.
In the Mark 4.1 software release Unisys has made major improvements to CANDE. This series of articles
is devoted to describing these enhancements and showing how to use them effectively. In some cases —
particularly the article on the FILES command — we have what is presently the only accurate description of
how the features work.4
This series is broken into six principal parts, as follows:
Part One describes the new features related to the CANDE editor. The emphasis is on page mode editing.
The new features described include the FIND:PAGEMODE command, horizontal scrolling within page mode,
and how to edit files containing non-printable characters.
Parts Two through Six describe enhancements to the CANDE shell commands.
Part Two describes the startup and automatic restart features you can use in a CANDE session. These are
not new with Mark 4.1. They are, however, extremely useful features, and they came out after our CANDE
Primer was published. Therefore, we have included an article on them as the first of the “shell” articles.
Part Three discusses the FILES command: both the new reporting features and the wildcard searching fea-
tures. The enhancements Unisys has made here are simply outstanding. Once you find out about them,
you will never use the LFILES command again for the rest of your life!5 (You will also be able to return
those sneers from the Unix crowd.)
Part Four presents the enhancements to the DO command, particularly the parameters feature.
Part Five presents the on-line help facility.
Part Six wraps up the shell enhancements by describing the “one liners” — miscellaneous changes that im-
prove existing commands.
These articles are intended for A-Series users who are already familiar with CANDE. There is a certain
amount of terminology relative to CANDE that the reader should be aware of. If you are not, this informa-
tion is available in the book The Complete CANDE Primer, from Gregory Publishing Company.6 That book
introduces the concepts of “page mode” editing and presents the other standard functions of CANDE.
In addition, we also have an updated article for CANDE site administrators. We previously published an
article on how to manage CANDE in the February 1988 issue of the A-Series Technical Journal. Now we
have updated that article to the SSR 41.2 level of CANDE and included it in the October 1995 issue.
There are a number of new options that every site administrator needs to be aware of when supporting
CANDE. If you have never looked at your system options relative to CANDE, you will want to review this
last article closely. You may be missing out on quite a lot that CANDE can do!
Unisys has made some amazing changes to our venerable workhorse. It is impossible to do justice to these
changes in a few pages of documentation. While reading about these enhancements, you really must try
them out yourself on your terminal. Once you are familiar with them, you will wonder how you ever lived
without them!
1
Dialogs are extremely difficult in COMS transaction processing environments because you must save user “state” in-
formation from the time the response is sent until the next input is received. This is a problem in COMS that still has
no acceptable solution.
2
I don’t know of any other vendor who had this feature until Borland provided it with Turbo Pascal in 1984.
3
Several attempts have been made to “improve” on the CANDE editor. Two were tried by Unisys: a product from the
Mission Viejo plant called the Editor, and another product from the Tredyffrin plant originally called A Better Editor
but later changed to Intelligent Distributed Editor (IDE). Both of these fail in the most crucial area: you must fire up a
task to use the editor. (In the case of IDE, you fire up a task and a bunch of libraries as well!)
4
That may change if I ever get around to submitting a few UCFs. I found the documentation on the FILES command
in the Unisys CANDE Operations Reference Manual (release level SSR 41.2) both confusing, inaccurate, and contra-
dictory. The information presented in our article, on pages 9-205 – 9-221, has been tested for accuracy using the soft-
ware.
Volume 9.06
CANDE: Enhancements to Unisys’ Venerable Workhorse / 3
5
One person to whom I showed the reporting features commented that at last it was possible to get the file attributes in
a report that you could read!
6
Gregory, Donald J., The Complete CANDE Primer, Gregory Publishing Company, 1986.
September, 1995
CANDE: Editor Improvements
ark 3.4 gave us CANDE page mode editing. By selecting an initial line number, you could display a
screenful of text on your terminal. Then you could edit anywhere on the page and transmit back all or any
portion of those lines to update your workfile. Page mode editing turned the line-oriented, TTY-based
CANDE editor into a full-screen editor capable of working with most multi-line, “intelligent” terminals.
To begin page mode editing on a workfile, you enter a PAGE command. This brings up the first screenful of
data on which you can begin working. The PAGE command requires a sequence number which tells
CANDE where in your workfile that “first screenful” starts. Thus, it builds upon one of the oldest premises
of CANDE editing: that lines are identified for editing through their sequence numbers.
If you have worked with many PC-based editors, you already know that they do not use sequence numbers
for identifying lines. To locate the area in your file that you want to edit, you typically have the following
choices:
• You can manually scroll through the file until you find the spot where you want to start working.
• With some editors, you can “jump” to a location some percentage of the way through the file.
• You can search for some text that you know is at or near the location where you want to start working.
CANDE now provides equivalents to all three of these options, as follows.
To sequentially scroll through the workfile:
1. Use the PAGE command, with no <sequence number>, to display the first screenful of lines from the
workfile.
2. Use the NEXT, +, and - commands to move back and forth through the file.
To jump to a specific place in the workfile:
Use PAGE <sequence number> to display a screenful of workfile lines beginning with a specific one.
To display a page of lines by locating some text:
Use a FIND command specifying the PAGEMODE option.

All three methods present you with a page of text from your workfile. You may edit any of the lines on the
screen and then transmit the entire page back to apply those changes to the workfile.
Invoking Page Mode with FIND

Basic Operation
The PAGEMODE form of FIND combines the features of the FIND command with those of the PAGE command
to produce a very slick locate/display/edit system. To use it, append the modifier PAGEMODE to your FIND
command. It is used in place of the modifier TEXT.
The TEXT modifier gives you a series of single line reports listing only those lines, if any, where your target
text is located. This may be useful for viewing, but it is not very useful for editing. The “hits” are reported
using LIST statement formatting.
There is also a variation of TEXT called TEXT,PAGEFORMAT. This modifier pair returns the same report but
formats it in page mode format — i.e., using sequence numbers that are zero-filled on the left-hand side
and with no additional spacing between the sequence number and the text. Only lines containing the target
text are returned. However, you can edit any of these lines and transmit the entire set, or any portion
thereof, back to CANDE to apply changes to your workfile.
PAGEMODE generates a completely different type of report. In this case, CANDE sends you a full screen of
text for each “hit” in your workfile. You see the line containing your search target surrounded by its neigh
Volume 9.06
CANDE: Editor Improvements / 5
boring lines and formatted for page mode style editing. You may edit any of the lines on the page. When
you transmit the page (or a portion thereof) back, CANDE will search for the next occurrence of your tar-
get and, if found, return another full page of text. This continues until all of the “hits” have been displayed.
To illustrate this, first consider the familiar FIND statement that just reports lines containing your target.
Suppose that you want to find all references to the variable FILEREPORT in the file SYM/FINDWARNINGS.
The results would be:
FIND /FILEREPORT/:T
#WORKFILE SYM/FINDWARNINGS
10016000 WRITE (FILEREPORT, 30, OUTBUF);
10020000 FILEREPORT
10221000 % FILEREPORT sorted by warning number.
10264000 REPLACE ETEMPTITLE BY FILEREPORT.TITLE;
10277000 OPEN(FILEREPORT);
10382000 CLOSE (FILEREPORT, CRUNCH);
#
As a simple report, this shows you how the variable is used in the program. If you want to alter some or all
of the references, however, you could use the PAGEFORMAT option instead. For example:
FIND /FILEREPORT/:T,PA
#WORKFILE SYM/FINDWARNINGS
10020000 FILEREPORT
10221000 % FILEREPORT sorted by warning number.
10264000 REPLACE ETEMPTITLE BY FILEREPORT.TITLE;
#
In this case, your editing is limited to just those lines containing the text FILEREPORT.
To do page mode editing using either of these FIND commands, you would have to save your “hit” list on
one page of the terminal and execute a series of PAGE commands on another page of the terminal. A typical
sequence might be:1
FIND /FILEREPORT/:T
Receive the first report shown above.
Switch to a different screen page.
PAGE 10016000
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
10017000 END#;
10018000
10019000FILE
10020000 FILEREPORT
10021000 (KIND=DISK,
10022000 MAXRECSIZE=30, BLOCKSIZE=420, FRAMESIZE=48,
10023000 AREAS=50, AREASIZE=504, FLEXIBLE,
10024000 FILEUSE=OUT, NEWFILE=TRUE, SAVEFACTOR=30),
10025000 % User is to file-equate TITLE.
10026000 TEMPFILE
Edit and transmit changes.

A new page of text is returned.
Switch back to the page with the FIND report.
Determine the starting sequence number of the next hit.
Switch back to the page of text (or to another page).
PAGE 10020000
The page beginning at line 10020000 is returned,
and the cycle continues.
September, 1995
The new PAGEMODE option reduces this all to a single command for you. The command
FIND /FILEREPORT/:P
locates the first reference in your workfile to “FILEREPORT” and displays that line in line 2 of the screen.
The workfile lines after that line follow in normal page mode fashion. For example:
FIND /FILEREPORT/:P
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#;
10018000
10019000FILE
10020000 FILEREPORT
10026000 TEMPFILE
You may edit any of the lines on the screen. When finished, transmit from any place following your last
edit. CANDE will apply the edits to your workfile and then seek out the next occurrence of your target in
the file. For example:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#,
CLOSEREPORT =
CLOSE (FILEREPORT, CRUNCH)#; Transmit from here.
10018000
10019000FILE
10020000 FILEREPORT
returns:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10020000 FILEREPORT
10026000 TEMPFILE
10030000 FILEUSE=OUT, NEWFILE=TRUE, SAVEFACTOR=1);
Note the screen returned. This is not the next page in the workfile that follows the last transmit point. In-
stead, it begins with the next occurrence of the search target in line 2 of the screen.
Thus, you can now locate target text, edit lines that are around it, and move on to the next section contain-
ing the target immediately. There are no more unwanted screens of output. And, there is no need to save a
hit list aside and constantly shuffle between screen pages to figure out where in the workfile you want to go
next. CANDE handles the editing and moving all automatically for you.
Adjusting the View

When editing it is generally useful to see lines that are both before and after the target text. As described so
far, the FIND:PAGEMODE command will give you a page mode display with your target line positioned in line
2 of the screen. This makes your target line the first editable line on the screen. To view any lines prior to
that line, you have to break out of the FIND sequence and use a “-” command, such as
-4
Volume 9.06
to back up and see any prior lines.

Fortunately, you can follow the PAGEMODE modifier with the keyword DOWN to adjust the report so that the
target line appears anywhere (except on line 1, of course) on the screen. The syntax for doing this is:
FIND <delimiter><target><delimiter> : PAGEMODE
DOWN <integer>
This instructs CANDE to position the line containing the target text zero or more lines “down” the screen
from line 2. The <integer> denotes the number of lines the target is moved, and it must be a number be-
tween 0 and the maximum page size, less 2, of the screen. Most screens have a page size of 24 lines, so in
these cases the <integer> must be a number between 0 and 22. The page size of a terminal is determined
by the PAGE option of the TERMINAL command.
An example command would be:
FIND /FILEREPORT/:P D 4
This command causes the line containing the target to be displayed on line 6 of the screen. The response is:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10012000 WRITEDISK (MSG)=
10013000 BEGIN
10014000 REPLACE OUTBUF BY " " FOR 30 WORDS;
10015000 REPLACE OUTBUF BY MSG;
10016000 WRITE (FILEREPORT, 30, OUTBUF); Target Line.
10017000 END#,
10017100
10017200 CLOSEREPORT =
10017300 CLOSE (FILEREPORT, CRUNCH)#;
10018000
10019000FILE
Compare this response to that shown previously, where the target appeared on line 2 of the screen. This
version gives you a number of lines both before and after the search target, so you can really see it in full
context. Again, you may optionally edit any of the lines on the screen. Then simply transmit to move on to
a screen containing the next occurrence of the search target.
When you move on, CANDE will preserve your DOWN specification and automatically apply it to all subse-
quent pages returned during this search. In this case, each screen returned would have the line containing
“FILEREPORT” in line 6 and include 4 lines before the target line.
Note that if there are insufficient lines in the workfile to fulfill the DOWN request, it is ignored. For example,
the file SYM/FINDWARNINGS begins thusly:
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
10000000$ LEVEL 2
10001000COMMENT:
10002000 Program to report all files on the system having
10003000 de-implementation warnings against them.
10004000 ;
10005000PROCEDURE FINDWARNINGS(PARAM);
10006000ARRAY PARAM[*];
10007000BEGIN
10007050$$ SET ALLSCANDEFINES
10007100$$ INCLUDE SCANDEFINES = "INCLUDE/SCAN/DEFINES."
If we use the command:
FIND /FINDWARNINGS/:P D 10
the response will be:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10000000$ LEVEL 2
10001000COMMENT:
10002000 Program to report all files on the system having
10003000 de-implementation warnings against them.
10004000 ;
10005000PROCEDURE FINDWARNINGS(PARAM);
10006000ARRAY PARAM[*];
10007000BEGIN
September, 1995
10007050$$ SET ALLSCANDEFINES

10007100$$ INCLUDE SCANDEFINES = "INCLUDE/SCAN/DEFINES."
There are not 10 lines ahead of the target line in the file, so the DOWN request is ignored.
Similar results are obtained if the DOWN request is larger than the entire size of the file. A file with 2 records
cannot support a DOWN 10 request, so the DOWN request will be ignored.
If you attempt to use a DOWN size that exceeds the page size of your terminal, CANDE will generate an error
message, and the FIND will not be done.
The new +FIND Command

Now let’s examine in more detail how CANDE moves from one “hit” to the next through your workfile.
When you first enter page mode, CANDE returns a full page of text to your screen for editing. Line 1 of
this page contains a command that CANDE must receive in order to properly interpret your page of input.
When working sequentially through the file (by starting with the PAGE command), this command is NEXT.
When using the search and display technique (via FIND:PAGEMODE), this command is +FIND. The appear-
ance of both commands is illustrated by the screen examples given previously in this article.
+FIND tells CANDE to search your workfile and locate the next line which contains the target specified by
the most recently entered FIND command. Each time you enter a FIND command, CANDE saves that tar-
get (and any other options, such as a sequence range, column range, and DOWN request) aside for future ref-
erence. Whenever you enter +FIND, CANDE begins searching, with the line following the “current line”,
for the next occurrence of the search target.
The current line defines the starting point for the next search. If you enter
+FIND
by itself, with no other text, the current line is the line containing the hit that was most recently displayed.
In this case, searching resumes with the next line in the workfile. Thus, if we enter:
FIND /FILEREPORT/:P
and get the response:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#;
10018000
10019000FILE
10020000 FILEREPORT
10026000 TEMPFILE
then if we transmit just:
+FIND
with nothing else, the response will be:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10020000 FILEREPORT
10026000 TEMPFILE
10030000 FILEUSE=OUT, NEWFILE=TRUE, SAVEFACTOR=1);
Volume 9.06
Even though the search target appeared twice on the initial screen, CANDE moves to the next line con-
taining the target — a line we had previously seen.
If you transmit +FIND followed by any number of data lines, the “current line” becomes the last line trans-
mitted. In this case you “skip over” any hits that occur between the old “current line” and the last line in-
cluded in the transmission. This rule applies whether or not workfile changes are included in the lines
transmitted. Therefore, if you transmit back the entire page, searching will resume with the first line in the
workfile which follows that page.
For example, assume again that you are starting with:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#;
10018000
10019000FILE
10020000 FILEREPORT
10026000 TEMPFILE
Now you make some changes and end up transmitting:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#,
CLOSEREPORT =
CLOSE (FILEREPORT, CRUNCH)#;
10018000
10019000FILE
10020000 FILEREPORT Transmit from here.
CANDE will resume the search at line number 10022000. The last line transmitted is line number
10021000, so searching resumes at the line which follows it.
If you want to skip over some occurrences of your target, you can use the command:
+ <integer> FIND
The <integer> denotes the number of occurrences you want to skip. Thus, if you are viewing a page that
contains three occurrences of your target (the original “hit” plus two others), you can skip over the two on
the screen and locate the next hit beyond them in the workfile through the command:
+2FIND
The occurrences you skip over do not have to be already on the screen. You can skip over as many occur-
rences of your target as you want. However, note that there is no -FIND command, so if you miss one that
you wanted, you cannot back up. You will have to start over or use the other page mode commands to lo-
cate a target you’ve skipped.
You can change the DOWN request on any +FIND command. The syntax is:
+ FIND DOWN <integer>
As mentioned above, the DOWN request supplied with the original FIND command is automatically applied to
all subsequent +FIND commands until a new FIND command is entered. +FIND DOWN allows you to change
the DOWN request without respecifying the target or starting the search over. The new DOWN request is ap-
plied to all subsequent +FIND commands. For example:
FIND /FILEREPORT/ :P D 4
+FIND ....*....1....*....2....*....3....*....4....*....5...
10012000 WRITEDISK (MSG)=
10013000 BEGIN
10014000 REPLACE OUTBUF BY " " FOR 30 WORDS;
10015000 REPLACE OUTBUF BY MSG;
Target Line.
September, 1995

10017000 END#;
10018000
10019000FILE
10020000 FILEREPORT
+FIND DOWN 2
+FIND ....*....1....*....2....*....3....*....4....*....5...
10018000
10019000FILE
10020000 FILEREPORT Target Line.
10026000 TEMPFILE
All subsequent +FIND requests will use a DOWN specification of 2 as the search progresses through the work-
file.
You can use either of the options of +FIND described above in a single command. The complete syntax for
+FIND is:
+ FIND
< skip count> DOWN < integer>
As this diagram illustrates, you can skip occurrences and change the DOWN specification in a single com-
mand.
Mixing Editing Commands

The idea behind page mode editing is to make it as visual and an intuitive as possible to edit your file. At
the same time, CANDE must deal with the limitation that it receives inputs as complete screenfuls of data.
Unlike a PC, CANDE does not have the luxury of interpreting each individual keystroke entered by the
user. CANDE must determine what the user wants based upon the command submitted on line 1 and the
text entered on lines 2 through the end of the transmit.
When you display a page of text using the PAGE command, CANDE returns that display headed by the
command NEXT+. When that page is transmitted back, the NEXT+ tells CANDE to expect a screenful of
input lines in a single transmission. CANDE compares the lines sent in against the current ones in the
workfile, using the sequence numbers as a reference. Through this comparison, CANDE determines the
intended edits and applies them to the workfile. Thus, although CANDE does not have the ability to see
the individual keystrokes, it can determine with a high degree of accuracy what changes the user intended
to make to his file.2
After the comparison has been done, and any changes have been applied, NEXT+ instructs CANDE to move
on to the next sequential page of text in the workfile.
When you display a page of text using the FIND:PAGEMODE command, CANDE returns that display headed
by +FIND. When this is transmitted back, +FIND also tells CANDE to expect a screenful of input. The
same comparisons are performed, and any changes are applied against the workfile. However, +FIND in-
structs CANDE to move on to the next occurrence of the search target rather than moving to the next se-
quential page of text.
For maximum flexibility, you must be able to switch modes, as desired, when progressing through a work-
file. You should be able to interrupt a search and step sequentially when that it necessary. Moreover, you
should be able to resume a search, after interrupting it, at any point in the workfile. Fortunately, CANDE
fully supports the ability to do both!
Volume 9.06
You have the option, at any time, to switch between +FIND and traditional page mode operations. For ex-
ample, if you want to edit more lines around your target than appear in the initial report, transmit a page
mode command (SAME, NEXT-, etc.) as the last (or only) input line. This will switch you over to sequential
page mode processing. When you want to resume searching after that, type a +FIND as the last (or only)
input line. In this manner, you can alternate, as needed, between sequential page mode and searching page
mode.
For example:
FIND /FILEREPORT/ :PAGE
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#;
10018000
10019000FILE
10020000 FILEREPORT
10026000 TEMPFILE
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#,
CLOSEREPORT =
CLOSE (FILEREPORT, CRUNCH)#;
10018000
Type the word SAME
10019000FILE
on the last line and
SAME
transmit from there.
The screen you get back is then:
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
10017000 END#,
10017100
10018000
10019000FILE
10020000 FILEREPORT
Note that now you have “NEXT+” at the top of the screen. To switch back into search mode, type a +FIND at
the top of the screen, and transmit just that command. For example:
+FIND ....*....1....*....2....*....3....*....4....*....5...
10017000 END#, Transmit from here.
10017100
You could also enter some edits (with NEXT+) at the top of the screen and type your +FIND as the last input
line. In either case, CANDE will resume searching for the next occurrence of the target.
When you switch between sequential mode and searching mode, CANDE still tracks a “current line” so it
has a defined place to resume searching. If you switch by transmitting +FIND from the top line of the
screen, CANDE will resume searching with the workfile line that follows the text in line 2 of the screen. If
you switch by transmitting +FIND from somewhere else on the screen, CANDE will resume searching with
the line that follows the last line transmitted prior to the +FIND. For example, if you transmit:
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
10017000 END#,
10017100
Transmit here.
September, 1995
10018000
+FIND
10019000FILE
10020000 FILEREPORT
CANDE will resume searching at line number 10019000.
The End of a Search

After the last target has been found, CANDE will respond to your +FIND command with the message [sic]:
#NO MORE OCCURENCES OF TARGET
If you back up in the workfile, by entering a PAGE, NEXT- or - command, that will move your “current line”
back. If you then enter a +FIND command, searching will resume from that point in the workfile, reusing
your previous target and DOWN request. Thus, even after you’ve reached the end of the workfile, you can
back up and search again without repeating the original FIND command.
Improvements to Page Mode Editing
Offset Paging
The DOWN feature is also available in the PAGE command as well. If you’ve ever had to enter a sequence
such as:
PAGE 10050000
-5
(where the negative number is any number between –1 and –22), you will appreciate the PAGE DOWN com-
mand. The syntax is:
PAGE <sequence number> DOWN <integer>
This command combines the PAGE and “-” commands into a single command, saving you one unwanted
page of output. For example,
PAGE 10050000 DOWN 5
gives you a page of output beginning 5 lines before line number 10050000 in the workfile.
If the requested line does not exist, the output begins 5 lines before the first line with a sequence number
larger than the requested one. If there are not enough lines in the workfile to satisfy the DOWN request, it is
ignored.
Range Paging
You can apply a <sequence range> to a PAGE command in much the same manner as you can to a LIST
command. The options for specifying a <sequence range> are:
<sequence number> – <sequence number>
and:
<sequence number> – END
When this option is used, paging begins with the first line having a sequence number greater than or equal
to the first <sequence number>, and it continues through the last line that has a sequence number less than
or equal to the second <sequence number>. After the last line is displayed, paging stops with the message:
#DISPLAY COMPLETE
The <sequence range> is only in force so long as you continue to transmit NEXT+ commands. If you trans-
mit any other page mode command — such as SAME, +, -, or even NEXT- — the <sequence range> limit is
Volume 9.06
dropped. You can make changes to your workfile while operating within a <sequence range>. However,
the limit will only stay in effect if you use strictly NEXT+ to move from screen to screen. Again, any com-
mand other than NEXT+ will break the limit and return you to normal (entire file) paging.
Specifying END on the <sequence range> is really no different than using the original PAGE command:
PAGE <sequence number>
You can still back up from your starting location by using a NEXT- or - command, and you can page forward
to the end of the file. This syntax simply eliminates an annoying error message that used to occur if you
habitually typed in <sequence number> - END because you were used to the LIST command.
Note that PAGE END, without any <sequence number> or range, has always been available. This command
displays the last page of the workfile. You can then move backward as desired.
Horizontal Scrolling
Page mode editing was originally constrained on two fronts:
• the width of the terminal;
• the length of the text portion of a file.
The standard terminal has an 80-character line width. Most of the A-Series file types use 8-digit sequence
numbers. Displaying the sequence number leaves only 72 spaces on each line for the edit area. Most of the
standard file types have a text area of 72 characters, so this is not a problem in the majority of cases.
Some file types do not have a 72-character text area. Some are smaller, such as all file types that belong to
the COBOL family. COBOL files only have a 66-character text area. When you display a COBOL file in
page mode, blank space is left on the right-hand end of the screen. Each line, sequence number included,
only uses up 72 characters. CANDE page mode has no problems editing files in this category.
There are also file types which have text areas that exceed 72 characters. JOB files, for example, have an 80-
character text area. DATA, CDATA, and CSEQ files allow text areas of varying lengths. CANDE will edit these
files up to a 255-character line length. However, until recently, page mode editing was restricted to the first
72 columns of each record alone.
Now, with the 4.1 enhancements, you can display and edit any 72-character column range in your file. If
you have a data file with records larger than 72 characters, you can adjust the view to display the column
range that you want by adding a <column specification> to your PAGE command. The syntax is:
PAGE @ < single column>

< start column> - < end column >
+ < number of columns >
-
Everything following the at sign (@) is part of the <column specification>. Thus, you have four possible
<column specification>s:
@ <single column>
@ <start column> – <end column>
@ + <number of columns>
@ – <number of columns>
Suppose you have a job file and you want to edit text in columns 31 through 80. You could use the com-
mand:
PAGE @31-80
This would display just columns 31 through 80 of your job file for editing. The result would be:
NEXT+ ....*....4....*....5....*....6....*....7....*....8
00001000UEUE=2;
00002000
September, 1995
00003000
00004000
00005000IC96
00006000
00011000
00012000
00013000 07 08 09 0A 0B 0C 0D 0E 0F 00000100
00014000 17 18 19 1A 1B 1C 1D 1E 1F 00000200
00015000 27 28 29 2A 2B 2C 2D 2E 2F 00000300
You can make any changes to the displayed text, and these changes will be incorporated into your workfile.
Data in columns not shown is not changed by CANDE. Therefore, if you are displaying just columns 31
through 80 of a job file, the data in columns 1 through 30 is unaffected by any changes you transmit.
Note that this gives you a means of editing 80-column <data deck>s in your job files. Previously, columns
73 through 80 were not viewable through page mode. But this is where the all-important sequence num-
bers have to be written when compiling a merge deck against an ALGOL (and most other language) pro-
gram. Now you can view and edit those sequence numbers in page mode, as shown above.
The four <column specification> options give you a variety of ways to choose your column display.
@ <single column> displays only a single column of text.
@ <start column>-<end column> displays any selected range of text. The range may go from a single
column up to the width of the screen. If the range exceeds the editable line width of the terminal, it is
truncated by CANDE to fit the line width. (The editable line width is the line width, as specified by the
TERMINAL command, minus the space used by the sequence numbers.) CANDE does not wrap the excess
text onto a continuation line.3
@ + <number of columns> adjusts the current view to a higher-numbered column range.4 The <number
of columns> value is added to the number of the leftmost column to determine the first column of the new
display. For example:
PAGE @31-80
NEXT+ ....*....4....*....5....*....6....*....7....*....8
00001000UEUE=2;
00002000
00003000
00004000
00005000IC96
00006000
00011000
00012000
00013000 07 08 09 0A 0B 0C 0D 0E 0F 00000100
00014000 17 18 19 1A 1B 1C 1D 1E 1F 00000200
00015000 27 28 29 2A 2B 2C 2D 2E 2F 00000300
PAGE @+10
NEXT+ ....*....5....*....6....*....7....*....8..SSSSSSSS
00001000 00001000
00002000 00002000
00003000 00003000
00004000 00004000
00005000 00005000
00006000 00006000
00011000 00011000
00012000 00012000
0001300009 0A 0B 0C 0D 0E 0F 0000010000013000
0001400019 1A 1B 1C 1D 1E 1F 0000020000014000
0001500029 2A 2B 2C 2D 2E 2F 0000030000015000
The final display is of columns 41 through 90 of the workfile.
@ - <number of columns> adjusts the current view to a lower-numbered column range. The <number of
columns> value is subtracted from the number of the leftmost column to determine the first column of the
display.
Continuing the above example, we could enter:
Volume 9.06
PAGE @-20
NEXT+ ....*....3....*....4....*....5....*....6....*....7
00001000NTABLES; QUEUE=2;
00002000GEN;
00003000
00004000
00005000 NAME EBCDIC96
00006000 NAME LE
00011000
00012000
0001300004 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0001400014 15 16 17 18 19 1A 1B 1C 1D 1E 1F
0001500024 25 26 27 28 29 2A 2B 2C 2D 2E 2F
The final display is now of columns 21 through 70 of the workfile.
Once a <column specification> has been applied, CANDE retains it until it is canceled or until you change
workfiles. The <column specification> is applied to all subsequent NEXT, +, -, SAME, FIND:PAGEMODE, and
+FIND commands.
To cancel the <column specification>, use:

PAGE *
This returns your page mode display to the default column range for the file type of your workfile. That
default is columns 7 through 72 for the COBOL family of files, 6 through 80 for CSEQ files, and 1 through
72 for most all other types of files.
Horizontal Scrolling vs. Special Fields

CANDE recognizes that each line of a file is normally divided into three sections:
• the text portion;
• the sequence number;
• the Mark ID field.
The CANDE editor’s principal function is to edit the text portion of a file. However, as you shift your view
through horizontal scrolling, you can bring the other fields into your screen. For example, if we load
SYM/FINDWARNINGS, an ALGOL program, as our workfile and display columns 41 through 90 of it, we will
get:
PAGE @41-90
NEXT+ ....*....5....*....6....*....7..SSSSSSSSMMMMMMMMMM
10000000 10000000
10001000 10001000
10002000tem which have 10002000
10003000ainst them. 10003000
10004000 10004000
10005000 10005000
10006000 10006000
10007000 10007000
10007050 10007050
10007100EFINES." 10007100
10008000IRECTORY/DEFINES." 10008000
Both the sequence number field and the Mark ID field are visible in the edit area of the screen.
CANDE has two rules which come into play when either of these fields are displayed. These rules are:
1. You cannot change any data in the sequence number field, even if it is displayed in the edit area.
2. If any part of the Mark ID field is displayed in the edit area, the entire field is treated as a user text field.
The sequence number field is not editable in order to preserve the data integrity of the workfile. If you
want to change a record’s sequence number, you can do so using the RESEQ, MOVE¸ or (if you want to copy it)
the INSERT commands. Sequence numbers are CANDE’s reference points for identifying data records.
Therefore, if you make any changes to data in the sequence number field, they are ignored.
September, 1995
PAGE
< sequence number>
- < sequence number> DOWN < integer>
END
END
*
@ < single column>
< start column> - < end column >
+ < number of columns >
-
Figure 1
Full Syntax of the PAGE Command
The purpose of the Mark ID field is to provide a record of patches to a file. Before editing a file, you can
establish a Mark ID value for your session through the command:
MARKID <delimiter><id><delimiter>
You can change this value at any time with another MARKID command. You may also cancel it with the
command:
MARKID –
If you have a Mark ID value set for your session, every change you make to your workfile is tagged with that
<id> value. The <id> value is written automatically into the Mark ID field of each line as you alter it.
If you use horizontal scrolling to display any portion of the Mark ID field on the screen, automatic tagging
of the workfile is disabled. In this case, any setting by the MARKID command is ignored. Mark ID action
will not resume until you change the view so that no part of the Mark ID field is displayed on the screen.
If any portion of the Mark ID field is visible, you can alter the visible portion directly just as you would the
text portion. The non-visible portion is automatically set to blanks.
The display on line 1 of the screen tells you what portions of the file you are viewing. The text portion is
marked by the standard column notation, with numbers, dots, and asterisks. The sequence field is marked
by a heading of all S’s. The Mark ID field is headed by all M’s. For example, columns 73 through 80 of an
ALGOL file are the sequence field, and columns 81 through 90 are the Mark ID field. You can tell this
from the page mode display of columns 41 through 90 of SYM/FINDWARNINGS on the previous page.
These labels serve as a reminder of where you are working.
Summary of the PAGE Command

The complete syntax for the PAGE command is shown above in figure 1. Use this command to apply or
change either <sequence range> limitations or <column specification> views. This diagram shows the cor-
rect order in which the various components of the command must be specified.
Editing Files that Contain Non-Printable Characters

You can now edit files that contain records with non-printable characters. To do this, you must define an
<escape character> which will be used to delimit those characters on your terminal. Once defined, the <es
Volume 9.06
cape character> will appear both before and after each sequence of non-printable characters. The non-
printable characters themselves will be displayed using two-character hexadecimal codes.
To define an <escape character>, use the ESCAPE command. The basic syntax is:
ESCAPE HEXADECIMAL = <special character>
For example,
ESC HEX = !
Once the character is defined, you must use the character in pairs. The first use denotes the start of a
hexadecimal sequence. The second denotes the end of that sequence. The characters in between must be
valid hexadecimal characters (i.e., 0 – 9 and A – F; only upper case A through F are valid). For example:
100Use !18!these!1E! instructions:
CANDE interprets the “18” and the “1E” in this line as being the EBCDIC characters CAN and RS, respec-
tively.
When you have an <escape character> defined, each occurrence of a single non-printable character in the
file is displayed thusly:
<ec><sp><hex pair><sp><ec>
where <ec> is the <escape character> and <sp> is a blank space. For example, listing the above line would
return:
100 Use ! 18 !these! 1E ! instructions:
If you turn off the <escape character> feature, listing this same line will display (on a TD830-compatible
terminal):
100 Use these| instructions:
and the word these will be blinking at you.

If you display a line with two or more non-printable characters adjacent to each other, CANDE only uses a
single escape sequence to display them. Each non-printable character is displayed as a pair of hexadecimal
codes, and each pair is separated by a space. For example, if instead of just CAN, the line above contained
both SUB and CAN prior to the word “these”, an escape mode display of the line would return:
100 Use ! 3F 18 !these! 1E ! instructions:
The two non-printables SUB and CAN are displayed in a single escape sequence.
Take care that you do not define a character you want to use in your file as the <escape character>. For
example, if you set your <escape character> to the per cent sign (%), you will have to change your habits
whenever you want to use a per cent sign in your file. To use the <escape character> in your file, you must
type it twice. When CANDE displays a line containing the <escape character> to you, it will print it twice.
Therefore, if you’ve entered:
ESC HEX = %
and then you list a file containing the line:
%%%% Heading One %%%%
you will get:
100 %%%%%%%% Heading One %%%%%%%%
Each per cent sign is doubled in the display. Moreover, each pair of per cent signs that you transmit back is
reduced to a single per cent sign when stored in the file.
For best results, choose a character you are not going to use in your file. Then you will be spared some
rude potential surprises.
Escape character editing is available in both line mode editing and page mode editing. When working in
page mode editing, you have to realize that there is no longer a column correspondence between what you
see and what is stored in the file. The extra space used on your screen is condensed when the data gets
stored in the file.
September, 1995
For example, consider:

PAGE
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
00000100Use ! 18 !these! 1E ! instructions:
#DISPLAY COMPLETE
The display shows the text ! 18 ! in columns 5 through 10. In truth, these 6 columns represent one EB-
CDIC character that is stored in column 5 of the file, and the word these is stored in columns 6 through
10. If you list the file using SYSTEM/DUMPALL, you will see that the character only uses one column in the
file. Also, if you turn off escape mode and then PAGE the file, you will get a true picture of what column
each character is stored in; viz.:
ESC HEX NONE
#UPDATING
#NO ESCAPE HEXADECIMAL CHARACTER DEFINED
PAGE
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
00000100Use these| instructions:
#DISPLAY COMPLETE
Similarly, if there are two non-printables on the line, the column numbering will get even further skewed:
ESC HEX = !
#UPDATING
#ESCAPE HEXADECIMAL = !
PAGE
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
00000100Use ! 3F 18 !these! 1E ! instructions:
#DISPLAY COMPLETE
Now the expression covering columns 5 through 13 in the display represents a mere 2 columns (numbers 5
and 6) in the actual file.
You can reduce the amount of space used by CANDE in the display through the SQUASHED option. The
syntax for specifying this is:
ESCAPE HEXADECIMAL = <special character> SQUASHED
For example:
ESC HEX = ! SQUASHED
When SQUASHED is selected, CANDE omits the extra spaces between the hexadecimal pairs. For example,
listing our example line returns:
100 Use !3F18!these!1E! instructions:
This feature is most useful when editing in page mode, where the response will be:
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
00000100Use !3F18!these!1E! instructions:
#DISPLAY COMPLETE
Now the escape sequences use less space, which may help you out in page mode. However, they are less
obvious than they were in the non-squashed mode.
When entering escape sequences into your file, you do not need to use the extra spaces; they are optional.
CANDE will always add them (if SQUASHED is not selected) when returning the line to you.
You must always enter your hexadecimal numbers in pairs. If you do not, you will get an error message.
For example:
NEXT+ ....*....1....*....2....*....3....*....4....*....5...
00000100Use !F18!these!1E! instructions:
#EVEN NUMBER OF HEXADECIMAL CHARACTERS EXPECTED AT LINE 2

PREVIOUS VALID SEQUENCE NUMBER=0
You will get a similar error if you use a lower-case letter for a hexadecimal character. Always remember to
use capitals for the characters A through F.
Volume 9.06
ESCAPE HEXADECIMAL
?
.
NONE
= < special character>
SQUASHED
Figure 2
Syntax for the ESCAPE HEXADECIMAL Command
The full syntax for the ESCAPE command is shown above, in figure 2. This syntax enables you to set, cancel,
and query the current escape character.
To cancel the current escape character, use:
ESC HEX NONE
If an <escape character> was previously defined, that definition is canceled. If you display text that contains
an unprintable character while the escape feature is turned off, that character will be sent to your terminal
unfiltered. For example:
ESC HEX = !
LIST
100 Use ! 3F 18 !these! 1E ! instructions:
#
ESC HEX NONE
LIST
100 Use these| instructions:
#
Note that it can be extremely dangerous to send unfiltered non-printable characters to your terminal in
some cases. For example, if you are running on a poll/select line, and you send text that contains an ETX
(hex 03) character to your terminal, you can hang your terminal. Unless you are absolutely certain that your
file does not contain characters that interfere with your communication protocol, always have an <escape
character> of some sort defined for your session.
The command
ESC HEX .
is equivalent to
ESC HEX NONE
Both commands turn off the escape feature.
If you forget what your currently defined <escape character> is, you can determine it through either the
command:
ESCAPE HEXADECIMAL
or:
ESCAPE HEXADECIMAL ?
Both report the current <escape character>. For example:
ESC HEX ?
If no <escape character> is currently defined, the response is:

September, 1995
No <escape character> is defined when you start a session. To use the escape feature, you must enter at
least one ESCAPE command when you start a new CANDE session.
Protection of your Workfile

One of the perennial problems facing CANDE users is the risk of concurrent updating. If two people are
working under the same usercode, they can both load the same permanent file as a private workfile.
Changes are applied to each workfile separately. However, when the SAVE commands are entered to store
the changes, all sorts of problems can occur.
This problem can also occur when a single user uses multiple CANDE windows. All you have to do is load
a file on one window, make some changes, get interrupted, move to another CANDE window, load the
same file, and make other changes to it. Then you are in the same situation.
To reduce the risk of this occurring, CANDE now gives a warning if you GET a file that someone else has
loaded as a workfile. Moreover, it loads said file as an untitled workfile. For example:
GET MYFILE
#WORKFILE IS NOT NAMED; SOURCE IS (Q)MYFILE ON CONTINUUM (IN USE BY PSJC10/CANDE/2,LSN
= 17): SEQ, 1011 RECORDS
If the file is in use by a program, but not loaded as anyone else’s workfile, just the warning is given. You will
still retrieve the file under its original name. For example:
GET MYFILE
#WORKFILE MYFILE(MAY BE IN USE BY A PROGRAM): SEQ, 1011
RECORDS
In both cases, you can proceed to edit the file if you want and save it. However, in most cases, you will
probably want to immediately discard the workfile and then go talk to the other person who is working on
the same file.
If someone has loaded a particular file as his workfile, and you absolutely insist on loading the same file un-
der its original name as your workfile, you can do so with the OVERRIDE option. The command is:
GET <file name>:OVERRIDE
This will always load the designated file as your workfile under its original name. It will still give you the
warning, but now both of you will have the file loaded under the original name. Unless you are absolutely
certain that the other person is not editing the file at all, this is an extremely dangerous thing to do!
For those who thrive on danger, it is possible to make the OVERRIDE option the default action. From SSR
41.2 forward, there is a session option available called GETWARN. The syntax for using it is:
SO GETWARN
? = SET
DEFAULT
RO GETWARN
?
Use the RO syntax to reset the option. Use the SO syntax to either set the option or to set it to the “default.”
If you reset the option, the GET statement will always assume that you want to do a GET..:OVERRIDE. It
will give you a warning when you load a workfile that is in use, but it will let everyone load the file under its
original name.
If you set the option, the GET statement will not automatically load as your workfile a file that someone else
already has loaded. Instead, it will load such a file as an untitled workfile. You will have to type in
:OVERRIDE to load the file under its original name.
The third option, DEFAULT, lets you default to the system-wide default set by your site administrator.
For site administrators, there is a new CANDE runtime option called NOGETWARN, which is set via the ?OP
command. The syntax is:
Volume 9.06
? OP NOGETWARN
+
-
By default, NOGETWARN is reset. In this condition, the GET statement will not load a workfile under its origi-
nal name if it is in use by another user. If you set NOGETWARN, the system-wide default will be equivalent to
GET..:OVERRIDE.
NOGETWARN only has effect on users who run with their GETWARN session option set to DEFAULT. If a user
sets his GETWARN option to either SET or RESET, his selection will override.
The defaults for both options, as provided by Unisys, are the safest options. These defaults are:
?OP - NOGETWARN
and
SO GETWARN = DEFAULT
These cause the GET statement to load a workfile that is currently loaded elsewhere as an untitled workfile.
If you do load a file that someone else is currently working on, that person will receive a warning message as
well. This message is:
#YOUR WORKFILE MAY BE UPDATED BY PSJC10/CANDE/3, LSN = 18
It is displayed each time someone attempts to load the file as a workfile.
Because of this new feature, it is now a good idea to always REMOVE a workfile when you are done with it. If
you GET a file, make some edits, and save it, you will still be marked as the user of the file after it is saved. If
you then go out for lunch, you will remain the user of the file for all of that time, even though you may not
be making any edits to it. To delink yourself from the file, you must either get a different file or execute the
command:
REMOVE
This will delink you from the file, but it will leave the saved copy safely on disk for the next user.
Warning! If your site runs two or more copies of CANDE, you should always make sure that those who
might be sharing files always work from the same copy. CANDE uses its internal tables to determine if a
particular file is loaded as someone’s workfile. If two users, each on a different CANDE, attempt to load
the same file as a workfile, neither CANDE will notice the conflict, and no warning will be given.
Setting Default Specs for your Terminal

The TERMINAL command is not directly involved with editing. Rather, it provides various specifications that
the editing commands use in handling both input and output with your terminal.
Most of the values set by the TERMINAL command should be set by your system administrator to appropriate
defaults. Except for the DOWN and FORMSCAPABLE options, you will rarely need to change the defaults pro-
vided by the system administrator.
The complete syntax for the TERMINAL command is given in figure 3. Using this command, you may pro-
vide the following information to CANDE regarding your terminal:
Keyword Function
BUFFER Denotes that the terminal is buffered and, optionally, the size of the buffer in characters. Buffered
means that the terminal can receive and store data locally before displaying it to the user. The
number represents the maximum number of characters CANDE can send in a single output.
Range: 0 – 9168 (characters).
CONTINUOUS
This instructs CANDE to write all outputs continuously. It is useful on hardcopy terminals. On a
screen device, continuous outputs will overwrite earlier outputs, so you will not see all of a report.
(See WAIT.)
September, 1995
DOWN The default number of lines “down” from line 2 that the current line is to be displayed when using
the PAGE, FIND:PAGEMODE, and +FIND commands.
Range: 0 – (PAGE size - 2).
FORMSCAPABLE
If you set this option to TRUE, it means that your terminal understands TD830-style escape se-
quences. In this case, CANDE will add characters which will jump the cursor past the NEXT+
when sending a page mode output. By default, this option is always FALSE.
HARDCOPY This means that the terminal is not a screen device. The output is printed onto paper or some
permanent medium. (See SCREEN.)
LINE The number of characters in each line of the screen. (Same as WIDTH.) The standard value is
80.
MAXOUTPUT
This means the same as BUFFER. It denotes that the terminal is buffered and the maximum
number of characters the terminal can store. CANDE ensures that no single output transmission
exceeds the MAXOUTPUT of the terminal.
PAGE The number of lines on the screen, not counting the “status line” at the bottom. The standard
value is 24.
Range: 0 – 255 (lines).
Setting the value to 0 or 1 automatically sets CONTINUOUS. Setting the value to 2 or higher
automatically sets WAIT.
SCREEN This means that the terminal is a screen device. (See HARDCOPY.)
UNBUFFERED
This means that the terminal does not have buffering capability. The terminal can only function in
single line mode, and it displays each character as it is sent from CANDE. An UNBUFFERED
terminal cannot use CANDE page mode editing.
WAIT This instructs CANDE to pause after each page of output. A “page” is the number of lines set by
PAGE, above. After PAGE lines have been written, CANDE will wait for a “null input” before con-
tinuing. This is useful on screen devices where you need to read the output before continuing. It
is irritating on hardcopy devices. (See CONTINUOUS.)
WIDTH The number of characters in each line of the screen. (Same as LINE.) The standard value is 80.
WRAPAROUND
Tells CANDE how the terminal behaves after receiving the last character of a line. If WRAP-
AROUND is TRUE, the terminal automatically moves to the next line when a line is filled. In this
case, CANDE does not append a carriage return/line feed to each line when writing page mode
output to the terminal. If WRAPAROUND is FALSE, the terminal does not move to the next line
when a line is filled. In this case, CANDE must append a carriage return and line feed to each line
of a page mode output.
If you set your line width to a value smaller than that of your physical terminal, you will want to set
WRAPAROUND to FALSE when using page mode. Otherwise, the lines will be displayed in a
jumble.
"<character>"
If a line of output exceeds the line width of the terminal, CANDE wraps the line to the next. To in-
dicate that the line has been wrapped, this <character> is appended at the end of the line. The
default wrap character is the backward slash (\).
This feature is not used by page mode editing. It is for report-style outputs, such as those gener-
ated by the LIST or FIND..:TEXT commands.
Volume 9.06
TERMINAL
BUFFER
< number of characters >
CONTINUOUS
DOWN < number of lines>
FORMSCAPABLE
TRUE
FALSE
HARDCOPY
LINE < number of characters in the line >
MAXO UTPUT
< number of characters >
PAGE < number of lines>
SCREEN
UNBUFFERED
WAIT
WIDTH < number of characters in the line >
WRAPAROUND
TRUE
FALSE
" < character> "
Figure 3
Syntax for the TERMINAL Command
To successfully use page mode editing, your terminal must be a screen device capable of displaying at least
3 lines of output. The capabilities of your terminal are determined by the MAXOUTPUT (or BUFFER), LINE (or
WIDTH), and PAGE options. The total number of lines your terminal can display is the minimum of:
• the PAGE specification;

• MAXOUTPUT ∋ LINE
If the number of lines is adequate, and SCREEN is true, you can use page mode editing.
It is very critical that your LINE and PAGE specifications, as reported by the TERMINAL command, match the
true dimensions of your terminal. CANDE formats page mode output — and interprets the input — based
upon these specifications. If your TERMINAL specifications do not match those of the device you are using,
the page display output by CANDE will be incorrect, and CANDE will not correctly interpret your input.
If you set WRAPAROUND to FALSE, you can use a line width that is smaller than the true line width of your
terminal in page mode editing. As implemented in SSR 41.2, changes applied in page mode are only ap-
plied to the data that is displayed on the screen. Columns of the workfile not displayed are not affected by
any edits. Thus, you can edit using a smaller line width, but you cannot edit by trying to use a line width
that is larger than the real line width of your terminal.
September, 1995
Most of the TERMINAL attributes will be set for you by your system administrator. Only in rare cases will
you need to make any changes. If you need to set the LINE, PAGE, and SCREEN attributes, you can do it us-
ing three separate commands, or you can combine it all together into a single command such as:
TERMINAL LINE 80 PAGE 24 SCREEN
Note that there is no comma or other separator between the different attributes.
There are only two TERMINAL specifications that cannot be automatically set by your site administrator:
DOWN and FORMSCAPABLE.
TERMINAL DOWN <integer> sets a “default” DOWN specification for your FIND, +FIND, and PAGE commands.
As we stated previously, you can use a DOWN specification in each of these commands. For the PAGE com-
mand, that specification applies only to the one command. For FIND and +FIND, it applies to the current
command and all subsequent +FIND commands used on the same search. When a new FIND command is
entered, the DOWN specification used with the previous FIND is discarded.
Through TERMINAL DOWN you can set a more permanent DOWN value. This value becomes the default speci-
fication that is used unless a DOWN specification is included with the PAGE, FIND, or +FIND command. Thus,
if you always want your page mode displays to be offset 4 lines down the screen, the single command:
TERMINAL DOWN 4
will set that as a default for the duration of the CANDE session.
TERMINAL FORMSCAPABLE TRUE activates an option of page mode that was implemented in an earlier re-
lease. This command tells CANDE that your terminal supports TD830-style screen instruction codes. If
you set FORMSCAPABLE to true, CANDE will automatically position the cursor after the NEXT+ on each
screen of page mode output. This can make it easier to page through a series of screens you are not updat-
ing.
When you make changes with the TERMINAL command, remember that they are only in force for the dura-
tion of your session. If you log off (via BYE or HELLO), the TERMINAL specifications will revert to the site-
assigned defaults, and your DOWN and FORMSCAPAPBLE specifications will revert to 0 and FALSE, respectively.
Similarly, if you are running multiple CANDE windows under COMS, each CANDE window will start with
the site-assigned defaults for TERMINAL, and you will have to change each window individually. This rule
also applies to any session options you set (such as GETWARN) and any <escape character> you define.
If you always want to use the same values, you can put your TERMINAL preferences into a <startup file>.
This is a file similar to a DO file except that it is automatically executed whenever you begin a CANDE ses-
sion. The next article in this series describes how to use <startup file>s to ensure that your TERMINAL,
ESCAPE, and session options are all defined as you want them each time you start a new CANDE session.
1
For formatting purposes only, all of the page mode “screens” shown in this article are 53 columns wide and 12 lines in
height. On a standard terminal, they would be 80 columns wide and 24 lines in height.
2
Note that this technique is fine for lines that are added and lines that are changed. It is not adequate for lines that are
deleted. For this reason, CANDE does not change or delete lines that you have deleted from your screen. To delete a
line from the workfile, you must either use the VOID command or the DELETE command.
3
Moreover, if you lie to CANDE and set your line width (via the TERMINAL command) larger than your actual line
width, you will court disaster. Text may be wrapped around when displayed to you, depending upon your terminal and
its option settings. However, when you transmit the page back in, CANDE will get very confused and your changes will
not be accepted. The line width and page specifications must not exceed the physical characteristics of your terminal
for page mode editing to work correctly.
4
The CANDE Operations Reference Manual states that @+ “shifts the column range of records to the left.” In my
opinion, it shifts it to the right. Certainly my view of the text moves to the right, not the left. To avoid confusion, I’ve
chosen different wording.
Volume 9.06
CANDE: Session Control Features / 25
CANDE: Session Control Features
we said at the beginning of this issue, CANDE is both an editor and a system shell. The shell com-
mands provide access to the various functions of the A-Series computer. In this article and the next
we will present several shell enhancements that have been added since the publication of The Com-
plete CANDE Primer. All of these exist in SSR 41.2, though some were added prior to that release.
Startup Files
Twenty-one years ago, when I was a programmer apprentice at Pacific Bell in Sacramento, California,
we used a timeshare service (Remote Computing Corporation [a.k.a., RCC]) which sold computer
time on a Burroughs B5500. The operating system shell on that system was one developed by RCC
named RALPH.1 RALPH had the look and feel of B6700 CANDE, but in those days no one cared
about such things. However, RALPH had a few enhancements over CANDE. One of those enhancements
was a feature whereby you could instruct RALPH to automatically execute a series of commands each time
you logged on.2 These commands could be any legal RALPH commands. Typically, they configured your
session with the options you normally used when working.
To use this feature in RALPH required two steps:
1. You first created a file containing the commands to be executed.
2. You then used a special RALPH command which stored that file as your “log on” file.
Once those two steps were complete, your file was automatically executed each time you logged on.
A few years later this concept became more commonplace when it was introduced onto micro-computers. I
don’t remember if CP/M™ had this feature, but MS-DOS™ continues to have it to this day. In MS-DOS,
you can store any sequence of shell commands in a file titled AUTOEXEC.BAT. The file must be on your boot
drive. If it is there, it will be executed each time you boot the machine.3
In Mark 3.7, Unisys added a similar feature to CANDE.4 The CANDE implementation requires that you
create a file of CANDE commands, just like the RALPH implementation. Then, for CANDE to recognize
it, you give it a specific name. In CANDE, this file is called a <startup file>.
A <startup file> is just like a DO file. It may contain any CANDE command that is valid in a DO file. It may
not use parameters, as DO files now can, but that is the only restriction.
To designate a file as your <startup file>, you must assign it your site-defined <startup name>. The
CANDE default for the <startup name> is CANDE/STARTUP, but that can be changed through the ?STUP
operator command.5 Once you have given your file the proper name, it will become active the next time
you log on.
The <startup file> is executed each time you log on to a new CANDE session. The three ways to log on
that activate the <startup file> are:
• You open a CANDE dialog from COMS through the ?ON command.
• You start a new session using the HELLO command.
• Your terminal is connected directly to CANDE through an NDLII protocol and you start a dialog.
Note that SPLIT, CHARGE, and so forth do not cause the execution of the <startup file> because session op-
tions are retained when you change sessions using these commands.
When CANDE searches for your <startup file> it performs an 8-step search. The first file found in this
sequence is executed as the <startup file>.
To begin the search, CANDE appends your station name to the <startup name>. Thus, if the <startup
name> is CANDE/STARTUP, your station name is PSJC10, and your <family specification> is DISK =
CONTINUUM OTHERWISE DISK, the first file CANDE will look for is:
September, 1995
CANDE/STARTUP/PSJC10 ON CONTINUUM
under your usercode. It will then progressively do the remaining steps of the standard system four-way
search, looking under *, then under your usercode on the alternate family, and finally under * on the alter-
nate family. For example, if your usercode is Q, the four names searched will be:
(Q)CANDE/STARTUP/PSJC10 ON CONTINUUM
*CANDE/STARTUP/PSJC10 ON CONTINUUM
(Q)CANDE/STARTUP/PSJC10 ON DISK
*CANDE/STARTUP/PSJC10 ON DISK
If you always work at the same terminal — and always connect directly in using the same station name —
CANDE will find your <startup file> and execute it.
However, if you ever work from home, using a dial-in connection, or connect through station transfer from
one A-Series host to another, your station name may vary when you log on. Fortunately, CANDE has a
backup plan to address this situation. If CANDE cannot find the <startup file> using the four steps given
above, CANDE will attempt another search without appending the station name. In this case, the search
will be in the same four locations for a file with the <startup name> alone. Using the above example, the
search would be:
(Q)CANDE/STARTUP ON CONTINUUM
*CANDE/STARTUP ON CONTINUUM
(Q)CANDE/STARTUP ON DISK
*CANDE/STARTUP ON DISK
Thus, you can choose the option that best fits your working habits, whether you always come in on the same
station or whether you never know what station you will be coming in on.
A <startup file> can contain a DO command. This enables you to have several different <startup file>s
which execute other files in order to set your session preferences. For example, if you want mostly the
same options set on stations PSJC10 and PSJC11, but need a couple of differences, you could create two
<startup file>s and have them each perform a DO on a common file. For example:
#FILE CANDE/STARTUP/PSJC10
100 TERM LINE 80 PAGE 24 WAIT
200 DO CANDE/PREFERENCES
#FILE CANDE/STARTUP/PSJC11
100 TERM LINE 132 PAGE 24 WAIT
200 DO CANDE/PREFERENCES
Thus, PSJC11 is set up as a 132-character line terminal, while PSJC10 is an 80-character line terminal. All
of the other options for the two terminals are the same.
This leads us now to a discussion regarding the content of your <startup file>s. <Startup file>s allow you to
tell CANDE what your session preferences are each time you log on. You are able to tell CANDE to set
these options itself so you don’t have to be bothered with doing it manually. Each time CANDE is im-
proved, more options are added. To date, there are several options available through the TERMINAL com-
mand, several through the SO and RO commands, and even some special purpose options, such as that set
through the ESCAPE, CONTINUE, and PDIR commands. By using <startup file>s, you can have CANDE
automatically configure all of these options to exactly what you want during your session.
Since we ended the last article in this series with a discussion of the TERMINAL command, let’s start our ex-
amples there. Suppose you are a regular user of a dial-in line, and since you use a screen device, you know
your terminal can handle CANDE page mode. However, your network administrator is of the old school,
and he configures all of the dial-in lines as hardcopy terminals with a page size of 1 line. To make your ter-
minal page-mode capable each time you log on, you could do the following:
MAKE CANDE/STARTUP
#WORKFILE CANDE/STARTUP: SEQ
100TERM PAGE 24 LINE 80 SCREEN
SAVE
#UPDATING
#WORKSOURCE CANDE/STARTUP SAVED
Volume 9.06
Providing your terminal has 80-character lines and 24 data lines on the screen, this will do the job. Each
time you log on from this point forward, CANDE will execute your <startup file>, CANDE/STARTUP, and
properly set your terminal attributes.
After reviewing the new 4.1 features in the previous article, you might now want to set a few other options
as well. In particular, if you would like your default DOWN specification to be 4 lines and you want CANDE
to position the cursor for you after the word NEXT when working in page mode, you could add the line:
200TERM DOWN 4 FORM TRUE
TERMINAL commands are cumulative, so the second command does not cancel the settings of the first one.
Following this, you might want to set a default <escape character>, a default <continuation character>, and
make sure that in-use files are loaded as untitled workfiles. This is easily done by adding three more lines:6
300ESC HEX = ~
400CONT = %
500SO GETWARN = SET
Now save this file, and all of these options will automatically be set each time you log on. The complete file
is:
#FILE CANDE/STARTUP
100 TERM PAGE 24 LINE 80 SCREEN
200 TERM DOWN 4 FORM TRUE
300 ESC HEX = ~
400 CONT = %
500 SO GETWARN = SET
#
When you log on, CANDE will display each of the commands, and the corresponding responses, as it exe-
cutes them. For example:
HELLO Q/HUMAN
#END SESSION 0434 ET=10:31.4 PT=3.4 IO=1.3
#USER = Q 18:16:02 06/30/95
#MicroA:27910 CANDE SSR 41.2 (41.253.0182) AT A00SJC2

#YOU ARE PSJC10/CANDE/1(17)
#SESSION 0436 18:16:02 Friday, June 30, 1995 (PST)
#
#FILE (Q)CANDE/STARTUP ON CONTINUUM
#
TERM PAGE 24 LINE 80 SCREEN
#LINE = 80, PAGE = 24, MAXOUTPUT = 1920, MAXINPUT = 1920,
SCREEN, WAIT, WRAPAROUND = TRUE, FORMSCAPABLE = FALSE,
DOWN = 0, "\"
TERM DOWN 4 FORM TRUE
SCREEN, WAIT, WRAPAROUND = TRUE, FORMSCAPABLE = TRUE,
DOWN = 4, "\"
ESC HEX = ~
#ESCAPE HEXADECIMAL = ~
CONT = %
#CONTINUATION CHARACTER = %
SO GETWARN = SET
#GETWARN SET
You might also want to add a default print destination or other option as well. Whatever you choose, you
can either put it in this file or put it in a file that you execute via a DO command in your CANDE/STARTUP
file.7
If you work under several different usercodes, you will have to put a <startup file> under each usercode.
Here is where the DO option also comes in quite handy. To save having to update lots of files every time you
want to change your startup preferences, just create one file with the preferences, secure it public, and have
the other <startup file>s execute it. For example, you could do the following under usercode Q:
MAKE CANDE/PREFERENCES
#WORKFILE CANDE/PREFERENCES: SEQ
September, 1995
300ESC HEX = ~
400CONT = %
500SO GETWARN = SET
SAVE
#UPDATING
#WORKSOURCE CANDE/PREFERENCES SAVED
SECURITY CANDE/PREFERENCES PUBLIC IN
# (Q)CANDE/PREFERENCES ON CONTINUUM SECURITY CHANGED
MAKE CANDE/STARTUP
100DO (Q)CANDE/PREFERENCES ON CONTINUUM
SAVE
#UPDATING
Now copy this CANDE/STARTUP file to every usercode you work under. Your preferences will now be set to
the same values, regardless where you are working.
The <startup file> may contain any CANDE command that is legal in a DO file. This includes all CANDE
commands except for control commands (those that begin with question marks). If the <startup file> con-
tains an invalid command, the command is first displayed, as normal, followed by the CANDE error mes-
sage. After that, processing stops and the message:
#QUEUED INPUT PENDING
is displayed. You can resume processing of the <startup file> by entering:

?GO
Alternatively, you can discontinue processing of the rest of the file by entering any other CANDE com-
mand.
Since the <startup file> is nothing more than a <DO file> (sans parameters), you can test your <startup
file> using the DO command. If DO can process the file successfully, it will work as a <startup file>. (When
doing this, be sure to note that some commands, particularly CONT, may not work in the same manner if
executed twice. For more information, see endnote #6.)
It is perfectly acceptable to use the RUN command in a <startup file>. If you have a program that you want
run every time you log on, include it in your <startup file>!
If you are a site administrator and want to establish a standard set of default preferences for all of your us-
ers, you can create a *CANDE/STARTUP file on whatever pack family is visible to the largest number of users.
For example, if everyone at your site has an <alternate family> of DISK, save the file as
*CANDE/STARTUP ON DISK
and be sure to secure it PUBLIC IN! Then each user who does not have his own <startup file> will auto-
matically inherit your system-wide one.
You can force all users to use your system-wide <startup file>.8 However, if you do so, they will not be able
to use their own as well. If you want users to apply your defaults to their sessions, have them insert DO
statements in their files which execute your <startup file> first.
As we said earlier, the name CANDE/STARTUP is the default <startup name>. Through the ?STUP command,
the site manager can change that name (or disable the startup facility entirely). There is also an inquiry-
only ?STUP command that is available to all users. This command will tell you if the startup facility is en-
abled and what the <startup name> is. The syntax for this command is:
?STUP
For example:
?STUP
# STARTUP NAME: CANDE/STARTUP; RESTART NAME:
CANDE/STARTUP/RESTART
The startup facility is an excellent tool for optimizing your working environment under CANDE. Of
course, there is always the potential for abuse (or stupidity, depending on how you look at it). As they
Volume 9.06
warned in the old RALPH user’s manual, do not create a CANDE/STARTUP file that contains the single com-
mand BYE and nothing else. This will make it extremely hard for you to log on in the future.
Automatic Recovery of Work

AUTORECOVER is a feature that was added in Mark 3.9 CANDE. The purpose of this feature is to provide a
means for CANDE to automatically recover user work that is in progress at the time of a system or CANDE
failure.
CANDE has always supported the “recovery file” feature. This feature, as described in the Complete
CANDE Primer,9 preserves your workfile edits as they are entered.
When you first start editing a workfile, CANDE does not make any changes to the original. Instead, your
updates are saved in a special file called the tank file. Each time you see the #UPDATING message, your edits
are copied from the tank file and merged with the data in the original file. However, the original file is still
left untouched and stored on disk with its original name. The merged file is stored in another file called
CANDE/TEXTnnn. This file is a temporary copy of your edited workfile that is entered into the disk directory
so that it will be saved in the event of a halt/load or other unexpected interruption.
When you enter a SAVE command, the original file is removed, and the CANDE/TEXTnnn file is saved in its
place. Thus, until the SAVE command is entered, the original file is never actually touched. This makes it
easy for CANDE to respond if you decide to discard your changes. When you enter REMOVE (against the
workfile), the CANDE/TEXTnnn file is removed, leaving the original file untouched.
If the system halts or CANDE terminates anywhere during this cycle, your edits are saved either in the tank
file, in the CANDE/TEXTnnn file, or in some combination of both. When CANDE comes back up, it deter-
mines the state of your workfile. If there are unsaved edits, it creates a recovery file which you can retrieve
via the RECOVER command. This process is all documented in the aforementioned book.
The AUTORECOVER enhancement directs CANDE to not only create the recovery file, but to automatically
GET it for you the next time you log on. For example, with AUTORECOVER enabled, you might experience the
following:
GET CANDE/PREFERENCES
#WORKFILE CANDE/PREFERENCES: SEQ, 5 RECORDS, SAVED
350CONT *
600PD (PRINTDISPOSITION=CLOSE)
After these two lines have been transmitted in, CANDE goes down for some reason. Sometime later, CANDE is
back up, and you log on:
Q/HUMAN

#AUTORECOVER 170
#
After the interruption, you are back where you left off. You can continue editing from there.
If a workfile is recovered through AUTORECOVER, CANDE will also store the last command entered into
your saved command queue. You can display that command via the ?SHOW command. For example, using
the above sequence:
?SHOW
600PD (PRINTDISPOSITION=CLOSE)
Of course, you can also use the LIST:ANF command to view what changes have been preserved. If the
workfile was updated, you can use the MATCH command to compare it with the original file before saving it.
Both methods will help you determine where you left off and how successful CANDE was in saving all of
your work.
AUTORECOVER not only recovers your workfile automatically, it also automatically restarts the last program
you were running. If you entered a RUN, UTILITY, or COMPILE command, and it was still in progress at the
time of the interruption, AUTORECOVER restarts the program for you. It also sets your various environmen
September, 1995
tals (FAMILY, PRINTDEFAULTS) to the settings you had prior to the interruption. Each setting is displayed as
part of the AUTORECOVER procedure. For example:
#AUTORECOVER 190
#
#FAMILY DISK = CREAM OTHERWISE ICE
#PRINTDEFAULTS: PRINTDISPOSITION = EOJ
#NO WORKFILE
#RUNNING 2334
Your ability to use AUTORECOVER is determined by your site administrator. Through the CANDE control
command RECOVERSESSION, your administrator has three choices:
NONE — The AUTORECOVER feature is completely disabled.
REQUESTED — AUTORECOVER is available on an individual basis based upon the usercode of the user.
ALL — AUTORECOVER is always attempted for all users.
If your site is running with RECOVERSESSION set to NONE, you may as well skip this section and the rest of
this article. You are not able to use this feature.
If your site is running with RECOVERSESSION set to ALL, all of this material applies to you.
If your site is running with RECOVERSESSION set to REQUESTED, you can only take advantage of autorecovery
if the USERDATA option CANDEAUTORECOVER is set on your usercode. If it is set, you have the option of
participating in autorecovery. If it is not, you cannot participate in autorecovery.
You exercise the option to participate in autorecovery through the session option AUTORECOVER. The syntax
for using this session option is:
SO AUTO RECOVER
? RO
This session option only works if CANDEAUTORECOVER is set on your usercode or the site is running with
RECOVERSESSION set to ALL. If either of these are true, your session AUTORECOVER option will be automati-
cally set each time you log on. You can turn the option off by resetting it (RO AUTORECOVER) and turn it
back on again by setting it. If the option is set when an interruption takes place, you will go through autore-
covery. If it is not set when an interruption takes place, you will go through normal session startup, and you
must do any recovery action manually through the RECOVER command.
Thus, if your session begins with AUTORECOVER enabled, you can manually turn it off. However, if your ses-
sion begins with it disabled, you cannot turn it on. Entering SO AUTORECOVER in this case will not return
any error, and it will tell you that autorecovery is enabled. However, testing reveals that no autorecovery
will take place should an interruption occur. There are only two ways in which you can have AUTORECOVER
enabled when you start a session: either the entire site runs with RECOVERSESSION set to ALL, or the site
runs with RECOVERSESSION set to REQUESTED, and your usercode has the CANDEAUTORECOVER option set.
Without one of these configurations, you cannot use autorecovery.
Also note that two other items are involved in determining if CANDE will do an automatic recovery. They
are the usercode and the station name. To achieve automatic recovery, you must log on to the same station
you were on at the time of the interruption using the same usercode. If you are using a COMS window to
access CANDE, you must go on to the same dialog number from the same terminal. Any deviation will
result in a normal session startup. (The workfile, if any, will still be available as a recovery file through the
RECOVER command.)
Restart Files
If you use the AUTORECOVER feature, and you also use <startup file>s, watch out for a potential conflict.
<Startup file>s are not executed if an automatic recovery takes place.
Volume 9.06
The logic behind this is simple. The <startup file> may set environmental variables (FAMILY,
PRINTDEFAULTS) that differ from those in effect at the time your session was interrupted. This could po-
tentially cause the restarted execution of a program to run in the wrong environment. Moreover, the
<startup file> might itself run a program, which could interfere with the resumption of the program to be
restarted or with the recovery of the workfile.
The difficult part is that certain session attributes are not restored during an automatic recovery. For ex-
ample, after an automatic recovery, you will be back to the default <escape character>, <continuation char-
acter>, and TERMINAL settings. To address these requirements you still need some sort of <startup file> to
handle session recovery as well.
The answer to this is the <restart file>. The <restart file> is almost the same thing as a <startup file>. It is
a sequence of CANDE commands stored in a DO file. It may contain your typical session configuration
commands, such as TERMINAL, ESCAPE, and CONT commands. It should not contain environmental com-
mands that are restored during autorecovery. (Currently, this means the CONVENTION, FAMILY, LANGUAGE,
and PRINTDEFAULTS specifications.) It should not contain any commands which process a task. It may not
contain any CANDE editing commands that would affect the workfile being recovered.
The <restart file> is stored under the <restart name>. CANDE uses the same logic to find the <restart
file> that it uses to find a <startup file>. It first searches for all possibilities under:
<restart name>/<station name>
It then searches for a file named just:
<restart name>
If a file is found in any of these searches, it is processed first. Then the workfile is recovered and/or the
interrupted task is restarted.
The default <restart name> is CANDE/STARTUP/RESTART. As with the <startup name>, your site adminis-
trator may set the <restart name> to anything he chooses.
Like <startup file>s, a <restart file> may contain a DO command. Thus, you can have a kernel file, like
CANDE/PREFERENCES given above, which sets your terminal specifications. Then you can have another,
performed only from the <startup file> which sets your PRINTDEFAULTS and other environmental attrib-
utes. This still allows you to use the same <startup file> under each usercode and the same <restart file>
under each usercode.
For example:
MAKE CANDE/PREFERENCES
300ESC HEX = ~
400CONT = %
500SO GETWARN = SET
SAVE
#UPDATING
#WORKSOURCE CANDE/PREFERENCES SAVED
SECURITY CANDE/PREFERENCES PUBLIC IN
# (Q)CANDE/PREFERENCES ON CONTINUUM SECURITY CHANGED
MAKE CANDE/ENVIRONMENTALS
#WORKFILE CANDE/ENVIRONMENTALS: SEQ
100PD (DESTINATION="LP20", PRINTDISPOSITION=CLOSE)
200LANGUAGE ENGLISH
SAVE
#UPDATING
#WORKSOURCE CANDE/ENVIRONMENTALS SAVED
SECURITY CANDE/ENVIRONMENTALS PUBLIC IN
# (Q)CANDE/ENVIRONMENTALS ON CONTINUUM SECURITY CHANGED
MAKE CANDE/STARTUP
200DO (Q)CANDE/ENVIRONMENTALS ON CONTINUUM
September, 1995
SAVE
#UPDATING
MAKE CANDE/STARTUP/RESTART
#WORKFILE CANDE/STARTUP/RESTART: SEQ
SAVE
#UPDATING
#WORKSOURCE CANDE/STARTUP/RESTART SAVED
Now copy CANDE/STARTUP and CANDE/STARTUP/RESTART to each of your usercodes, and you will have
identical session attributes and environments in all of your workplaces.
1
The name was an acronym, but I do not remember what the letters stood for.
2
Sorry, but after all of these years, I cannot remember the name of the command for this feature. Perhaps someone in
the audience knows?
3
In the MS-DOS and other micro-computer cases, this feature is a cross between the “log on” file and the “system su-
pervisor” file. In the MS-DOS case, the commands not only set session options; they also set operating system options.
4
Unisys Corporation, Mark 3.7.0 Documentation Changes (D Notes), March 12, 1987, pp. 177 – 181.
5
The ?STUP command is documented in Part Five of this series, which will be published in the October, 1995 issue of
the Journal.
6
Beware with the <continuation character>! If you have a <continuation character> already set, the line:
400 CONT = %
will cause CANDE to merge lines 400 and 500 into one command, producing erroneous results. To guarantee that the
CONT command works in all situations, you can always precede it with a command to cancel any existing <continuation
character>. That command is:
CONT *
7
Note that, after this <startup file> is executed, you now have the tilde character (~) defined as your <escape charac-
ter>. If you now LIST or PAGE the <startup file> you will see the following at line 300:
300 ESC HEX = ~~
Since the tilde is now your <escape character> two tildes will appear on your screen for every one tilde in your file.
(For more information on this, cf., Part One of this series, pp. 9-191 – 9-194.)
8
Details for doing this are described in the section on the ?STUP command in our next issue.
9
Gregory, Donald J., the Complete CANDE Primer, Gregory Publishing Company, 1986, pp. 205 – 207.
Volume 9.06
CANDE: File Searching / 33
CANDE: File Searching

ne of the most common functions needed in a shell program is the ability to search a directory of files.
Historically, CANDE has addressed this need through two commands: FILES and LFILES. The FILES
command has provided a short report, listing just file names and their associated types. (N.b., A “file type”
in CANDE is the same as the FILEKIND attribute in the MCP.) The LFILES command provides a much
larger report, listing a large number of file attributes for each file. Moreover, the LFILES report can be
configured to list just file attributes of interest. The penalty for using LFILES, however, is that it initiates a
separate task each time it is used.1 FILES, on the other hand, runs out of the GRIND stacks, so it responds
much more quickly.
In Mark 4.1 Unisys documented the utility program *SYSTEM/PDIR for general use. For the first time in
history, A-Series CANDE had Unisys-supported system software giving it the ability to search for files by
(a) using wildcard characters in the search target, and (b) using file attributes in search conditions.
*SYSTEM/PDIR could be run through CANDE’s UTILITY command (or RUN command), and the parameters
to that program provided the specifications of the search. We previously documented this program in our
June, 1995 issue.2
The lifelong dream of CANDE users, however, has been to have these highly important features become an
in-built part of CANDE. In-built commands, such as FILES, are superior to external commands, such as
LFILES, for several reasons. The most obvious is that no task is fired up when an internal command is used.
This saves a lot of overhead since firing up a task, opening a remote file to write the report, and allocating
array space in which to format said report are three of the most expensive things you can do on an A-Series
computer. For something as simple as listing the files in one’s directory, having the system do all of this
work is just ridiculous.
There are additional reasons why in-built commands are superior. In-built commands all recognize your
CANDE session settings, particularly your TERMINAL configuration. Much of this information is not passed
from CANDE to any tasks it runs, so external commands don’t always have a consistent feel with the rest of
CANDE.
Fortunately, in Mark 4.1, Unisys made everyone’s dream come true. Three important new features were
added to the FILES command:
• The report is now expandable and may include a variety of file attribute information, not just the file
type (FILEKIND).
• Wildcard and pattern match searching is now available.
• Searching by file attribute value is also now available.
But most important above all, these features are all a built-in, integrated part of CANDE. The FILES
command does not fire off any additional tasks to provide all of these features.3
FILES Command Basics

In the Complete CANDE Primer we presented the fundamentals of the FILES command. These are:
• How to search a directory under your usercode for file titles.
• How to search another usercode (if you’re privileged) or the system node (*) for file titles.
• How to search another pack family for file titles.
• How to limit the depth of the search within the directory tree.
You must have a full understanding of how to use these features before reading the material in this article.
If you are familiar with SYSTEM/PDIR, a lot of the material in this article will look familiar. There are some
subtle differences between the operation of CANDE FILES and SYSTEM/PDIR. However, both use the
same internal MCP procedure (ASERIES_INFO) to get their reports. It’s just that new options were added
to that procedure to support the CANDE FILES command, and SYSTEM/PDIR was never retrofitted with
those same enhancements.
September, 1995
Although we documented SYSTEM/PDIR in depth in June, there are enough differences between it and
FILES that we decided to provide a completely new document on FILES. Though the material overlaps in
many areas, it is not exactly the same. FILES provides several options that are not available in PDIR. FILES
is also tailored to the specific workings of CANDE and provides a much more natural fit into the CANDE
environment.
Report Options
You now have several options for formatting your FILES report. Report options are selected by following
the FILES command with one or more <output options>, according to the syntax:
<FILES command> : <output options>
The possible <output options> are specified using the following syntax:
,
1 SINGLELINE
LONGFORMAT
1 RES
NON
ALL
1 < depth>
Note the colon (:) that must appear after the <FILES command> and before the first <output option>.
These options are available to all variations of the FILES command.
Report Layout Options

The first two options specify the layout of the report. The next three specify what files are included in the
report. The last one, <depth> controls the depth in the directory tree that is searched; this option is un-
changed from before and is documented in the Complete CANDE Primer.4
Volume 9.06
FILES SYM/F=:S
SYM/F= ON CONTINUUM
File Name Filekind Records Sectors CreationTime

--------------------------+------------+------------+------------+------------
SYM/FORM ALGOLSYMBOL 1558 784 07/30/1992

SYM/FORM/SAMPLE1 COBOL74SYMBO 42 28 05/10/1992
SYM/FALCON DCALGOLSYMBO 1158 588 11/27/1991
SYM/FSRCOPY/1 ALGOLSYMBOL 131 70 04/19/1994
SYM/FSRCOPY/2 COBOL74SYMBO 119 56 04/19/1994
SYM/FUPDATE ALGOLSYMBOL 322 168 11/12/1991
SYM/FORMTEST ALGOLSYMBOL 443 224 05/30/1992
SYM/FILEMATCH/DATA COBOLSYMBOL 13 14 12/15/1992
SYM/FILEMATCH/TEST ALGOLSYMBOL 86 56 12/15/1992
SYM/FILESEARCH DCALGOLSYMBO 1601 812 11/12/1991
SYM/FINDWARNINGS DCALGOLSYMBO 462 238 05/23/1994
SYM/FORMINFOTEST ALGOLSYMBOL 45 28 05/10/1992
SYM/FALCONSUPPORT DCALGOLSYMBO 568 294 04/07/1992
SYM/FILEDIRECTORY ALGOLSYMBOL 84 42 03/20/1995
14 FILES FOUND
#
Figure 1
Sample FILES:SINGLELINE Report
If you specify SINGLELINE, and your report fits into an 80-column line, the FILES command will place each
file name on a single output line followed by your selected attributes. A sample output using the
SINGLELINE option is shown in figure 1.
LONGFORMAT is your alternative to SINGLELINE. LONGFORMAT prints the file title first, followed by your at-
tribute list in the format <attribute> = <value>. A sample of this output is shown in figure 2.
If the number of attributes you request in your report does not fit into a single output line, CANDE uses
LONGFORMAT automatically.
If you do not specify either <output option>, the format of the report will depend upon the type of request
you enter. If you request a FILES report without using any wildcard characters, you will get the old “one
node at a time report”. This report shows only the name and type of each file. For example:
September, 1995
(Q) ON CONTINUUM
. SYM
. . AI
. . . TEST : ALGOL
. . . ATTLIST : ALGOL
. . . C74TEST : COBOL74
. . IR : COBOL74
. . RE
. . . TEST : ALGOL
. . . TEST
. . . . IN : DATA
. . . . OUT : DATA
. . CCE
. . . C74
. . . . SAMPLE1 : COBOL74
. . . . SAMPLE2 : COBOL74
If you request a report that uses wildcard characters in the search, you will get the SINGLELINE report with
FILES SYM/F=:L
SYM/F= ON CREAM
File Name Attributes

-----------------------------+------------------------------------------------
SYM/FORM Filekind= ALGOLSYMBOL Records= 1558

Sectors= 784
CreationTime = 07/30/1992 @ 15:07:07
SYM/FORM/SAMPLE1 Filekind= COBOL74SYMBOL

Records= 42 Sectors= 28
CreationTime = 05/10/1992 @ 15:18:59
SYM/FALCON Filekind= DCALGOLSYMBOL

CreationTime = 11/27/1991 @ 17:35:51
SYM/FSRCOPY/1 Filekind= ALGOLSYMBOL Records= 131

Sectors= 70
CreationTime = 04/19/1994 @ 13:48:39
SYM/FSRCOPY/2 Filekind= COBOL74SYMBOL

Figure 2
Sample FILES:LONGFORMAT Report
the attributes FILEKIND, SECTORS, RECORDS, and CREATIONTIME included, as shown in figure 1.
Showing Archived Files

The next set of <output options> determine what files are included in the report. You may choose one of
the following:5
RES
NON
ALL
The default is determined by your session option SHOWALLFILES. If you use the defaults CANDE is
shipped with, the default is RESident.
If your site uses Unisys’ ARCHIVE/BACKUP to back up your files, both files present on disk and those ar-
chived to tape can be included in your FILES report. Those present on disk are called resident files. Those
present in the archive log, but not present on disk, are called nonresident. Using the corresponding key-
word, you can specify exactly which group of files you want to see.
For example:
Volume 9.06
FILES SYM/PRINT=:NON
SYM/PRINT= ON CONTINUUM
File Name Filekind Records

--------------------------+------------+------------+
SYM/PRINTS/DUMP/950128 NULLFILE
SYM/PRINTS/LOAD/950130 NULLFILE
2 FILES FOUND
#
This report shows just non-resident files under our usercode.
FILES SYM/PRINT=:ALL

--------------------------+------------+------------+
SYM/PRINTS/DUMP ALGOLSYMBOL 2322

SYM/PRINTS/LOAD ALGOLSYMBOL 416
SYM/PRINTS/EXPAND ALGOLSYMBOL 142
5 FILES FOUND
#
This report shows a combination report of both resident and non-resident files under our usercode. Note
that the non-resident files are identified by a FILEKIND of NULLFILE.
In the normal course of work, it is possible to accumulate a large number of non-resident files. Any file that
is present at the time the backup is run will become an archived file. So long as that file is resident on disk,
it will be included in the RESIDENT report. But when you remove that file, it will switch to the non-resident
state.
You can reduce the number of unwanted non-resident files in your directory by using two commands, both
of which are WFL commands.
The command
WFL ARCHIVE PURGE <file name list>
will delete the specified files from the archive tables. If the target files are non-resident, this means that the
files are deleted without any (convenient) means of later retrieval. If the target files are still resident, they
remain resident; only the backup information is deleted.
For example:

--------------------------+------------+------------+
2 FILES FOUND
#
WFL ARCHIVE PURGE SYM/PRINTS/= FROM CONTINUUM
#RUNNING 1327
#BOT 1328 (Q)WFLCODE ON CONTINUUM
#1328 PK47 5 ARCHIVE RECORDS PURGED UNDER (Q)SYM/PRINTS/= ON
CONTINUUM
#EOT 1328 (Q) (Q)WFLCODE ON CONTINUUM
#
September, 1995
#NO MATCHING FILES FOUND
#
Note that all of the information on the two files SYM/PRINTS/DUMP/950128 and SYM/PRINTS/LOAD/950130
has now been removed from the FILES report.
If you have a resident file that you want to remove, and you want to eliminate all of the backup information
on that file at the same time, you can do so with the WFL command:
WFL REMOVE [DESTROY] <file name list>
The square brackets around the keyword DESTROY are required. Otherwise, the system will interpret
“DESTROY” as a file name and give you a syntax error.
After using this command, the target files will no longer appear in any FILES report. For example:

--------------------------+------------+------------+

SYM/PRINTS/EXPAND ALGOLSYMBOL 142
5 FILES FOUND
#
WFL REMOVE [DESTROY] SYM/PRINTS/EXPAND FROM CONTINUUM
#RUNNING 1454
#1454 PK47 (Q)SYM/PRINTS/EXPAND ARCHIVE RECORD PURGED ON
CONTINUUM
#1454 PK47 (Q)SYM/PRINTS/EXPAND ON CONTINUUM REMOVED WITH
DESTROY OPTION
#

--------------------------+------------+------------+

4 FILES FOUND
#
The file SYM/PRINTS/EXPAND is now completely obliterated. It does not even show up as an archived
“NULLFILE” since both the file, and all of its backup information, have been destroyed.
Take care that you only use ARCHIVE PURGE and REMOVE [DESTROY] to eradicate files that you are certain
you no longer want ever again. If a file has been backed up, neither command will directly affect the copy
of the file that currently sits on the tape. However, you will no longer have any record regarding the spe-
cific tape the file is stored on, and AUTORESTORE will not recover the file.
Neither ARCHIVE PURGE nor REMOVE [DESTROY] are CANDE commands. You must prefix these com-
mands with the word WFL to execute them successfully.
Volume 9.06
SHOWALLFILES
The set of files included in the FILES report by default is determined by the session option SHOWALLFILES.
This option can be set or reset at any time during your session. The syntax is:
SO SHOWALLFILES
? RO
If SHOWALLFILES is set, default action for the FILES command is to include all files in the report. If
SHOWALLFILES is reset, default action is to include only resident files. To set SHOWALLFILES, use the com-
mand:
SO SHOWALLFILES
To reset it, use:
RO SHOWALLFILES
As distributed, CANDE comes with the SHOWALLFILES option in the reset state. Your site administrator
can change that by setting the global CANDE option SHOWALLFILES. Therefore, you should first check to
see what your local default is for this option. Then, if you want to change it for your sessions, you can either
enter an SO or RO command, as appropriate.
This option will revert to its default value each time you start a new session. To permanently set the option
to your preference, put your SO or RO command in both your <startup file> and your <restart file>.
Wildcard Name Searching

The basic syntax for the FILES command is:
FILES
< selection expression> < file options>
< file options>
ON < family name >

(CDROM)
: < output options >
Every construct after the word FILES is optional. If you omit them all, you get the default report which lists
every file under your usercode in the “one node at a time” report format.
The <selection expression> determines what files will be considered for inclusion in the report. The <selec-
tion expression> always specifies the candidate files by name. It may be a directory name, a file name, or a
title expression that includes wildcard characters. The possible options are:
1. A single, complete <file name>.
This identifies a single file. It is primarily useful when requesting attribute information about a file, as we
will show when we discuss <file options> later in this article.
Example:
FILES SYM/PRINTS/DUMP
(Q) ON CONTINUUM
. SYM
. . PRINTS
. . . DUMP : ALGOL
#
2. A <file directory>.
September, 1995
This is a directory name without the trailing equal sign. It generates a list of the files under the specified
directory. The full name of the file is returned. For example:
FILES SYM/PRINTS
(Q) ON CONTINUUM
. SYM
. . PRINTS
. . . DUMP : ALGOL
. . . LOAD : ALGOL
. . . EXPAND : ALGOL
#
3. A <directory name>.
This is a directory name with a trailing /= appended. It generates exactly the same report as that produced
using the <file directory> option (#2, above). The significant thing about this is that you can now append
the /= to a directory name and, instead of returning a syntax error, CANDE will give you a directory report.
4. A list of <name>s containing wildcard characters or pattern matching expressions.

This is the primary enhancement of Mark 4.1. It allows you to generate a report given only some portion of
the file name. It can be anything from a single equal sign (denoting all files under your usercode) to a com-
plex expression involving wild card characters and pattern matching instructions.
Reports using wildcard characters are always returned in either SINGLELINE or LONGFORMAT style. The old
“one node at a time” style is not used when you do a wildcard search.
Wildcard Characters
The FILES command supports three wildcard characters: the equal sign (=), the tilde (~), and the question
mark (?). These characters perform the following functions:
Equal sign (=):
This character matches zero, one, or many occurrences of any character. It ignores forward slashes (/),
so you can use it to span directory nodes. For example, if you have the files
SYM/EVALUATE
SYM/EVALUATE/2
SYM/EVALUATEX/1
SYM/EVALUATE2
under your usercode, the command:
FILES SYM/E=
will give you this report (truncated on the right for formatting purposes):
SYM/E= ON CONTINUUM

--------------------------+------------+------------+
SYM/EVALUATE ALGOLSYMBOL 61
SYM/EVALUATE/2 ALGOLSYMBOL 66
SYM/EVALUATEX/1 ALGOLSYMBOL 66
SYM/EVALUATE2 ALGOLSYMBOL 66
4 FILES FOUND
#
Tilde (~):
This character matches zero, one, or more occurrences of any character, just like the equal sign does.
However, the tilde stops at a forward slash (/), so it will not cross a directory boundary. If a match is
found that consists of directory nodes only, the FILEKIND for the file will be listed as DIRECTORY. If a
file and a directory have the same name, the file is listed, and the directory is ignored. Otherwise, the
report is the same as that given for the equal sign character.
Given the same list of files, the command
Volume 9.06
FILES SYM/E~
will generate the report:
SYM/E~ ON CONTINUUM

--------------------------+------------+------------+
SYM/EVALUATE ALGOLSYMBOL 61
SYM/EVALUATEX DIRECTORY
3 FILES FOUND
#
Note that the directory SYM/EVALUATE is not included in the report since there is also a file of the same
name.
Question mark (?):
This character matches any single character in the file name. It does not match a forward slash (/) or a
left or right parenthesis (( or )). Therefore, given the same list of files, the command
FILES SYM/EVALUATE?
will produce the report:
SYM/EVALUATE? ON CONTINUUM

--------------------------+------------+------------+
SYM/EVALUATEX DIRECTORY
2 FILES FOUND
#
You can mix the wildcard characters together as much as you want in formulating your FILES command.
You can also use any number of wildcard characters in a single command. Thus, any of the following are
legal requests:
FILES SYS=M=
This reports every file whose name begins with the three letters SYS and contains an M somewhere in it.
It would match SYSTEM/MCP, SYS/MATCHPACKS, SYSTEM/X, and SYS/AMERICA/1. It would not match
OBJECT/SYSTEM/X because that name does not begin with the letters SYS.
FILES SYS=M
This reports every file whose name begins with the three letters SYS and ends with the single letter M.
It would match SYSTEM/M, but it would not match either SYSTEM/MCP or SYSTEM/MATCHPACKS.
FILES =SYS=M=
This reports every file whose name contains the letters SYS and M within it. The only constraint is that
SYS must appear before M. It would match REPORT/UNISYS/FTRS/MARC as well as SYSTEM/MCP and
OLD/SYS/MATCHPACKS. It would not match MY/SYS because the target constants are in the wrong se-
quence.
FILES =MCP=
This reports every file whose name contains the letters MCP in any location. It would report
SYSTEM/MCP412C or SYSTEMCPINFO.
FILES SYS~/M=
This reports every file that is stored under any directory whose name begins with the letters SYS where
the second node of the file name begins with the letter M. It would include both SYSTEM/MCP and
SYS/MATCHPACKS. However, it would not include SYSTEM/COMS (second node does not begin with M),
SYS/VERSION2/MATCHPACKS (same reason), or OBJECT/SYSTEM/MCP (the first node does not begin with
SYS).
September, 1995
FILES S~M/=
This reports every file that is stored under a directory whose name begins with S and ends with M. Files
under the SYSTEM/= or the SYM/= directory would be reported.
FILES S?M/=X=
This reports every file under a three-letter directory that begins with S and ends with M where the file
name also contains an X within it. It would include SYM/XREF, SYM/TRAX, and SYM/TRAXSUPPORT, but
would not include SYSTEM/TRAX (too many letters in the first node) or SYMX (not enough directory lev-
els).
None of the wild card characters match the left or right parenthesis of a usercoded file name. If you are
privileged, you can use wildcard characters to search for files under other people’s usercodes. You can also
use a wildcard character inside the parentheses to match several different usercodes. But you cannot use a
wildcard character to combine a usercode and a file name into a single pattern.
Thus, as a privileged user, you can use the command
FILES (=)=
to list all of the files stored under any usercode on your current pack family. Similarly,
FILES (V=)=
will list all of the files stored under usercodes that begin with the letter V on your current pack family.
However, you cannot accomplish the same thing with
FILES (V=
This will give an error requesting a right parenthesis.
Wildcard Characters vs. Quoted Names

We briefly mentioned quoted <file name>s in the Complete CANDE Primer, merely touching on their ex-
istence.6 Although supported, the use of quoted file names is not recommended — especially the use of file
names that include embedded periods. Many software products that analyze file titles will fail if the title
contains an embedded period because Unisys internally uses a period to delimit the end of a title.7 If you
want to avoid these problems, avoid the use of quoted names in file titles.
According to the Unisys documentation,8 the tilde and the equal sign both match a quotation mark ("), but
the question mark does not. This is not true. All three will match a quotation mark. The key is that
CANDE requires all of your quotation marks to be balanced. In other words, you must always supply them
in multiples of two, and each pair denotes a single <name> in a file title.
On the A-Series, a node is either quoted or unquoted. If the node is quoted, it may contain any graphic
character. However, the entire node must be quoted. Therefore, you could have a file name such as:
MY/"$%@!"/FILE
or:
MY/"$%@!FILE"
but you cannot have a file such as:
MY/"$%@!"FILE
Unquoted and quoted text must be separated by a slash so that they are separate nodes.
If used inside the quotes, the slash is a part of the name; it does not separate nodes. Therefore,
MY/"$%@!/FILE"
is a name with two nodes: MY and "$%@!/FILE". Thus, any quoted name must be exactly a single node in
the file title.
You must consider this when using wildcard searching where quoted names are involved. If the quoted
node is several characters in length, you must allow for that in your search specification. Now the three
wildcard characters, the equal sign (=), the tilde (~), and the question mark (?) all retain their “wild” mean-
ing inside the quotes. Therefore, the request:
Volume 9.06
FILES "="
will search for all single-node, quoted names under your usercode. It would match names such as "$%*",
"A.B.C", and "*". It would not match any files with names larger than a single node, as in "SYS###"/X. It
would also not match any names beginning with unquoted nodes, as in *SYSTEM/ALGOL or SYS/FILES.
To match titles that have both quoted and unquoted nodes, you must use a wildcard expression that com-
bines both. Now of course,
FILES =
will match everything, quoted or unquoted, because the equal sign matches every character. The problem
comes in when you want to use a quoted node at the beginning. In that case,
FILES "="
as we stated, only matches single-node names. To match other names, you would have to use another equal
sign, as in:
FILES "="=
The first three characters limit you to file names where the first node is quoted. The second equal sign al-
lows anything to follow that initial quoted node. Therefore, this expression would match both "$*%" and
"SYS###"/X. However, it would not match *SYSTEM/ALGOL (the first node is not quoted) nor
MY/"$%@!"/FILE (same reason).
Note that expressions such as

FILES "=
are not valid. If you use quotes, they must be balanced inside the command, even though the wildcard
character logically matches a quote.
When searching with question marks, you have to supply enough question marks and place them properly
to achieve a match. Suppose that you have a file titled SYS/"X.Y". If you list all of the files under SYS with
the command:
FILES SYS/~
the report will list SYS/"X.Y" in the company of other files where the second node is 3 characters long. A
sample output might be:
SYS/~~ ON CONTINUUM

--------------------------+------------+------------+
SYS/GEN DCALGOLCODE 772

SYS/WFL DIRECTORY
SYS/"X.Y" SEQDATA 1
SYS/XXX ALGOLCODE 7
If you try to find this file using question marks, and you use:
FILES SYS/???
the file SYS/"X.Y" will not be included in the report. When searching with the question mark character,
the second node is considered five characters long instead of three. Therefore if you enter:
FILES SYS/?????
then you get something like:

SYS/????? ON CONTINUUM

--------------------------+------------+------------+
SYS/"X.Y" SEQDATA 1
SYS/ALGOL DIRECTORY
SYS/DCKEY DCALGOLCODE 27
September, 1995
SYS/TEST1 ALGOLCODE 10
SYS/TEST2 ALGOLCODE 10
Now the file is reported at the top of the list, where the quote (instead of the X) would come in the collating
sequence.
Again, CANDE requires that quotes be balanced in a command. Even though a question mark can match a
quotation mark in a search, you cannot put one quotation mark in your command and expect to balance it
with a question mark. For example, the command:
FILES SYS/"????
is invalid; CANDE will want an “ending quote.”
You can, however, use question marks inside the quotes. For example,
FILES SYS/"???"
is perfectly acceptable and will locate the file SYS/"X.Y". You can also do the reverse if your constant char-
acters inside the quotes are letters or digits. For example,
FILES SYS/?X?Y?
is acceptable and matches our target file. However,
FILES SYS/?X.Y?
is not valid: CANDE will complain of an invalid file name and flag the period.
The Backslash Character

Since the three wildcard characters retain their function even inside quotes, you must take an extra step if
you want to use any of those characters in their original meaning. To cancel the “wild” meaning of any of
these characters, prefix the character with a backslash (\) character. Thus, while:
FILES "="=
will match all files that begin with a quoted node, the command:
FILES "\="=
only matches files whose first node is "=". This would match, for example, "="/DATA/ONE, but it would not
match "%"/DATA/ONE (wrong character) or "=3"/DATA/ONE (too many characters).
If you want to search for a file whose name includes a backslash character, you must use two backslashes in
your request. For example:
FILES "\\"=
will successfully locate "\"/SYSTEM/ALGOL. However,
FILES "\"=
is invalid. The backslash character must be followed by another character, and that character will be given
its literal meaning. If the character is anything other than an equal sign, a tilde, or a question mark, the
backslash is simply redundant.
Pattern Matching in Unquoted Names

You can narrow the candidates of a FILES search on a character by character basis through pattern match-
ing. Pattern matching allows you to specify a select list of characters you want in the reported file titles.
This list of characters is considered a single <pattern character>. The <pattern character> must match one
single character in the title for the title to be included in the report.
The <pattern character> is defined by enclosing one or more characters inside square brackets ([ and ]).
For example, if you are looking for all of the files under your usercode that begin with the letters A, B, or C,
you could use the command:
FILES [ABC]=
Volume 9.06
Note that although three characters are given between the brackets, the entire expression matches only a
single character in the file titles: in this case, the first character. This expression would match the titles
ABC, A12, B/123, and CBA.
If you omit the equal sign, as in:

FILES [ABC]
the request will only match three possible candidates: A, B, and C. In this case, you are requesting a search
for all one-character file or directory names that begin with A, B, or C.
You may use as many <pattern character>s in your request as you like. Each <pattern character> repre-
sents a single character. For example:
FILES [ABC][ABC]
matches all two-character file or directory names that use the letters A, B, and C. This will match the names
AA, AB, AC, BA, BB, BC, CA, CB, and CC. It will not match any other names.
The characters inside the brackets are limited to letters and digits unless you enclose the entire <pattern
character> in quotes (which we’ll deal with momentarily). Blanks may optionally be used inside the brack-
ets for readability purposes; they are ignored. Therefore, the commands:
FILES [A B C][DE]
FILES [ABC][D E]
FILES [A BC][D E]
are all equivalent and identical to:
FILES [ABC][DE]
If you use lowercase letters inside the brackets, they will be converted to uppercase automatically. Letter
case is ignored in A-Series file names (unless the node is enclosed in quotes), so the following are also
equivalent:
FILES [abc][DE]
FILES [Ab C][de]
FILES [ABC][DE]
For some reason that, as far as I can tell, is rather arbitrary, you are limited to 17 characters within any sin-
gle <pattern character> definition. Fortunately, you can use character ranges inside your <pattern charac-
ter> definition. This allows you to specify a large number of characters with a minimum of typing.
To create a character range, use a hyphen between two characters, as in:
FILES [A-Z][Ø-9]
In this example, the first <pattern character> is the list of all characters in the collating sequence between A
and Z. The second <pattern character> is the list of all characters in the collating sequence between the
digits 0 and 9. This request would therefore match names such as: A1, C7, Z4, Q5, and so forth. It would
not match 1A, 9F, AA, or 35. (The actual results vary depending upon the collating sequence you are using.
For the remainder of this article, we will stick with the EBCDIC collating sequence, which is the A-Series
default.)
When specifying a range, the first character must be lower in the collating sequence than the second. Thus,
FILES [A-K]
is valid because K is higher than A in the EBCDIC collating sequence. The reverse,
FILES [K-A]
will not work; it will return an error.
The EBCDIC collating sequence puts the digits at a higher location than the letters. Therefore,
FILES [A-9]
is a valid request for all letters and digits (and some stuff in between). However,
FILES [Ø-Z]
(where Ø represents the number zero) is not valid because Z is lower than Ø.
September, 1995
If your system collating sequence has been set to some flavor of ASCII, then the reverse will be true. In
ASCII, the digits precede the letters, so [Ø-Z] will be valid, and [A-9] will not be.
You can use several character ranges in a single <pattern character>. Just put them adjacent to each other,
optionally separating them with blanks. For example:
FILES [A-C R-T X-Z]=
This uses three ranges: A through C, R through T, and X through Z. The command will match any file name
that begins with one of the letters A, B, C, R, S, T, X, Y¸ or Z.
You can specify the ranges in any order. For example,
FILES [R-T A-C X-Z]=
also works and produces the same results.
You can also intermix character ranges with single characters to specify just the characters you want. For
example:
FILES [R-T PQ F-J]=
uses the two ranges R through T and F through J plus the two single character P and Q. It will match any file
whose name begins with F, G, H, I, J, P, Q, R, S, or T.
When constructing a <pattern character> using ranges, you are limited to a total of 17 units, where each
unit is either a single character or a range.
You also have the option of specifying a character range and/or list of characters that are not to be included
in the report. To do this, use an exclamation point (!) as the first character of the <pattern character>. For
example:
FILES [!A-C]=
This lists every file under your usercode whose name does not begin with the letters A, B, or C. It would
report DATA/ONE, but not ALPHA/ONE.
The negation applies to all of the characters listed in the <pattern character>. For example,
FILES [!A-M XYZ]=
excludes all files whose names begin with A through M, X, Y, and Z. It includes all other files.
If you want to include an entire class of characters in the <pattern character>, you can specify that using a
name. To do this, use the sequence:
[:<class name>:]
This sequence is used inside the first pair of square brackets. For example:
FILES [[:ALPHA:]]=
reports every file whose name begins with a letter.
The possible character classes are:
Character Class Characters Included
[:ALNUM:] a through z, A through Z, and 0 through 9
[:ALPHA:] a through z and A through Z
[:LOWER:] a through z
[:UPPER:] A through Z
[:DIGIT:] 0 through 9
[:GRAPH:] All printable characters excluding those in the [:ALNUM:] class.
Again, when dealing with unquoted file names, letter case is not pertinent. A-Series file names use upper-
case letters only. The lowercase options are for quoted file names only.
There is a subtle difference between specifying the range A-Z and the character class [:UPPER:] when
working in EBCDIC. The EBCDIC collating sequence has gaps between the letters I and J and the letters
R and S. If you specify A-Z, that denotes the inclusion of all characters between hex "C1" and hex "E9",
including those in the gaps. If you specify [:UPPER:], that denotes just the upper case letters. This dis-
tinction is not important when using unquoted names, since these can only have letters, digits, hyphens, and
underscores in their names. However, it is important when dealing with quoted names.
Volume 9.06
Pattern Matching in Quoted Names

When enclosed in quotes, the <pattern character> may include any graphic character in the collating se-
quence. Moreover, lowercase and uppercase letters are no longer equivalent. Thus, your range of charac-
ters is much greater than is possible with the unquoted <pattern character>.
The quoted <pattern character> is simply one that is enclosed in quotes, as in:
"[$%&]"
This represents a <name>, enclosed in quotes, that is one character long. It would match files whose names
were "$", "%"¸ or "&".
If the <name> is 2 characters long, you need 2 characters inside the quotes. For example:
"[$%&][*a]"
would match file names such as "$a" or "%*".
Inside a quoted <pattern character> all characters are valid, including the blank. You can also specify
ranges using the graphic characters, and the blank can be a valid character for starting a range. Thus,
FILES "[ -+]"=
(note the blank prior to the hyphen) will report all files whose names begin with " ", "[", ".", "<", "(",
and "+".
Inside all <pattern character>s the hyphen (-) and the exclamation point (!) have special meanings. If you
want to search for names that contain a hyphen in quotes, specify it at the very beginning of the list so that
it will not be confused as a range specifier. For example,
FILES "[-%]"=
denotes file names that begin with "-" or "%". If you want to use the exclamation point as an exclamation
point, do not put it first in the expression. For example,
FILES "[$!]"=
will give you all files that begin with "$" or "!". However,
FILES "[!$]"=
will give you all files that have a single character quoted name except for those which begin with "$".
There is no way to specify a right square bracket (]) in a <pattern character>. The right square bracket
always delimits the end of the <pattern character>.
Note the important distinction between the two file names:
*SYSTEM/ALGOL
"*"/SYSTEM/ALGOL
The first one denotes a file stored globally, without a usercode. The second denotes a file under your user-
code where one of the nodes is an asterisk enclosed in quotes. These are completely different file names,
and you would use different search patterns to locate them. The command:
FILES *=
would report *SYSTEM/ALGOL but not "*"/SYSTEM/ALGOL. Similarly,
FILES "*"=
would report "*"/SYSTEM/ALGOL but not *SYSTEM/ALGOL. Quoted nodes and unquoted nodes are com-
pletely different things. Therefore, a command such as:
FILES "[$*%]"=
will not include files under the global node, such as *SYSTEM/ALGOL, in the report.
The Hyphen and the Underscore

Standard, unquoted A-Series file names can contain hyphens and underscore characters. You can use ei-
ther of these characters in your FILES command without enclosing it in quotes. For example:
September, 1995
FILES ?-?
is perfectly valid and will report the file X-Y.
However, you cannot include a hyphen or an underscore in an unquoted <pattern character>. The follow-
ing are both illegal and will not locate the file X-Y:
FILES X[_-]Y
FILES X"[-_]"Y
In the first case, CANDE complains about the pattern. The second is simply an invalid file name.
The command
FILES "X[_-]Y"
is certainly legal, but it will not locate the target file either. The target file is not a quoted file name; there-
fore, the quotes cause the match to fail. Altogether, I have not found a syntax that will solve this problem.
Optimizing your Search

Now that wildcard searching is supported, a simple FILES report can take a long time to produce. If you
have many files under your usercode, CANDE may have to do quite a bit of analysis before your FILES
report is complete. Unlike the old, un-wildcarded method, CANDE cannot always start at the top of your
directory and list the files a page at a time as it finds them. Now it must often take the entire list and dis-
card all unwanted ones before it can write line one of the report.
You can shorten the amount of time spent locating files by specifying as many constant directory nodes as
you can at the left-hand end of your request. If you know that all of the files you are looking for are under
the directory XSYSTEM, for example, then you should specify that in your command. The request:
FILES XSYSTEM/[ST]=
will give a much faster response than:
FILES X=[ST]=
even though you might only have one directory under your usercode whose name begins with the letter X.
The first request only analyzes files in the directory XSYSTEM, while the second analyzes all of the files under
your usercode.
The determination of where to search is made at the directory level. Therefore, the more complete direc-
tory nodes you can supply on the left-hand end of the request, the fewer files will be candidates for a match,
and the faster the FILES request will perform.
File Options
The SHOW, SELECT, and SORT options available in the PDIR program are also available to FILES command
users. For the most part, these options work in CANDE just as they do in PDIR. There are, however, some
interesting enhancements as well. In addition, CANDE adds a new option — SEARCH — which determines
where CANDE will look for the files.
In the syntax of the FILES command, SHOW, SELECT, SORT, and SEARCH are considered <file options>. They
may be used alone or in combination with a wildcard specification. They must appear before any ON
<family name> part or any <output options>. The overall syntax is:
Volume 9.06
FILES
< selection expression> < file options>
< file options>
ON < family name >

(CDROM)
: < output options >
To distinguish <file options> from other parts of the syntax, they must be enclosed in a single set of braces
({}). The left brace denotes the start of the <file options>. As the syntax diagram above shows, the <file
options> must be the last item in the command before the optional ON part and <output options>.
The syntax for the <file options> is:
{ < SHOW specification> }

<SELECT specification>
< SORT specification>
< SEARCH specification>
Note that the order of the options is unimportant, which is different from the PDIR program. The PDIR
program requires that SHOW come first, then SELECT, and, lastly, SORT. In CANDE FILES, you can specify
these clauses in any sequence you desire, so long as you only specify each one a single time.
The specifications given in your <file options> determine what files are listed in your final report, what at-
tributes are reported, and how those files are ordered. If you do not specify a <selection expression> — a
name, directory, or wildcard expression — in the FILES command, the default area searched will be your
entire usercode. If you do not specify an ON <family name> part, the search will be done on your current
primary pack family. Thus, the <selection expression> determines the original domain of valid file titles; the
<file options> then further filter that list down to the ones that are finally reported on your terminal.
The SHOW Specification

We described the default report format produced by the FILES command at the start of this article. De-
pending upon your <selection expression>, you will either get the traditional report with one node per line
and the FILEKIND, or you will get a SINGLELINE-formatted report showing the attributes FILEKIND,
RECORDS, SECTORS, and the date portion of CREATIONTIME.
Through the <SHOW specification>, you can choose the specific file attributes you want included in the
report. This is done through the syntax:
SHOW < attribute name >

< file attribute expression>
ALL
The list of valid <attribute name>s is the same as that used in the SELECT and SORT specifications. They
are also the same as used in the PDIR program. We have reproduced that list, adding the abbreviations that
CANDE accepts, in this issue. Note that there are no commas separating the attributes in the list — only
spaces.9
If the list of file attributes is small enough, the report will be written using the SINGLELINE format. Other-
wise, it will be written using LONGFORMAT. For example:
September, 1995
FILES SYS/PRINTS/E= {SHOW SECURITYTYPE

SECURITYUSE}
generates the report:
SYS/PRINTS/E= ON CONTINUUM {SHOW SECURITYTYPE SECURITYUSE}
File Name SecurityType SecurityUse

--------------------------+------------+------------------
SYS/PRINTS/EXPAND PUBLIC IN
1 FILE FOUND
#
On the other hand, the command:
FILES SYS/PRINTS/E= {SHOW SECURITYTYPE
SECURITYUSE MAXRECSIZE BLOCKSIZE
AREAS AREALENGTH}
produces:
SYS/PRINTS/E= ON CREAM {SHOW SECURITYTYPE SECURITYUSE
MAXRECSIZE BLOCKSIZE AREAS AREALENGTH}
File Name Attributes

-----------------------+-----------------------------------
SYS/PRINTS/EXPAND SecurityType= PUBLIC

SecurityUse= IN
Maxrecsize= 30
Blocksize= 270 Areas= 1
AreaLength= 15120
1 FILE FOUND
#
In both cases, the attributes are listed in the sequence that you specify in the <SHOW specification>. The
NAME will always be printed first, even though it need not be specified.
If you want to include all of the file attributes in the report, specify SHOW ALL. This will give you a report in
the LONGFORMAT form, listing every attribute (except for a few that have both mnemonic and integer for-
mats, in which case only the mnemonic format is given). The report is useful if you have forgotten an at-
tribute name or its usage.
The syntax allows ALL to be used in combination with other attributes. If other attributes are specified,
they are superseded by the ALL specification.
The <file attribute expression> option directs CANDE to “show” the file in the report only when the speci-
fied condition is fulfilled. The syntax for a <file attribute expression> is:
OR
AND
< attribute name > = < value>
>
<
>=
<=
<>
!=
The relational operators are defined thusly:
Volume 9.06
= The value of the file attribute must be equal to the requested <value> for the file to be included in the
report.
> The value of the file attribute must be greater than the requested <value> for the file to be included in
the report.
< The value of the file attribute must be less than the requested <value> for the file to be included in the
report.
>= The value of the file attribute must be greater than or equal to the requested <value> for the file to be
included in the report.
<= The value of the file attribute must be less than or equal to the requested <value> for the file to be
included in the report.
<> The value of the file attribute must not be equal to the requested <value> for the file to be included in
the report.
!= Same as <>.
AND Joins two relations, and both must be true.

OR Joins two relations, and at least one must be true.
(More information regarding OR and AND follows in the discussion on SELECT, in the next subsection.)
This works in the same manner in the <SHOW expression> as it does in the <SELECT expression> (de-
scribed next). It is provided in the <SHOW expression> to reduce the amount of typing you need to do in
order to both select and show the same attribute. For example,
FILES = {SHOW EXTMODE <> EBCDIC}
= ON CONTINUUM {SHOW EXTMODE <> EBCDIC}
File Name Extmode

--------------------------+------------------------
SYS/X SINGLE
SYS/AI/TEST SINGLE
SYS/RE/TEST2 SINGLE
SYS/C74/TEST1 SINGLE
SYS/C74/CIRCLE SINGLE
SYS/C74/MATHTEST1 SINGLE
SYS/GEN SINGLE
SYS/XXX SINGLE
SYS/COMS/DIALOGSUPPORT SINGLE
9 FILES FOUND
#
Only files with a non-EBCDIC EXTMODE are selected for the report, and the report shows just the name of
the file and the EXTMODE. If you used a <SELECT expression> instead, as in:
FILES = {SELECT EXTMODE <> EBCDIC}
you would get a list of the non-EBCDIC files, but the attributes shown in the report would be the default
ones (FILEKIND, RECORDS, SECTORS, and CREATIONTIME).
Both forms of the <SHOW expression> may be used in a single command so you can tailor the output ex-
actly to your liking. For example,
FILES = {SHOW FILEKIND EXTMODE <> EBCDIC SECTORS}
= ON CONTINUUM {SHOW FILEKIND EXTMODE <> EBCDIC SECTORS}
File Name Filekind Extmode Sectors

--------------------------+----------------+-------+-------
September, 1995
SYS/X COMPILERCODEFILE SINGLE 45

SYS/AI/TEST ALGOLCODE SINGLE 36
SYS/RE/TEST2 ALGOLCODE SINGLE 72
SYS/C74/TEST1 COBOL74CODE SINGLE 18
SYS/C74/CIRCLE COBOL74CODE SINGLE 18
SYS/C74/MATHTEST1 COBOL74CODE SINGLE 81
SYS/GEN DCALGOLCODE SINGLE 774
SYS/XXX ALGOLCODE SINGLE 9
SYS/COMS/DIALOGSUPPORT DCALGOLCODE SINGLE 432
9 FILES FOUND
#
The selection is still done based upon the EXTMODE, but the report includes the FILEKIND, the EXTMODE,
and the SECTORS count. Thus, you can select the files you want and include other attributes as well in the
display using a single <SHOW expression>.
You can also use the <file attribute expression> in combination with the keyword ALL. This will select files
based upon your <file attribute expression> but report all of each file’s attributes. For example,
FILES SYM/= {SHOW ALL FILEKIND = DCALGOLSYMBOL}
displays only DCALGOLSYMBOL files in the directory SYM, but it lists all of the attributes for each file dis-
played.
The SELECT Specification

Through the <SELECT specification> you can use a series of file attribute relations to determine what ac-
tual file titles are included in your report. Only files that fulfill the attribute requests specified are included;
all others, though they may fulfill the requirements of the outer <selection expression>, are rejected.
The syntax for the <SELECT specification> is:
SELECT < file attribute expression>
The syntax for the <file attribute expression>, with a description of the various parts, is given on the previ-
ous page.
The simplest relation is one involving a numeric-valued file attribute. Of these, the most commonly wanted
search has got to be the search for the “big offender” — i.e., that monster file that you swear is out there
needlessly using up all of your disk space. Using a simple SELECT expression, you can list all of your files
that are above a certain size. If the target size is 50,000 sectors, the command is:
FILES {SELECT SECTORS > 50000}
A possible response would be:
= ON CONTINUUM {SELECT SECTORS > 50000}

------------+-----------+---------+------------+------------
SYSTEM/MCP MCPCODEFILE 84557 84564 04/20/1995
1 FILE FOUND
#
Note that the attributes reported are the default ones. (SECTORS just happens to be one of the default
ones.) Had SHOW been used instead of SELECT, only the file name and the sectors value would have been
reported.
To test for a boolean-valued attribute, you must use a complete relation; use either
<attribute> = TRUE
or
<attribute> = FALSE
Volume 9.06
As shown, you can abbreviate TRUE and FALSE to a single letter. For example:
FILES DATA/= {SELECT INUSE = T}
This would restrict the report to just those files in the DATA directory that are in use. Similarly,
FILES DATA {SELECT INUSE = FALSE}
reports those files that are not in use.

For string-valued attributes, simply specify the target string after the relational operator. The target string
must not be enclosed in quotes. A simple example is:
FILES {SELECT FILEKIND = DCALGOLSYMBOL}
This expression lists all of the files under your usercode that have a FILEKIND of DCALGOLSYMBOL. All other
files are ignored. You would not get the same results with:
FILES {SELECT FILEKIND = "DCALGOLSYMBOL"}
This command would be accepted and processed. However, it would report that no such files exist since
none of the FILEKINDs are represented by the word DCALGOLSYMBOL in quotes.
You may use wildcard characters in your string target. The wildcard characters are the same three pre-
sented earlier (i.e., the equal sign, the tilde, and the question mark), and they have the same meanings as
before. For example, if you would like a listing of all of the DCALGOL source and object files on a pack fam-
ily, use the <SELECT specification>:
SELECT FILEKIND = DCALGOL=
Similarly, if you would like to locate all of the codefiles on a pack family, use:
SELECT FILEKIND = =CODE
If you want to select files by any of the date attributes, be sure to note that all of the date and time values
are given as strings, in the format:
YYYYMMDDHHMMSSdddd
where:
YYYY represents a four-digit year;
MM is a two-digit month;
DD is a two-digit day of the month;
HH is a two-digit hour, in 24-hour notation;
MM is a two-digit minute;
SS is a two-digit seconds value;
dddd is a four-digit number providing fractions of a second.
This format allows you to use wildcard characters when searching for date-related values. The date-related
attributes are ALTERTIME, CREATIONTIME, LASTACCESSTIME, and TIMESTAMP.
If, for example, you want to obtain a list of all of the files in your usercode that have been changed in some
manner today — and “today” is September 15, 1995 — use the <SELECT specification>:
TIMESTAMP = 19950915=
For example:
FILES {SELECT TIMESTAMP = 19950915=}
The report would look like:
= ON CONTINUUM {SELECT TIMESTAMP = 19950915=}

--------------------------+------------+------------+
O/FACS/T/CATALOG ALGOLCODE 4641

S/FACS/T/CATALOG ALGOLSYMBOL 18853
ERR/S/FACS/T/CATALOG DATA 1
September, 1995
OLD/SYM/FACSMANAGER DMALGOLSYMBO 2236

SYM/FACSCOPIER DMALGOLSYMBO 1033
SYM/FACSMANAGER DMALGOLSYMBO 2236
SYM/FACSSUPPORT DMALGOLSYMBO 1865
7 FILES FOUND
#
Similarly, if you want to find all of the files that have not been opened since the beginning of the year, use
the command:
FILES {SELECT LASTACCESSTIME < 1995=}
The trailing wildcard accounts for all of the extra positions (down to the fractions of a second) that are
stored as part of the date.
Pattern matching is also supported for the string-valued attributes. The syntax and operation is the same as
described earlier for file name searching. For example, if you want to find only the files under your user-
code that are of type DCALGOLSYMBOL or DMALGOLSYMBOL, you could use:
FILES {SELECT FILEKIND = D[MC]ALGOLSYMBOL}
Although you must not enclose your target string in quotes, if the target you are searching for contains
quotes, then you must use quotes that match those of your target. For example, if you have the file
X/"Y.Z" under your usercode, you could locate it using the following command:
FILES X= {SELECT NAME= ="Y.Z"}

In this case, the quotes are part of the target, so they must be specified in order to locate a match.
You cannot use blanks in the target string at all. If your target contains blanks, you must substitute a
wildcard character to handle them. For example, the SSR 41.2 version of SYSTEM/ALGOL has a RELEASEID
of SSR 41.2 (41.253.0327). If you attempt to locate it through:
FILES {SELECT RELEASEID = SSR 41.2 (41.253.0327)}
you will get a syntax error as CANDE interprets the “41.2” as the start of another attribute expression. To
avoid this problem, you must use a wildcard expression, as in:
FILES {SELECT RELEASEID = SSR?41.2?(41.253.0327)}
This will successfully find the file.
You can apply more than one condition to your FILES search. To do this, join the different conditions to-
gether with AND or OR operators. For example, to find all of the files under your usercode that haven’t been
touched this year and are over 500 sectors in size, use:
FILES {SELECT SECTORS > 500 AND
LASTACCESSTIME < 1995=}
To further refine the list by excluding all files that are under the directories SYMBOL and SYSTEM, use:
FILES {SELECT SECTORS > 500 AND
LASTACCESSTIME < 1995= AND
NAME <> SYMBOL/= AND
NAME <> SYSTEM/=}
You may intermix AND and OR operations in the same SELECT request. The ORs are evaluated first and then
the ANDs. Parentheses cannot be used in a SELECT expression, so you are stuck with the default evaluation
rules.
This means that if you use an expression such as:
SELECT LASTACCESSTIME > 1991= AND
LASTACCESSTIME < 1995= OR
SECTORS > 500
the expression
LASTACCESSTIME < 1995= OR SECTORS > 500
Volume 9.06
will be evaluated first, and the result of that will be ANDed with LASTACCESSTIME > 1991 to determine
whether or not the file is included in the report.
For easily predictable results, construct your SELECT condition using either all ANDs or all ORs.
If you are using a SELECT expression, and you want to see the actual file attribute value which fulfilled your
condition, you will need to include a SHOW condition as well. This will be true unless the attribute whose
relation you’ve specified is included in the default report.
As we mentioned earlier, SHOW supports the same syntax as SELECT. Therefore, if you want to locate files
based upon some attribute, and you want to include that attribute in your report, you do not need to specify
it twice. Simply substitute the word SHOW for SELECT, and you’ve got it!
For example, to locate all of the files last opened before the start of the year that are over 500 sectors in
size, and show the name, date, and sector size in the report, use:
FILES {SHOW SECTORS > 500 AND
LASTACCESSTIME < 1995=}
This is the same command given above, with SHOW substituted for SELECT. The generated report looks like
this:
= ON CONTINUUM {SHOW SECTORS > 500 AND LASTACCESSTIME <
1995=}
File Name Sectors LastaccessTime

--------------------------+----------+---------------------
DBF/TESTGEMCOSDB 4096 05/15/1993 @ 16:38:58

SYM/DEPOT/FEEDTPMCS 868 12/21/1994 @ 16:49:26
SYM/IXLOG 532 12/16/1993 @ 11:47:07
SYM/ZOLLE 546 12/21/1994 @ 16:42:01
COMS/DUMP/032093/183340 1400 03/19/1994 @ 18:35:05
5 FILES FOUND
#
Therefore, use SELECT when you want to use a relation but not include it in the report, and use SHOW when
you want the attribute included in the report.
The SORT Specification

The <SORT specification> determines the order of the report. By default, the report is ordered in the
same manner as a FILEDATA report: first by the length of each directory node, and then alphabetically.
You can override this ordering with a <SORT specification> and generate instead a report that is ordered by
any combination of file attribute values.
The syntax for the <SORT specification> is:
SORT + < attribute name >

-
Again, this is the same list of <attribute name>s that you can use in a SHOW or SELECT clause. There are no
commas used if more than one attribute is specified. Use only spaces to separate the items.
If you specify:
+ <attribute name>
the report will be written in ascending order by that attribute; if you specify:
– <attribute name>
the report will be in descending order by that attribute. As the diagram shows, you may specify as many
different attributes as you like.
Suppose, for example, that you want to obtain a list of all of the files under your usercode that are over 500
sectors in size, and you want that report sorted with the largest files at the top. The command would be:
September, 1995
FILES {SHOW SECTORS > 500 SORT –SECTORS}

A partial report would look like this:
= ON CONTINUUM {SHOW SECTORS > 500 SORT - SECTORS}
File Name Sectors

--------------------------+------------------------
OLD/SYM/TPMCS/TPMCSSUPPORT
5614
SYM/TPMCS/TPMCSSUPPORT 5614
DBF/TESTGEMCOSDB 4096
SYM/SITENETSUPPORT 3738
SYM/SITENETSUPPORT/930512 3724
SYM/TPMCS/JANUS 2058
TOURIST/S/TP/Z100 2044
SYM/TPMCS/LAPIN 1568
Since you can sort on any file attribute, you can obtain a variety of different reports that were previously
difficult to obtain. For example, if you sort by LASTACCESSTIME, you can quickly locate files that haven’t
been touched in years. If you sort by FILEKIND, you can list your files in order by type — first the codefiles,
then the source files, then the data files, etc. There is no longer any excuse for losing track of your files!
Lastly, if you want a report that is in true alphabetical order by file name, sort by the NAME attribute. For
example:
FILES {SORT +NAME}
The SEARCH Specification

The <SEARCH specification> allows you to specify the global domain of the FILES command via the syn-
tax:
SEARCH RESIDENT
NON RESIDENT
ALL
CDROM
USERCODEONLY
The first three values deal with archived files. They perform the same function as the RES, NON, and ALL
<output options>, respectively. For more information on them, see the subsection titled “Showing Ar-
chived Files”, starting on page 9-207.
If your SEARCH clause conflicts with your <output options>, the <output options> are ignored. For exam-
ple,
FILES {SEARCH RESIDENT}:NON
reports just the resident files.
The CDROM option tells CANDE to list the files on an ISO standard CD-ROM. For example, if you insert
the LINC 15.2 documentation CD into a CD-ROM drive that is connected to your A-Series system, and
you enter the command:
FILES = ON LINC152_PTX {SEARCH CDR}
you will get a report that begins thusly:
*= ON LINC152_PTX {SEARCH CDR}

--------------------------+------------+------------+
*BOOKLIST DATA 2312

*H/"ACCEL.300" DATA 842
Volume 9.06
*H/"ACCESS.300" DATA 468

*H/"ACTON.300" DATA 404
*H/"ADVISORS.300" DATA 1352
*H/"BARCHART.300" DATA 1698
*H/"BARON.300" DATA 288
*H/"BOOL.300" DATA 950
*H/"BYID.300" DATA 269
*H/"BYSORT.300" DATA 983
You need to supply the correct name in the command for CANDE to identify what CD-ROM you want
searched. Moreover, the disk in the CD-ROM drive must be named. (Not all are, so beware.) To obtain
the name of the disk, use the ODT (or MARC) command:
PER CD
Unfortunately, this option does not work with a system software distribution CD-ROM, as those are in Li-
brary/Maintenance format.
Note that specifying {SEARCH CDROM} is completely different from putting the modifier (CDROM) after a
<family name> in your FILES command. The command:
FILES ON STORAGE(CDROM)
searches a CD-ROM disk named STORAGE that is formatted in A-Series directory format. SEARCH{CDROM},
on the other hand, expects a disk that uses an ISO directory structure. Again, neither one works with a CD-
ROM in Library/Maintenance format.
The final option,

SEARCH USERCODEONLY
instructs CANDE to only search for your target files under your usercode. Default action is to search the
global (*) directory if the directory you specify in your command cannot be found under your usercode.
SEARCH USERCODEONLY inhibits this default action.
For example, if you enter:

FILES SYSTEM/= {SHOW FILEKIND = NEWPCODE}
and there is no SYSTEM directory under your usercode, CANDE will give you a report on the *SYSTEM di-
rectory (on your pack family). If you want to prevent that action, specify:
FILES SYSTEM/= {SHOW FILEKIND = NEWPCODE
SEARCH USERCODEONLY}
Now CANDE will only look under your usercode.
Side-Effects of the File Options

There are side-effects to using <file options> in your command. FILES commands that use <file options>
are processed by the MCP procedure ASERIES_INFO, while those without <file options> are processed by
the old CANDE logic. I have noticed a particular inconsistency when using a <file directory> with <file
options> as opposed to a <directory name> or a wildcard expression in the same context.
As stated at the beginning of this article, the commands:
FILES <file directory>
and
FILES <directory name>
mean the same thing. A <file directory> does not use the trailing /=, while a <directory name> does. With
a simple FILES command, both return the same results.
However, if you include any <file options> in your command, these two do not return the same results.
When <file options> are specified, the rules are as follows:
September, 1995
1. If a <file directory> is given (i.e., no /=), only the directory name is returned; none of the files under that
directory are reported.
2. If a <directory name> is given (i.e., the /= is included), the files under that directory are reported.
This is a bit of inconsistency caused by the retention of the old logic in combination with the new logic.
Keep this in mind when specifying <file options> in your FILES commands.
Wrap-up
There are additional features available in the FILES command which are beyond the scope of this article.
In particular, there are additional pattern matching features available which support characters not in the
standard USA character set. For a complete description of the FILES command, plus several more pattern
matching and wildcarding examples, see the Unisys CANDE Operations Reference Manual.
And while you’re at it, send Unisys a thank-you note for implementing such a great feature in CANDE!
1
The LFILES command runs the program *SYSTEM/FILEDATA.
2
Gregory, Donald J., “PDIR: the Modern Way to Search for Files”, Gregory’s A-Series Technical Journal, vol. 9:04,
June, 1995, pp. 9-109 – 9-120.
3
The work, however, was moved from the GRIND stacks to a new stack called the SERVANT stack. We will discuss this in
Part Five of this series in the next issue of the A-Series Technical Journal.
4
Gregory, Donald J., the Complete CANDE Primer, Gregory Publishing Company, 1986, §8.2.4.
5
According to the CANDE Operations Reference Manual, these words may be fully spelled out as RESIDENT and
NONRESIDENT. This is not true. You must use a three-letter token of RES, NON, or ALL.
6
The Complete CANDE Primer, op. cit., pp. 17 – 18.
7
The Common Scan Routines will properly recognize an embedded period in a quoted file name. This is one of the
few parsing libraries that properly handle quoted file titles. Most programs attempt to identify the end of a title by
“scanning for a period”, which will fail if you have a period inside quotes in your file title. Therefore, don’t do it!
8
Unisys Corporation, A-Series CANDE Operations Reference Manual, form #8600 1500-200, Section 3, “CANDE
Commands: FILES: Selecting Files with Directory Name Nodes: Using the ? (Question Mark) Wild-Card Character”
(Doc ID #13256 in SSR 41.2).
9
SYSTEM/PDIR requires commas between the attributes.
Volume 9.06
CANDE: Using Parameters with ‘DO Files’ / 59
CANDE: Using Parameters with ‘DO Files’

eginning in the Mark 2.8 release, Unisys gave CANDE users the ‘DO file’ feature. This feature enables the
CANDE user to save a series of instructions in a disk file and submit them, as a script, to CANDE for exe-
cution. The script runs from the user’s terminal. Responses are returned to the user’s terminal. All be-
havior is the same as if the user entered the commands from the terminal rather than from a disk file.
The <DO file> may contain any CANDE command except control commands. A simple example of a
<DO file> is:
100 TERM DOWN 4
200 ESC HEX = !
If these two lines are stored in a disk file named SCRIPT/1, then the command:
DO SCRIPT/1
would cause them to be executed. The CANDE response would be:
#FILE (Q)SCRIPT/1 ON CONTINUUM
#
TERM DOWN 4
DOWN = 4, "\"
ESC HEX = !
When the DO command is entered, CANDE takes the contents of SCRIPT/1 and inserts it into the user’s
input queue. Each line of the script is then executed in turn as it comes to the top of the queue. Before
execution, each line is displayed to the user, as shown in the above example. The response to the com-
mand, if any, is also displayed. When the sequence completes, CANDE is ready for the next input from the
user.
We discussed the ‘DO file’ facility in depth in the Complete CANDE Primer.1 There are several options
available with the DO command which are discussed in that book. The material which follows is written un-
der the assumption that the reader is familiar with that in the CANDE Primer.
The Need for Parameters

The original implementation of the ‘DO file’ feature provided only for static scripts. While useful in a few
limited contexts, this does not address the general problem. Scripting provides an excellent solution to a
very large number of problems. Through effective scripting, you can eliminate repetitious work and
thereby save yourself hours of time. But effective scripting requires one very important ingredient that the
CANDE ‘DO file’ feature has been lacking until now. That feature is parameters.
We gave a simple example of a static script in the previous section. Let’s now tackle a more complex script.
Suppose we want a quick and easy way of submitting compiles into WFL job queues so we can avoid using
the on-line COMPILE command in CANDE. Without the parameter facility, we can write a simple script to
process a single program. That script would be:
100 MAKE WFL/COMPILEIT JOB
200 100?BEGIN JOB COMPILEIT;
300 200QUEUE = 2;
400 300COMPILE OBJECT/P1 WITH ALGOL LIBRARY;
500 400COMPILER FILE SOURCE
600 500 (KIND=DISK, TITLE=P1);
700 600COMPILER DATA CARD
800 700$$ SET MERGE RESET LIST
900 800?END JOB
1000 START
1100 REMOVE
September, 1995
This script, called SCRIPT/2, creates a WFL job that will compile the source file P1 and create the codefile
OBJECT/P1. An example execution of it is:

#
MAKE WFL/COMPILEIT JOB
#WORKFILE WFL/COMPILEIT: JOB
100?BEGIN JOB COMPILEIT;
200QUEUE = 2;
300COMPILE OBJECT/P1 WITH ALGOL LIBRARY;
400COMPILER FILE SOURCE
500 (KIND=DISK, TITLE=P1);
600COMPILER DATA CARD
700$$ SET MERGE RESET LIST
800?END JOB
START
#UPDATING
#RUNNING 6624
#JOB 6625 IN QUEUE 2
#
REMOVE
#
#6625 BOJ COMPILEIT
#6625\6626 BOT ALGOL OBJECT/P1
#6625\6626 EOT (Q) *ALGOL OBJECT/P1
#6625\6625 EOJ (Q) JOB COMPILEIT
The problem with this setup is that if you want to compile a different program, you have to load this file,
use the REPLACE command to change the program name, save it, and then DO it. (You have to save it be-
cause the script itself MAKEs a workfile, so the script will not successfully run if you have a workfile loaded.)
If you decide to keep both versions of the DO file, you will begin to accumulate many little files all for the
same purpose but with different program names. You might also want to change other things about the file,
leading to the proliferation of more little <DO file>s. Then, when you want to use a file you made weeks
previously, you may not even remember which file contains the instructions you want!
The answer to this, of course, is to use parameters in your <DO file>.
Declaring Script Parameters

To use parameters in your <DO file>, you must first declare those parameters at the beginning of the <DO
file>. The syntax for a <parameter declaration> is:
PARAMETERS ( < parameter specification> )
: SUBCHAR < param delimiter >
The word PARAMETERS and the left parenthesis (() must both appear on the first line of the <DO file>. The
remaining text may be spread across multiple lines of the file.
Inside the parentheses you define a series of parameter names and optional default values. This is done
through the <parameter specification>, which has the syntax:
99 ,
< parameter name >
< default spec>
Each <parameter name> may be up to 63 characters in length. The <parameter name> must begin with a
letter; the other characters may be letters, numbers, hyphens (-), or underscores (_). Thus, the following
are all valid <parameter name>s:
Volume 9.05
P1 PARAMETER-1
PARAMETER1 PARAM_1_STRING
We will discuss the use of the <default spec> in a later section.
Using Parameters in the Script

Using a parameter in a <DO file> script is extremely simple. Just insert the parameter name into the script
and surround it with <param delimiter> characters. The default <param delimiter> is the pound sign (#).
For example:
100 PARAMETERS (PARAM1)
200 TERM DOWN #PARAM1#
When you submit this file, you must supply a value for the parameter. That value will be used wherever the
<parameter name> appears. The substitution will be a literal one, so whatever you type for the parameter’s
value will be inserted to create the CANDE statement.
Thus, if the above file is called SCRIPT/3, you could enter:
DO SCRIPT/3 (4)
The resulting execution would be:
PARAMETERS (PARAM1)
#
TERM DOWN 4
DOWN = 4, "\"
Note that the 4 has been substituted for the text #PARAM1# in the file, and the command executed was:
TERM DOWN 4
A parameter can substitute for any part of a CANDE command. It is not limited to a single token in that
command. Whatever you enter as the parameter’s value (through the DO command) is literally inserted in
place of the parameter when the command is submitted to CANDE. Thus, if we have a file called
SCRIPT/4 that contains just:
100 PARAMETERS (PARAM1)

200 TERM #PARAM1#
we could do either of the following:
DO SCRIPT/4 ("DOWN 4")
This substitutes the text DOWN 4 for #PARAM1#¸ creating the command
TERM DOWN 4
which is submitted to CANDE.
DO SCRIPT/4 ("LINE 80 PAGE 24 WAIT")
This substitutes the text LINE 80 PAGE 24 WAIT for #PARAM1#¸ creating the command
TERM LINE 80 PAGE 24 WAIT
and submits that to CANDE.
Thus, we now have a much more flexible script because the parameter substitutes for part of a command
rather than just a single token.
Parameter “Types”
As you may have noted, the parameter to SCRIPT/4 was enclosed in quotes, while that to SCRIPT/3 was
not. The need for quotes is determined by the parameter type, which CANDE infers from the usage of the
parameter.
There are four possible parameter types: integer, real, boolean, and string. Each may receive a constant
value when you enter the DO command. The rules for defining each possible constant are as follows:
September, 1995
• An integer constant is a number composed entirely of digits. It may be from 1 to 12 digits in length. It
may be prefixed by an optional sign (+ or –).
• A real constant is the same as an integer constant except that it may contain an optional decimal point
inside the number. (There is no provision for specifying an exponent, however.)
• A boolean constant is either the keyword TRUE or FALSE.
• A string constant may be any sequence of characters enclosed in quotes. If a quote is to be included
inside the string, you must substitute two quotes where you want the quote to be. For example:
"This pair of quotes here ("") represents a single quote to CANDE."
String constants must be enclosed in quotes. For the other constants, quotes are optional.
In our previous examples, SCRIPT/3 used an integer parameter, while SCRIPT/4 required a string parame-
ter. Thus, SCRIPT/3 could be executed with either of the following commands:
DO SCRIPT/3 (4)
DO SCRIPT/3 ("4")
However, SCRIPT/4 could only be executed with the parameter value enclosed in quotes, as in:
DO SCRIPT/4 ("DOWN 4")
Specifying Default Values

As noted earlier, the PARAMETERS clause permits you to include a <default spec> as part of a <parameter
name> definition. With the <default spec>, you can give the parameter a default value. This value will be
used if no value is supplied in the DO command.
The syntax for the <default spec> is:
= < parameter name>
DEFAULT &
< string constant>
< integer constant>
< real constant>
< boolean constant>

The equal sign is required. The keyword DEFAULT is optional.
The following variation of SCRIPT/3 illustrates the use of a <default spec>:
100 PARAMETERS (PARAM1 DEFAULT = 4)
200 TERM DOWN #PARAM1#
If this file is called SCRIPT/5, you can use any of the following commands to set your default “down” speci-
fication to 4:
DO SCRIPT/5
DO SCRIPT/5(4)
DO SCRIPT/5("4")
Now it is no longer an error to omit the parameter. Instead, if the parameter is not specified, the default
value of 4 is used instead.
You cannot split a <string constant> over different lines in a <DO file>. If you have a single <string con-
stant> that requires more than a single line, you must separate the string into separate segments and use
the ampersand (&) to join them together. CANDE will then treat the entire expression as a single string
value for one parameter.
For example, consider the following modification to SCRIPT/4:
100 PARAMETERS (PARAM1 DEFAULT =
200 "LINE 80 " &
Volume 9.05
300 "PAGE 24")

400 TERM #PARAM1#
CANDE joins the two segments "LINE 80 " and "PAGE 24" into the single <string constant>:
"LINE 80 PAGE 24"
This value is then used as the default for the TERM command if no parameter is specified.
Building a Compile Utility

We began this article with an example <DO file> that would build a WFL job and initiate a batch compile
of a program. Using the parameter feature, we can turn this into a more general-purpose <DO file> that
can compile a variety of programs and set various options in the process.
To begin with, we will make the program name a parameter. The revised <DO file>, now called
COMPILE/SCRIPT/1, follows below. The shading depicts the lines which were revised from the original.
100 PARAMETERS (
200 PROGRAMNAME)
400 100?BEGIN JOB COMPILE/#PROGRAMNAME#;
500 200QUEUE = 2;
600 300COMPILE OBJECT/#PROGRAMNAME# WITH ALGOL LIBRARY;
800 500 (KIND=DISK, TITLE=#PROGRAMNAME#);
1100 800?END JOB
1200 START
1300 REMOVE
To compile program P1 with this <DO file>, use the command:

DO COMPILE/SCRIPT/1 ("P1")
The results will be:
#FILE (Q)COMPILE/SCRIPT/1 ON CONTINUUM
PARAMETERS (
PROGRAMNAME)
#
100?BEGIN JOB COMPILE/P1;
200QUEUE = 2;
300COMPILE OBJECT/P1 WITH ALGOL LIBRARY;
800?END JOB
START
#UPDATING
#RUNNING 6634
#
REMOVE
#
#6635 BOJ COMPILE/P1
#6635\6636 BOT ALGOL OBJECT/P1
#6636 PK47 (Q)OBJECT/P1 REPLACED ON CONTINUUM
#6635\6636 EOT (Q) *ALGOL OBJECT/P1
#6635\6635 EOJ (Q) JOB COMPILE/P1
Now we have the ability to change the program name at any time.
Suppose we also want to specify the compiler through a parameter as well. In this case, we want the default
compiler to be ALGOL. However, in some cases we might need to use DCALGOL, DMALGOL, or NEWP. The
September, 1995
simplest answer is to create a second parameter that has a default value of "ALGOL". The file, called
COMPILE/SCRIPT/2, would be as follows. Again, the changes are highlighted.
100 PARAMETERS (
200 PROGRAMNAME,
250 COMPILERNAME = "ALGOL")
500 200QUEUE = 2;
600 300COMPILE OBJECT/#PROGRAMNAME#
650 350 WITH #COMPILERNAME# LIBRARY;
1100 800?END JOB
1200 START
1300 REMOVE
Now if we use the command:
DO COMPILE/SCRIPT/2 ("P1")
we will get the same results as with COMPILE/SCRIPT/1. The default value for COMPILERNAME is "ALGOL",
so P1 is compiled with the ALGOL compiler. But we could also use:
DO COMPILE/SCRIPT/2 ("P1", "DCALGOL")
In this case, the results are:
PARAMETERS (
PROGRAMNAME,
COMPILERNAME = "ALGOL")
#
200QUEUE = 2;
300COMPILE OBJECT/P1 WITH DCALGOL LIBRARY;
800?END JOB
START
#UPDATING
#RUNNING 6642
#
REMOVE
#
#6643\6644 BOT DCALGOL OBJECT/P1
#6643\6644 EOT (Q) *DCALGOL OBJECT/P1
And program P1 has now been compiled with the DCALGOL compiler.
You can add as many variations as you like by adding more parameters. For example, you might want to
make the queue specification at line 500 (of the <DO file>) changeable. This could be another parameter
with a default value.
One of the more interesting things you can do with these parameters is use them when building a <data
deck> for the WFL file. CANDE doesn’t care where in the <DO file> the parameter is used. It can be in
any context. CANDE will literally paste the value you supply with the DO command into the file when
processing it. Therefore, you can also use parameters inside lines that become part of a <data deck> that is
later read as input to the WFL job.
Volume 9.05
You can put this feature to good use by providing a few parameters whereby the user can supply <compiler
options> to the compile job. The default for these parameters would be blank or the single character "%"
so they would be ignored by the compiler if not used. For example, consider COMPILE/SCRIPT/3:
100 PARAMETERS (
200 PROGRAMNAME,
250 COMPILERNAME = "ALGOL",
260 COMPOPTION1 = "%",
280 COMPOPTION3 = "%")
500 200QUEUE = 2;
600 300COMPILE OBJECT/#PROGRAMNAME#
650 350 WITH #COMPILERNAME# LIBRARY;
1010 710$$ #COMPOPTION1#
1100 800?END JOB
1200 START
1300 REMOVE
We will use a DO command with only two sets of <compiler options>, so the third parameter will take its
default value. The DO command is:
DO COMPILE/SCRIPT/3 ("P1", "DCALGOL",
"SET LIST STACK LINEINFO NOBINDINFO",
"RESET XREF XREFFILES")
The result is:
PARAMETERS (
PROGRAMNAME,
COMPILERNAME = "ALGOL",
COMPOPTION1 = "%",
COMPOPTION2 = "%",
COMPOPTION3 = "%")
#
200QUEUE = 2;
300COMPILE OBJECT/P1
350 WITH DCALGOL LIBRARY;
710$$ SET LIST STACK LINEINFO NOBINDINFO
720$$ RESET XREF XREFFILES
730$$ %
800?END JOB
START
#UPDATING
#RUNNING 6651
#
REMOVE
#
#6652\6653 BOT DCALGOL OBJECT/P1
#6652\6653 EOT (Q) *DCALGOL OBJECT/P1
September, 1995
Since the ALGOL compilers do not complain about lines that begin with two dollar signs and are followed
immediately by a comment character (%), this sequence works.
This is fortunate because there is no testing facility provided in the CANDE ‘DO file’ feature. All uses of a
parameter must be unconditional. There is no way to code an expression such as:
If COMPOPTION3 = "%" then don’t include it.
If you want to use COMPOPTION3 at all within your <DO file>, you must use it in a context that will give you
error free results for every combination that your <DO file> is designed to handle.
If you are processing a <DO file> that uses several optional parameters, you may omit any combination of
the optional ones in your DO command. The ones you omit do not have to be at the end of the list.
To omit a parameter in the middle of the list, use two adjacent commas. For example, to process
COMPILE/SCRIPT/3 using the default value for COMPILERNAME but including a "SET LIST" instruction in
COMPOPTION1, use the command:
DO COMPILE/SCRIPT/3 ("P1",,"SET LIST")

This will compile program P1 with the ALGOL compiler, setting the LIST option.
Changing the Parameter Delimiter

The character used to identify parameter usage in the <DO file> is called the <param delimiter>. This
character must not be used for any other purpose inside the file. If it happens to be used out of context,
CANDE will reject your <DO file> with the message:
#SYNTAX ERROR IN DO FILE RECORD
#DO FILE ABORTED AT LINE <line number>
The default <param delimiter> is the pound sign (#). In a large number of contexts, you will not run into
any conflict with this character. If you do, however, you will need to redefine the <param delimiter> as
another character.
To redefine it, you must specify a different character in your <parameters declaration> at the start of the
<DO file>. Recall that the syntax for a <parameters declaration> is:
PARAMETERS ( < parameter specification> )
: SUBCHAR < param delimiter >
The optional SUBCHAR part allows you to redefine the <param delimiter> to any character of your choice.
To use the SUBCHAR part, you must put the right parenthesis, the colon, and everything that follows the co-
lon on a single line of your <DO file>. If you fail to do this, CANDE will either ignore your SUBCHAR speci-
fication or give you a runtime error. For example, the sequence:
100 PARAMETERS (
200 PROGRAMNAME,
300 COMPILERNAME = "ALGOL"
400 ) : SUBCHAR @
will work because all four elements are on the same line. However,
100 PARAMETERS (
200 PROGRAMNAME,
300 COMPILERNAME = "ALGOL")
400: SUBCHAR @
does not work; the SUBCHAR specification is completely ignored. Other variations result in a runtime error.
The <param delimiter> character, as shown in the above examples, is not enclosed in quotes.
Volume 9.05
Suppose that your <DO file> contains a WFL subroutine where a string expression must be used in a
REMOVE statement. The WFL syntax for doing this requires that you use a pound sign. For example:
SUBROUTINE CLEANUP (STRING FYLENAME);

BEGIN
REMOVE OBJECT/#FYLENAME;
END;
You could not use this inside a <DO file> and use the default <param delimiter>. Instead, you would have
to change the <param delimiter> to some other character that was not used anywhere in the file. In
COMPILE/SCRIPT/4, the file below, we substitute the at sign (@) as the <param delimiter>. Again, the
changes are highlighted.
100 PARAMETERS (
200 PROGRAMNAME,
250 COMPILERNAME = "ALGOL",
280 COMPOPTION3 = "%"
290 ) : SUBCHAR @
400 100?BEGIN JOB COMPILE/@PROGRAMNAME@;
500 200QUEUE = 2;
510 210
520 220SUBROUTINE CLEANUP (STRING FYLENAME);
530 230 BEGIN
540 240 REMOVE OBJECT/#FYLENAME;
550 250 END;
560 260
570 270CLEANUP ("@PROGRAMNAME@");
580 280
600 300COMPILE OBJECT/@PROGRAMNAME@
650 350 WITH @COMPILERNAME@ LIBRARY;
800 500 (KIND=DISK, TITLE=@PROGRAMNAME@);
1010 710$$ @COMPOPTION1@
1100 800?END JOB
1200 START
1300 REMOVE
After changing the <param delimiter> character through the SUBCHAR specification, we had to make sure
that all of the parameters were now delimited by the new character — the at sign (@).
1
Gregory, Donald J., the Complete CANDE Primer, Gregory Publishing Company, 1986, pp. 276 – 280.
September, 1995
CANDE: The Help Facility
elp first became a standard feature of the Unisys A-Series computer line in the Mark 3.5 release. When
COMS and MARC first became available, they were distributed with a new on-line “help” system. For
the first time in history, A-Series users were able to get software documentation on line from a standard
set of reference files authored by Unisys Corporation.
Because CANDE was invented long before COMS and MARC, it did not come with on-line help sup-
port. Yet CANDE, being a command-oriented software product, is far more needful of on-line help than
MARC or any of the other form-based software products. CANDE expects its users to know proper
command syntax, and this always has to be memorized. On-line help provides the easiest way for a user
to obtain the needed command syntax.
In the Mark 4.1 software release Unisys gave CANDE users on-line help. In doing so, they implemented a
robust Help facility with many user-friendly features. Now the syntax and usage details of every CANDE
command are at any user’s fingertips. Moreover, this Help facility is compatible with the other Unisys
documentation files, so you can use it to access documentation on MARC, IDC, and other Unisys products.
And the best part is that anyone can use this feature at any time — without firing up a task.
Help Mode
To get on-line help through CANDE, you begin by entering the command:
HELP
This places your session into help mode. While in help mode, CANDE behavior is similar to what you
would expect if you had run a program. Only commands related to the Help facility and control commands
(those preceded by a question mark) are valid; all others return an error message. To exit help mode and
return to normal CANDE functions, enter either:
EXIT
or
QUIT
(The command BYE will also get you out of help mode. However, its use is not recommended as it will have
deleterious side-effects should you enter the command thinking you are in help mode when you actually are
not!)
Although help mode acts differently than normal CANDE, entering help mode does not fire off a task. The
entire feature is handled by a CANDE worker. Thus, the feature is extremely fast to both enter and exit,
and you can do so as often as you wish without incurring system overhead. This is probably the slickest part
of the implementation.
Help Screen Layout

Help mode is the first TD830-specific feature in CANDE.1 When you enter help mode, you receive a
screen such as that given in figure 1 (shown on the next page). This screen is divided into four segments:
the command line, the option line, the error message line, and the display area.
The top line is the command line. You can enter any Help System command on this line.
There are two ways to enter a command on this line. You can type the command and press the {xmit} key.
Alternatively, you can position the screen cursor over any command already displayed there and press the
{specify} key.
The second line is the option line. This line gives you a list of prompts, showing the valid help mode com-
mands. You may type any of these commands on the command line and {xmit} it to execute the command.
Volume 9.06
CANDE: The Help Facility / 69
+ 6.29 HELP COMMAND Command Line

+ - KEys BAck FOrwrd PRev TOpics REf PArnt RLtd SUb QUit
________________________________________________________________________________ Option Line
HELP Command
Error Message
Line
Syntax
-- HELP ------------------------------------------------------------|
Display Area
| | | |
(for remainder
|-<keyword>--------------------------| |- : -- PRINTER -|
of screen)
| | | | - |
|- KEYS -------| |- IN --<book name>-| |
| | |
|- TOPICS -----| |
| | |
|- REFERENCES -| |
| |
|- ? ---------------------------------------------------|
| |
|- * ---------------------------------------------------|
| |
|- = --<book name>--------------------------------------|
Figure 1
Initial Screen Response to the HELP Command
You may also position the cursor over any of these commands (on the option line) and press the {specify}
key; this will also execute the command.
The third line is where the Help System will report any error messages. If the most recent command was
not in error, this line will be filled with underscores all of the way across the screen.
The remainder of the screen contains the help information.
Using the Help Mode Commands

The prompts on the option line list most of the commands you may use. There are a couple of others not
listed that we shall also describe.
For the most part, the operation of the Help System is very straightforward. You select a topic, through the
HELP command, and the first page of information on that topic is displayed as shown in figure 1. You then
use the Help System commands to move forward and backward within this information or to move on to
other topics.
The following examples illustrate the various commands. (The screens are abbreviated for formatting pur-
poses.)
September, 1995
Entering a + command moves the screen + 6.29 HELP COMMAND

display one page forward, as shown on ________________________________________________________________________________
the right. This is the page that follows | |
|- : -- REMOVE ----------------------|
the one given in figure 1, above.
If you are at the end of a document, en- <book name>
tering a + command will leave the data
portion of the screen unchanged. How- --<help book file name>------------------------|
ever, the prompt in the upper left-hand | |
|- ON --<pack name>-|
corner will change to a –.
If the entire document fits on one screen, Explanation
the + command will not change the dis-
The HELP command enables you to access any help book
play. generated by the A Series Help Utility. The explanation of
Entering a - command moves the display + 6.29 HELP COMMAND

one page back. The screen to the right ________________________________________________________________________________
shows what happens if you enter the - HELP Command
command when viewing the screen given
at the bottom of page 9-236. In this case, Syntax
the – command returns us to the start of
the document, so the prompt in the up- -- HELP ------------------------------------------------------------|
| | | |
per left hand corner automatically |-<keyword>--------------------------| |- : -- PRINTER -|
changes to the + symbol. Had we not | | | | - |
|- KEYS -------| |- IN --<book name>-| |
reached the start of the document, that | | |
prompt would remain a -. |- TOPICS -----| |
| | |
|- REFERENCES -| |
| |
If you enter a + or a - by itself, you advance 1 page at a time. If you enter a number after the + or - symbol, you move that
number of lines.
The BACK command moves you to the + 6.28 HELLO COMMAND

help text that precedes the item you are ________________________________________________________________________________
currently viewing. For example, the HELLO Command
screen in figure 1 shows that we are cur-
rently viewing the documentation on the Syntax
HELP command, which is screen 6.29 in
the file. The section of help text prior to -- HELLO ------------------------------------%
---- | |
6.29 is 6.28, and this section documents |-<usercode>--------------------|
the HELLO command. Therefore, if you | |
|- . --------------|
are currently at screen 6.29 and you en- | |
ter the BACK command, you end up at |-------<password>-|
screen 6.28, which is shown at right. | |
|- / -|
Volume 9.06
The FORWARD command moves you to the + 6.30 INSERT COMMAND

section of text which follows the one you ________________________________________________________________________________
are currently viewing. If we start again INSERT Command
with the screen in figure 1, and enter the
FORWARD command, we move to screen Syntax
number 6.30: documentation on the
INSERT command. |<------------------------------------------------|
| |
-- INSERT -----/1*\---------------------------<file title>------|
-- | | | |
| |-<sequence range list>-| |
| | |
| |----------------<sequence range list>-|
| | | |
| |-<file title>-| |
| |
Thus, the BACK and FORWARD commands give you the ability to move sequentially through all of the pages of the help file.
If you cannot remember a keyword or topic that describes what you want, but you remember something close to it, you can
use these commands to get to your target.
The PREV command moves you back to + 6.29 HELP COMMAND
your previous screen. For example, if you ________________________________________________________________________________
begin at screen 6.29, and you enter the HELP Command
BACK command once, you end up at
screen 6.28. If you then enter the PREV Syntax
command, your current screen is dis-
carded and you step back to the screen -- HELP ------------------------------------------------------------|
| | | |
you had previously: in this case, screen |-<keyword>--------------------------| |- : -- PRINTER -|
6.29. | | | | - |
|- KEYS -------| |- IN --<book name>-| |
This command is useful if you make a | | |
|- TOPICS -----| |
mistake because you can easily back up a | | |
step. The system stores the most recent |- REFERENCES -| |
| |
10 screens, so you can back up as far as |- ? ---------------------------------------------------|
10 steps if you need to. | |
|- * ---------------------------------------------------|
Thus, use BACK to sequentially page backward through the help file. Use PREV to return to a screen you were previously
viewing.
September, 1995
The KEYS command returns a list of the + KEYS LIST OF KEYWORDS

keywords in the help file. To locate the ________________________________________________________________________________
documentation for an item by its key- <ALPHANUMERIC CHARACTER> <BASE>
<CHARACTER> <CODE VISIBILITY MNEMONIC>
word, you can use one of two methods: <COLUMN> <COMPILER NAME>
<COMPILER TYPE> <CONTROL CHAR MNEMONIC>
1. Enter the KEYS command to bring up <DIGIT> <DIRECTORY NAME>
the first page of keywords. Page through <DIRECTORY TITLE> <DLM>
<DOMAIN NAME NODE> <DOMAIN NAME>
the listing using + and - until you find the <EBCDIC CHAR OTHER THAN QUOTE> <EBCDIC OTHER THAN APOSTROPHE>
keyword you want. Place the cursor over <END COLUMN> <FAMILY NAME>
<FILE DIRECTORY> <FILE NAME>
the keyword, and press the {specify} key. <FILE TITLE> <HOST NAME>
<HYPHEN> <ID CHAR>
2. Enter on the command line: <IDENTIFIER> <INC>
<INTEGER> <IP ADDRESS NODE>
HELP <keyword> <IP ADDRESS> <LETTER>
<LSN RANGE> <LSN>
Option 2 is easier if you already know <MIX NUMBER LIST> <MIX NUMBER>
<NAME> <NLS>
what the keyword is. <NUMBER> <OPTION LIST>
<PASSWORD> <PERIOD>
<SEQUENCE NUMBER> <SEQUENCE RANGE LIST>
A keyword search brings you to the section of text which defines that keyword. Each keyword only references one section
of help text. As you may have noted, there are no commands available for moving from one “hit” to the next in a keyword
search. This is because each keyword search has a maximum of one reference.
There are a number of rules and conventions that apply to the usage of keywords when using the
HELP <keyword>
command. These are discussed in the section, “Rules for Keyword Searching”, later in this article
The TOPICS command lists the contents + TOPICS LIST OF TOPICS

of the help file in order by section. Each ________________________________________________________________________________
entry gives the screen number and title TOPICS LIST OF TOPICS
1 FRONT MATTER
for that section. You can scroll through 2 TRADEMARK INFORMATION
the list of topics using the + and - com- 3 INTRODUCTION
3.1 AUDIENCE
mands. When you find the topic you 3.2 PREREQUISITES
want, place the cursor over it and press 4 GENERAL INFORMATION
4.1 USER IDENTIFICATION AND LOGGING ON
the {specify} key. CANDE will return 4.1.1 STARTUP FILES AND RESTART FILES
the screen which matches that topic en- 4.1.2 ACCESSCODES AND RECOVERY FILES
4.1.3 ACCESSCODE TASK ATTRIBUTE
try. 4.2 MULTIPLE COMMANDS
4.3 BREAK CONDITION
4.4 RESPONSE TO CANDE COMMANDS
4.5 SAVED TEXT QUEUE MANIPULATION
4.6 INPUT QUEUE MANIPULATION
4.7 ATTRIBUTES OF CANDE FILES
If you press {specify} in the wrong place when on a KEYS or TOPICS screen, you can always return to the place that you
were by immediately entering a PREV command.
The PARNT command moves you to the + 6 CANDE COMMANDS

“parent” of the screen you are currently ________________________________________________________________________________
viewing. The parent screen is the screen CANDE Commands
Volume 9.06
whose number has one less node than

This section contains the CANDE commands for task initiation,
your current screen. If your current work file creation, user library manipulation, text editing,
screen is number 4.1.3, the parent will and so forth. The commands are presented in alphabetical
order along with the railroad syntax structure, explanation,
be screen 4.1. The parent of screen 4.1 and simple examples.
is screen 4.
Commands for which the syntax diagram terminates with a
The example at right shows the parent of percent sign (%) must appear alone on the input record to
CANDE or as the last command of that input record. Commands
screen number 6.29 (or any screen in the for which the syntax terminates with a vertical bar (|) may
6.n series), which is screen number 6. appear in sequence on the input record, each command
separated from the following command by a semicolon (;).
The RLTD command lists all of the topics + 6.29 HELP COMMAND
that are “related” to the current topic. ________________________________________________________________________________
This means all of the screens that have 6.1 ACCESS COMMAND
6.2 ADD COMMAND
the same number of nodes as the current 6.3 ALTER COMMAND
screen and whose parents are the same 6.4 APASSWORD COMMAND
6.5 BACKUPPROCESS COMMAND
number. 6.6 BIND COMMAND
6.7 BYE COMMAND
Section 6 of the CANDE help file dis- 6.8 CHANGE COMMAND
cusses the CANDE commands. Each 6.9 CHARGE COMMAND
6.10 COMPILE COMMAND
command has its own node number at 6.11 CONNECT COMMAND
level 2, but the first node is always num- 6.12 CONTINUE COMMAND
6.13 CONVENTION COMMAND
ber 6. Therefore, if you are currently 6.14 COPY OR ADD COMMAND
viewing the help screen for any CANDE 6.15 DCSTATUS COMMAND
6.16 DELETE COMMAND
command, entering the RLTD command 6.17 DESTNAME COMMAND
will return a list of all of the CANDE 6.18 DISCARD COMMAND
6.19 DO COMMAND
commands. 6.20 ESCAPE COMMAND
The example shown here illustrates this. It shows the screen returned if you enter the RLTD command while on the help
screen for the HELP command (screen 6.29).
The SUB command lists all of the sub- SUB 6 CANDE COMMANDS
topics, if any, which belong to a particular ________________________________________________________________________________
screen. If you are currently at an outer 6.1 ACCESS COMMAND
6.2 ADD COMMAND
node, such as node 6, you can easily get a 6.3 ALTER COMMAND
topics list for that section by entering the 6.4 APASSWORD COMMAND
6.5 BACKUPPROCESS COMMAND
SUB command. That is what was done to 6.6 BIND COMMAND
obtain the screen shown at right. 6.7 BYE COMMAND
6.8 CHANGE COMMAND
Many of the inner nodes, such as screen 6.9 CHARGE COMMAND
6.10 COMPILE COMMAND
6.29, do not have any sub-topics. En- 6.11 CONNECT COMMAND
tering the SUB command while on this 6.12 CONTINUE COMMAND
6.13 CONVENTION COMMAND
screen will return an error. However, 6.14 COPY OR ADD COMMAND
you may have noticed from the TOPICS 6.15 DCSTATUS COMMAND
6.16 DELETE COMMAND
screen shown earlier than screen 4.1 has 6.17 DESTNAME COMMAND
three sub-topics. Entering SUB while on 6.18 DISCARD COMMAND
6.19 DO COMMAND
screen 4.1 will return a listing of just 6.20 ESCAPE COMMAND
those three topics. 6.21 EXCLUDE COMMAND
The REF command lists help files that REFERENCES LIST OF REFERENCES
contain additional information. These ________________________________________________________________________________
help files are referenced by topics in the [MARC HELP TEXT]
current help file. As shown at right, the
CANDE help file currently has refer-
ences to the MARC help file.
You can read other help books using the
CANDE HELP command. While in help
September, 1995
mode, the easiest way to do this is to go to

the REF screen, place the cursor over the
file that you want, and press the {specify}
key. This will close your current help file
and open up the new one that you have
chosen.
One command not listed on the option line is REFRESH. If you enter this command, CANDE will re-send a
fresh copy of your current screen.
Two forms of the command HELP are also supported while in help mode. These are:
HELP <keyword>
and
HELP <keyword> IN <help file>
The first, as described previously under the KEYS command, routes you directly to the help screen for a
particular topic. This command looks for the keyword in your current help file.
The second format changes help files for you. It closes your current help file and opens the new one you’ve
specified (if available). It then looks for the keyword you’ve requested in that help file.
Once you change help files, you remain within that new help file. All of the commands you enter are exe-
cuted against that help file. If you have received less than 10 outputs from the new help file, you can return
to the old one by entering a series of PREV commands. Otherwise, your other options for changing help
files are:
1. Use the REF command to list related help files and select one from there using the {specify} key.
2. Use another HELP <keyword> IN <help file> command.
The last command shown in the option line is QUIT, which exits help mode and returns you to normal
CANDE functions. EXIT and BYE are accepted as synonyms.
Searching for Help on a Specific Topic

You may enter help mode using any of the commands shown in the following syntax diagram:
HELP
< keyword>
KEYS IN < help file>
TOPICS
REFERENCES
The option you choose determines the first screen presented.

To go directly to help information on a particular topic, use the
HELP <keyword>
syntax. For example,
HELP DO
will bring up documentation on the DO command.
The command ‘HELP’ by itself is a shorthand for the command:
HELP HELP
This is important to know, because if the <help file> you are using does not have the token “HELP” as a key-
word, the command will return an error.
Volume 9.06
Rules for Keyword Searching

Composite Keywords
Some keywords consist of a single word. Others consist of multiple words or a combination of words and
special characters. For example, the keyword
FILES
is a single word, but the keyword
<FILE DIRECTORY>
uses four tokens: two words, a left angle bracket, and a right angle bracket.
A keyword that consists of more than a single word is called a composite keyword.
As you may have noticed from the preceding examples, to look up a reference using a single-word keyword,
you simply use the word. For example,
HELP FILES
will bring you documentation on the FILES command.
The rules are different when using composite keywords. In this case, you must surround the keyword with
asterisks. CANDE will then recognize everything between the asterisks as a single keyword. For example:
HELP *<FILE DIRECTORY>*
Note that the complete keyword, including the angle brackets, was specified inside the asterisks.
All of the control commands — those beginning with a question mark — are listed as composite keywords.
The question mark is considered part of the keyword. Therefore, you must use this syntax when searching
for any control command. For example, to find the documentation on the ?DS command, use the com-
mand:
HELP *?DS*
Abbreviating Keywords
A few shorthands have been provided to improve the convenience of the help system. In particular, you
can abbreviate keywords providing your abbreviation is unique. This provides an easy way to jump to refer-
ences where the keywords are quite lengthy. If the abbreviation you use maps to more than one keyword,
you get an error message.
One unfortunate oversight in the current CANDE help book seriously affects the usefulness of keyword
abbreviations. All of the CANDE commands are entered twice in the book: once under their single-word
names, and once as a composite keyword using the format:
<command name> COMMAND
This is very annoying because you cannot use any command abbreviations when searching for references on
CANDE commands. In particular, if you enter something like:
HELP CHAN
you will get the error message:
!!!KEYWORD NOT UNIQUE (MORE THAN ONE FOUND WITH
MINIMUM ABBREVIATION)
You must use the complete command, as in:
HELP CHANGE
to avoid the error and get the information you want.
Thus, the abbreviation feature currently has only a limited use at present. It is useful when you have a long
term that can be easily abbreviated, however. For example, there is only one keyword that begins with HA,
(*HALT/LOAD, GLOSSARY TERM*), so you can use HELP HA to locate it.
September, 1995
You can also abbreviate composite keywords. As just shown, if the abbreviation is a single word, you can
just type the abbreviation. However, if the abbreviation requires two or more words, or any special char-
acters, then you must surround the entire abbreviation with asterisks.
You can, for example, abbreviate the keyword <FILE DIRECTORY> to just <FILE D. The correct command
would be:
HELP *<FILE D*
An asterisk must appear on both sides of the abbreviation. If you omit the right-hand one, you will get an
error message.
Abbreviations may be used in both your initial HELP command and in any use you make of the command
HELP <keyword>
while in help mode.
Printing HELP Information

The commands shown in the diagram on page 9-241 may be suffixed with the option:
: PRINTER
This fires off a task which prints the requested help information. For example:
HELP DO:PRINTER
#RUNNING 5157
#
This command does not put you into help mode. You remain in normal CANDE mode when it completes.
This command is only valid from the normal CANDE environment. There is no facility from within help
mode for printing the help information.
Changing the Help ‘Book’

The files containing help information are called help books. CANDE has a default help book called
*BOOK/CANDE/ENGLISH. (The last node will vary depending upon the language in use on your machine.)
This file contains the information we have shown throughout this article.
As a general rule, help book files are kept under the *BOOK directory on your resource family. You can list
the ones available through the FILES command. For example:
FILES *BOOK/= ON DISK:S
*BOOK/= ON DISK

--------------------------+------------+------------+
*BOOK/RD/ENGLISH DATA 63
*BOOK/IDC/ENGLISH DATA 4594
*BOOK/IDC/SHORTHELP/ENGLISH
DATA 1121
*BOOK/IMG/ENGLISH DATA 1823
*BOOK/IMG/SHORTHELP/ENGLISH
DATA 318
*BOOK/COMS/ENGLISH DATA 3675
*BOOK/MARC/ENGLISH DATA 34009
*BOOK/MARC/SHORTHELP/ENGLISH
DATA 8294
*BOOK/CANDE/ENGLISH DATA 11519
*BOOK/MARCUS/ENGLISH DATA 2709
This report lists some of the *BOOK files you can find on your system. Any of these files, except for those
with ‘SHORTHELP’ in the title, may be read using the HELP command.2
To select a file as your default help book, use the command:
Volume 9.06
HELP = <help file>

For example:
HELP = *BOOK/MARC/ENGLISH
CANDE will respond with:
#SESSION HELP BOOK = *BOOK/MARC/ENGLISH ON DISK
From this point forward, every time you enter help mode, you will use the MARC help book. This change
will remain in force until you either log off or change it again through a HELP command.
If the help book is not on either your primary or alternate pack families, you can append an “ON
<familyname>” clause to the command. For example:
HELP = *BOOK/MARC/ENGLISH ON HELPPACK

If you want to know what your current help book is, use the command:
HELP ?
The response will be along the lines of:
#SESSION HELP BOOK = *BOOK/MARC/ENGLISH ON DISK
#DEFAULT HELP BOOK = *BOOK/CANDE/ENGLISH ON DISK
The first line reports that you’ve changed your session’s default help book to *BOOK/MARC/ENGLISH. The
second line reports the default help book title for CANDE.
To change your session help book back to CANDE’s default, use the command:
HELP *
The response will be:
#SESSION HELP BOOK = *BOOK/CANDE/ENGLISH ON DISK
These commands that deal with the help book do not put you into help mode. They simply change the de-
fault help book you will access when you next enter help mode.
Changing the Default Help Book

If you have CANDE control station privileges, you can set CANDE’s default help book. CANDE is deliv-
ered with *BOOK/CANDE/ENGLISH ON DISK as the default help book. You may change this using the ?BOOK
command. The syntax for this command is:
?BOOK
< help file>
ON < family name >
*
For example:
?BOOK *BOOK/CANDE/ENGLISH ON HELPPACK
The response will be:
#DEFAULT HELP BOOK = *BOOK/CANDE/ENGLISH ON
HELPPACK
The help book title is saved in the tankfile. Any change made via the ?BOOK command is therefore perma-
nent. It will remain in force even if CANDE is taken down and brought back up. Only if the tankfile is
reinitialized will the help book title revert to the default of *BOOK/CANDE/ENGLISH ON DISK.
To change CANDE’s default help book back to the plant-specified default, use the command:
?BOOK *
Then you get the response:
September, 1995

Again, this command is part of CANDE “site management.” It is not intended for general use.3
Conclusion
The help facility provides a valuable improvement to the CANDE product. As a command-oriented prod-
uct, CANDE has long needed on-line documentation. This feature has now been provided in a form that is
very easy to use.
The command for accessing the help information is easy to remember. Moreover, entering and exiting help
mode is a low-overhead operation. As a result, this feature should address a great many needs for CANDE
documentation at a large number of A-Series installations.
1
To date, all CANDE features have been compatible with the lowliest of TTY terminals. This is not true of the Help
facility, which uses the SPECIFY key of the TD830.
2
You can also create your own help files using the Help Utility. Any file compatible with *SYSTEM/HELPSUPPORT can
be processed through CANDE’s HELP command.
3
For some reason, ?BOOK is documented in the CANDE Operations Reference Manual instead of the CANDE Configu-
ration Reference Manual in both the 41.2 and 42.2 documentation CD’s. Its use is restricted to control-capable users
only, so it belongs in the CANDE Configuration Reference Manual.
Volume 9.06
CANDE: Other Improvements / 79
CANDE: Other Improvements
here are a couple of minor enhancements to CANDE that, while important, do not rate an entire article
apiece. The first is an improvement to the START command. The second is an improvement in CANDE’s
ability to handle large workfiles. With these topics, we will conclude our series on the recent improvements
to CANDE.
Parameters in the START Command

When CANDE was first developed, it provided a rather isolated environment from the rest of the system.
Up through the Mark 2.6 release, there was no interaction between CANDE and WFL. WFL jobs were
submitted on punched cards through card readers or through ODT commands. If you used CANDE, you
could run programs “on line” through the RUN command. However, there was no provision for submitting a
WFL job and monitoring it from a CANDE session as there is now.1
In Mark 2.7 the START command and the job monitoring commands were added to CANDE. You used
START in the same manner as you do today. You create a file of type JOB or DATA, enter your WFL com-
mands, and submit it into a job queue by entering the command START. If the file is saved on disk, but not
a workfile, you use the command:
START <file name>
If the file is loaded as a workfile, you can start it with the simple command:
START
In this case, the workfile can be either saved or unsaved.
In Mark 3.0, the START command was enhanced so that users could pass parameters to WFL jobs. How-
ever, only the START <file name> version of the command would accept parameters. Therefore, if you
were writing a WFL job that used parameters, you were required to first save the file. Then you could use:
START <file name> (<parameter list>)
to get it going.
Now, in Mark 4.1, Unisys has finally made it possible for you to start a WFL job that requires parameters
without first saving it. The new variation,
START (<parameter list>)
will start a job from a saved or unsaved workfile. For example:
START ("XYZ")
#UPDATING
#RUNNING 7816
#
#7817 BOJ TESTIT
#7817 DISPLAY:XYZ.
#7817\7817 EOJ (Q) JOB TESTIT
CANDE File Limits

This next feature is from the SSR 42.1 release.
The SSR 42.1 SYMBOL/MCP contains more than 1,048,575 records. As soon as the file crossed that bound-
ary, CANDE would refuse to load it. CANDE gave the error message:
#FILE HAS TOO MANY RECORDS
CANDE was quickly patched so that it would load larger workfiles. The new official limit is
549,755,813,887 records. However, since all CANDE files must use sequence numbers, and the largest
sequence field CANDE uses is 8 characters in length, I suspect the real limit is 99,999,999 records.
September, 1995
1
From a CANDE terminal you could write a program in ALGOL, COBOL, or FORTRAN that would start a WFL job
through the ZIP statement. However, such a job could not be monitored from the CANDE station.
Volume 9.06
CANDE: Site Management / 81
CANDE: Site Management
nisys’ A-Series CANDE product is one of the simplest products to install and support that you will find
around. This product was written back in the days when engineers were allowed to develop products with-
out interference from budget-conscious managers, marketing types, and over exuberant software theorists
or purists.1 It was also developed before the invention of A-Series Libraries, and it uses no special support
libraries of its own. The product is dependent only upon system modules — such as the MCP, GENER-
ALSUPPORT, and DATACOMSUPPORT — which must always be present. Therefore, installation is a
breeze. Once installed, nearly all of CANDE’s options can be configured on line. Thus, it is very easy to
manage and tune. In many ways, CANDE provides a model that many other software product designers
(both on A-Series and on other machines) could certainly learn from!
This article describes how to manage CANDE. It is intended for the Site Administrator. It describes the
various CANDE environmental options and how to configure them for the best performance.
To do the activities described in this article, you must have “control” status over CANDE. This can be
achieved using any one of the following methods, which are listed from most convenient (also least secure)
to least convenient (most secure).
Method 1.
• Set system SECOPT CLASS = UNSPECIFIED. (This is the default if you are not running InfoGuard.)
• Set CANDE option NOCOMSCTRL to FALSE.
• Log on to COMS with a COMSCONTROL-capable usercode.
With NOCOMSCTRL set to FALSE, CANDE will grant you control station privileges if you are working from a
COMS control station. You can achieve control station status in COMS by logging on:
a) with a COMSCONTROL-capable usercode;
b) to a station that is defined as a Control Station in COMS Utility;
c) to any station that is defined as a SPO in the Network Definition Language II (NDLII) or through the
Interactive Datacomm Configurator (IDC).
If you have done any one or more of the three, the usercode you log onto CANDE with is immaterial: it
may be any usercode (privileged or non-privileged, control-capable or not control-capable). Of course, you
must access CANDE through a COMS window.
The remaining methods are required for sites that run with the NOCOMSCTRL CANDE option set to TRUE. If
you are not running InfoGuard, or have your system security class set to UNSPECIFIED, you must set this
option through the CANDE command:
?OP + NOCOMSCTRL
and then you must take CANDE down and up for it to take effect. If you are running with InfoGuard, and
use a SECOPT CLASS of S0, S1, or S2, you must also use one of the following methods. These security
classes force NOCOMSCTRL to true, and you cannot turn it off.
These methods will also work if NOCOMSCTRL is FALSE. However, method #1, above, is more convenient
when NOCOMSCTRL is FALSE.
Method 2.
Log on to CANDE with a CANDECONTROL-capable usercode.
Method 3.
Have someone that is currently on a CANDE control station manually designate your CANDE station
as a control station through the command:
September, 1995
?CONTROL <station name>

If you are on a CANDE window through COMS, the <station name> must include the window and
dialog name. For example:
?CONTROL PSJC10/CANDE/7
is required if the user is on dialog #7 of the CANDE window, originating from station PSJC10.
Method 4.
Designate the station as a SPO station in the NDLII or through the Interactive Datacomm Configurator
(IDC). This is useful only if the station connects directly to CANDE without going through a COMS
window, which is not possible for a BNAv2 supported terminal.
Once you have CANDE control status, you have the privilege and responsibility of tuning CANDE for your
site, using any of the commands discussed in this article.
CANDE Runtime Options

CANDE supports a large number of runtime options. These are your primary tools for tuning CANDE to
the specific requirements of your installation.
CANDE also provides a single command that lists nearly all of the CANDE options and their current val-
ues.2 This command is:
?INFO
It gives you a report in the following format:
16:26:50 Friday, August 18, 1995 (PST)
#OPTIONS SET: ALLMSG LOWMEMORY NOJOBSUMIO
#OPTIONS RESET: DUMPOK KEEPSTA DIALLOGIN ALLLOGIN CATDEFAULT
CATALOGOK SECDIALIN SECPSEUDO SECALL USECOMSPRIV
NOCOMSCTRL NOGETWARN SYSDUMPOK LASTLOGON PASTBATCH
LEADINGNUM SHOWALLFILES
#THERE ARE NO LOGSTATIONS
# MAXSTATIONS=200; MAXTASKS=200; COMPILESPERCENT=100%;
MAXGRINDS=10; GRINDLIMIT=2; FACTORS - WORK=80, QUIT=25;
SAVED TEXT DEPTH=10; LAISSEZFILE=0; TANKING=UNSPECIFIED
#SERVANTLIMIT = 4
# NO NEWSFILE
#SCHEDULE LIMIT=10 NO USERLIMIT
# STARTUP DIRECTORY: CANDE/STARTUP
# RESTART DIRECTORY: CANDE/STARTUP/RESTART
#RECOVERSESSION = ALL
Each section of the report begins with a pound sign (#).
The first section provides CANDE identification information.
The next two sections show “on/off” options you can set through the ?OP command. Each of these options
is turned on (or “set”) through the command:
?OP + <option name>
Each can be turned off (or “reset”) through the command:
?OP – <option name>
Next is the report on CANDE log stations. These are monitoring stations which report various user activi-
ties as they take place on CANDE.
After that comes a report of various multi-valued CANDE options. These include some very critical op-
tions that can determine how well CANDE performs on your machine.
The report wraps up with newsfile, schedule, and startup information.
Volume 9.06
All of these options are documented in the CANDE Configuration Reference Manual3. In the discussions
which follow, we will provide additional information about these options. We will also describe why the
options exist and what results you can expect from various settings.
Tuning CANDE Performance

The options described in this section directly affect the performance of CANDE. They can also have an
effect upon the overall performance of your system as well.
Grinding out the Work(ers)

The CANDE architecture consists of one main stack, called SYSTEM/CANDE, and a number of dependent
stacks. The main stack handles all of the data communications activity. The dependent stacks process the
editing and “shell” commands that CANDE users are so familiar with.
Inside the symbolic for CANDE you will find one procedure named GRIND. Within this procedure is one
called ENVIRON, and within ENVIRON is one called WORKER. When CANDE comes up, it initiates one or
more copies of procedure GRIND as separate tasks. These are called the grind stacks, and they handle all of
the CANDE user commands. The grind stacks appear in the mix with the names CANDE/STACK01,
CANDE/STACK02, and so forth.
The CANDE options MAXGRINDS and GRINDLIMIT determine the number of grind stacks CANDE will exe-
cute. MAXGRINDS specifies the absolute maximum number of grind stacks that may be executing at any sin-
gle instant. To change this value, use the command:
?MAXGRINDS = <number>
To query its value, use either ?INFO or the command:
?MAXGRINDS
You can enter a change to MAXGRINDS at any time. However, your change will not take effect immediately.
You must take CANDE down and up before the new value will take effect.
The maximum value you can set MAXGRINDS to is 13.
GRINDLIMIT is a bit more immediate than MAXGRINDS, but it is more limited in power. GRINDLIMIT also
specifies the maximum number of grind stacks that may execute, but its value may be changed at any time,
and the change takes effect immediately. However, the value given to GRINDLIMIT cannot exceed that
specified for MAXGRINDS.
To change the GRINDLIMIT, use the syntax:
?GRINDLIMIT = <number>
To query the current value, use:
?GRINDLIMIT
Thus, MAXGRINDS tells CANDE how many structures it needs to have available to handle the largest num-
ber of grind stacks that will be running. GRINDLIMIT specifies the maximum number of grind stacks you
want running at the moment. You can lower GRINDLIMIT to any value between 1 and MAXGRINDS.
CANDE will never run more than GRINDLIMIT grind stacks at any given instant.
When a grind stack is executed, the only thing it does is call procedure ENVIRON. All of the rest of the work
is done inside that procedure. ENVIRON calls itself multiple times to set up separate “working environ-
ments” for the CANDE users. The number of times ENVIRON calls itself is determined by a DEFINE in
CANDE called MAXWORKS. As distributed, MAXWORKS is set to 5, meaning that there are 6 CANDE “Work-
ers” available in each grind stack that is executing. (The MAXWORKS variable is zero-based.)
According to the CANDE Configuration Reference Manual, it is more efficient to change the number of
grind stacks than to change the number of Workers per grind stack. Certainly it is easier to change the
number of grind stacks. You have two commands, described above, which allow you to do that at runtime.
In the worst case, CANDE must be taken down and restarted for the command to take effect.
September, 1995
To change the number of Workers per grind stack, you must patch the source file for CANDE. You would
have to change MAXWORKS to another value and recompile CANDE. This is rarely done and is certainly not
a Unisys-approved procedure. I’ve been able to get plenty of good service out of CANDE by changing
MAXGRINDS and GRINDLIMIT without messing around with MAXWORKS.
CANDE divides its work into four general categories:

• Session management, such as the processing of log on or log off requests.
• Directory management, such as that work done through the SECURITY or REMOVE commands.
• Task management, such as the running of user programs, the running of internal programs (such as
BACKUPPROCESSOR or LFILES), and the running of Work Flow Language (WFL) processes (such as the
COPY command or any command that begins with the word WFL).
• File manipulation, such as that work done by the LIST, FILES, FIND, and various editing commands.
CANDE assigns different work to its Workers and its grind stacks based upon the category a particular
command falls into. Only Worker #0 can handle commands falling into the first three categories. Workers
#1 through #5 are reserved for handling exclusively the file manipulation work. The division of the work
between the various grind stacks is determined by the number of grind stacks run.
CANDE is distributed with default values of 1 for both MAXGRINDS and GRINDLIMIT. This puts all of the
CANDE functions into a single grind stack. Worker #0 of that stack will process session log on, directory
activities, and the running of external processes. Workers #1 through #5 do the file manipulation activities.
With this setup, your CANDE service will be very poor if you have more than just a handful of CANDE
users.
When GRINDLIMIT is set to 2, CANDE fires up exactly 2 grind stacks, and it splits the chores between
them. Session log on, directory activities, and the running of external processes are all processed out of
worker #0 of one grind stack. File manipulation is handled by workers #1 through #5 of the other grind
stack. This is a good setting for a machine with very limited resources (especially memory).
If GRINDLIMIT is set to 3, CANDE fires up 3 grind stacks. Session log on and directory activities are per-
formed through Worker #0 of one grind stack. The running of external processes is done through Worker
#0 of a second. File manipulation is handled by Workers #1 through #5 of the third.
If GRINDLIMIT is higher than 3, CANDE starts off with an initial setup of 3 grind stacks, as described above.
As demand increases, more grind stacks are run. These additional grind stacks provide additional workers
to do file manipulation activities. In all of these additional grind stacks only Workers #1 through #5 are
used.
On our Micro A, which has only 12 megabytes of memory, we use a GRINDLIMIT of 2. However, with 24 or
more megabytes, I strongly recommend that both MAXGRINDS and GRINDLIMIT be set to at least 3. Then
CANDE will separate its functions so that the user functions and the overhead functions are not done by
the same grind stacks. If you have the available resources, set MAXGRINDS to a large number (such as 10).
This will give you greater freedom to tune your environment through the GRINDLIMIT command, which can
be set to any value between 1 and MAXGRINDS without having to interrupt CANDE.4
You will have to experiment to determine the best number for your site. If CANDE does not have suffi-
cient Workers available when a user requests an “internal function”, he will receive the message
#WAITING FOR WORKER
If this message is appearing much too frequently, increase both MAXGRINDS and GRINDLIMIT, take CANDE
down, and bring it back up.
Several of the CANDE commands generate more than one screen page of output. When this is the case,
each page of output is followed by a pause during which the user may read the output. To move on to the
next page of output, the user must enter a “null input” — an input of no characters or an input that is all
blank.
During this pause, CANDE must retain all of its information about what the user is doing so it knows how
to begin processing the next page of output. It keeps this information in a Worker, thereby tying up that
Worker. Only when the user completes or aborts the command is the Worker liberated for other use.
Volume 9.06
Thus, if your users are constantly leaving their screens in the middle of a LIST or FILES report, you will
experience frequent occurrences of WAITING FOR WORKER. In this case you have more of a training prob-
lem than a resource problem. You must train your CANDE users to either finish or “break” their list re-
ports when leaving their terminals. Tell them to use the command:
?BRK
to abort a list report without incurring an error. The alternative is to use:
?DS
This command also aborts a list report; however, it also invokes CANDE’s error recovery logic. Queued
commands are marked “pending”, which is not the case when using ?BRK.
It is important to note that, while the LIST, FILES, FIND:TEXT, and FIND:TEXT,PAGEFORMAT commands all
hold a Worker in use between output pages, the PAGE, NEXT, FIND:PAGEMODE, and other page mode editing
commands do not. Like all internal commands, the page mode commands use a Worker to generate a sin-
gle page of output. They then store the vital information in some station tables and relinquish the Worker
after writing one screen of output to the user. Each new input to one of these commands is handled by the
first Worker available, which may not be the same Worker that sent the previous page of output.
Thus, while you do not want to leave your terminal in the middle of a list report, you can certainly leave it
showing the output of a page mode command without adversely affecting CANDE Worker usage.
GRIND’s Servants
Grind stacks are designed to do short bursts of work. The idea is to quickly process some activity and ship a
report out to the user. By doing this fast enough, CANDE gives each user the illusion that he is the sole
user of the machine.
Some commands simply cannot be processed that quickly. Activities that involve wildcard searching or in-
volve sorting in any fashion are going to take time. To avoid the situation where user A’s FILES command
might noticeably interfere with user B’s LIST command, CANDE employs a different stack: the servant
stack.
Servant stacks handle lengthy activities. Servant stacks receive their commands from the grind stacks. As
we said before, every internal command is processed by a grind stack Worker. If, during evaluation of the
command, the Worker determines that a lengthy activity is requested, it will hand the request off to a ser-
vant stack. That Worker will then attend to other business.
The servant stack will complete the work and queue the response. It will then notify CANDE, which will
have a grind stack Worker pick up the response and send it out to the user. During the reporting period,
the Worker will be in use, as described above for the LIST command. The important difference is that the
Worker is not tied up during the processing of the command — only during the reporting phase.
Servant stacks operate in a fashion similar to grind stacks. However, each servant stack can only process
one task at a time. It must process each task to completion before moving on to the next. Thus, if two peo-
ple enter a command that uses a wildcard expression, and only one servant stack is available, one of the us-
ers will wait while the other one is processed. There is no time-slicing between the two users.
Once the servant stack completes the request, it sends the report to a grind stack Worker and immediately
moves on to the next request. If there are no workers available, the output is queued so the servant stack
can move on to service the next request.
The number of servant stacks is controlled by the command SERVANTLIMIT. The syntax for setting the limit
is:
?SERVANTLIMIT = <number>
The number may be set to any value between 1 and 49.
To inquire about the current limit, the command is:
?SERVANTLIMIT
For some reason, CANDE is shipped with a default SERVANTLIMIT of 1. Unless you have an entire A-
Series machine dedicated to your personal use, this value is wholly inadequate. A more reasonable limit is
September, 1995
somewhere between 5 and 10, depending on the amount of memory you have available. After your users
start working heavily with the wildcard commands (particularly the FILES command), you will get a better
feeling for a reasonable local limit. Each time a servant stack is needed, and one is not available, the user
will get the message:
#WAITING FOR A SERVANT
Managing the Grind and Servant Stacks

If you have GRINDLIMIT set to 3 or higher, CANDE starts off with three grind stacks and one servant stack.
As user demand increases, CANDE will fire up more grind stacks and servant stacks. This will continue
until the limits you’ve specified by GRINDLIMIT and SERVANTLIMIT have been reached.
The decision to fire up an additional grind stack is determined by the option called FACTOR. To set FAC-
TOR¸use the command:
?FACTOR WORK = <number>

This <number> represents a percentage value. When the number of workers doing file manipulation func-
tions equals or exceeds the total number of workers multiplied by FACTOR WORK¸ CANDE starts a new
grind stack. The default value for FACTOR WORK is 80%.
Suppose you have set GRINDLIMIT to 5 and FACTOR WORK set to its default value. CANDE has just begun
execution, and it has 3 grind stacks running. This gives you 5 workers for file manipulation. Since
5 % .8 = 4
CANDE will start up grind stack #4 when either 4 or 5 workers all have work to do. After stack #4 is run-
ning, you would have to get
10 % .8 = 8
workers all busy before grind stack #5 would be started. Once grind stack #5 was up, there would be no
further changes in grind stacks unless you changed the value of GRINDLIMIT.
Now if you retain the same GRINDLIMIT but change the FACTOR, the results will change. If you set FACTOR
WORK to 85%, you would have to have at least
5 % .85 = 4.25
workers busy before a new grind stack would start. This effectively means that all 5 workers must be busy
before another grind stack will start.
Servant stacks do not have internal workers. Each servant stack can only process a single function. There-
fore, if all servant stacks are busy, and another one is needed, CANDE starts a new one right away. If the
SERVANTLIMIT has been reached, no additional servant stacks are started. Instead, the user must wait until
an existing one becomes available. Thus, the number of servant stacks is controlled strictly by the
SERVANTLIMIT.
After a grind stack or a servant stack is started, it remains in the mix indefinitely unless you’ve set the
LOWMEMORY option. If you turn on LOWMEMORY, CANDE will use FACTOR QUIT to determine when to shut
down extra grind and servant stacks.
To enable LOWMEMORY, use the command:
?OP + LOWMEMORY
To set FACTOR QUIT, use:
?FACTOR QUIT = <number>
The default value for FACTOR QUIT is 25%.
Once you’ve done this, CANDE dynamically shuts down grind and servant stacks as usage drops off. With a
grind stack, the formula is:
<threshold> =
(<number of grind stacks> – 3) % <FACTOR QUIT>
Volume 9.06
When the concurrent activity drops below <threshold>, a grind stack is shut down. CANDE will not drop
the number of grind stacks below 3 (providing GRINDLIMIT 8 3).
So, if you have 5 grind stacks running, and FACTOR QUIT is 25%, your <threshold> would be:
(5 – 3) % .25 = .5
Since there are 5 workers to a grind stack and
5 % .5 = 2.5
the workload would have to drop to 2 workers or less before CANDE would drop the number of grind
stacks down to 4. Once down to 4, the workload would have to drop to less than
(4 – 3) % .25 = .25
5 % .25 = 1.25
workers before CANDE would drop the number of grind stacks down to 3.
Servant stacks operate in a similar fashion, except the calculation is simpler. In this case, the <threshold> is
calculated thusly:
<threshold> =
(<number of servant stacks> – 1) % <FACTOR QUIT>
Since each servant stack handles only a single operation, the calculation is simple. If the <threshold> drops
below the number of active servant stacks, a servant stack is terminated. For example, if you have 7 servant
stacks running, and FACTOR QUIT is 25%, the <threshold> would be:
7 % .25 = 1.75
This means that servant jobs would have to drop to 1 before any servant stacks would be shut down. Once
it did drop to 1, CANDE would shut down 3 servants since you have to get down to 4 stacks before
<number of servant stacks> % .25 7 1.
You can always manually lower the number of active grind or servant stacks by changing GRINDLIMIT or
SERVANTLIMIT. For most sites, setting the number manually is better than having CANDE change things
automatically. As most people know, one of the most expensive operations on the A-Series is the starting or
ending of a task. If CANDE is constantly starting and stopping servants and grind stacks, you will be burn-
ing up your processor doing a lot of overhead. Unless you have extremely little system memory and very
few CANDE users on the system, you will get much better performance out of CANDE by letting your
grind stacks and servant stacks remain at your specified limits. If there are too many stacks, shut down a
few by changing GRINDLIMIT or SERVANTLIMIT. If there are too few, and users are getting too many
WAITING FOR... messages, increase the limits.
To operate these limits in a manual mode, reset the LOWMEMORY option. The command is:
?OP – LOWMEMORY
This is the default setting as shipped from the plant. It is also the recommended setting unless you really
have a serious system memory shortage.
You can get a report of the number of workers and servants in use at any time through the ?COUNTS com-
mand. The syntax is very simple:
?COUNTS
The report is:
# 4 TASKS, 0 COMPILES, 2 WORKERS, 1 SERVANTS WORKING; 40 STATIONS ACTIVE, 75 ATTACHED
This command is available to all users of CANDE. It provides an easy way to determine what CANDE is
doing at a specific moment. If response is slow, or you are waiting for a worker or a servant, this command
will give you an idea of how many other users you are contending with for CANDE resources.
September, 1995
User Management
CANDE must provide resources for each user. Since CANDE runs a dialog with each user, it must main-
tain information regarding what each user is doing. This is done through various internal data structures.
Because CANDE is so old, it uses older technology in its memory management activities. In particular,
many of the functions ALGOL programmers take for granted today — such as the resizing of multi-
dimensioned arrays and EVENT ARRAYs, not to mention the STRUCTURE BLOCK facility — were not available
when CANDE was originally written. To this day, ALGOL RESIZE still does not support TASK ARRAYs. As
a result, some CANDE specifications must be set before the program is started and, when changed, require
that CANDE be restarted before they take effect.
The number of resources available for users is controlled through the MAXSTATIONS option. The syntax for
setting it is:
?MAXSTATIONS = <number>
The <number> denotes the maximum number of users CANDE will support at one time. If more than
MAXSTATIONS users attempt to log on, the extra users will be refused.
To query the current value of MAXSTATIONS, use either the ?INFO command or:
?MAXSTATIONS
If your users are accessing CANDE through COMS, it is very important to remember that each CANDE
window denotes a separate count against MAXSTATIONS. Thus, if you open 8 CANDE windows, you are
using 8 “stations” in CANDE. You don’t have to run the numbers very far to see that it is very easy to use
up a lot of CANDE stations very quickly.
Other CANDE options, particularly MAXTASKS, are dependent upon MAXSTATIONS.
CANDE is distributed with MAXSTATIONS set to the original 1973 limit of 25. (This also forces MAXTASKS,
described next, to 25 as well.) MAXSTATIONS is limited to 255 — a value that is much too small in the cur-
rent world of COMS windows and 96 mega-word operating environments. Nonetheless, you are currently
limited to 255 “stations”, and that is what you should set MAXSTATIONS to.5
Note that any change to MAXSTATIONS does not take effect immediately. You must bounce CANDE before
the new limit will take effect.
As a CANDE control user, you can get a summary report of the CANDE users who are currently on line.
To do this, use the command:
?WHERE
An example report would be:
C 6368 <2 Q ON PSJC10/CANDE/1(17)
6374 <1 EXAMPLE ON PSJC11/CANDE/2(18)
.... LOGON ON PSJC12/CANDE/1(23)
6379 6382 SAMSON ON PSJC13/CANDE/1(24)
6375 FILE DELILAH ON PSJC21/CANDE/1(31)
Each line represents a different CANDE user. To interpret the report, consider the illustration below:
Control station indicator.
Log station indicator.
Session Number.
Activity Indicator.
C L 6368 FILE Q ON PSJC10/CANDE/1(17)
Usercode.
Station name.
Logical Station Number (LSN).
The <control station indicator> reports whether or not the user is on a CANDE control station. If the field
is blank, the station is not a control station. If the field contains a ‘C’, it is a control station.
Volume 9.06
The <log station indicator> reports whether a user is on a CANDE log station. If the field is blank, the
station is not a log station. If the field contains an ‘L’, it is a log station.
The <session number> is the CANDE session number of the user’s session.
The <activity indicator> reports any activity that is currently in progress at the station. This field will con-
tain one of the following:
LOGON —
The user is in the process of logging onto the station.
I/O —
The user’s station has been assigned to a remote file that was opened by a “foreign task.” (Foreign tasks
are described on page 9-254 in this article.)
the first four letters of a CANDE command —
The CANDE command the user is currently doing.
a mix number —
The mix number of a task the user is running.
+—
The user is editing a workfile, and some of his edits have not yet been stored in the tankfile.
< number —
It has been less than <number> minutes since the station was busy.
> number —
It has been more than <number> minutes since the station was busy. This timer is limited to 15 min-
utes, so the highest value that will appear here is > 14.
The <usercode> field reports the usercode the user is currently logged on with.
The <station name> field reports the station name as recognized by CANDE. If the user is logged on
through a COMS window, the window name and dialog number will be included in the <station name> (as
shown here).
The <logical station number> is the number CANDE uses as the SOURCESTATION for all jobs started by this
user. This number is passed to all WFL jobs that are START-ed by this user. The messages generated by a
WFL job are automatically displayed at the job’s SOURCESTATION, providing the usercode of the job
matches the usercode on the station.
Thus, you have the ability to see who is on line and what they are doing at any time.
Task Management
User Task Limits
The original tasking facilities of CANDE were included in order to provide one function: they allow users
to compile and execute their own programs. Through CANDE it is possible to edit, compile, and execute a
program without experiencing the tedium of entering and exiting a separate file editor. For many users this
is still one of the fundamental benefits afforded by CANDE.
Over time, additional CANDE functions have been added as separate tasks. When implementing a new
function, the CANDE author has three choices: the function can either run out of a grind stack, out of a
servant stack, or as a separate task. A function implemented as a separate task uses the same mechanism as
user-written programs. This means:
• CANDE runs the program as a separate, but dependent, task.
• If communication with the user is needed, a remote file is opened to the user.
• If two or more users invoke the same function, or run the same program, a separate copy is run for
each one.
September, 1995
The only real difference between CANDE functions that run as tasks and user programs which run as tasks
is the command used to start the task. Each CANDE function has a verb of its own. User programs must
be started through the RUN or UTILITY commands. A user WFL job is started through the START or WFL
commands.
CANDE commands which run a task are:
ADD ALTER BACKUPPROCESS
BIND COMPILE COPY DCSTATUS
EXECUTE LFILES LOG RUN
START UTILITY WFL WRITE
Each of these commands requires the same amount of overhead in CANDE as that used to run a user-
written program.
The management of CANDE tasks is controlled through a paltry two commands: MAXTASKS and
COMPILESPERCENT. MAXTASKS limits the total number of tasks CANDE will run at the same time. It is set
via the ?MAXTASKS control command, which has the syntax:
?MAXTASKS = <number>
The <number> may be any value between 0 and 255, but it cannot exceed the MAXSTATIONS value. The
good news is that changes to MAXTASKS take effect immediately; there is no need to bounce CANDE for
this change.
To query MAXTASKS, use either the ?INFO command or the command:
?MAXTASKS
If a user attempts to run a process, and the maximum allowed number of tasks are currently in use, he re-
ceives the message:
#WAITING FOR AVAILABLE TASK
Upon receiving this message, the user must either wait (without any idea how long that wait may be) or ?DS
his task in order to regain control of his terminal.
The COMPILESPERCENT option sets a limit on the maximum number of compiles which may be done
through CANDE at the same time. This limit is a percentage of the total number of tasks allowed via
MAXTASKS. The COMPILESPERCENT value is also specified by a control command; viz.:
?COMPILESPERCENT = <number>
The <number> is a percentage value. For example,
?COMPILESPERCENT = 10
means that 10% of the running tasks may be COMPILEs. So if MAXTASKS is 200 and COMPILESPERCENT is 10,
the maximum number of concurrent compiles is
200 % 0.1 = 20.
To query the current value, use the ?INFO command or:
?COMPILESPERCENT
If COMPILESPERCENT is 100, the maximum number of concurrent compiles is the same as the maximum
number of concurrent tasks: i.e., the MAXTASKS value.6
Because of the large number of verbs which are handled as tasks, the single control feature provided by
MAXTASKS is wholly inadequate. We strongly advise that no site use the MAXTASKS control as a tool for man-
aging system resources. Here is why:
• MAXTASKS puts a strict limit on the total number of tasks CANDE will run at the same time. When that
limit is reached, all new requests for tasks are put into a “task queue.” This queue is maintained strictly
on a first-come, first-served basis. There is no consideration given for task priority or task type (except
in the case of on-line compiles).
• A user cannot determine how long it will be before his task is executed. All he gets is the annoying
message:
#WAITING FOR AVAILABLE TASK
Volume 9.06
His terminal is marked busy, and he cannot do any further work until his task is run.
• The START command is blocked by MAXTASKS. Users — especially highly paid, expensive programmers
— should be able to submit WFL jobs through this command very quickly so they can liberate their
terminals for additional CANDE work. Unfortunately, CANDE treats START as a task, on the same
level with RUN and LOG. If you are running at MAXTASKS capacity, all START commands will trudge
through the task queue, competing with long running programs for a chance to execute.
• Until recently, it was impossible to get file information (aside from the file name and its FILEKIND)
without running a task. If you are still using the LFILES command, you will experience delays when the
task queue is full since LFILES runs the program SYSTEM/FILEDATA. Fortunately, the new extensions
to the FILES command eliminate this problem (providing you have a decently high SERVANTLIMIT).
• If you use either IDE or the Editor, you are using up a MAXTASKS slot for each editing session of each
user. (This is one of the principal reasons why these products are not particularly popular with the A-
Series community.)
We strongly recommend that sites avoid using MAXTASKS altogether.7,8 A more advantageous plan is to set
MAXTASKS to a very large number (such as 200), and declare (through management fiat) that all resource-
intensive programs be run through the system job queues. Encourage people to use the START command
rather than the RUN command for all long-running programs — especially any programs that do not require
an interactive dialog with the user. Above all, never run programs in CANDE schedule sessions when there
is a resource problem. Always run such tasks out of WFL jobs in job queues.9
Using Schedule Sessions

CANDE users may compose a script of CANDE commands and submit it for execution in either of two
ways: immediately via the DO command, and separately via the SCHEDULE command. When the SCHEDULE
command is used, the script is run as a completely separate CANDE session. An artificial “station” is cre-
ated that serves as the user of the script. The results of the script are written to a disk file that the user can
later view through the LIST command. While the script runs, the user’s own terminal is available for other
work since it is a completely separate CANDE session.
As a site manager, you have control over the entire schedule facility. This includes such matters as the
maximum number of concurrent schedule sessions and the maximum number each user may run. Control
of the facility is provided through the ?SCHEDULE command.
To determine the availability of the schedule feature, use the command:
?SCHEDULE <limit>
The limit must be a positive number. If you set <limit> to zero, you turn off the schedule facility. CANDE
is distributed with the <limit> set to zero, so you must use this command at least once in order to start up
the schedule facility. Once you’ve set a limit, it is stored in CANDE’s tankfile and applied to all future runs
of CANDE.
The <limit> determines the number of schedule sessions CANDE will process concurrently. You can think
of it as a mix limit on a job queue. For example, if you use:
?SCHEDULE 5
CANDE will limit your users to a total of 5 schedule sessions altogether.
You can also limit each individual user to a maximum number of concurrent schedule sessions. To do this,
use the command:
?SCHEDULE USERLIMIT <user limit>
In this case, <user limit> must be greater than zero. For example,
?SCHEDULE USERLIMIT 2
Using these combined specifications, CANDE limits each user to a maximum of 2 concurrently running
schedule sessions and applies an overall limit of 5 concurrent sessions to the entire facility.
September, 1995
A user can submit as many schedule sessions as he wants. They will remain queued until a slot in the
schedule becomes open. Queued schedule sessions, unlike queued tasks, do not keep a user’s terminal
busy. He can go on to other work while waiting for his script to run.
You can raise or lower the limits at any time. If you lower the limits below what is currently running,
CANDE will retain the older, higher limit until some of the schedule sessions finish. As they finish, those
schedule slots will be discarded and the number of concurrent sessions will drop through attrition until your
new, lower limit is reached.
There are many additional functions of the ?SCHEDULE command. Complete documentation may be found
in the CANDE Configuration Reference Manual. You should review this information if you intend to make
extensive use of the schedule facility.
Be warned, though! Many installations make the mistake of thinking that the CANDE schedule facility is
the same thing as the system job facility. They allow users to create schedule scripts which run like WFL
jobs. In particular, we know of one site where many of the users continuously ran a data modeling program
on their A-Series machine throughout the workday. In order to avoid tying up their terminals, these users
wanted to run the program in a batch fashion. Unfortunately, the data center management there told these
users to set up schedule scripts to run these programs.
All tasks run out of CANDE schedule sessions are handled in the same manner as those run directly from a
terminal. In other words, each one uses a “task slot” and counts towards the MAXTASKS limit. The use of
the schedule scripts therefore meant that many of these modeling programs were running simultaneously,
but (because this same management insisted on using the MAXTASKS limit as well) regular on-line users were
unable to process any LFILES or START commands without waiting upwards of 30 minutes for “available
tasks!”
The moral of all this is quite simple: the schedule facility is intended to allow users to run scripts of
CANDE commands (file editing, benchmark testing, etc.). It is not intended as an alternate batch proces-
sor. Batch programs should still be run through the system job queues via WFL.
Other Task Related Options

CANDE supports two different styles of tasks: “native” tasks and “foreign” tasks. Native tasks are those
executed directly from a terminal (e.g., via RUN or a similar command) which open a remote file to the origi-
nating terminal. Foreign tasks are those which originate from a WFL job or from a different terminal on
the network; these may or may not open a remote file.
A user may monitor the foreign tasks that are running under his usercode through a variety of CANDE
control commands: ?M, ?JA, ?LIBS, ?MSG, and ?C, just to name a few. The particular tasks the CANDE
user can view through these commands is controlled by the CANDE option ALLMSG.
If ALLMSG is RESET, a CANDE user cannot view his currently running WFL jobs from any terminal except
the one at which he entered the START command. The STARTing terminal is identified through its logical
station number (LSN). So if you start a WFL job from a terminal that has a logical station number of 12,
then you can only view that job if you enter your ?M, ?LIBS, ?MSG, and so forth commands from the termi-
nal with logical station number 12.
This restriction is very dated because in these days of multiple CANDE windows under COMS, each
CANDE dialog gets its own logical station number. So if you open two dialogs, CANDE/3 and CANDE/4, both
under the same usercode, and you START a WFL job from CANDE/3, you cannot view that job from dialog
CANDE/4.10
To get around this problem, turn on the ALLMSG option. The command is:
?OP + ALLMSG
Once ALLMSG is set, visibility to WFL jobs is controlled strictly by usercode. Now the user can view any jobs
that are running under his usercode from any terminal or CANDE window.
Once again this is a change you must make to CANDE after you first install it since CANDE is distributed
with ALLMSG reset. Once the change is made, it is stored permanently in the CANDE tankfile. To view the
current setting, use the ?INFO command.
Volume 9.06
In addition to allowing users to view running jobs, CANDE also allows programs to open remote files to any
terminal or pseudo-station that is attached to CANDE. This feature allows you to write multi-user transac-
tion processing systems using standard remote files. It serves as an alternative to the COMS and GEMCOS
on-line servers.
Back in the 2.6 system release, CANDE allowed any program to open any terminal on its network without
restriction. Some individuals would write programs that simulated a CANDE log-on sequence and direct
these programs to other users’ terminals. The other users would think CANDE had gone down and re-
started. They would obligingly “log on” by entering their usercodes and passwords to these programs. The
programs would quietly record the usercodes in a file for the benefit of the author and then release the vic-
tim’s terminal back so that he could resume his session.11
In order to counter this problem, a facility was added to CANDE to notify users any time a foreign task
attempted to open their terminals. This facility is controlled through the CANDE option LAISSEZFILE,
which has seven possible values. These seven values control three aspects of assigning a user’s terminal to a
foreign task. The three aspects are:
1. Should the user be informed that his terminal is being acquired by a foreign task?
2. Should CANDE limit the number of jobs which can simultaneously acquire the user’s terminal?
3. Should the user be prompted with a question and allowed to decide whether or not his terminal is to be
acquired?
The answer to question #1 determines whether or not a message is posted to the user when a foreign task
acquires his terminal. If you specify that a message is to be given, CANDE announces the acquisition with
a message that has the following format:
#FILE <file name> OPEN: USER = "<usercode>",
PROG = <program name>
This tells the user in no uncertain terms that an external program — either a program in a WFL job or one
from another terminal — is attempting to acquire his terminal for an interactive dialog.
If you specify that no message is to be given, the user will not be notified any time a foreign task tries to
acquire his terminal.
The answer to question #2 determines the maximum number of jobs that may simultaneously assign a user’s
terminal to a remote file. If you specify that CANDE is to limit access, then only one job can open output
files to the user’s terminal at any given instant. If you specify that CANDE is not to limit access, then up to
100 output files, from any combination of jobs, may be assigned to a user’s terminal at one time.
By reason of a separate rule that has been around since B6700 days, only one input file may be assigned to a
user’s terminal. This limit has never been increased.12
The answer to question #2 can be specified in three ways: Should there be any limit? Should the limit ap-
ply to the terminal in all cases? Should the limit apply only if the terminal is logged on? If a limit is in
force, CANDE automatically postpones an acquisition request if the user at the target terminal is already
running a program or processing a CANDE command.
The answer to question #3 determines if the user is prompted to allow any foreign acquisition. If the an-
swer is “yes”, CANDE prompts the user with the question:
#RESPOND "OK" OR "DENY"
The user must answer the question with either the command OK or DENY. If OK is entered, the acquisition is
allowed. If DENY is entered, the acquisition is refused.
If the answer to question #3 is “no”, this prompt is not displayed. All acquisition attempts are automatically
allowed.
The “OK or DENY” question is only asked if the station is logged on, regardless of the LAISSEZFILE set-
ting.
LAISSEZFILE sets a CANDE-wide rule for all tasks and all users. You must choose the value which best fits
your local needs. The following table lists the seven possible values of LAISSEZFILE and how each value
answers these three questions:
September, 1995
LAISSEZFILE Value Announce Limit to 1 Job Ask

0 Yes All Stations Yes
1 Yes if Logged On Yes
2 Yes All Stations No
3 Yes if Logged On No
4 No All Stations No
5 No if Logged On No
6 No No No
CANDE is distributed with LAISSEZFILE set to 0, which is the most secure setting for a general-purpose
multi-user environment. Use the other values if your users would be confused by the messages and you
regularly run jobs that acquire users’ terminals. Note that the value 6 causes CANDE to automatically
make all terminal assignments without giving any notification — just as it used to in the Mark 2.6 release.
When using foreign tasks, it is also wise to make sure that the ALLLOGIN option is RESET (which it is by de-
fault). If ALLLOGIN is SET, every station must be logged on before it can be used. In particular, if a WFL
job opens a remote file to a terminal that is not logged in, and the ALLLOGIN option is SET, CANDE will
deny the open request. In this case, the program will receive an end-of-file response when it attempts to
use the terminal. If ALLLOGIN is RESET, on the other hand, CANDE will allow the assignment based upon
the setting of LAISSEZFILE.
If you use ADM EVENT PRINTLABEL via the REMOTESPO program in order to print tape labels, be wary of this
side-effect. REMOTESPO will not work if it is directed to a terminal that is not logged in and the ALLLOGIN
option for CANDE is SET.
Security-Related Options
CANDE maintains several different security features that enable users to function in a comfortable envi-
ronment while at the same time maintaining control over what those users do. The options which help en-
force security are DIALLOGIN, ALLLOGIN, SECDIALIN, SECPSEUDO, SECALL, USECOMSPRIV, NOCOMSCTRL,
and the “log station” facility. In addition, certain privileges are accorded to users based upon how their
usercodes are defined in the system’s USERDATAFILE.
As mentioned in the previous section, ALLLOGIN specifies that all stations must be logged on to some user-
code before they can be used. This includes use by a WFL job or REMOTESPO trying to write output to the
station. This option is best left RESET unless you are sure it will not interfere with your overall operations.
DIALLOGIN works in the same manner as ALLLOGIN, except that it controls only dial-in stations. By SET-ing
DIALLOGIN (recommended) and RESET-ing ALLLOGIN, you require that all dial-in stations log in but allow
tasks to use other stations without requiring that those be logged in.
After gaining access to the system, a CANDE user’s privileges are determined by the particular usercode he
has chosen to log on with. There are two USERDATA options the site administrator may set for usercodes
that CANDE recognizes: PU and CANDECONTROL. If the PU option is set, that user is considered a “privi-
leged user”, and he may access any file on the system. If the CANDECONTROL option is set, that user has the
CANDE “control” privileges, as described at the beginning of this article.
There are five CANDE options which provide different methods whereby the site administrator may re-
strict the privileges of PU-designated usercodes.
If SECDIALIN is SET, no one who enters the system through a dialup line will be allowed privileged access.
If SECPSEUDO is SET, the user who comes through a pseudo-station will not be allowed privileged access
unless all four of the following conditions are met:
• He is coming from a COMS Window (not just a BNA station).
• The USECOMSPRIV CANDE option is SET.
• The user’s station is designated as privileged for COMS.
• The user’s usercode is marked as privileged in the system’s USERDATAFILE.
Any user who accesses CANDE through a COMS window is using a pseudo station and is, therefore, sub-
ject to the SECPSEUDO restriction. To access CANDE without going through COMS, the user must connect
through an NSP/LSP, DCDLP, EDCDLP, or DCHA station. He can then use the MCS command to con
Volume 9.06
nect directly to CANDE. Such a user would not be using a pseudo station and, therefore, not be subject to
the effects of the SECPSEUDO command.
If SECALL is SET, the restrictions mentioned above for pseudo-stations are applied to all stations. This
would prevent any local user from obtaining privileged access by transferring his station through the MCS
command.
Both SECPSEUDO and SECALL require that USECOMSPRIV be SET in order to allow CANDE users to have
privileged access to the system. To disallow privileged usercodes from doing any on-line activities via
CANDE, set SECALL and reset USECOMSPRIV. Just be careful that you do not lock yourself out of your own
system!
The last security related option is NOCOMSCTRL. We discussed this option in detail at the beginning of this
article. By default, a COMS user with control capability automatically assumes CANDE control capability
when he logs onto CANDE through a CANDE window. The usercode he logs on with is immaterial.
To change this behavior, set the NOCOMSCTRL option through the command:
?OP + NOCOMSCTRL
With this option set, CANDE control capability is only conferred on users with CANDECONTROL status (or
through the other means described at the start of this article).
Note that when you change NOCOMSCTRL, you must bounce CANDE before the change will take effect.
NOCOMSCTRL is automatically set if your system’s security class is S0 or above. In that case, you cannot reset
it.
As a CANDE control user, you can obtain a report of the number of control stations on CANDE through a
single command. That command is:
?CONTROL
It generates the following report:
#CURRENT CONTROL STATIONS
C 6374 <1 TP ON PSJC10/CANDE/7(18)
C 6368 <2 Q ON PSJC10/CANDE/1(17)
This report is the same as that returned by the ?WHERE command except that it only lists control stations.
All control stations are listed, including those which inherited control status from COMS.
You can use the ?CONTROL command to designate a specific station as a control station. The syntax for do-
ing this is:
? CONTROL
< station name>
- < d:l:s>
< lsn>
ALL
The <station name>, <d:l:s>, and <lsn> are different ways of accomplishing the same thing: identifying the
target station. (<d:l:s> is only valid on NDLII/IDC supported stations.) The command:
?CONTROL <target station>
gives CANDE control capability to the designated CANDE-owned station. The command:
?CONTROL – <target station>
removes control capability from the station. The command:
?CONTROL ALL
marks all stations as control stations. This is intended only for Unisys testing and is not recommended for
general use. Once you do this, you will have to take CANDE down to undo it.
September, 1995
If the target station is a CANDE window under COMS, you must include the window name and dialog
number in the command. For example:
?CONTROL PSJC32/CANDE/1
Once you make a station a control station, it remains one until you remove the privilege through ?CONTROL
–. Most importantly, the privilege is not dropped just because the user on the station logs off. You must
explicitly remove the privilege if you do not want the next user on the station to have control privileges. For
this reason, do not designate a dial-in line as a CANDE control station through the ?CONTROL command.
You can give control privileges to any CANDE-controlled station. The station does not have to be logged
on.
The control station list is reinitialized when CANDE goes down. Therefore, use the ?CONTROL command
only to designate temporary control stations. For permanent control stations (where logging on is not de-
sired), do one of the following:
• If the station is an NDLII/IDC station that is controlled by CANDE, designate it as a SPO in IDC.
• If the station is a BNAv2 station, designate it as a Control Station in the Station Definition screen of
COMS Utility. Then make sure that the NOCOMSCTRL option is reset in CANDE.
The “Log Station” facility provides the site manager with a means of tracking security violations and other
user activity. There are a large number of options provided when using Log Stations which are described in
the CANDE Configuration Reference Manual. Anyone interested in monitoring system security should
review these options and set up some log stations accordingly.
Miscellaneous Features
One of the most valuable features of CANDE is the “saved command” feature. CANDE will save up to 20
previously processed commands for each user. The user is able to retrieve any of these saved commands
and re-enter them again without having to retype them.
The number of commands each user may save is controlled by the ?DEPTH command. The syntax for this
command is:
?DEPTH = <number>
The <number> denotes the number of commands CANDE will save for each user. The user may retrieve,
modify, or alter these commands as desired.
To query the current “depth” value, use the ?INFO command or:
?DEPTH
The response takes the format:
#SAVED TEXT DEPTH=<number>
The value in use is reported as the SAVED TEXT DEPTH. For some reason, CANDE is distributed with
SAVED TEXT DEPTH set to zero. This, of course, defeats the whole purpose of the feature.
Although up to 20 commands per user may be saved, we achieve quite acceptable results using a SAVED
TEXT DEPTH of 10. This is our recommendation for setting the ?DEPTH command.
You may define a “news” file for CANDE. If you do so, CANDE will automatically pick up the first line of
this file and transmit it to each user as he logs on. Each user may then read the remainder of that file by
entering the NEWS command.
To specify a News file, use the ?NEWS command. The syntax is:
?NEWS <file title>
For example,
?NEWS (XYZ)NEWSFILE ON PACK
The command takes effect immediately.
Volume 9.06
When composing the news file, two things should be borne in mind. The first line becomes the “headline”;
therefore, something worthwhile should be put there. If the majority of the terminals on the network are
TD-compatible, it will be useful to put a highlight character into the headline. (In particular, putting the
headline in “bright” characters has proven quite effective.)
The second consideration is that most readers will not want to reread the same information over and over.
If the news file is more than a single screen long, be sure to add newer text at the start of the file (immedi-
ately after the headline). Users have no means of simply listing the end of the file. Therefore, if new items
are always appended to the end (the natural thing considering how CANDE editing works), most users will
never read them — they will not read past the first page.
Other important CANDE options can be briefly listed with appropriate recommendations. These are:
NOJOBSUMIO —
This option stops CANDE from writing a job summary. It should be set at all times; CANDE per-
formance will be improved. (Events that would normally be written to the job summary are still writ-
ten to the system log, so no information is lost.)
KEEPSTA —
If this option is reset, CANDE will automatically return any station to its original owner when the user
of that station logs off. If this option is set, the station will remain on CANDE, even if it did not start
there. One effect of setting this option is that users entering CANDE from COMS (via the ?ON com-
mand) will not automatically return to MARC upon logging off; they must enter a ?CLOSE command to
exit any CANDE window. For most purposes, this option should be left reset.
LEADINGNUM —
In some CANDE commands the syntax is sufficiently ambiguous that numbers could be interpreted as
either sequence numbers or as parts of a file name. For example, the command:
MATCH 1X TO Y
can be interpreted in either of two ways:
a) Match all of file 1X to all of file Y.
b) Match line 1 of file X to line 1 of file Y.
The original intent in CANDE was the first interpretation. However, the code that was written fol-
lowed the second interpretation. This was fixed on Mark 4.1 so that CANDE now uses the first inter-
pretation.
If you want CANDE to use the second interpretation when processing commands, turn on the
LEADINGNUM option.
SHOWALLFILES —
This option controls the files that are reported by default through the FILES command.
If SHOWALLFILES is reset (the default), only resident files are included in response to a user’s FILES
command.
If SHOWALLFILES is set, both resident and archived/non-resident files are included in the report.
Since a user can override this option through the RES, NON, and ALL options of the FILES command, the
recommended setting for SHOWALLFILES is reset.
LASTLOGON —
PASTBATCH —
These options are only valid on a system running the InfoGuard security software. When set, they re-
port the last activity done on the usercode to the user when he logs on. They can alert users to poten-
tial unauthorized uses of their usercodes. Set these if you use InfoGuard.
September, 1995
Startup and Restart

You have several options in controlling the Startup and Restart facilities of CANDE. We discussed the
Startup facility in part two of our CANDE update series.13 This feature is entirely controlled through the
?STUP command, which has the syntax:
? STUP
*
+
-
< file name>
= < file name>
REST =
CANDE is distributed with both the Startup and the Restart facilities enabled. Startup files are sought un-
der the directory CANDE/STARTUP/=. Restart files are sought under the directory
CANDE/STARTUP/RESTART/=. CANDE looks for these directories under the usercode of the person logging
on.
As the CANDE site administrator, you have complete control over the Startup/Restart facility. You can
disable it completely. You can also change the directory names that are used.
To disable the Startup/Restart facility, use the command:
?STUP –
When disabled, CANDE does not automatically process startup files. It also does not perform any autore-
covery if a recovery file is found.
To re-enable the Startup/Restart facility, use:
?STUP +
This reinstates the feature using whatever startup and restart directory names were in use at the time the
?STUP – command was entered.
To reinstate the Startup/Restart feature using CANDE’s default directory names, use:
?STUP *
This restores the feature to the defaults as shipped from the plant.
To use your own file names, use the command:
?STUP <file name>
When you do this, you have several options depending upon what you want for your users when they log on.
In particular, you can:
• Specify default directories – either the plant-supplied defaults or one of your own — in which users
must put their startup and restart files.
• Specify a pack family that all startup and restart files must be put on.
• Specify a particular directory or file that all users must use when they log on.
To specify your own directories, just specify a <file name>, without any usercode prefix or packname suffix,
in the ?STUP command. The <file name> becomes the startup directory, and <file name>/RESTART be-
comes the restart directory.
For example,
?STUP STARTUP
sets the startup directory to STARTUP and the restart directory to STARTUP/RESTART.
If you want to specify your own restart directory as well, supply two file names to the ?STUP command. For
example,
?STUP STARTUP RESTART
Volume 9.06
makes STARTUP the startup directory, and RESTART the restart directory. You may optionally prefix the re-
start directory name with the keyword REST. For example:
?STUP STARTUP REST RESTART
When you supply just a <file name>, CANDE expects to find the startup and restart files under the user’s
usercode using his default pack family specification. If you specify the startup directory via the command:
?STUP XYZ
CANDE will search as follows for a startup file:
(<usercode>)XYZ/<station name> ON <primary family>
*XYZ/<station name> ON <primary family>
(<usercode>)XYZ/<station name> ON <alternate family>
*XYZ/<station name> ON <alternate family>
(<usercode>)XYZ ON <primary family>
*XYZ ON <primary family>
(<usercode>)XYZ ON <alternate family>
*XYZ ON <alternate family>
The first 4 tries include the <station name> the user logs on with; the second 4 do not. This is the configu-
ration you want if you want users to make their own startup files.
To limit CANDE’s searching to a particular pack family, include an “ON <family name>” suffix in your <file
name>(s). For example:
?STUP XYZ ON ICEPACK
Now CANDE will ignore the user’s family specification. Instead, it will search under the user’s usercode
for the startup file, but only on family ICEPACK. The searching will be:
(<usercode>)XYZ/<station name> ON ICEPACK
*XYZ/<station name> ON ICEPACK
(<usercode>)XYZ ON ICEPACK
*XYZ ON ICEPACK
If you want to prevent users from making their own startup files, put a usercode or asterisk prefix on the
<file name>. If you specify:
?STUP *XYZ
CANDE will only look for *XYZ/<station name> and then *XYZ on the user’s primary and alternate disk
families. If you specify:
?STUP *XYZ ON ICEPACK
CANDE will only look for *XYZ/<station name> and then *XYZ on the family ICEPACK.
Similar results can be obtained by prefixing the <file name> with a usercode in parentheses. For example:
?STUP (Q)XYZ ON CONTINUUM
If you use an asterisk or usercode prefix, you are directing CANDE to your own global startup file first.
Users will not be able to make their own startup files unless you include a DO command in your startup file
that executes the user’s file. The actions performed in the startup file are all done under the user’s user-
code and apply to his session. Thus, you can use this feature to set some global defaults for all users and,
through the DO command, allow them to add more options as desired. You can also use this feature to
automatically run a program each time the user logs on. This can be extremely useful when trying to make
life easier for an unsophisticated CANDE user.
All of the options specified above for the startup directory apply to the restart directory as well. If you
specify both <file name>s in the ?STUP command, you can use different options for the startup and restart
features.
External Configuration
So far we have discussed how to use internal CANDE options to configure and tune CANDE. There are
also environmental options you can set to help your CANDE users. These options are set in two places:
September, 1995
W - WINDOW ACTIVITY (MCS) COMS

Action: [INQUIRE ]
CReate MOdify INquire DElete GO HOme (Press SPCFY for help)
SEarch FIrst LAst NExt PRevious DUmp
Window Name. . . . . . . . [CANDE ]

Subaddress [ ]
Window Type. . . . . . . . [M] D - Direct R - Remote-File M - MCS
Virtual Terminal Name [LSCANDE ]
Maximum Users. . . . . . . [0 ] Maximum Dialogs. . . . . . [8]
Notify Open (Y/N) and Text [N] [ ]
Notify On (Y/N) and Text . [N] [ ]
Installation Data Name [NONE ]
MCS Window specific fields:
Truncated Results (Y/N). [Y]
Hostname or Domain Name [NONE
]
MCS Title [SYSTEM/CANDE
]
Remote Window Name . . . [ ] Single Window (Y/N). . . . [N]
Figure 1
Configuring the CANDE Window in COMS Utility
• in COMS;
• in the system USERDATAFILE.
COMS Considerations
At most sites users access CANDE through COMS windows. If your site is running on BNAv2, all users
who access the system via that software must connect first to COMS and access CANDE through a window.
Only if you are connecting via a derivative of NDLII — i.e., the station connects through an NSP/LSP, a
DCDLP, an EDCDLP, or a DCHA (Micro A adaptor) board — can your station connect directly to
CANDE.
As delivered, COMS includes one window named CANDE with two dialogs. This gives each user up to two
CANDE dialogs: CANDE/1 and CANDE/2. I find two dialogs to be not nearly enough. I prefer to set the
number up around 8, although I generally only use 5 or 6 at one time. Your upper limit will be constrained
by the number of users who have to share CANDE, since CANDE itself has an internal limit of 255 users.14
If you want to change the default specifications for your CANDE window, you will first need to go onto
COMS Utility. This requires that you have COMS control capability rather than CANDE control capabil-
ity. (We discussed how to obtain both COMS and CANDE control capability on page 9-245 in this article.)
Once onto Utility, go to the Window Activity screen and enter your changes. The changes take effect im-
mediately upon entry.
To go to the Window Activity screen from the Utility Home menu, enter the command W. This brings
up an empty, default Window Activity screen. Enter Inquire into the Action line of the screen, and type
CANDE into the Window Name field. This will bring up a screen as shown in figure 1.
The fields of this screen are defined as follows.

Window Name: CANDE
This is the name the user must use in order to access CANDE. If you want to use a different name,
create a window with a different name (using the same values for the rest of the fields) and then delete
this window.
Window Type: M
CANDE must be defined as an MCS window.
Volume 9.06
Virtual Terminal Name: LSCANDE

This field is only valid for terminals that connect through a front-end datacomm processor, such as a
CP2000. It tells the front-end processor how to format input and output messages for the terminal. If
you want to use the Virtual Terminal Name specified for the terminal in the CP, give this field a
value of DEFAULT. Otherwise, use the value LSCANDE.
Maximum Users: 0
From COMS’ point of view, you want to let an unlimited number of users access CANDE. CANDE
knows its own limits and will reject an attempt to exceed its own MAXSTATIONS limit. It is better to let
CANDE handle that situation than to try and coordinate it with COMS.
Maximum Dialogs: [choose your best fit]
Ideally, you should be able to put this at a number like 4, 6, or 8. Two is just not enough. It takes at
least 4 dialogs for a programmer to get serious work done. However, non-programmers may be able to
get by with just 1 or 2 dialogs. Unfortunately, the maximum applies to everyone — there is no distinc-
tion by usercode.
Divide the number of expected concurrent users into 256 to get a good starting number. Then use that
number or 4, whichever is larger. If you expect to have more than 100 concurrent users, seriously con-
sider running multiple copies of CANDE.
Notify Open: N
Notify On: N
Make sure both of these are set to N (No). When a user first opens a CANDE window, he is automati-
cally logged on with the usercode he is using on COMS. Any text you put in this field will be inserted
into the user’s input queue for processing after log on. If the user has a startup file, that file will be
executed first, before the COMS text is processed.
If the user switches out of CANDE and then back in, you do not want to transmit anything to CANDE.
You have no way of knowing what state the user left a dialog in. If he is in the middle of a listing, for
example, you can really mess things up if you give CANDE some canned text when the user goes back
onto the dialog.
Even supplying a default text of all blanks can be very annoying. Most of the time CANDE responds to
blank input with a single pound sign (#). But if the user is listing a file, a blank input will move him to
the next page of output. Similarly, if the user is running a program, a blank input may have serious re-
percussions. The safest course is to not let COMS send any automatic text to CANDE after a ?ON.
Truncated Results: Y
This field is set to Y for MCS programs which can handle messages that contain just a COMS header.
Unisys sets this field to Y by default for the CANDE window. They should know best...
Hostname or Domain Name: blanks
You are running CANDE and COMS on the same host, so leave this field blank.
MCS Title: SYSTEM/CANDE
For the true CANDE window, make this title SYSTEM/CANDE, without any pack family specification.
If you create multiple CANDE windows at some time in the future, you will need to use different MCS
Titles for each of those windows. Each MCS must have a unique title.
The default value supplied here by Unisys is SYSTEM/CANDE. This means *SYSTEM/CANDE on the family
specified in your DATACOMINFO file.15 By default, that is the pack family named DISK. If the codefile is
on any pack family other than DISK, you will get the message:
* 6488 10:58 COMS:SYSTEM/CANDE. (MCS) REQUIRED
This happens if CANDE is not already running when the first user attempts to go “?ON” to the CANDE
window. The window itself will be dead. The user must use ?CLOSE to exit the window and escape
back to MARC.
This rule applies although COMS itself may be running from a pack family that is not named DISK. It
also applies even if you add a pack name into the MCS Title field. For example, if your MCS Title
reads:
SYSTEM/CANDE ON ICE
September, 1995
COMS will still attempt to run *SYSTEM/CANDE ON DISK. To put *SYSTEM/CANDE on a pack family
other than DISK, and have COMS bring it up automatically, you must assign a FAMILYNAME to the defi-
nition of SYSTEM/CANDE in the DATACOMINFO file (through the IDC program).
If you bring up CANDE manually — i.e., if you enter the primitive command:
??RUN SYSTEM/CANDE ON <family name>
at the ODT, users will be able to access CANDE successfully even though the <family name> is not
DISK. The requirement that *SYSTEM/CANDE be on family DISK applies only if you want COMS to
automatically start CANDE should it not already be running.
Remote Window Name
Single Window
These fields are not used with the CANDE MCS.
The COMS Utility program allows the site manager to designate that certain usercodes are “control capa-
ble”. This means that these users may enter COMS network control commands (such as ?READY, ?SAVE,
and so forth) when they are logged on to the system. If such a user opens a CANDE Window, he retains
this control capability. This means that he may enter any CANDE control commands also. In particular,
such a user can change any of the option settings reported by the ?INFO command to anything he wants at
any time.
If the CANDE option NOCOMSCTRL option is set, a COMS “control capable” user is not granted CANDE
control capability.
USERDATA Considerations
There are a number of options you can apply to the usercodes at your site which will make life easier for
your CANDE users. These options are all set in the system USERDATAFILE through the program
SYSTEM/MAKEUSER.16 We will highlight the most important ones here. However, you should review the
Security Administration Guide to get a complete list of the usercode options available to you.
First and foremost, be sure to set a default FAMILY specification for your CANDE users. I’ve seen many
sites omit this step, and the result is that all of the users end up by default on family DISK. (They end up on
“no” family if the site does not have a family named “DISK”.) Use the MAKEUSER specification:
FAMILY DISK = <name 1> OTHERWISE <name 2>
<Name 1> must be the pack family where you want users to store their files. This is their primary work-
space. <Name 2> must be the “resource” pack family. This is the pack family where the global system
utilities, compilers, and such are stored. If you have no “resource” family, you can use this syntax instead:
FAMILY DISK = <name 1> ONLY
One of the last things you want is for users to hard code pack family names in their WFLs, “DO” files, and
schedule files. This is best minimized (and often totally avoided) by giving everyone’s usercode a proper
FAMILY specification.
The next most important option after the FAMILY specification is the PRINTDEFAULTS specification. The
syntax for including this is very awkward. That’s because the general syntax is:
PRINTDEFAULTS = " <attribute list> "
The entire <attribute list> must appear inside the quotes. Each specification is separated from the next by
a comma.
If you cannot fit everything into a single line, you must end each line with a quote and begin each succeed-
ing line with another quote. For example:
PRINTDEFAULTS =
" <attribute specifications> "
Volume 9.06
This shows how to spread a PRINTDEFAULTS specification over three lines of MAKEUSER input. It looks sim-
ple enough — until you realize that many of the <attribute specifications> themselves also use quote char-
acters. DESTINATION, PAGECOMP, and TRANSFORM — just to name a few — use strings as values that must be
enclosed in quotes. To keep from confusing MAKEUSER, you must substitute 3 quotes in each place where
you want a single quote. Therefore, a simple DESTINATION, such as LP20, must be encoded thusly:
PRINTDEFAULTS = "DESTINATION="""LP20""""
If you need to split a string over two lines, as in some TRANSFORM specifications, you end up with something
hideous like:
PRINTDEFAULTS =
"TRANSFORM = """ADJUST (SHIFT = +8)"
"IN SL TRANSFORMSUPPORT""""
This is all a MAKEUSER problem, but you need to be aware of it if you want to give your users detailed
PRINTDEFAULTS specifications.17
The two most common PRINTDEFAULTS values you need to set are DESTINATION and PRINTDISPOSITION.
For example:
PRINTDEFAULTS =
"DESTINATION = """CSJC12""","
"PRINTDISPOSITION = CLOSE"
This example directs all of the user’s outputs to the printer CSJC12. Outputs are released for printing the
instant the printer file is closed. With the PRINTDISPOSITION = CLOSE specification, your users will never
have to use the SPLIT command to release an output.
If you want users to keep their files as backup files and manually release them using SPLIT, set
PRINTDISPOSITION to EOJ. For example,
PRINTDEFAULTS =
"DESTINATION = """CSJC12""","
"PRINTDISPOSITION = EOJ"
If you do not want a user to automatically generate printed output, you can also use:
PRINTDEFAULTS = "PRINTDISPOSITION=DONTPRINT"
This will force the user to either change his PRINTDEFAULTS or use BACKUPPROCESSOR in order to print the
output of his CANDE (and all other) jobs.
Choose the PRINTDEFAULTS specification that best suits your needs. Since this is a usercode attribute, you
can give each user a different specification if desired.
Another attribute of importance is SHOWFILES. This attribute affects the visibility of the user’s files for
other users on the system. If you turn SHOWFILES on for a user, all of the other users on the system can use
the FILES command to view the titles (and other attribute information) of the non-PRIVATE files owned by
that user. This can be useful if PUBLIC or GUARDED files under the usercode are frequently accessed by
other users. If you turn off SHOWFILES, non-privileged users cannot obtain information about the user’s
files through the FILES command.
To enable SHOWFILES, use:
+ SHOWFILES
To disable it, use:
– SHOWFILES
Again, this must be set on an individual usercode basis. It determines how other users of the system see the
files that belong to this user.
The three usercode attributes given above are system-wide attributes. They affect everything the user does:
in CANDE, in WFL jobs, in COMS, and so forth. CANDE is just one environment in which these attrib-
utes have meaning.
September, 1995
There is also a group of usercode attributes that are CANDE-specific. They only have meaning to CANDE
and are ignored by the rest of the system software. These attributes are:
CANDEGETMSG —
If set, this attribute means that the CANDE user will automatically receive job messages at his termi-
nal. It causes the MSG option to be automatically set each time the user begins a new session.
This option should be set for programmers, WFL writers, and others who need to monitor the progress
of WFL jobs from their terminals. It should be reset for on-line users who would be confused by the
messages. The default setting for this option is “reset”.
CANDEAUTORECOVER —
This attribute determines if the user can use the automatic recovery feature described in Part Two of
our CANDE update series.18 If you have set the CANDE option RECOVERSESSION to REQUESTED (de-
scribed earlier in this article), then only the usercodes for which you enable the CANDEAUTORECOVER
option can use the automatic recovery feature. The feature is not available to all of your other users.
CANDEQWAIT —
If this attribute is set, the QWAIT option for the session is automatically set each time the user logs on.
With QWAIT set, all “pending” input to CANDE immediately becomes “waiting” input. The user must
explicitly discard “waiting” input (through the ?PURGE command) or execute it (through the ?GO or
?REPEAT commands) before CANDE will accept any further input from him.
At most sites, you will want to have this option disabled (the default setting).
CANDECONTROL —
If set, this user has control capability when logged onto CANDE. If reset, the user does not have con-
trol capability. This option should be reset except for site administrators and those who are responsible
for configuring CANDE runtime options.
These are all boolean-valued usercode attributes. To set or enable any of these attributes, use the syntax:
+ <attribute>
To reset or disable any one of these attributes, use:
– <attribute>
All of these attributes are reset by default.
There is one last CANDE-oriented usercode attribute of interest: CANDECONTCHAR. Use this attribute to
set a default <continuation character> for the user. The syntax is:
CANDECONTCHAR = "<special character>"
For example:
CANDECONTCHAR = "%"
The per cent sign is the traditional <continuation character> for CANDE. That character is not used in any
standard CANDE command.
To remove the default <continuation character> for the user, if he already has one, use the syntax:
– CANDE
By default, a usercode will not have a <continuation character>.
Given all of the above, here is a minimal MAKEUSER profile for a typical CANDE user. Note that MAKEUSER
requires a semi-colon as a statement terminator, so the following is all one statement even though it is
spread over multiple input lines.
+ USER CANDYUZER
FAMILY DISK = ICE OTHERWISE DISK
PRINTDEFAULTS =
"PRINTDISPOSITION = CLOSE, "
"DESTINATION = """CSJC12""""
+ CANDEGETMSG
+ CANDEAUTORECOVER;
Volume 9.06
This provides a basic configuration for a non-privileged, non-control CANDE user who can handle the
automatic reception of job messages.
Conclusion
As we have shown in this article, there are many ways to tune CANDE so that it will perform at its best on
your A-Series system. There are a large number of options and settings, and all of these have default values.
For some of the options, the plant-supplied defaults are the wisest choice. In other cases, however, this is
not true. As the CANDE site administrator, you need to know how each of these options affects CANDE
behavior and what the best choice is in each case for your installation.
As Unisys continues to improve CANDE, more options will be added in the future. As shown in this arti-
cle, there are already a large number of options to deal with. By dealing with the current ones today, you
will be far ahead when it comes time to configure the CANDE of tomorrow.
1
That’s assuming such days ever really existed. It’s the only reason I can think of to explain why CANDE is so easy to
install and manage while other products require so much work! Usually, you have to install a product and a bunch of
support Libraries, and there are all sorts of dependencies between the modules. This is done for the convenience of
the developers, but it puts a major burden on those of us who have to install this stuff. If developers would use Binder a
little more and Libraries a little less, the system software would be much cleaner and easier to support. ...but enough of
my soapbox...
2
The setting for the ?BOOK command is missing.
3
Unisys Corporation, CANDE Configuration Reference Manual, form #8600 1344-200.
4
Running more than 3 grind stacks has proven to cause problems if CANDE is improperly compiled. Be sure to set the
NOSTACKARRAYS compile time option when compiling CANDE if more that 3 grind stacks are desired.
5
In an extremely tight memory environment, such as a Micro A with 12 megabytes of memory, where you have less
than 8 CANDE users, you might reduce MAXSTATIONS to a smaller number. Otherwise, set it to 255.
6
The COMPILESPERCENT feature is a prime illustration of how Unisys used to treat CANDE in the bad old days of the
mid 1980’s. This feature was implemented as a response to a user New Feature Suggestion (NFS). However, it did not
address the NFS at all. In the original NFS, the users asked that an option be provided so that they could turn off the
on-line compile feature of CANDE and force programmers to use batch queues only. The specific request was that, in
response to a COMPILE command, CANDE would generate a WFL job to do the compile and submit it into a job
queue. This is not hard to do, and, in fact, the patch to do this has been on our bulletin board since 1988. However,
somebody in Unisys must have thought it would be cute to take a shortcut and implement this revulsive
COMPILESPERCENT feature instead. Certainly you can completely disable the ability to do compiles on line by setting
COMPILESPERCENT to zero. However, doing so does not cause CANDE to tell programmers that they cannot do com-
piles. Instead, when a programmer submits a compile, he gets the standard message:
#WAITING FOR AVAILABLE COMPILE TASK
He waits forever. As implemented, this feature can noticeably reduce the productivity of your programmers.
7
To put it another way, using MAXTASKS to control task activity is a great way to encourage your users to demand a Unix
computer instead. You would be better off patching CANDE to (a) eliminate the commands you do not want (e.g.,
COMPILE, LOG), and (b) enforce resource limits on all user tasks rather than trying to manage your environment
through MAXTASKS.
8
If the MAXTASKS limit applied strictly to the RUN, UTILITY, and COMPILE commands, I would feel differently about it.
It’s the application to the START command that really makes MAXTASKS a burden.
9
It is also worth noting that MARC does not have a MAXTASKS feature. The clever user can exploit this to get around
any CANDE task limit.
10
Note that we are not talking about the automatic job messages which are always routed only to the logical station
number at which the WFL job originated. This discussion strictly has to do with the job monitoring commands, such as
?MSG.
11
That’s only one story. I remember one jerk who thought it was funny to open a remote file to your terminal and write
a single form feed. Poof! — and an entire page of carefully composed text vanished before your eyes.
12
This limit exists to resolve an ambiguity. If two or more input files could read from the same terminal at the same
time, and the user entered one input, to which file would that input go?
September, 1995
13
Gregory, Donald J., “CANDE: Enhancements to Unisys’ Venerable Workhorse, Part Two — Session Control Fea-
tures”, Gregory’s A-Series Technical Journal, vol. 9:06, pp. 9-199 – 9-204.
14
This limit includes schedule stations and such, so your actual limit may be lower.
15
This name is specified through the Interactive Datacom Configurator (IDC).
For more information on SYSTEM/MAKEUSER, see: Unisys Corporation, A-Series Security Administration Guide, form
16
#8600 0973-200, Section 9, “Using SYSTEM/MAKEUSER.”

17
Note that you do not want to use device transforms (now called drivers) in a MAKEUSER specification. Drivers are
specific to hardware devices. The TRANSFORM specified as a usercode attribute would be applied to each output gener-
ated by that user, as a “file transform.”
18
Gregory, Donald J., “CANDE: Enhancements to Unisys’ Venerable Workhorse, Part Two — Session Control Fea-
tures”, Gregory’s A-Series Technical Journal, vol. 9:06, September, 1995. The automatic restart feature is discussed on
pp. 9-202 – 9-204.
Volume 9.06

Cande:: Enhancements To Unisys' Venerable Workhorse

Uploaded by

Copyright:

Available Formats

Cande:: Enhancements To Unisys' Venerable Workhorse

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cande:: Enhancements To Unisys' Venerable Workhorse

Uploaded by

Copyright:

Available Formats

CANDE:

Enhancements to Unisys’ Venerable Workhorse

CANDE: Editor Improvements

Use a FIND command specifying the PAGEMODE option.

Invoking Page Mode with FIND

Edit and transmit changes.

Adjusting the View

to back up and see any prior lines.

10007050$$ SET ALLSCANDEFINES

The new +FIND Command

10016000 WRITE (FILEREPORT, 30, OUTBUF);

Mixing Editing Commands

The End of a Search

Improvements to Page Mode Editing

PAGE @ < single column>

To cancel the <column specification>, use:

Horizontal Scrolling vs. Special Fields

Summary of the PAGE Command

Editing Files that Contain Non-Printable Characters

and the word these will be blinking at you.

For example, consider:

#EVEN NUMBER OF HEXADECIMAL CHARACTERS EXPECTED AT LINE 2

If no <escape character> is currently defined, the response is:

Protection of your Workfile

Setting Default Specs for your Terminal

• the PAGE specification;

CANDE: Session Control Features

#MicroA:27910 CANDE SSR 41.2 (41.253.0182) AT A00SJC2

is displayed. You can resume processing of the <startup file> by entering:

Automatic Recovery of Work

#MicroA:27910 CANDE SSR 41.2 (41.253.0182) AT A00SJC2

ALL — AUTORECOVER is always attempted for all users.

CANDE: File Searching

FILES Command Basics

Report Layout Options

File Name Filekind Records Sectors CreationTime

SYM/FORM ALGOLSYMBOL 1558 784 07/30/1992

File Name Attributes

SYM/FORM Filekind= ALGOLSYMBOL Records= 1558

SYM/FORM/SAMPLE1 Filekind= COBOL74SYMBOL

SYM/FALCON Filekind= DCALGOLSYMBOL

SYM/FSRCOPY/1 Filekind= ALGOLSYMBOL Records= 131

SYM/FSRCOPY/2 Filekind= COBOL74SYMBOL

Showing Archived Files

File Name Filekind Records

File Name Filekind Records

SYM/PRINTS/DUMP ALGOLSYMBOL 2322

File Name Filekind Records

File Name Filekind Records

SYM/PRINTS/DUMP ALGOLSYMBOL 2322

File Name Filekind Records

SYM/PRINTS/DUMP ALGOLSYMBOL 2322

Wildcard Name Searching

ON < family name >

: < output options >

4. A list of <name>s containing wildcard characters or pattern matching expressions.

File Name Filekind Records

File Name Filekind Records

File Name Filekind Records