Syntax

── UTILITY ─┬─────┬─<file title>─┬────────────┬────────────────────────►
            └─ $ ─┘              ├─<text>─────┤
                                 └─ '<text>' ─┘
►─┬───────────────────────────────┬────────────────────────────────────┤
  │ ┌◄──────────────────────────┐ │
  └─┴─ ; ──<task equation list>─┴─┘

Explanation

The UTILITY command allows user-written programs to modify the current work file. The utility to be used is specified by name (as in executing any other program). An optional string of text can be passed in an array parameter to the utility. CANDE makes the work file available to the utility for access or modification, using file equation and the task value for communication. The <text> is any string of data not including an unquoted semicolon (;). One or more elements from the <task equation list> can be included (as for the EXECUTE verb).

The dollar sign ($), <file title>, and <task equation list> elements are treated the same as for the EXECUTE verb. The <text> is copied into an array that is passed as a parameter to the utility. Except between quotation marks, any lowercase letter is translated to uppercase and any redundant blanks are discarded. (A blank is considered redundant if it is adjacent to another blank, or if it either begins or ends the <text>.) If any alterations are made to the work file, the work file is updated before the utility is invoked.

The utility must be a procedure accepting an array parameter, as in the following ALGOL heading:

 $ SET LEVEL 2
 PROCEDURE U(A); ARRAY A[*];

The array contains the text from the utility command, in EBCDIC, followed by at least one NUL. The length of the array is arbitrarily large; all characters beyond the text are NUL.

CANDE includes file-equation for the files specified in File-Equatable Files. The Attributes column indicates the attributes that are included in the file equations.

If the CANDE session has no work file, no file equation is done. If a work file exists, it may or may not be named. If a work file exists and is named, then WORKFILE.TITLE is equated to the work file name. The name has neither a usercode prefix nor a family suffix and serves only for identification. The utility is not expected to process any input or output through the file WORKFILE.

A work file can be empty. If the work file is not empty, a work source file is made containing the line images for the file. If a work source exists, then WORKSOURCE.TITLE is equated to its title. A utility reads this file to obtain the work file contents. To be consistent with CANDE conventions, the utility should not write to WORKSOURCE.

If the work file has been compiled, the object code is contained in a work object file. If a work object exists, WORKOBJECT.TITLE is equated to its title. A utility could read this file to display or analyze the code.

If any work file (named or not, empty or not) exists, file equation is performed for the files NEWWORKSOURCE and NEWWORKOBJECT. All the attributes listed above for NEWWORKSOURCE are equated to the appropriate values for the work file. The utility may write a new work source with these attributes to replace the old work source file. The TITLE of NEWWORKOBJECT is equated; a file of this name may be created if the utility invokes (or is) a compiler to create a new work object.

All the source and object titles are complete, including usercode prefix and family suffix, except that ON DISK cannot appear for files on disk.

On entry to the utility, the utility TASKVALUE is set as follows:

On termination of the utility, CANDE interprets the TASKVALUE as follows:

If the utility is abnormally terminated, CANDE ignores the TASKVALUE and acts as though bit 46 were ON and all others OFF.

If a work file exists, an UPDATE to that work file is done before the UTILITY command is executed.

Examples

The following example assumes a CANDE user with usercode of MY and family specification of DISK = MINE OTHERWISE DISK, using station number 12, with access to a utility program named OBJECT/P. The following session fragments result in running the utility with the attributes noted. Those TITLE attributes not mentioned in each case default to the INTNAME. In each case that NEWWORKSOURCE.TITLE is specified, all the other attributes listed previously have been equated to the values appropriate to the work file.

No work file exists.

INPUT
-----
REM;U P
STATUS OF UTILITY TASK
----------------------
MYSELF.TASKVALUE = 0

A named, empty work file exists.

INPUT
-----
MAKE T;U P
STATUS OF UTILITY TASK
----------------------
MYSELF.TASKVALUE = 3
WORKFILE.TITLE = "T."
NEWWORKSOURCE.TITLE = "(MY)CANDE/TEXT120 ON MINE."
NEWWORKOBJECT.TITLE = "(MY)CANDE/CODE120 ON MINE."

A named work file with an unsaved work source and work object exists.

INPUT
-----
MAKE T
100BEGIN
...
900END.
C
U P
STATUS OF UTILITY TASK
----------------------
MYSELF.TASKVALUE = 15
WORKFILE.TITLE = "T."
WORKSOURCE.TITLE =    "(MY)CANDE/TEXT120 ON MINE."
WORKOBJECT.TITLE =    "(MY)CANDE/CODE120 ON MINE."
NEWWORKSOURCE.TITLE = "(MY)CANDE/TEXT120 ON MINE."
NEWWORKOBJECT.TITLE = "(MY)CANDE/CODE120 ON MINE."

A named work file with a saved work source and work object exists.

INPUT
-----
GET Z;U P
STATUS OF UTILITY TASK
----------------------
MYSELF.TASKVALUE = 15
WORKFILE.TITLE = "Z."
WORKSOURCE.TITLE = "(MY)Z ON MINE."
WORKOBJECT.TITLE = "(MY)OBJECT/Z ON MINE."
NEWWORKSOURCE.TITLE = "(MY)CANDE/TEXT120 ON MINE."
NEWWORKOBJECT.TITLE = "(MY)CANDE/CODE120 ON MINE." 

A named work file with a borrowed work source exists.

INPUT
-----
G (U)X ON F AS W
U P
STATUS OF UTILITY TASK
----------------------
WORKSOURCE.TITLE = "(U)X ON F."
NEWWORKSOURCE.TITLE = "(MY)CANDE/TEXT120 ON MINE."
NEWWORKOBJECT.TITLE = "(MY)CANDE/CODE120 ON MINE." 

An unnamed work file with a borrowed work source exists.

INPUT
-----
G SYMBOL/ALGOL
U P
STATUS OF UTILITY TASK
----------------------
WORKSOURCE.TITLE = "*SYMBOL/ALGOL."
NEWWORKSOURCE.TITLE = "(MY)CANDE/TEXT120 ON MINE."
NEWWORKOBJECT.TITLE = "(MY)CANDE/CODE120 ON MINE."