The format of a specification should preferably follow the MDC standard approach for the interface, e.g.

where

result is optional and has the form :datatype

param has the format [.]name [:[datatype] [ : optional]]

datatype is one of BOOLEAN, COMPLEX, INTEGER, MATRIX, NAME, REAL, STRING

optional is M or O

plus a description of the functionality and any error codes that are appropriate... An example from the standard is:

Main menu for utilities - Interactive utility.

Main menu for File/Device utilities - Interactive utility.

File directory utility - Interactive utility.

File Lister - Interactive utility.

Not callable at the main entry point. Holds miscellaneous file/device related subroutines for the other %U utility routines.

1. read(device::O, .result::M, length:INTEGER:O, timeout:INTEGER:O)

Reads into result from device (defaults to current one). result must be defined and if non-null then this will be treated as the default value for the field, i.e. returned in the field value if the read encounters a null string.

If a length is specified then this is the maximum length allowed.

2. write(device::O, text::O)

Writes text to the specified device (defaults to current one).

3. select(device::O, params::O)

Prompts for and selects an output device, using params as the device parameters.

4. open(device::O, type::O, params::O, timeout:INTEGER:O)

Opens device using params with timeout. Valid value for type are - "in", "out", "inout" and "new".

If the open is unsuccessful and the type is not "in" then a second attempt is made to open the device as a "new" file.

The first comma piece of the return value, if not a negative error code, is the device number/name to be used in subsequent read/write/close^%Ufxxx calls.

5. close(device::O)
   
   Closes device
6. header(device, type::O, comment::O)
   
   Writes a two line header to the device. The first one contains type - current date/time, contained in ****s. The second line is comment.
7. trailer(device, type::O)
   
   Writes a two line trailer to the device. The first one is null and the second contains type - current date/time, contained in ****s.
8. rmdir(path)
   
   Removes host file directory!!!!
9. mkdir(path)
   
   Create Host file directory
10. direx(path)
    
    Tests if directory exists

Main menu for Global utilities - Interactive utility.

Global Delete - Interactive utility.

1. go(select)
   
   Deletes the globals defined in select (same format as used by gsel^%Ugxxx).

Global directory utility - Interactive utility.

Global Export - Interactive utility.

Entry points:

1. export(device::M, work::O, comment::O) is non-interactive. comment is put into the header records on the file, in addition to the current date/time.
2. go(device::M, work::O, comment::O) is non-interactive (calling routine has to Open/Close device). comment is put into the header records on the file, in addition to the current date/time

Global Import - Interactive utility. This allows for the user to restore all globals; alternatively to selectively decide to not restore a global or restore it with a different name. ("-" = skip, "*" = restore all remaining globals, "^" = abort import.)

Entry points:

1. import(device::M, all:BOOLEAN:O) is non-interactive
   Imports globals from the file/device device into the current UCI/namespace. Note: if all is not true then interactive response is required for each global.
2. go(device::M, all:BOOLEAN:O) is non-interactive (calling routine has to Open/Close device).
   Note: if all is not true then interactive response is required for each global.

Global Lister - Interactive utility.

Global Lister - Interactive utility. (Alternative version).

Global Search and Replace - Interactive utility.

1. go(device::M, work::O, .search:M, .replace::O, subscript:BOOLEAN:O)
   
   Searchs the globals defined in work (same format as used by gsel^%Ugxxx) replacing any found string in the array search with the corresponding array element in replace. If there is no corresponding entry in replace then no change is made. The old and new nodes are output to device.
   
   If subscript is true then the subscript values for all nodes are also searched and replaced. This may involve the changing of multiple nodes in one change. Note: If the new subscript is not in the range remaining to be searched then any sub-tree nodes of this node will not have their data portion scanned.

Not callable at the main entry point. Holds miscellaneous global related subroutines for the other %U utility routines.

1. gsel(work)
   
   Global selector, creating result in work (defaults to normal %U work global)
2. gseldisp(work)
   
   Display currently selected globals.
3. valid (global)
   
   True if global is a valid global name.
4. process (work::M, exec1::M, exec2::M)
   
   Processes the list of global specifications defined in work, executing the string exec1 for each one found and exec2 for each node encountered within the global specification.

Main menu for Routine utilities - Interactive utility.

Routine Delete - Interactive utility.

1. go(select)
   
   Deletes the routines defined in select (same format as used by rsel^%Urxxx). Any routines which are not deleted are left defined in select.

Routine Directory - Interactive utility.

Routine Editor - Not callable at the main entry point.

d init^%Uredi initialises Editor. This can then be executed by x^%Ue

Routine Export - Interactive Utility.

1. go(device::M, select::M, comment::O, version::O, separate:BOOLEAN:O)
   
   Creates/outputs to a file named device the routines defined in select (same format as used by rsel^%Urxxx). comment is put into the header records on the file, in addition to the current date/time. If version is not null then the first line of each routine will have version added to it preceded by "; " (if version doesn't start with punctuation and the line already contains a comment).
   
   If separate is true then each routine is saved in a separate file - device/routine.m

Routine First Line Lister - Interactive utility.

1. go(work::M, device::O)
   
   Lists the first line of routines defined in work (same format as used by rsel^%Urxxx) on to device.

Routine Import - Interactive utility. This allows for the user to restore all routines; alternatively to selectively decide to not restore a routine or restore it with a different name. ("-" = skip, "*" = restore all remaining routines, "^" = abort import.)

Entry points:

1. import(device::M, all:BOOLEAN:O) is non-interactive
   Imports routines from the file/device device into the current UCI/namespace. Note: if all is not true then interactive response is required for each routine.
2. go(device::M, all:BOOLEAN:O) is non-interactive (calling routine has to Open/Close device).
   Note: if all is not true then interactive response is required for each routine.

Routine Lister - Interactive utility.

1. go(work::M, device::O)
   
   Lists the routines defined in work (same format as used by rsel^%Urxxx) on to device.

Routine Search and Replace - Interactive utility.

1. go(device::M, work::O, .search:M, .replace::O)
   
   Searchs the routines defined in work (same format as used by rsel^%Urxxx) replacing any found string in the array search with the corresponding array element in replace. If there is no corresponding entry in replace then no change is made. The old and new lines are output to device.

Not callable at the main entry point. Holds miscellaneous routine-related subroutines for the other %U utility routines.

1. rsel (work)
   
   Routine selector, creating result in work (defaults to normal %U work global)
2. rseldisp (work)
   
   Display currently selected routines
3. save (routine::M, .array::M)
   
   Saves text defined in array into routine.
4. delete (routine)
   
   Deletes routine
5. exists (routine)
   
   True if the routine exists.
6. valid (routine)
   
   True if routine is a valid routine name.
7. process (work::M, exec::M)
   
   Processes the list of routines defined in work, executing the string exec for each one found.

Returns a formatted date and time. Non-interactive.

^%Uxdat(date:INTEGER:O, .format:INTEGER:O)

1. date^%Uxdat(date:INTEGER:O, .format:INTEGER:O)

Returns formatted date (defaults to +$h). The format codes are the same as for ^%Uxdat()

2. time^%Uxdat(time:INTEGER:O, .format:INTEGER:O)

Search and Replace functions - non-interactive utility.

1. find (old::M, .search:M, type::O)
   
   Searchs the string old for a string in the array search. The result is true if a match occurs.
   
   Type can have the following values
   0 - plain string replacement (default value)
   1 - allows ellipsis (...)
2. search (old::M, .search:M, .replace::O, type::O)
   
   Searchs the string old replacing any found string in the array search with the corresponding array element in replace. If there is no corresponding entry in replace then no change is made. The default value for type here is 1 (see above).
3. input (.search::M, .replace::M)
   
   User input function to set up search and replace arrays.
4. header (device::M, description::M, .search::M, .replace::O)
   
   Outputs standard header for search/replace at top of listings. description is the type of search being undertaken, e.g. Global, Routine.

Not callable at the main entry point. Holds miscellaneous subroutines for the other %U utility routines.

1. init()

Initialises %U utility variables

2. read(prompt::O, .result::M, help::O, length:INTEGER:O, PX:INTEGER:O, PY:INTEGER:O X:INTEGER:O, Y:INTEGER:O, timeout:INTEGER:O)

Reads into result from the current device. prompt is output, subject to any language conversion. result must be defined and if non-null then this will appear between < and > after any prompt string and be treated as the default value for the field, i.e. returned in the field value if the user doesn't enter anything.

If a length is specified then this is the maximum length allowed, and may be used in any screen handling implemented (using X and Y as the location or PX and PY for the prompt location). If validation is specified then this will be executed prior to returning a result.

The following conventions are used on user input:

? = help (calls help())
@ = return null string (needed when default is specified)
^ = user abort
^^ = ^
^? = ?
^@ = @

3. readn(prompt::O, .result::M, help::O, length:NUMBER:O, timeout:INTEGER:O)

As for read except that a newline precedes prompt.

4. readyn(prompt::O, .result::M, help::O)

As for readn except that the result can only be 1/0, corresponding to entering Yes/No.

5. write(device::O, text::O, X:INTEGER:O, Y:INTEGER:O)

Writes text to the current device at location X,Y.

6. writen(text::O)

As for write except that a newline precedes text.

7. writep(device::O, text::O)

As for writen except that text is converted using lprompt().

8. writef(format::O, text::O)

As for write except that format is treated as a M[UMPS] format string and precedes text.

9. rerror(text::M)

Displays an error as a result of previous user input, converting text using lprompt() and preceding it with " - ". text starting with a "?" will not be converted.

10. merror (number:INTEGER:M)
    
    Displays an error message corresponding to the (negative) %Utility errors below.
11. error (text::M)

Displays an error message, converting text using lprompt() and preceding it with "Error - ".

12. help(help::O)
    
    Displays help text associated with help. help is of the form subject.item, where subject is normally the routine name for %U utilities. If this subject.item does not exist then subject is shortened one character at a time until a match occurs.
13. lprompt (text::M)

Returns text converted into a prompt in the appropriate user language. All text after a "-" is left unchanged and if the text contains "~" this is changed to " - " and the preceding text is also left unchanged.

14. upper (text::M)

Returns text with any lower case characters converted into upper case, taking into account language.

15. lower (text::M)

All errors are negative numbers and returned in the format error,function thus allowing for calling programs to determine, if necessary, exactly where the error occurred. All calling programs should test the result of the extrinsic function and if <0 then an error has occured. Non-negative values may be used to indicate, e.g. the number of values returned, etc. Negative values should be unique throughout the utilities. The ones allocated so far are:

All utilities are named %U*---, where * is the type of utility (c=character, f=file/device, g=global, j=job, k=lock, l=library, n=namespace, r=routine, s=system, x=general) and --- is the name, e.g. dir for directory. All routines which are subsumed within an overall routine will have a 2 digit suffix, e.g. %Ugdir01.

All input and output will, eventually, be handled through common input/output extrinsic functions. This should allow for greater consistency and also easier language independence if so desired. The read/write %Uxxxx extrinsic functions will automatically convert these prompts into the current language setting, pulling information off ^%Uprompt(language, prompt) if it exists.

All exposed entry points should have alpha labels and be called as extrinsic functions. All internal labels should start with a %.

All routines/functions should have no other side-effects/accesses, e.g. other variables or globals, except where defined in the specification. Apart from anything else all internally used variables should be NEWed (preferably at the initial entry point). [Note: Any changes to $T or the naked reference are not considered side-effects here, but should be avoided if possible - extrinsic functions automatically restore $T anyway.]

It would be nice to have a standard usage of variable names, but ...

Standard global names should follow the routine naming standard. A standard work file (normally ^uwork($j)), which can be modified on a per UCI/namespace basis as part of the system configuration is set up when calling the initialisation module. This should be accessed in any utility using subscript indirection, e.g. @%Uwork@(...)

To allow easy modification it would be sensible for all accessing to specifically named globals, i.e. not those whose names are passed as parameters, within functions should be via name indirection in order to make them easier to change if necessary.