#-h- summary 2306 asc 19-may-80 11:02:31 .bp .rm 70 .in 0 .he 'LIBRARY'11/13/78'LIBRARY .fo ''-#-'' .ce OVERVIEW OF SOFTWARE TOOLS LIBRARY ROUTINES .nf .in 7 .ti -7 FILE ACCESS open - open an existing file for reading, writing, or both create - create a new file (or overwrite an existing one) close - close (detach) a file remove - remove a file from the file system amove - move (rename) file1 to file2 fsize - determine number characters in file gettyp - get type of file tty - determine if file is a teletype/CRT device termin - pick up name of input channel to user's teletype trmout - pick up name of output channel to user's teletype .sp 1 .ti -7 I/O getch - read character from file getlin - read next line from file putch - write character to file putlin - write a line to a file prompt - write a line to a teletype; suppress carriage-return/line-feed remark - print single-line message putdec - print integer n in field width >=w seek - move read/write pointer markl - determine file position of next record to be read/written fcopy - copy file in to file out acopy - copy n characters from file1 to file2 fskip - skip n characters on file .sp 1 .ti -7 STRING MANIPULATION scopy - copy string at from(i) to to(j) stcopy - copy string at from(i) to to(j); increment j addset - put c in array(j) if it fits, increment j length - compute length of string index - find character c in string str equal - compare str1 to str2; return YES if equal type - determine type of character alldig - return YES if str is all digits ctoi - convert string at in(i) to integer, increment i itoc - convert integer to character string fold - convert string to lower case clower - convert character to lower case upper - convert string to upper case cupper - convert character to upper case skipbl - skip blanks and tabs at str(i) getwrd - get non-blank word from in(i) into out, increment i .sp 1 .ti -7 ERROR HANDLING error - print error message and stop cant - print 'filename: can't open' and terminate execution .sp 1 .ti -7 MISCELLANEOUS getarg - get command line arguments delarg - delete command line argument 'n' spawn - execute subtask initr4 - initialize all standard files and common variables endr4 - close all open files and terminate program usrbin - pick up name of major utility directory gtime - get current time gdate - get current date #-h- acopy 646 asc 19-may-80 11:02:33 .bp .rm 70 .in 0 .he 'ACOPY'11/13/78'ACOPY' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br acopy - copy n characters from file1 to file2 .sp 1 .ti -7 SYNOPSIS .br call acopy (int1, int2, n) .sp 1 .ti -7 DESCRIPTION .br .bd Acopy copies .bd n characters from one open file to another. Neither file is repositioned before or after the copy. If an EOF is encountered on file1 the copy is terminated. .bd Int1 and .bd int2 are internal identifiers returned by calls to open or create. .sp 1 .ti -7 IMPLEMENTATION .br .bd Acopy simply makes repeated calls to getch and putch. .sp 1 .ti -7 SEE ALSO .br fsize, fskip, fcopy .sp 1 .ti -7 DIAGNOSTICS .br None #-h- addset 592 asc 19-may-80 11:02:35 .bp .rm 70 .in 0 .he 'ADDSET'11/13/78'ADDSET .fo ''-#-'' .fi .in 7 .ti -7 NAME .br addset - put c in array(j) if it fits, increment j .sp 1 .ti -7 SYNOPSIS .br stat = addset(c, array, j, maxsize) .sp 1 .ti -7 DESCRIPTION .br Adds a character at a time to a specified position of an array and increments the index. It also checks that there's enough room to do so. The array is an ascii character array stored one character per word. 'c' is a single ascii character. YES is returned if the routine succeeded, otherwise NO. .sp 1 .ti -7 SEE ALSO .br scopy .sp 1 .ti -7 DIAGNOSTICS .br None #-h- alldig 439 asc 19-may-80 11:02:36 .bp .rm 70 .in 0 .he 'ALLDIG'11/13/78'ALLDIG .fo ''-#-'' .fi .in 7 .ti -7 NAME .br alldig - return YES if string is all digits .sp 1 .ti -7 SYNOPSIS .br stat = alldig(str) .sp 1 .ti -7 DESCRIPTION .br Tests a string to see if it contains only digits. The string is an ascii character array terminated with an EOS marker. Returns YES if string is all digits, otherwise NO. .sp 1 .ti -7 SEE ALSO .br type .sp 1 .ti -7 DIAGNOSTICS .br None #-h- amove 1035 asc 19-may-80 11:02:37 .bp .rm 70 .in 0 .he 'AMOVE'11/10/78'AMOVE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br amove - move (rename) file1 to file2 .sp 1 .ti -7 SYNOPSIS .br call amove (name1, name2) .sp 1 .ti -7 DESCRIPTION .br .bd Amove moves the contents of the file specified by .bd name1 to the file specified by .bd name2. It is essentially a renaming of the file. Both file names are character strings representing pathnames or filenames in whatever format is expected by the local operating system. The names are passed as ascii character arrays terminated with an EOS marker. The files need not be connected to the running program to be renamed. .sp 1 .ti -7 IMPLEMENTATION .br .bd Amove could be easily implemented by opening the first file, creating the second, copying the first to the second, and then removing the first file. Or, if possible, it might be implemented by asking the system to rename the file. .sp 1 .ti -7 SEE ALSO .br fcopy, getlin, putlin .sp 1 .ti -7 DIAGNOSTICS .br A diagnostic is printed if the first file cannot be opened. #-h- cant 485 asc 19-may-80 11:02:39 .bp .rm 70 .in 0 .he 'CANT'11/13/78'CANT .fo ''-#-'' .fi .in 7 .ti -7 NAME .br cant - print 'name: can't open' and terminate execution .sp 1 .ti -7 SYNOPSIS .br call cant(name) .sp 1 .ti -7 DESCRIPTION .br On ERROUT, prints the filename specified by 'name' followed by the message "can't open" and terminates execution. All open files are closed. Name is an ascii character array terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br error, remark .sp 1 .ti -7 DIAGNOSTICS .br None #-h- close 955 asc 19-may-80 11:02:40 .bp .rm 70 .in 0 .he 'CLOSE'11/10/78'CLOSE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br close - close (detach) a file .sp 1 .ti -7 SYNOPSIS .br call close (int) .sp 1 .ti -7 DESCRIPTION .br .bd Close closes the connection between a file and the running program. Any write buffers are flushed and the file is rewound. .sp 1 "Int" is an internal file descriptor as returned from an .bd open or .bd create call. .ti -7 IMPLEMENTATION .br Breaks the connection between the program and a file accessed via .bd open or .bd create. If necessary, the file's write buffer is flushed and the end of the file is marked so that subsequent reads will find an EOF. If a file has been opened multiple times (that is, more than one internal descriptor has been assigned to a file), care is taken that multiple closes will not damage the file. .sp 1 .ti -7 SEE ALSO .br open, create .sp 1 .ti -7 DIAGNOSTICS .br If the file descriptor is in error, the routine simply returns. #-h- clower 362 asc 19-may-80 11:02:42 .bp .rm 70 .in 0 .he 'CLOWER'11/13/78'CLOWER .fo ''-#-'' .fi .in 7 .ti -7 NAME .br clower - fold c to lower case .sp 1 .ti -7 SYNOPSIS .br c = clower(c) .sp 1 .ti -7 DESCRIPTION .br Fold character c to lower case, if not already there. If c is not alphabetic, returns it unchanged. .sp 1 .ti -7 SEE ALSO .br fold, cupper, upper .sp 1 .ti -7 DIAGNOSTICS .br None #-h- create 1425 asc 19-may-80 11:02:43 .bp .rm 70 .in 0 .he 'CREATE'11/10/78'CREATE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br create - create a new file (or overwrite an existing one) .sp 1 .ti -7 SYNOPSIS .br int = create (name, access) .sp 1 .ti -7 DESCRIPTION .br Creates a new file from within a running program and connects the external name of the file to an internal identifier which is then usable in subsequent subroutine calls. If the file already exists, the old version will be overwritten. "name" is a character string representing a pathname or filename in whatever format is used by the local operating system. It may be passed as a quoted string or as an array of ascii characters terminated with an EOS marker. "access" is a descriptor for the type of access desired - READ, WRITE, READWRITE, or APPEND. "int" is returned as a one-word integer internal descriptor to be used by local subroutines whenever referring to the file. .sp 1 .ti -7 IMPLEMENTATION .br .bd Create is similar to .bd open except that .bd create generates a new file. If the file already exists, the old version is removed or truncated and overwritten. All other functions are similar to .bd open. If the file is new, the file type (ASCII or LOCAL) should be set to whichever default you have chosen. .sp 1 .ti -7 SEE ALSO .br open, close .sp 1 .ti -7 DIAGNOSTICS .br The function returns ERR if the file could not be created or if there are already too many files open. #-h- ctoi 810 asc 19-may-80 11:02:45 .bp .rm 70 .in 0 .he 'CTOI'11/13/78'CTOI .fo ''-#-'' .fi .in 7 .ti -7 NAME .br ctoi - convert string at in(i) to integer, increment i .sp 1 .ti -7 SYNOPSIS .br n = ctoi(in, i) .sp 1 .ti -7 DESCRIPTION .br Converts a character string to an integer. Starts looking at position .bd i of .bd in. Plus and minus signs are not allowed. Leading blanks and tabs are ignored; any subsequent digits are converted to the correct numeric value. The first non-digit seen terminates the scan; upon return, .bd i points to this position. .bd n is the value of the integer. The .bd in array is an ascii character array terminated with an EOS marker (or a non-numeric character). Zero is returned if no digits are found. .sp 1 .ti -7 SEE ALSO .br itoc .sp 1 .ti -7 DIAGNOSTICS .br There are no checks for machine overflow. #-h- cupper 388 asc 19-may-80 11:02:46 .bp .rm 70 .in 0 .he 'CUPPER'11/13/78'CUPPER' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br cupper - convert character to upper case .sp 1 .ti -7 SYNOPSIS .br c = cupper(c) .sp 1 .ti -7 DESCRIPTION .br Converts ascii character c to upper case, if not already there. Non-alphabetic characters are returned unchanged. .sp 1 .ti -7 SEE ALSO .br upper, clower, fold .sp 1 .ti -7 DIAGNOSTICS .br None #-h- delarg 643 asc 19-may-80 11:02:48 .bp .rm 70 .in 0 .he 'DELARG'6/5/79'DELARG' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br delarg - delete command line argument number 'n' .sp 1 .ti -7 SYNOPSIS .br call delarg (n) .sp 1 .ti -7 DESCRIPTION .br .bd Delarg deletes reference to the command line argument number 'n' so that subsequent calls to 'getarg' do not see it. .sp 1 .ti -7 IMPLEMENTATION .br .bd Delarg works in conjunction with 'getarg'. It generally re-orders indices to an array holding the command line arguments. 'Delarg' is used only by the shell. .sp 1 .ti -7 SEE ALSO .br getarg, initr4 .sp 1 .ti -7 DIAGNOSTICS .br If argument 'n' does not exist, delarg simply returns. #-h- endr4 655 asc 19-may-80 11:02:49 .bp .rm 70 .in 0 .he 'ENDR4'11/10/78'ENDR4' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br endr4 - close all open files and terminate program .sp 1 .ti -7 SYNOPSIS .br call endr4 .sp 1 .ti -7 DESCRIPTION .br Normally called at the end of any ratfor program or program which uses ratfor primitives. Closes all open files and terminates program execution. .sp 1 .ti -7 IMPLEMENTATION .br Any open files are closed. If any files have been opened multiple times (that is, they have more than one internal descriptor assigned to them), care is taken that multiple closes do not damage the file. .sp 1 .ti -7 SEE ALSO .br close, initr4 .sp 1 .ti -7 DIAGNOSTICS .br None #-h- equal 420 asc 19-may-80 11:02:50 .bp .rm 70 .in 0 .he 'EQUAL'11/13/78'EQUAL' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br equal - compare str1 to str2; return YES if equal .sp 1 .ti -7 SYNOPSIS .br stat = equal(str1, str2) .sp 1 .ti -7 DESCRIPTION .br Compares two strings, returning YES if they are the same, NO if they differ. Each string is an ascii character array terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br .sp 1 .ti -7 DIAGNOSTICS .br None #-h- fcopy 570 asc 19-may-80 11:02:52 .bp .rm 70 .in 0 .he 'FCOPY'11/13/7'FCOPY' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br fcopy - copy file in to file out .sp 1 .ti -7 SYNOPSIS .br call fcopy (in, out) .sp 1 .ti -7 DESCRIPTION .br Assuming that both files are opened, positioned, and ready to go, the routine copies lines from the current file position until an EOF is reached on file 'in'. 'in' and 'out' are file identifiers returned by open or create. .sp 1 .ti -7 IMPLEMENTATION .br 'Fcopy' simply makes repeated calls to getlin and putlin. .sp 1 .ti -7 SEE ALSO .br acopy .sp 1 .ti -7 DIAGNOSTICS .br None #-h- fold 431 asc 19-may-80 11:02:53 .bp .rm 70 .in 0 .he 'FOLD'11/13/78'FOLD' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br fold - convert string to lower case .sp 1 .ti -7 SYNOPSIS .br call fold (str) .sp 1 .ti -7 DESCRIPTION .br Converts the array 'str' to lower case characters. Non-alphabetic characters are left unchanged. The 'str' array is ascii characters terminated by an EOS marker. .sp 1 .ti -7 SEE ALSO .br clower, cupper, upper .sp 1 .ti -7 DIAGNOSTICS .br None #-h- fsize 874 asc 19-may-80 11:02:54 .bp .rm 70 .in 0 .he 'FSIZE'11/13/78'FSIZE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br fsize - determine size of file (in characters) .sp 1 .ti -7 SYNOPSIS .br size = fsize (filename) .sp 1 .ti -7 DESCRIPTION .br .bd Fsize opens the file specified by .bd filename, and determines its size in characters. It then closes the file. NEWLINES are counted as characters. The filename is passed as an ascii character array terminated with an EOS marker. .sp 1 .ti -7 IMPLEMENTATION .br The normal implementation of .bd fsize is to have it count calls to 'getch' before an EOF is encountered. However, some systems provide more efficient ways of determining a file's size. This routine is generally used by the archiver to store a file's size in the archive header. .sp 1 .ti -7 SEE ALSO .br acopy, fskip .sp 1 .ti -7 DIAGNOSTICS .br ERR is returned if the file could not be opened. #-h- fskip 743 asc 19-may-80 11:02:56 .bp .rm 70 .in 0 .he 'FSKIP'11/13/78'FSKIP' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br fskip - skip n characters on file .sp 1 .ti -7 SYNOPSIS .br call skip (int, n) .sp 1 .ti -7 DESCRIPTION .br From the current position in the file specified by .bd int, .bd fskip skips .bd n characters forward. NEWLINES are counted as characters. .sp 1 .ti -7 IMPLEMENTATION .br The most common implementation of .bd fskip is to have it call .bd getch for the appropriate number of times. However, in more congenial systems it may be possible to have the routine skip without reading the intervening data. .bd Fskip is generally used by the archiver to skip over its internal files. .sp 1 .ti -7 SEE ALSO .br acopy, fsize .sp 1 .ti -7 DIAGNOSTICS .br None #-h- gdate 922 asc 19-may-80 11:02:58 .bp .rm 70 .in 0 .he 'GDATE'6/5/79'GDATE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br gdate - get current date .sp 1 .ti -7 SYNOPSIS .br call gdate(date) .sp 1 .ti -7 DESCRIPTION .br 'Gdate' is used to get the current date, which is returned as an ascii character array 'date', terminated with an EOS, in the format: .ce dd-mmm-yy .sp 1 .ti -7 IMPLEMENTATION .br Operating systems generally have some mechanism for picking up the current date. This date should be converted into ascii characters in something similar to the above format. 'Gdate' is used by the archiver to include the date in an archive header (for informational purposes only). It is also used by the 'date' tool. 'Gdate' is not critical to the implementation of the tools and can be left as a stub if the operating system does not allow for its implementation. .sp 1 .ti -7 SEE ALSO .br gtime, 'date' tool, 'ar' tool .sp 1 .ti -7 DIAGNOSTICS .br None #-h- getarg 1916 asc 19-may-80 11:02:59 .bp .rm 70 .in 0 .he 'GETARG'11/10/78'GETARG' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br getarg - get command line arguments .sp 1 .ti -7 SYNOPSIS .br stat = getarg (n, array, maxsize) .sp 1 .ti -7 DESCRIPTION .br 'Getarg' gets command arguments from the command line or control card and copies the "n"th command line argument into the ASCII character array 'array', terminating it with an EOS marker. 'Maxsize' is passed as the maximum number of characters array is prepared to deal with (including the EOS marker); getarg truncates the argument if necessary to fit into the space provided. The number or characters in the argument (not including the EOS marker) is returned in the functional call. If there are less than 'n' arguments, EOF is returned. .sp 1 .ti -7 IMPLEMENTATION .br .sp 1 The implementation of 'getarg' may be quite different on different operating systems. Some systems allow only upper case (or lower case) on the command line; they may limit size; they may not even provide access at all without considerable contortions. When implementing 'getarg', the designer should keep in mind that a 'delarg' will also be needed. One possible design would be to create a routine 'makarg', which would pick up the arguments from the system, convert them to ascii strings, handle any upper-lower case escape conventions, and store them in an array. 'Getarg' could then access this array, stripping off any quoted strings surrounding the arguments, and passing them along to the user. 'Delarg' could also access this array when removing reference to arguments. If it is absolutely impossible to pick up command line arguments from the system, 'makarg' could be taught to prompt the user for them. When the shell is implemented, 'getarg' (or perhaps 'markarg') will have to be altered to read arguments as passed from the shell. .sp 1 .ti -7 SEE ALSO .br initr4, delarg .sp 1 .ti -7 DIAGNOSTICS .br None #-h- getch 1091 asc 19-may-80 11:03:01 .bp .rm 70 .in 0 .he 'GETCH (GETC)'11/10/78'GETCH (GETC) .fo ''-#-'' .fi .in 7 .ti -7 NAME .br getch - read character from file .br getc - read character from standard input .sp 1 .ti -7 SYNOPSIS .br c = getch (c, int) .br c = getc (c) .sp 1 .ti -7 DESCRIPTION .br .bd Getch reads the next character from the file specified by .bd int. .bd Getc reads the next character from the standard input file (STDIN). The character is returned in ascii format both as the functional return and in the parameter .bd c. If the end of a line has been encountered, NEWLINE is returned. If the end of the file has been encountered, EOF is returned. .sp 1 .ti -7 IMPLEMENTATION .br Interspersed calls to .bd getch and .bd getlin work properly. A common implementation is to have .bd getlin work by repeated calls to .bd getch. If the input file is not ascii, characters are mapped into their corresponding ascii format via .bd inmap. .bd Getch is able to recognize an end-of-file marker from either a terminal or a file. .sp 1 .ti -7 SEE ALSO .br getlin, putch, putlin .sp 1 .ti -7 DIAGNOSTICS .br None #-h- getlin 1754 asc 19-may-80 11:03:03 .bp .rm 70 .in 0 .he 'GETLIN'11/10/78'GETLIN' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br getlin - get next line from file .sp 1 .ti -7 SYNOPSIS .br stat = getlin (line, int) .sp 1 .ti -7 DESCRIPTION .br .bd Getlin copies the next line from the file with the internal name .bd int into the character array .bd line. Characters are copied until a NEWLINE marker (end-of-record marker, or whatever method is used to determine an end-of-line by the local operating system) is found or until MAXLINE characters have been copied. A NEWLINE character is returned whenever an end-of-line marker has been sensed. The characters are returned in an ascii character array terminated with an EOS marker (possibly preceded by a NEWLINE character). .bd Getlin returns EOF when it encounters an end-of-file, and otherwise returns the line length (excluding the EOS). Interspersed calls to getlin and getch are allowed and work properly. .sp 1 .ti -7 IMPLEMENTATION .br If the file contains characters in a representation other than ascii, the characters are mapped (via .bd inmap) into their internal ascii representation. Getlin generally assumes a maximum size of the array .bd line passed to it (MAXLINE). If the input line exceeds the limit, no NEWLINE character is returned and the remainder of the line is returned on subsequent calls to .bd getlin. .bd Getlin and .bd getch are compatible; that is, interspersed calls to .bd getlin and .bd getch are allowed and work properly. A common implementation is to have .bd getlin call getch until a NEWLINE character is found (or MAXLINE is reached). .bd Getlin is able to recognize end-of-file marks from both terminals and files. .sp 1 .ti -7 SEE ALSO .br getch, putch, putlin .sp 1 .ti -7 DIAGNOSTICS .br None #-h- gettyp 1710 asc 19-may-80 11:03:05 .bp .rm 70 .in 0 .he 'GETTYP'11/13/78'GETTYP' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br gettyp - get type of file .sp 1 .ti -7 SYNOPSIS .br type = gettyp (int, type) .sp 1 .ti -7 DESCRIPTION .br 'Gettyp' determines whether the file specified by 'int' is ascii characters, local characters (if different from ascii), or binary. The type is returned as ASCII, LOCAL, or BINARY in the functional call and as the parameter 'type'. If the file is empty or new, the default file type (generally ASCII) is returned. .bd Int is passed as the file identifier returned from an open or create call. .sp 1 .ti -7 IMPLEMENTATION .br When a file is opened (via a call to open or create), an internal flag is usually set which specifies the file type. .bd Gettyp then simply reads the flag. The file type may have been determined by locating system information about the file or by actually reading part of it and making a reasonable 'guess'. 'Gettyp' is called by the archiver to store a file's type in the archive header (for informational purposes only). If it is impossible to implement 'gettyp' on a particular system, the call to it in the archiver may simply be left out. The shell also uses 'gettyp' to determine whether a command verb given by the user represents a script file or an executable tool. If the file turns out to be a character (i.e. script) file, the shell then spawns itself with the file as input. Thus, again, if 'gettyp' could not be reliably implemented on a particular system, the user would have to specifically execute her script files by: .ce % sh script ... .sp 1 .ti -7 SEE ALSO .br open .sp 1 .ti -7 DIAGNOSTICS .br ERR is returned if the file descriptor is incorrect. #-h- getwrd 718 asc 19-may-80 11:03:08 .bp .rm 70 .in 0 .he 'GETWRD'11/13/78'GETWRD .fo ''-#-'' .fi .in 7 .ti -7 NAME .br getwrd - get non-blank word from in(i) into out, increment i .sp 1 .ti -7 SYNOPSIS .br size = getwrd(in, i, out) .sp 1 .ti -7 DESCRIPTION .br Starting at position 'i' in array 'in', skips any leading blanks and tabs and returns the next word and its length. A word is any series of characters terminated by a BLANK, TAB, or NEWLINE. The terminator is not returned as part of the word. 'i' is incremented to the position just past the end of the word. The word is returned in array 'out'. Both 'in' and 'out' are ascii character arrays terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br skipbl .sp 1 .ti -7 DIAGNOSTICS .br None #-h- gtime 957 asc 19-may-80 11:03:09 .bp .rm 70 .in 0 .he 'GTIME'6/5/79'GTIME' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br gtime - get current wall-clock time .sp 1 .ti -7 SYNOPSIS .br call gtime(time) .sp 1 .ti -7 DESCRIPTION .br 'Gtime' is used to get the current time, which is returned as an ascii character array 'time', terminated with an EOS, in the format: hh:mm:ss .sp 1 .ti -7 IMPLEMENTATION .br Operating systems generally have some mechanism for picking up the current wall-clock time. This time should be converted into ascii characters in something similar to the above format. 'Gtime' is used by the archiver to include the time in an archive header (for informational purposes only). It is also used by the 'date' tool. 'Gtime' is not critical to the implementation of the tools and can be left as a stub if the operating system does not allow for its implementation. .sp 1 .ti -7 SEE ALSO .br gdate, 'date' tool, 'ar' tool .sp 1 .ti -7 DIAGNOSTICS .br None #-h- index 457 asc 19-may-80 11:03:11 .bp .rm 70 .in 0 .he 'INDEX'11/13/78'INDEX' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br index - find character c in string str .sp 1 .ti -7 SYNOPSIS .br loc = index(str, c) .sp 1 .ti -7 DESCRIPTION .br Returns the index of the first character in 'str' that matches 'c', or zero if 'c' isn't in the array. 'Str' is an ascii character array terminated with an EOS marker. 'c' is a single ascii character. .sp 1 .ti -7 SEE ALSO .br .sp 1 .ti -7 DIAGNOSTICS .br None #-h- initr4 1571 asc 19-may-80 11:03:12 .bp .rm 70 .in 0 .he 'INITR4'11/10/78'INITR4' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br initr4 - initialize all standard files and common variables needed for the ratfor primitives .sp 1 .ti -7 SYNOPSIS .br call initr4 .sp 1 .ti -7 DESCRIPTION .br This routine is generally the first routine called by any program desiring to use the ratfor primitives. It opens STDIN, STDOUT, and ERROUT files, performing any file substitutions necessary. It also prepares the list of arguments needed by .bd getarg and sets up any buffers, variables, etc. needed by the ratfor primitives. .sp 1 .ti -7 IMPLEMENTATION .br 'Initr4' initializes any common blocks, variables, buffers, arrays, or whatever is necessary to allow the other ratfor primitives to operate. It may also have to retrieve (via 'makarg') the list of command arguments passed to the program, if this is not automatically available from the operating system. 'Initr4' is also responsible for parsing the command line to determine if there have been any file substitutions for STDIN, STDOUT, or ERROUT. The appropriate files (either the user's terminal or the substitutions) are then opened and properly positioned. Arrangements are made so that 'getarg' won't pick up standard file substitution flags on subsequent calls (probably by a call to 'delarg'). .sp 1 .ti -7 SEE ALSO .br endr4, getarg, delarg, termin, trmout .sp 1 .ti -7 DIAGNOSTICS .br If .bd initr4 cannot function for some reason, the program generally aborts (possibly without an error message since standard output files may not have been opened). #-h- itoc 554 asc 19-may-80 11:03:14 .bp .rm 70 .in 0 .he 'ITOC'11/13/78'ITOC' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br itoc - convert integer to character string .sp 1 .ti -7 SYNOPSIS .br length = itoc(int, str, size) .sp 1 .ti -7 DESCRIPTION .br Converts an integer 'int' to characters in array 'str', which is at most 'size' characters long. 'length' is returned as the number of characters the integer took, not including the EOS marker. Characters are stored in ascii character arrays terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br ctoi, putdec .sp 1 .ti -7 DIAGNOSTICS .br None #-h- length 381 asc 19-may-80 11:03:15 .bp .rm 70 .in 0 .he 'LENGTH'11/13/78'LENGTH' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br length - compute length of string .sp 1 .ti -7 SYNOPSIS .br n = length(str) .sp 1 .ti -7 DESCRIPTION .br Computes the length of a character string, excluding the EOS. The string is an ascii character array terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br .sp 1 .ti -7 DIAGNOSTICS .br None #-h- markl 1085 asc 19-may-80 11:03:17 .bp .rm 70 .in 0 .he 'MARKL'11/13/78'MARKL' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br markl - determine file position of next record to be read/written .sp 1 .ti -7 SYNOPSIS .br call markl(int, offset) .sp 1 .ti -7 DESCRIPTION .br .bd Markl works in conjunction with .bd seek. Markl is used to pick up the file position of the next record to be read/written on the file. It is usually used as the file is being written, picking up the pointer to the end of the file before each record is inserted there. .bd Offset is a two-word integer in which is stored a character count, word address, block and record address, or whatever is appropriate for the operating system in use. .bd Offset should be retained (untouched) by the user and passed to .bd seek when access to the record is desired. .sp 1 .ti -7 IMPLEMENTATION .br .bd Markl is compatible with whatever implementation is chosen for .bd seek and the opening of files at READWRITE access. In the editor, markl is called to locate the end of file for subsequent writes. .sp 1 .ti -7 SEE ALSO .br seek .sp 1 .ti -7 DIAGNOSTICS .br None #-h- open 2683 asc 19-may-80 11:03:18 .bp .rm 70 .in 0 .he 'OPEN'11/10/78'OPEN' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br open - open an existing file for reading, writing, or both .sp 1 .ti -7 SYNOPSIS .br int = open (name, access) .sp 1 .ti -7 DESCRIPTION .br .bd Open attaches an existing file to a running program and associates the external file name with an internal identifier which is then usable by the program. The file is positioned at the beginning. Opening a fresh instance of an already open file is permissible. "name" is a character string representing a pathname or filename in whatever format is used by the local operating system. Name is passed as an array of ascii characters terminated with an EOS marker. "access" is a descriptor for the type of access desired - READ, WRITE, READWRITE, or APPEND. "int" is returned as an integer descriptor to be used by local subroutines whenever referring to the file. The file is positioned at the beginning unless APPEND access is requested, in which case the file is prepared for extension. .sp 1 .ti -7 IMPLEMENTATION .br .bd Open connects the file to the running program and does what manipulations are necessary to allow reading and/or writing to the file. An internal descriptor (usually an integer) is assigned to the file and subsequently used when calling other primitives such as close, getch, putch, getlin, and putlin. .bd Open may have to set up an internal io buffer for the file. It may also have to do an initial read to determine the file type (character or binary). Information about the file's type and teletype characteristics (yes or no) is generally maintained. This information is then made available to the user via the .bd tty and .bd gettyp functions. .bd Open is generally taught to read characters of ascii type as well as local character type (if not ascii). Translation of characters from local to ascii is done when the characters are passed to .bd getch and .bd getlin. Opening a fresh instance of an already opened file is permissible and does not affect the position of the file as accessed by subsequent or previous calls. There is generally a limit to the maximum number of files open at any one time. None of the tools require more than 6. READWRITE access may cause problems. The only tool which needs this access is the editor. If necessary you may have to implement it by opening the file twice--once at read and once at write access. .sp 1 .ti -7 SEE ALSO .br create, close, remove .sp 1 .ti -7 DIAGNOSTICS .br Open returns ERR if the file does not exist, if one of the necessary directories (if any) does not exist or is unreadable, if the file is not readable/writeable, or if too many files are open. #-h- prompt 950 asc 19-may-80 11:03:21 .bp .rm 70 .in 0 .he 'PROMPT'6/5/79'PROMPT' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br PROMPT - output a line onto a teletype; suppress line feed/carriage return .sp 1 .ti -7 SYNOPSIS .br call prompt (line, int) .sp 1 .ti -7 DESCRIPTION .br Prompt outputs the character array 'line' onto the file specified by 'int'. The carriage return/line-feed sequence is suppressed so the line actually appears as a prompt, much like the shell's '%' prompt. No NEWLINE character is necessary to cause the buffer to be flushed. If one appears, the carriage-return/line-feed sequence will be restored. If the file specified by 'int' is not a teletype-like device, no I/O is done. .sp 1 .ti -7 IMPLEMENTATION .br Implemented much like 'putlin' and 'remark', except the file is checked via 'tty' to make sure it is a teletype device and the carriage-return/line-feed sequence is suppressed. .sp 1 .ti -7 SEE ALSO .br putlin, remark .sp 1 .ti -7 DIAGNOSTICS .br None #-h- putch 1015 asc 19-may-80 11:03:23 .bp .rm 70 .in 0 .he 'PUTCH (PUTC)'11/10/78'PUTCH (PUTC)' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br putch - write character to file .br putc - write character to standard output .sp 1 .ti -7 SYNOPSIS .br call putch (c, int) .br call putc (c) .sp 1 .ti -7 DESCRIPTION .br .bd Putch writes the character .bd c onto the file specified by .bd int. .bd Putc writes the character onto the standard output file (STDOUT). If .bd c is the NEWLINE character, the appropriate action is taken to indicate the end of the record on the file. The character is assumed to be in ascii format; however, if the output file is not of ascii type, the necessary conversion is done. .sp 1 .ti -7 IMPLEMENTATION .br Interspersed calls to .bd putch and .bd putlin work properly. One implementation is to have .bd putlin perform repeated calls to .bd putch. If the output file is not ascii, characters are mapped into their corresponding format via .bd outmap. .sp 1 .ti -7 SEE ALSO .br putlin, getch, getlin .sp 1 .ti -7 DIAGNOSTICS .br None #-h- putdec 546 asc 19-may-80 11:03:24 .bp .rm 70 .in 0 .he 'PUTDEC'11/13/78'PUTDEC' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br putdec - write integer n in field width >=w .sp 1 .ti -7 SYNOPSIS .br call putdec(n, w) .sp 1 .ti -7 DESCRIPTION .br This routine writes onto the standard output the number 'n' as a string of at least 'w' characters, including a sign if 'n' is negative. If fewer than 'w' characters are needed, blanks are inserted to the left to make up the count; if more than 'w' are needed, more are provided. .sp 1 .ti -7 SEE ALSO .br itoc .sp 1 .ti -7 DIAGNOSTICS .br None #-h- putlin 1684 asc 19-may-80 11:03:26 .bp .rm 70 .in 0 .he 'PUTLIN'11/10/78'PUTLIN' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br putlin - output a line onto a given file .sp 1 .ti -7 SYNOPSIS .br call putlin (line, int) .sp 1 .ti -7 DESCRIPTION .br Outputs the character array .bd line onto the file specified by .bd int. The line array is generally an ascii character array terminated with an EOS marker. NEWLINE characters are permitted. If none is given, no carriage return (or end-of-record) is assumed. The line array may also be a quoted string (as generated by the ratfor quoted-string capability). Any necessary character translation is done if the output file is not of ascii type. .sp 1 .ti -7 IMPLEMENTATION .br Handling quoted (i.e. hollerith) strings may cause some problems since it is difficult to locate the end of the string on some systems. Some installations allow Fortran formatting (nL... or nH...) which terminates the string with zeroes. Another possibility would be to have the ratfor compiler terminate all quoted strings with a '.'. If a quoted string has been passed, .bd putlin only sends a NEWLINE marker to the file if one has been included in the quoted string (possibly by some sort of convention such as "@n"). If the output file is to contain characters in a representation other than ascii, the characters are mapped (via .bd outmap) into their proper representation. .bd Putlin and .bd putch are compatible; that is, interspersed calls to .bd putlin and .bd putch are allowed and work properly. A common implementation is to have .bd putlin call .bd putch until an EOS marker is found. .sp 1 .ti -7 SEE ALSO .br putch, prompt, remark, getch, getlin .sp 1 .ti -7 DIAGNOSTICS .br None #-h- remark 1247 asc 19-may-80 11:03:28 .bp .rm 70 .in 0 .he 'REMARK'11/13/78'REMARK' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br remark - print single-line message .sp 1 .ti -7 SYNOPSIS .br call remark (message) .sp 1 .ti -7 DESCRIPTION .br .bd Remark writes the message onto the standard error file ERROUT. A NEWLINE is always generated, even though one may not appear in the message. The message array is generally a Fortran hollerith string in the format generated by the Ratfor quoted string capability. It may also be an ascii character array terminated with an EOS marker. .sp 1 .ti -7 IMPLEMENTATION .br .bd Remark is very similar to .bd error except it returns after printing, instead of stopping. It is also similar to .bd putlin except it guarantees that a newline character is generated after the line is printed. A common way to implement .bd remark is to have it call .bd putlin with the message and then have it call .bd putch with a newline character to generate the necessary new line. The handling of the Fortran hollerith string is done in whatever manner was decided upon by the ratfor implementor. It may be necessary to terminate the string with a '.' or other end-of-string marker. .sp 1 .ti -7 SEE ALSO .br error, putlin, prompt .sp 1 .ti -7 DIAGNOSTICS .br None #-h- remove 779 asc 19-may-80 11:03:30 .bp .in 0 .in 0 .rm 70 .he 'REMOVE'11/10/78'REMOVE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br remove - remove a file from the file system .sp 1 .ti -7 SYNOPSIS .br call remove (filename) .sp 1 .ti -7 DESCRIPTION .br From within a running program, remove a file from the file system. "filename" is a character string representing a pathname or filename in whatever format is used by the local operating system. It is passed as an ascii character array terminated with an EOS marker. .sp 1 .ti -7 IMPLEMENTATION .br The file to be removed need not be connected to the running program. However, if it is, .bd remove closes the file before removing it. .sp 1 .ti -7 SEE ALSO .br open, close, create .sp 1 .ti -7 DIAGNOSTICS .br If the file does not exist the routine simply returns. #-h- scopy 373 asc 19-may-80 11:03:31 .bp .rm 70 .in 0 .he 'SCOPY'11/13/78'SCOPY' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br scopy - copy string at from(i) to to(j) .sp 1 .ti -7 SYNOPSIS .br call scopy(from, i, to, j) .sp 1 .ti -7 DESCRIPTION .br Copies the (sub)string of 'from', starting in location 'i', into array 'to', starting at 'j'. .sp 1 .ti -7 SEE ALSO .br stcopy, addset .sp 1 .ti -7 DIAGNOSTICS .br None #-h- scratf 1557 asc 19-may-80 11:03:33 .bp .rm 70 .in 0 .he 'SCRATF'6/5/79'SCRATF' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br scratf - get scratch file name based on 'seed' .sp 1 .ti -7 SYNOPSIS .br call scratf (seed, name) .sp 1 .ti -7 DESCRIPTION .br 'Scratf' is used to generate scratch file names. 'Seed' is passed as an array generally containing one to three characters to be used in generating the scratch file name. 'Name' is returned as a scratch file name to pass to an 'open' or 'create' call. It should contain some sort of process name or identifier so that the name produced is unique to the process creating it. It may also contain a specific scratch file directory identifier. .sp 1 .ti -7 IMPLEMENTATION .br 'Scratf' is used to avoid conflicts which occur when more than one user is logged in under a single user or directory name. The optimum implementation would be to return an absolutely unique file name based on 'seed'. However, on most systems this is impossible. Another solution would be to append (or prepend) some sort of process identifier to 'seed', thus making the file name at least unique to the calling process. To avoid privilege violations it might also be necessary to choose a specific directory for all scratch files, with appropriate privileges being assigned to it. On single-user systems, systems with local files, or other circumstances where unique file names are not a problem, 'scratf' can simply return the 'seed' as 'name'. .sp 1 .ti -7 SEE ALSO .br .sp 1 .ti -7 DIAGNOSTICS .br If the file name could not be generated a message should be printed. #-h- seek 1422 asc 19-may-80 11:03:35 .bp .rm 70 .in 0 .he 'SEEK'11/13/78'SEEK' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br seek - move read/write pointer .sp 1 .ti -7 SYNOPSIS .br call seek (offset, int) .sp 1 .ti -7 DESCRIPTION .br .bd Seek positions the file specified by .bd int for a subsequent read beginning at .bd offset. The offset is a 2-word array containing information in terms of characters, words, records, block numbers, lines, or whatever is appropriate for the operating system. .bd Offset is originally obtained by a call to .bd markl. Once the file is positioned by a call to .bd seek, reading can be done using the standard I/O calls (getch, getlin). .bd Seek can also be used for seeking to the end of a file and performing a write (thus extending the file). Rewriting in place is generally not allowed. .sp 1 .ti -7 IMPLEMENTATION .br .bd Seek depends heavily upon the peculiarities of the operating system. It can generally be used on files opened at READWRITE access. The offset units are chosen to be whatever is most appropriate for the system involved. On some systems READWRITE access may have to be implemented by opening the file twice, once at READ and once at WRITE access. 'Seek' is used only by the editor. Hopefully it can be made compatible with the standard reading and writing routines. If not, the routine 'readf' in the editor will have to be adjusted. .sp 1 .ti -7 SEE ALSO .br markl .sp 1 .ti -7 DIAGNOSTICS .br None #-h- skipbl 417 asc 19-may-80 11:03:37 .bp .rm 70 .in 0 .he 'SKIPBL'11/13/78'SKIPBL' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br skipbl - skip blanks and tabs at str(i) .sp 1 .ti -7 SYNOPSIS .br call skipbl(str, i) .sp 1 .ti -7 DESCRIPTION .br Starting at position 'i' of array 'str', increments i while str(i) is a BLANK or TAB. 'Str' is an ascii character array terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br getwrd .sp 1 .ti -7 DIAGNOSTICS .br None #-h- spawn 3002 asc 19-may-80 11:03:38 .bp .rm 70 .in 0 .he 'SPAWN'11/13/78'SPAWN' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br spawn - execute subtask .sp 1 .ti -7 SYNOPSIS .br stat = spawn(command, args, desc, waitflg) .sp 1 .ti -7 DESCRIPTION .br .bd Spawn is called to cause execution of a subtask. 'command' is an ascii character array giving the (file)name of the task to be executed, in whatever format is needed by the operating system. 'Args' is an ascii character array giving the command line arguments to be passed to the subtask. The arguments are separated by blanks and the entire string is terminated with an EOS marker. 'Desc' is returned as a character array containing an ID for the spawned subtask. This ID may be passed to the 'pstat', 'suspnd', 'resume', and 'kill' process control tools. 'Waitflg' is a flag indicating whether or not spawn should return before execution of the task is completed. If WAIT is passed, spawn does not return until execution of the task has completed. If NOWAIT is passed, spawn begins execution of the task and immediately returns (for use with real pipes). If BACKGROUND is passed, spawn executes the task as a background process and immediately returns. If a variable is used for waitflg, it must be declared of type character. If the task cannot be executed, spawn returns ERR; otherwise it returns OK. Spawned tasks must be properly taught to read their command line arguments in whatever manner spawn sends them. .sp 1 .ti -7 IMPLEMENTATION .br Spawn is, by far, the most difficult primitive to implement. A few of the major obstacles which must be overcome are: .sp .in +5 .ti -3 1. Does the target operating system permit a running process to spawn a subprocess? If it provides a multi-user, interactive environment, it most certainly does, but it may not be common knowledge as to how to do it. For example, the following DEC implementations have been done by the LBL group: .sp .in +5 .ti -3 a) RSX11M - a loadable pseudo-driver is used to stuff MCR commands into MCR's queue, via qio requests. .sp .ti -3 b) IAS - the TCS macros provided by the operating system for custom CLI construction are used. The only interface is from assembly language, so that is the language used. .sp .ti -3 c) VMS - the sys$creprc system service, which is callable from any supported language, is used. In fact, the entire spawn primitive is written in ratfor. .sp .in -5 .ti -3 2. Once one has determined how to spawn the process, it is necessary to determine how to control it. If the operating system does not provide any synchronization methods, then they must be implemented. .sp .ti -3 3. Finally, one must determine how to communicate the arguments and environment information to the subprocess. This generally entails an exploration of the system provided interprocess-communication mechanisms, and often requires the invention of better ones. .sp .in -5 .sp 1 .ti -7 SEE ALSO .br .sp 1 .ti -7 DIAGNOSTICS .br A message 'Cannot spawn process' is printed if that situation occurs. #-h- stcopy 545 asc 19-may-80 11:03:41 .bp .rm 70 .in 0 .he 'STCOPY'6/6/79'STCOPY' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br stcopy - copy string at from(i) to to(j); increment j .sp 1 .ti -7 SYNOPSIS .br call stcopy(from, i, to, j) .sp 1 .ti -7 DESCRIPTION .br Copies the (sub)string of 'from', starting in location 'i', into array 'to', starting at 'j'. 'j' is incremented to point to the next available position in 'to' (i.e. the EOS marker inserted by the copy). In all other respects, 'stcopy' is similar to 'scopy'. .sp 1 .ti -7 SEE ALSO .br scopy .sp 1 .ti -7 DIAGNOSTICS .br None #-h- symbols 4130 asc 19-may-80 11:03:43 .he //Ratfor symbols/ .bp ##################################################################### # # General symbol definitions ##################################################################### # General definitions for the software tools # Should be put on a file named 'symbols' define(ALPHA,-9) define(ASCII,12) # flag for ascii-type file define(AMPER,38) # ampersand define(AND,38) # same as ampersand define(APPEND,4) define(ARB,100) define(ATSIGN,64) define(BACKSLASH,92) define(BACKSPACE,8) define(BANG,33) # exclamation mark define(BAR,124) define(BIGA,65) define(BIGB,66) define(BIGC,67) define(BIGD,68) define(BIGE,69) define(BIGF,70) define(BIGG,71) define(BIGH,72) define(BIGI,73) define(BIGJ,74) define(BIGK,75) define(BIGL,76) define(BIGM,77) define(BIGN,78) define(BIGO,79) define(BIGP,80) define(BIGQ,81) define(BIGR,82) define(BIGS,83) define(BIGT,84) define(BIGU,85) define(BIGV,86) define(BIGW,87) define(BIGX,88) define(BIGY,89) define(BIGZ,90) define(BINARY,60) #flag for binary file define(BLANK,32) define(CARET,94) define(COLON,58) define(COMMA,44) define(DASH,45) #same as MINUS define(DIG0,48) define(DIG1,49) define(DIG2,50) define(DIG3,51) define(DIG4,52) define(DIG5,53) define(DIG6,54) define(DIG7,55) define(DIG8,56) define(DIG9,57) define(DIGIT,2) define(DOLLAR,36) define(DQUOTE,34) define(EOF,-1) define(EOR,-973) define(EOS,0) define(EQUALS,61) define(ERR,-3) define(ERROUT,3) #standard error file define(ESCAPE,ATSIGN) #escape character for ch, find, tr, ed define(FILENAMESIZE,40) #max characters in file name (includes EOS) define(GREATER,62) define(LBRACE,123) define(LBRACK,91) define(LESS,60) define(LETA,97) define(LETB,98) define(LETC,99) define(LETD,100) define(LETE,101) define(LETF,102) define(LETG,103) define(LETH,104) define(LETI,105) define(LETJ,106) define(LETK,107) define(LETL,108) define(LETM,109) define(LETN,110) define(LETO,111) define(LETP,112) define(LETQ,113) define(LETR,114) define(LETS,115) define(LETT,116) define(LETTER,1) define(LETU,117) define(LETV,118) define(LETW,119) define(LETX,120) define(LETY,121) define(LETZ,122) define(LPAREN,40) define(LOCAL,6) # flag for local-type character files define(MAXARGS,20) define(MAXCARD,399) define(MAXLINE,400) define(MINUS,45) define(NCHARS,33) # number of special characters define(NEWLINE,10) define(NO,0) define(NOT, BANG) define(OK,0) # success flag define(OR,BAR) define(PATH,5) # not local file spec == LOCAL - 1 define(PERCENT,37) define(PERIOD,46) define(PLUS,43) define(QMARK,63) define(RBRACE,125) define(RBRACK,93) define(READ,1) # flag to open file at read access define(READWRITE,3) #flag to open file at read/write access define(RPAREN,41) define(SEMICOL,59) define(SHARP,35) define(SLASH,47) define(STDIN,1) #standard input file define(STDOUT,2) #standard output file define(SQUOTE,39) define(STAR,42) define(TAB,9) define(TILDE,126) define(UNDERLINE,95) define(WRITE,2) # flag to open file at write access define(YES,1) define(character,logical*1) define(linepointer,integer*4) define(NULLPOINTER,0) define(andif,if) define(abs,iabs) #NOTIAS #NOTVMS define(max,max0) #NOTIAS #NOTVMS define(min,min0) #NOTIAS #NOTVMS define(termnl,gtty) define(termin,gtty) define(trmout,gtty) define(TERMINAL,'TI:') # Process control definitions define(PIDSIZE,7) #Size of process ID field define(ARGBUFSIZE,256) define(WAIT,LETW) define(NOWAIT,LETN) define(BACKGR,LETB) define(spawn,sspawn) # rawmode io definitions define(COOKED,0) # processed characters define(RAW,1) # raw characters #end sym #-h- termin 686 asc 19-may-80 11:03:46 .bp .rm 70 .in 0 .he 'TERMIN'6/5/79'TERMIN' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br termin - pick up identifier of read channel to users terminal .sp 1 .ti -7 SYNOPSIS .br call termin(name) .sp 1 .ti -7 DESCRIPTION .br 'Termin' is used to get the name of the user's terminal so that a channel to it can be opened (via an 'open' call) for reading. .sp 1 .ti -7 IMPLEMENTATION .br Most systems have a standard file name associated with a user's terminal. This routine is used by initr4 to open STDIN, as well as by the roff tool, the form tool, and the label tool to open a line to the user's terminal for reading. .sp 1 .ti -7 SEE ALSO .br trmout, initr4 .sp 1 .ti -7 DIAGNOSTICS .br None #-h- trmout 666 asc 19-may-80 11:03:48 .bp .rm 70 .in 0 .he 'TRMOUT'6/5/79'TRMOUT' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br trmout - pick up identifier of write channel to users terminal .sp 1 .ti -7 SYNOPSIS .br call trmout(name) .sp 1 .ti -7 DESCRIPTION .br 'Trmout' is used to get the name of the user's terminal so that a channel to it can be opened (via an 'open' call) for writing. .sp 1 .ti -7 IMPLEMENTATION .br Most systems have a standard file name associated with a user's terminal. This routine is used by initr4 to open STDOUT and ERROUT, and by the shell, the form tool, and several other tools for prompting the user. .sp 1 .ti -7 SEE ALSO .br termin, initr4 .sp 1 .ti -7 DIAGNOSTICS .br None #-h- tty 823 asc 19-may-80 11:03:49 .bp .rm 70 .in 0 .he 'TTY'11/13/78'TTY .fo ''-#-'' .fi .in 7 .ti -7 NAME .br tty - determine if file is a teletype/CRT device .sp 1 .ti -7 SYNOPSIS .br stat = tty(int) .sp 1 .ti -7 DESCRIPTION .br This function returns YES if the file specified by 'int' is a teletype-like device, otherwise it returns NO. 'Int' is a file identifier returned by a call to open or create. .sp 1 .ti -7 IMPLEMENTATION .br When a file is opened, a flag is usually set indicating what device the file is associated with. This function generally reads that flag. Other implementations are possible, depending upon the operating system involved. 'Tty' is generally used by the tools to determine whether they should issue prompts or not. .sp 1 .ti -7 SEE ALSO .br open, create .sp 1 .ti -7 DIAGNOSTICS .br NO is returned if 'int' is in error. #-h- type 392 asc 19-may-80 11:03:51 .bp .rm 70 .in 0 .he 'TYPE'11/13/78'TYPE' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br type - determine type of character .sp 1 .ti -7 SYNOPSIS .br t = type(c) .sp 1 .ti -7 DESCRIPTION .br This function determines whether the character 'c' is a letter, a digit, or something else; it returns LETTER, DIGIT, or the character itself. .sp 1 .ti -7 SEE ALSO .br alldig .sp 1 .ti -7 DIAGNOSTICS .br None #-h- upper 462 asc 19-may-80 11:03:52 .bp .rm 70 .in 0 .he 'UPPER'11/13/78'UPPER' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br upper - convert string to upper case .sp 1 .ti -7 SYNOPSIS .br call upper(str) .sp 1 .ti -7 DESCRIPTION .br Converts the array 'str' to upper case, if not already there. If any characters are non-alphabetic, it leaves them unchanged. 'Str' is an ascii character array terminated with an EOS marker. .sp 1 .ti -7 SEE ALSO .br cupper, fold, clower .sp 1 .ti -7 DIAGNOSTICS .br None #-h- usrbin 903 asc 19-may-80 11:03:53 .bp .rm 70 .in 0 .he 'USRBIN'6/5/79'USRBIN' .fo ''-#-'' .fi .in 7 .ti -7 NAME .br usrbin - get name of /usr/bin (major tools utility directory) .sp 1 .ti -7 SYNOPSIS .br call usrbin (name) .sp 1 .ti -7 DESCRIPTION .br 'Usrbin' returns the name of the directory where all the tools utilities reside. .sp 1 .ti -7 IMPLEMENTATION .br It is most advantageous to put all the software tools in a single place for easy access by a multitude of users. The location of this directory may then be determined by calling 'usrbin'. 'Usrbin' is used by the ratfor preprocessor to find the location of the symbols file which it automatically opens for each user. It is also called by the shell to identify the directory to search when locating command names. On single-user or other systems without directory structures this routine may be a no-op. .sp 1 .ti -7 SEE ALSO .br .sp 1 .ti -7 DIAGNOSTICS .br None #-h- index3 8920 asc 19-may-80 11:03:56 .bp .in 0 .nf .he ''Permuted (kwic) Index'' to file2 aaacccooopppyyy - copy n characters from file1 fits, increment j aaaddddddssseeettt - put c in array(j) if it digits aaalllllldddiiiggg - return YES if str is all aaammmooovvveee - move (rename) file1 to file2 gggeeetttaaarrrggg - get command line arguments assign it to a specified 'int' aaassssssiiigggnnn - open/create a file and ssskkkiiipppbbblll - skip blanks and tabs at str(i) and terminate execution cccaaannnttt - print 'filename: can't open' ccclllooowwweeerrr - convert character to lower case cccuuuppppppeeerrr - convert character to upper case fffooolllddd - convert string to lower case uuuppppppeeerrr - convert string to upper case iiinnndddeeexxx - find character c in string str gggeeetttccchhh - read character from file iiitttoooccc - convert integer to character string pppuuutttccchhh - write character to file ccclllooowwweeerrr - convert character to lower case cccuuuppppppeeerrr - convert character to upper case tttyyypppeee - determine type of character aaacccooopppyyy - copy n characters from file1 to file2 fffsssiiizzzeee - determine number characters in file fffssskkkiiippp - skip n characters on file ccclllooossseee - close (detach) a file program eeennndddrrr444 - close all open files and terminate case ccclllooowwweeerrr - convert character to lower gggeeetttaaarrrggg - get command line arguments - initialize all standard files and common variables iiinnniiitttrrr444 equal eeeqqquuuaaalll - compare str1 to str2; return YES if ccclllooowwweeerrr - convert character to lower case cccuuuppppppeeerrr - convert character to upper case iiitttoooccc - convert integer to character string increment i ccctttoooiii - convert string at in(i) to integer, fffooolllddd - convert string to lower case uuuppppppeeerrr - convert string to upper case fffcccooopppyyy - copy file in to file out aaacccooopppyyy - copy n characters from file1 to file2 ssscccooopppyyy - copy string at from(i) to to(j) overwrite an existing one) cccrrreeeaaattteee - create a new file (or specified 'int' aaassssssiiigggnnn - open/ create a file and assign it to a ttttttyyy - determine if file is a teletype/ crt device integer, increment i ccctttoooiii - convert string at in(i) to case cccuuuppppppeeerrr - convert character to upper - determine if file is a teletype/crt device ttttttyyy aaalllllldddiiiggg - return YES if str is all digits terminate program eeennndddrrr444 - close all open files and YES if equal eeeqqquuuaaalll - compare str1 to str2; return eeerrrrrrooorrr - print error message and stop ssspppaaawwwnnn - execute subtask fffcccooopppyyy - copy file in to file out fffooolllddd - convert string to lower case characters in file fffsssiiizzzeee - determine number of fffssskkkiiippp - skip n characters on file gggeeetttaaarrrggg - get command line arguments gggeeetttccchhh - read character from file gggeeetttllliiinnn - read next line from file gggeeettttttyyyppp - get type of file in(i) into out, increment i gggeeetttwwwrrrddd - get non-blank word from str iiinnndddeeexxx - find character c in string files and common variables iiinnniiitttrrr444 - initialize all standard string iiitttoooccc - convert integer to character llleeennngggttthhh - compute length of string ccclllooowwweeerrr - convert character to lower case fffooolllddd - convert string to lower case next record to be read/written mmmaaarrrkkklll - determine file position of rrreeemmmaaarrrkkk - print single-line message aaammmooovvveee - move (rename) file1 to file2 ssseeeeeekkk - move read/write pointer reading, writing, or both ooopppeeennn - open an existing file for ssseeeeeekkk - move read/write pointer read/written mmmaaarrrkkklll - determine file position of next record to be eeerrrrrrooorrr - print error message and stop pppuuutttdddeeeccc - print integer n in field width >=w rrreeemmmaaarrrkkk - print single-line message increment j aaaddddddssseeettt - put c in array(j) if it fits, pppuuutttccchhh - write character to file width >=w pppuuutttdddeeeccc - print integer n in field pppuuutttllliiinnn - write a line to a file gggeeetttccchhh - read character from file gggeeetttllliiinnn - read next line from file ssseeeeeekkk - move read/write pointer rrreeemmmaaarrrkkk - print single-line message system rrreeemmmooovvveee - remove a file from the file aaammmooovvveee - move (rename) file1 to file2 to(j) ssscccooopppyyy - copy string at from(i) to ssseeeeeekkk - move read/write pointer ssskkkiiipppbbblll - skip blanks and tabs at str(i) fffssskkkiiippp - skip n characters on file str(i) ssskkkiiipppbbblll - skip blanks and tabs at ssspppaaawwwnnn - execute subtask ssspppaaawwwnnn - execute subtask ssskkkiiipppbbblll - skip blanks and tabs at str(i) ttttttyyy - determine if file is a teletype/CRT device teletype/CRT device ttttttyyy - determine if file is a tttyyypppeee - determine type of character gggeeettttttyyyppp - get type of file uuuppppppeeerrr - convert string to upper case pppuuutttllliiinnn - write a line to a file pppuuutttccchhh - write character to file ssseeeeeekkk - move read/ write pointer - open an existing file for reading, writing, or both ooopppeeennn .fi