From 93341be3963fde93c3392ae470ed68a8d7733905 Mon Sep 17 00:00:00 2001 From: Alhadis Date: Thu, 21 Jul 2016 08:41:05 +1000 Subject: [PATCH] Add language definition and samples for RUNOFF --- lib/linguist/languages.yml | 9 + samples/Groff/refs.rno | 35 + samples/RUNOFF/VMS_ZIP.RNH | 1467 ++++++ samples/RUNOFF/contributing.rnh | 324 ++ samples/RUNOFF/longlib.rno | 8644 +++++++++++++++++++++++++++++++ samples/RUNOFF/mcp_help.rnh | 1773 +++++++ 6 files changed, 12252 insertions(+) create mode 100644 samples/Groff/refs.rno create mode 100644 samples/RUNOFF/VMS_ZIP.RNH create mode 100644 samples/RUNOFF/contributing.rnh create mode 100644 samples/RUNOFF/longlib.rno create mode 100644 samples/RUNOFF/mcp_help.rnh diff --git a/lib/linguist/languages.yml b/lib/linguist/languages.yml index d3f50d9f..392e2e53 100755 --- a/lib/linguist/languages.yml +++ b/lib/linguist/languages.yml @@ -3154,6 +3154,15 @@ RMarkdown: - .rmd tm_scope: source.gfm +RUNOFF: + type: markup + color: "#665a4e" + extensions: + - .rnh + - .rno + tm_scope: text.runoff + ace_mode: text + Racket: type: programming color: "#22228f" diff --git a/samples/Groff/refs.rno b/samples/Groff/refs.rno new file mode 100644 index 00000000..451ff5fa --- /dev/null +++ b/samples/Groff/refs.rno @@ -0,0 +1,35 @@ +.\" Copyright (c) 1980 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)refs.rno 6.1 (Berkeley) 4/29/86 +.\" +.NS 1 "References" +.sp +.ip "[Bac78]" +John Backus, \*(lqCan Programming Be Liberated from the von Neumann Style? +A Functional Style and Its Algebra of Programs,\*(rq \fICACM\fP, Turing +Award Lecture, 21, 8 (August 1978), 613-641. +.sp 6p +.ip "[Fod80]" +John K. Foderaro, \*(lqThe \s-2FRANZ LISP\s+2 +Manual,\*(rq University of California, +Berkeley, California, 1980. +.sp 6p +.ip "[Joy79]" +W.N. Joy, O. Babaoglu, \*(lqUNIX Programmer's Manual,\*(rq November 7, +1979, Computer Science Division, University of California, Berkeley, +California. +.sp 6p +.ip "[Mc60]" +J. McCarthy, \*(lqRecursive Functions of Symbolic expressions and their +Computation by Machine,\*(rq Part I, \fICACM\fP 3, 4 (April 1960), 184-195. +.sp 6p +.ip "[Pat80]" +Dorab Ratan Patel, \*(lqA System Organization for Applicative Programming,\*(rq +M.S Thesis, University of California, Los Angeles, California, 1980. +.sp 6p +.ip "[Pat81]" +Dorab Patel, \*(lqFunctional Language Interpreter User Manual,\*(rq +University of California, Los Angeles, California, 1981. +.bp diff --git a/samples/RUNOFF/VMS_ZIP.RNH b/samples/RUNOFF/VMS_ZIP.RNH new file mode 100644 index 00000000..183ceeac --- /dev/null +++ b/samples/RUNOFF/VMS_ZIP.RNH @@ -0,0 +1,1467 @@ +.! +.! File: ZIP.RNH +.! +.! Author: Hunter Goatley +.! +.! Date: October 22, 1991 +.! +.! Description: +.! +.! RUNOFF source file for portable ZIP on-line help for VMS. +.! Adapted from MANUAL, distributed with ZIP. +.! +.! To build: $ RUNOFF ZIP.RNH +.! $ LIBR/HELP/INSERT libr ZIP +.! +.! Modification history: +.! +.! Hunter Goatley 22-OCT-1991 20:45 +.! Genesis. +.! Jean-loup Gailly 25 March 92 +.! Adaptation to zip 1.6. +.! Igor Mandrichenko 9-JUN-1992 +.! Added explanation of -V option. +.! Jean-loup Gailly 14 June 92 +.! Adaptation to zip 1.8. +.! Jean-loup Gailly 20 Aug 92 +.! Adaptation to zip 1.9. +.! Jean-loup Gailly 31 Aug 93 +.! Adaptation to zip 2.0. +.! Christian Spieler 20 Sep 93 +.! Adaptation to zip 2.0 and OpenVMS completed. +.! Christian Spieler 05 Dec 95 +.! Adaptation to zip 2.1, new options. +.! Christian Spieler 20 Jan 96 +.! Changed -L and -v descriptions. +.! Christian Spieler 11 Feb 96 +.! Added -X option. +.! Onno van der Linden, +.! Christian Spieler 13 Mar 96 +.! Removed -ee option. +.! Christian Spieler 09 Feb 96 +.! Updated copyright notice, Zip version. +.! Christian Spieler 21 Jul 97 +.! Added -P, -R, -i@, -x@ and -tt options, modified for Zip 2.2. +.! Christian Spieler 14 Oct 97 +.! unified spelling of "Info-ZIP", final cleanups for 2.2. +.! Steven Schweda 10 May 2007 +.! General update for version 3.0. +.! Ed Gordon 12 May 2007 +.! Minor updates for version 3.0. +.! +.noflags +.lm4 .rm72 +.indent -4 +1 ZIP +.br +Zip is a compression and file packaging utility for several operating +systems, including UNIX, VMS, MSDOS, OS/2, Windows 9x/NT/XP, Minix, Atari, +Macintosh, Amiga, and Acorn RISC OS. It is analogous to a combination of +tar and compress and is compatible with PKZIP (Phil Katz's ZIP) for +MSDOS systems. +.sk +Zip is useful for packaging a set of files for distribution, for +archiving files, and for saving disk space by temporarily compressing +unused files or directories. A companion program, UnZip, unpacks Zip +archives. +.sk +For brief help on Zip or UnZip, run the program without specifying any +parameters on the command line. +.sk +This description covers the Zip program which uses a UNIX-style command +line. A separate program is available which provides a VMS-style CLI +command line, and it has its own documentation. Refer to the Zip +installation instructions for details. +.sk +Format +.sk;.lm+2;.literal +ZIP [-options] archive inpath inpath ... +.end literal;.lm-2 +.!------------------------------------------------------------------------------ +.indent -4 +2 Basic_Usage +.br +Format +.sk;.lm+2;.literal +ZIP [-options] archive inpath inpath ... +.end literal;.lm-2 +.sk +The default action of Zip is to add or replace entries in "archive" from +the list of "inpath" file specifications, which can include directories +and file names with VMS-style wildcards, or the special name -@ to read +file specifications from SYS$INPUT (stdin). +.sk +With SET PROCESS /PARSE_STYLE = EXTENDED (available on recent non-VAX +systems), Zip preserves the case of the command line. Otherwise, mixed- +or upper-case options and arguments must be quoted. For example, +"-V". Examples in this document generally do not show this quotation, +so VAX and /PARSE_STYLE = TRADITIONAL users (that is, troglodytes) will +need to add quotation where needed when working with these examples. +.sk +General +.sk +Zip reads one or more files, compresses the data (normally), and stores +the compressed information into a single Zip archive file, along with +information about each file (name, path, date and time of last +modification, protection, and check information to verify file +integrity). On a VMS system, Zip can also save VMS/RMS file attributes, +allowing UnZip to restore the files without loss of important file +attributes. Zip can pack an entire directory structure into a Zip +archive with a single command. +.sk +Compression +.sk +Compression ratios of 2:1 to 3:1 are common for text files. Zip has one +standard compression method ("deflate") and can also store files without +compression. Zip (and UnZip) may be built with optional support for the +bzip2 compression method. Then, the user may select bzip2 compression +instead of the default "deflate" method. Zip automatically chooses +simple storage over compression for a file, if the specified compression +method does not actually compress the data in that file. +.sk +Compatibility +.sk +Zip and UnZip can work with archives produced by PKZIP (supporting most +PKZIP features up to PKZIP version 4.6), and PKZIP and PKUNZIP can work +with archives produced by Zip (with some exceptions, notably streamed +archives, but recent changes in the .ZIP file standard may facilitate +better compatibility). Zip version 3.0 is compatible with PKZIP 2.04 +and also supports the Zip64 extensions of PKZIP 4.5 which allows +archives as well as files to exceed the previous 2 GB limit (4 GB in +some cases). Zip also supports bzip2 compression if the bzip2 library +is included when Zip is built. Note that PKUNZIP 1.10 cannot extract +files produced by PKZIP 2.04 or Zip 3.0. You must use PKUNZIP 2.04g or +UnZip 5.0p1 (or later versions) to extract them. +.sk +Large Archives and Zip64 +.sk +Where the operating system and C run-time support allow, Zip 3.0 and +UnZip 6.0 (and later versions) support large files (input and archive), +using the Zip64 extensions to the original .ZIP file format. On VMS, +this genarally means non-VAX systems with VMS V7.2 or later (perhaps +requiring a C RTL ECO before VMS V7.3-2). +.sk +Zip automatically uses the Zip64 extensions when a file larger than 2 GB +is added to an archive, an archive containing a Zip64 entry is updated +(if the resulting archive still needs Zip64), the size of the archive +will exceed 4 GB, or when the number of entries in the archive will +exceed about 64K. Zip64 is also used for archives streamed to a +non-seekable output device. You must use a 4.5 compatible UnZip to +extract files using the Zip64 extensions such as UnZip 6.0 or later. +.sk +In addition, streamed archives, entries encrypted with standard +encryption, or split archives created with the pause option may not be +compatible with PKZIP as data descriptors are used, and PKZIP at the +time of this writing does not support data descriptors (but recent +changes in the PKWare published .ZIP file standard now include some +support for the data descriptor format Zip uses). +.!------------------------------------------------------------------------------ +.indent -4 +2 More_Usage +.br +Here is a very simple example of Zip use: +.sk;.indent 10; +$ zip stuff.zip *.* +.sk +This will create the Zip archive "stuff.zip" (assuming it does not +already exist) and put all the (non-directory) files (";0") from the +current default directory into "stuff.zip" in a compressed form. The +archive is opened using a default file specification of +"SYS$DISK:[].zip", so specifying "stuff" as the archive name would also +create (or use an existing) "stuff.zip", but specifying "stuff.other" +would give you that name. In general, Zip doesn't care about the type +in the file specification, but for split archives (archives split over +multiple files), the user should normally specify a type-less name, +because Zip will normally generate sequentially numbered types ".z01", +".z02", and so on for the early splits, and then the required ".zip" for +the last split. These file types are required by the Zip standard for +split archives. +.sk +Standard VMS wildcard expansion ($SEARCH) is used to interpret the +"inpath" file and directory specifications, like the "*.*" in this +example. +.sk +On VMS, the most natural way to archive an entire directory tree is to +use a directory-depth wildcard ("[...]"). For example: +.sk;.indent 10 +zip foo [...]*.* +.sk +This will create the file "foo.zip" containing all the files (";0") and +directories in and below the current default directory. A more +UNIX-like way to do this would be to use the -r (--recurse-paths) +option: +.sk;.indent 10 +$ zip -r foo *.* +.sk +Zip avoids including its own output files when selecting files to +include in the archive, so it should be safe, as in this case, to create +the archive in the same drectory as the input files. +.sk +One or more specific files, directories, or subdirectories may also be +specified: +.lm +10;.literal +zip foo.zip readme.txt [www...]*.* [.ftp...]*.* - + [.src]*.h [.src]*.c +.end literal;.lm -10 +.sk +For security reasons, paths in Zip archives are always stored as +relative paths, so some care is needed when creating an archive so that +it will create the intended directory structure when UnZip is used to +unpack it. +.sk +To use -r with a specific directory, the name of the directory file +itself must be specified: +.sk;.indent 10 +zip -r foo.zip [000000]www.dir ftp.dir +.sk +You may want to make an archive that contains the files in [.foo], but not +record the directory name, "foo". You can use the -j (junk path) option +to leave off the path: +.sk;.indent 10 +$ zip -j foo [.foo]*.* +.sk +If you are short on disk space, you might not have enough room to hold +both the original directory and the corresponding compressed Zip +archive. In this case, you can create the archive in steps, and use the +-m option. For example, if [.foo] contains the subdirectories [.tom], +[.dick], and [.harry], you could: +.sk +.lm +10;.literal +zip -m foo [.foo.tom...]*.* +zip -m foo [.foo.dick...]*.* +zip -m foo [.foo.harry...]*.* +.end literal;.lm -10 +.sk +The first command would create foo.zip, and the next two would add to +it. The -m option means "move", and it will cause Zip to delete all +files added to the archive after making or updating foo.zip. No +deletions will be done until the Zip operation has completed with no +errors. This option is obviously dangerous and should be used with +care, but it does reduce the need for free disk space. When -m is +used, the -T option is recommended and will test the resulting archive +before deleting the input files. +.sk +If a file specification list is too long to fit conveniently on the Zip +command line, the -@ option can be used to cause Zip to read a list of +file specifications from SYS$INPUT (stdin). If a DCL command procedure +is used, the names can be specified in the procedure: +.sk; +.lm +10;.literal +$ zip foo -@ +$ deck +file_spec_1 +file_spec_2 +file_spec_3 +$ eod +.end literal;.lm -10 +.sk +The file specifications can also be put into a separate file, and fed +into Zip by explicitly defining SYS$INPUT, or by using PIPE. For +example, with the list in foo.zfl: +.sk; +.lm +10;.literal +$ define /user_mode sys$input foo.zfl +$ zip foo -@ +.end literal;.lm -10; +or: +.lm +10;.literal +$ pipe type foo.zfl | zip foo -@ +.end literal;.lm -10 +.sk +If Zip is not able to read a file, it issues a warning but continues. +See the -MM option for more on how Zip handles patterns that are not +matched and files that are not readable. If some files were skipped, a +warning is issued at the end of the Zip operation noting how many files +were read and how many skipped. +.!------------------------------------------------------------------------------ +.indent -4 +2 Comments +.br +One-line comments may be included in the archive for each file added, +using the -c (--entry-comments) option. File operations (adding, +updating) are done first, and the user is then prompted for a one-line +comment for each file added or updated. Enter the comment followed by +, or just for no comment. +.sk +A single multi-line comment may be included for the archive as a whole, +using the -z (--archive-comment) option. UnZip (including UnZip SFX) +will display this comment when it expands the archive. The comment is +read from SYS$INPUT (stdin), and is terminated by the usual end-of-file +character, CTRL/Z. As usual, in a DCL command procedure, these data can +be included in-line in the procedure, or a user may DEFINE SYS$INPUT to +a file to get the comment from that file. Where supported, the DCL PIPE +command can also be used to redirect SYS$INPUT from a file. +.sk +Note that -z (--archive-comment) and -@ (read file specifications from +SYS$INPUT (stdin)) can't be used together (successfully). +.!------------------------------------------------------------------------------ +.indent -4 +2 Compression +.br +Zip can archive files with or without compression. The standard +compression method ("deflate") is compatible with all UnZip versions +(except really old ones that only understand the "store" method). +Current Zip and UnZip versions may be built with optional support for +the bzip2 compression method. (The bzip2 method can compress better, +especially when compressing smaller files, but uses more CPU time, and +requires an UnZip which includes the optional bzip2 support. See the +installation instructions for details on adding bzip2 compression +support at build time.) +.sk +Numeric compression level options control the effort put into data +compression, with -1 being the fastest, and -9 giving the most +compression. +.sk +Compression control options: +.sk;.lm +10;.literal +-Z mthd use compress method "mthd", +--compression-method mthd "bzip2" or "deflate" (default) + +-0 (--store) no compression +-1 (--compress-1) compression level 1 +-2 (--compress-2) compression level 2 +-3 (--compress-3) compression level 3 +-4 (--compress-4) compression level 4 +-5 (--compress-5) compression level 5 +-6 (--compress-6) compression level 6 +-7 (--compress-7) compression level 7 +-8 (--compress-8) compression level 8 +-9 (--compress-9) compression level 9 +.end literal;.lm -10 +.sk +Normally, a file which is already compressed will not be compressed much +further (if at all) by Zip, and trying to do it can waste considerable +CPU time. Zip can suppress compression on files with particular types, +specified as a colon- or semi-colon-separated list of file types: +.sk;.indent 10 +-n type1[:type2[...]] (--suffixes type1[:type2[...]]) +.sk +For example: +.sk;.indent 10 +zip -n .bz2:.gz:.jpeg:.jpg:.mp3:.zip foo [.foo]*.* +.sk +will put everything (";0") from [.foo] into foo.zip, but will store any +files that end in .bz2, .gz, .jpeg, .jpg, .mp3, or .zip, without trying +to compress them. +.sk +The default type list is .Z:.zip:.zoo:.arc:.lzh:.arj, and the comparison +is case-insensitive. +.sk +-9 (--compress-9) will override -n (--suffixes), causing compression to +be attempted for all files. +.!------------------------------------------------------------------------------ +.indent -4 +2 Encryption +.br +Zip offers optional encryption, using a method which by modern standards +is generally considered to be weak. +.sk;.literal +-e --encrypt +.end literal;.br +Encrypt new or updated archive entries using a password which is +supplied by the user interactively on the terminal in response to a +prompt. (The password will not be echoed.) If SYS$COMMAND is not a +terminal, Zip will exit with an error. The password is verified before +being accepted. +.sk;.literal +-P password --password password +.end literal;.br +Use "password" to encrypt new or updated archive entries (if any). +USING -P IS INSECURE! Many multi-user operating systems provide ways +for any user (or a privileged user) to see the current command line of +any other user. Even on more secure systems, there is always the threat +of over-the-shoulder peeking. Storing the plaintext password as part of +a command line in a command procedure is even less secure. Whenever +possible, use the non-echoing, interactive password entry method. +.sk +Because standard Zip encryption is weak, where security is truly +important, use a strong encryption program, such as Pretty Good Privacy +(PGP) or GNU Privacy Guard (GnuPG), on an archive instead of standard +Zip encryption. A stronger encryption method, such as AES, is planned +for Zip 3.1. +.!------------------------------------------------------------------------------ +.indent -4 +2 Exit_Status +.br +On VMS, Zip's UNIX-style exit values are mapped into VMS-style status +codes with facility code 1955 = %x7A3, and with the inhibit-message +(%x10000000) and facility-specific (%x00008000) bits set: +.sk +.literal + %x17A38001 normal exit + %x17A38000+ 16* Zip_error_code warnings + %x17A38002+ 16* Zip_error_code normal errors + %x17A38004+ 16* Zip_error_code fatal errors +.end literal +.sk +Note that multiplying the UNIX-style Zip error code by 16 places it +conveniently in the hexadecimal representation of the VMS exit code, +"__" in %x17A38__s, where "s" is the severity code. For example, a +truncated archive might cause Zip error code 2, which would be +transformed into the VMS exit status %x17A38024. +.sk +The Zip VMS exit codes include severity values which approximate those +defined by PKWARE, as shown in the following table: +.literal + + VMS Zip err + severity code Error description + ----------+---------+---------------------------------------------- + Success 0 Normal; no errors or warnings detected. + Fatal 2 Unexpected end of archive. + Error 3 A generic error in the archive format was + detected. Processing may have completed + successfully anyway; some broken archives + created by other archivers have simple work- + arounds. + Fatal 4 Zip was unable to allocate memory for one or + more buffers during program initialization. + Fatal 5 A severe error in the archive format was + detected. Processing probably failed imme- + diately. + Error 6 Entry too large to be split with zipsplit. + Error 7 Invalid comment format. + Fatal 8 Zip -T failed or out of memory. + Error 9 The user aborted zip prematurely with con- + trol-C (or equivalent). + Fatal 10 Zip encountered an error while using a temp + file. + Fatal 11 Read or seek error. + Warning 12 Zip has nothing to do. + Error 13 Missing or empty zip file. + Fatal 14 Error writing to a file. + Fatal 15 Zip was unable to create a file to write to. + Error 16 Bad command line parameters. + Error 18 Zip could not open a specified file to read. + Fatal 19 Zip was built with options not supported on + this system + Fatal 20 Attempt to read unsupported Zip64 archive +.end literal +.!------------------------------------------------------------------------------ +.indent -4 +2 Extra_Fields +.br +The .ZIP file format allows some extra data to be stored with a file in +the archive. For example, where local time zone information is +available, Zip can store UTC date-time data for files. (Look for +USE_EF_UT_TIME in a "zip -v" report.) On VMS, with -V or -VV, Zip will +also store VMS-specific file attributes. These data are packaged as +"extra fields" in the archive. Some extra fields are specific to a +particular operating system (like VMS file attributes). Large files +(bigger than 4GB) on any OS require an extra field to hold their 64-bit +size data. Depending on the capabilities of the UnZip program used to +expand the archive, these extra fields may be used or ignored when files +are extracted from the archive. +.sk +Some extra fields, like UTC date-times or VMS file attributes, are +optional. Others, like the Zip64 extra field which holds 64-bit sizes +for a large file, are required. +.sk +The -X (--strip-extra) option suppresses the saving of any optional +extra fields in the archive. (Thus, -X conflicts with -V or -VV.) +.!------------------------------------------------------------------------------ +.indent -4 +2 Environment +.br +A user can specify default command-line options and arguments by +defining an "environment variable" (that is, a logical name or DCL +symbol), "ZIP_OPTS" or "ZIPOPT", to specify them. If both "ZIP_OPTS" and +"ZIPOPT" are specified, the definition of "ZIPOPT" prevails. +.sk +The C RTL function getenv() is used to sense these variables, so its +behavior determines what happens if both a logical name and a symbol are +defined. As of VMS V7.3, a logical name supercedes a symbol. +.sk +The "zip -v" report should show the perceived settings of these +variables. +.!------------------------------------------------------------------------------ +.indent -4 +2 File_Names +.br +Zip deals with file names in the system file system and with file names +in Zip archives. File names in a Zip archive are stored in a UNIX-like +path-name format. For example, a VMS file specification like this: +.sk;.indent 10 +[.zip30.vms]descrip.mms +.sk +could appear in a Zip archive as: +.sk;.indent 10 +zip30/vms/descrip.mms +.sk +For security reasons, paths in Zip archives are always stored as +relative paths, so an absolute VMS directory specification will be +transformed to a relative path in the archive (that is, no leading "/"). +For example, the following absolute directory specification would give +the same archive path as the previous (relative) example: +.sk;.indent 10 +[zip30.vms]descrip.mms +.sk +Also, device names are dropped, so the following file specification +would also give the same archive path: +.sk;.indent 10 +sys$sysdevice:[zip30.vms]descrip.mms +.sk +If an archive is intended for use with PKUNZIP under MSDOS, then the -k +(for "Katz", --DOS-names) option should be used to attempt to adjust the +names and paths to conform to MSDOS character-set and length +limitations, to store only the MSDOS file attributes (just the +owner:write attribute from VMS), and to mark the entry as made under +MSDOS (even though it wasn't). +.sk +Note that file specifications in the file system must be specified using +VMS notation, but file names in an archive must be specified using the +UNIX-like notation used in the archive. For example, where a BACKUP +command might look like this: +.sk.indent 10 +$ back [.zip30...]*.* /excl = [...vms]*.c stuff.bck /save +.sk +a corresponding Zip command might look like this: +.sk;.indent 10; +$ zip stuff.zip [.zip30...]*.* -x */vms/*.c +.sk +because the files to be added to the Zip archive are specified using VMS +file specifications, but the -x (--exclude) option excludes names based +on their archive path/file names. Options dealing with archive names +include -R (--recurse-patterns), -d (--delete), -i (--include), -x +(--exclude), and -U (--copy-entries). +.sk +Note: By default, on VMS, archive name pattern matching (-R, -d, -i, -x, +and -U) is case sensitive, even when the file system is not case +sensitive (or even case preserving). This allows accurate matching of +mixed-case names in an archive which may have been created on a system +with a case sensitive file system, but it can involve extra effort on +VMS, where it may be necessary to use unnatural case names (or the same +names in multiple cases, like "*.obj *.OBJ") for this kind of pattern +matching to give the desired behavior. If completely case-blind pattern +matching behavior is desired, specify the -ic (--ignore-case) option. +.!------------------------------------------------------------------------------ +.indent -4 +3 Case +.br +For better compatibility with UNIX-like systems, Zip, by default, +down-cases ODS2 file names. For example, the following file on an ODS2 +file system: +.sk;.indent 10 +[.ZIP30.VMS]DESCRIP.MMS +.sk +would appear in an archive as: +.sk;.indent 10 +zip30/vms/descrip.mms +.sk +Zip versions before 3.0 down-cased all VMS file names. Now, various +options give the user control over these conversions: +.sk +.lm +10;.literal +-C preserve case of all file names +-C- down-case all file names +-C2 preserve case of ODS2 names +-C2- down-case ODS2 file names (default) +-C5 preserve case of ODS5 names (default) +-C5- down-case ODS5 file names +.end literal;.lm -10 +.sk +Case is handled differently for archive member names, which the user +specifies with the -R, -d, -i, -x, and -U options. By default, on VMS, +archive name pattern matching is case sensitive, even when the file +system is not case sensitive (or even case preserving). This allows +accurate matching of mixed-case names in an archive which may have been +created on a system with a case sensitive file system, but it can +involve extra effort on VMS, where it may be necessary to use unnatural +case names (or the same names in multiple cases, like "*.obj *.OBJ") for +this kind of pattern matching to give the desired behavior. If +completely case-blind pattern matching behavior is desired, specify the +-ic (--ignore-case) option. +.!------------------------------------------------------------------------------ +.indent -4 +2 Fixing_Damage +.br +Two options can be used to fix a damaged Zip archive. +.sk;.literal +-F --fix +-FF --fixfix +.end literal;.sk +The -F (--fix) option can be used if some portions of the archive are +missing, but it requires a reasonably intact central directory. The +input archive is scanned as usual, but zip will ignore some problems. +The resulting archive should be valid, but any inconsistent entries +will be left out. +.sk +If the archive is too damaged or the end (where the central directory is +situated) has been truncated, you must use -FF (--fixfix). This is a +change from zip 2.32, where the -F option is able to read a truncated +archive. The -F option now more reliably fixes archives with minor +damage, and the -FF option is needed to fix archives where -F and -FF +was used before. +.sk +With -FF, the archive is scanned from the beginning and Zip scans for +special signatures to identify the limits between the archive members. +The -F option is more reliable if the archive is not too much damaged, +so try this option first. +.sk +Neither option will recover archives that have been incorrectly +transferred, such as by FTP in ASCII mode instead of binary. After the +repair, the -t option of UnZip may show that some files have a bad CRC. +Such files cannot be recovered; you can remove them from the archive +using the -d option of Zip. +.sk +Because of the uncertainty of the "fixing" process, it's required +to specify an output archive, rather than risking further damage to the +original damaged archive. For example, to fix the damaged archive +foo.zip, +.sk;.indent 10 +zip -F foo --out foo_fix +.sk +tries to read the entries normally, copying good entries to the new +archive foo_fix.zip. If this doesn't work, as when the archive is +truncated, or if some entries are missed because of bad central +directory entries, try -FF: +.sk;.indent 10 +zip -FF foo --out foo_fixfix +.sk +and compare the resulting archive to the archive created using -F. The +-FF option may create an inconsistent archive. Depending on what is +damaged, you can then use the -F option to fix that archive. +.sk +A split archive with missing split files can be fixed using -F if you +have the last split of the archive (the ".zip" file). If this file is +missing, you must use -FF to fix the archive, which will prompt you for +the splits you have. +.sk +Currently, the fix options can't recover an entry which has a bad +checksum or is otherwise damaged. +.!------------------------------------------------------------------------------ +.indent -4 +2 Log_File +.br +Zip normally sends messages to the user's terminal, but these may be +also directed to a log file. +.sk;.literal +-la --log-append +.end literal;.br +Append to an existing log file. Default is to create a new version. +.sk;.literal +-lf logfilepath --logfile-path logfilepath +.end literal;.br +Open a logfile at the given path. By default, a new version will be +created, but with the -la option an existing file will be opened and the +new log information appended to any existing information. Only +warnings and errors are written to the log unless the -li option is also +given, then all information messages are also written to the log. +.sk;.literal +-li --log-info +.end literal;.br +Include information messages, such as file names being zipped, in the +log. The default is to include only the command line, any warnings +and errors, and the final status. +.!------------------------------------------------------------------------------ +.indent -4 +2 Modes_of_Operation +.br +Zip supports two distinct types of command modes, external and +internal. The external modes (update, grow, and freshen) read files +from the file system (as well as from an existing archive) while the +internal modes (delete and copy) operate exclusively on entries in an +existing archive. +.sk;.literal +-u --update +.end literal;.br +Update existing entries and add new files. If the archive does not +exist, create it. This is the default mode, so -u is optional. +.sk;.literal +-g --grow +.end literal;.br +Grow (append to) the specified Zip archive, instead of creating a new +one. If this operation fails, Zip attempts to restore the archive to +its original state. If the restoration fails, the archive might become +corrupted. This option is ignored when there's no existing archive or +when at least one archive member must be updated or deleted. +.sk;.literal +-f --freshen +.end literal;.br +Update existing entries in an existing archive. Does not add new files +to the archive. +.sk;.literal +-d --delete +.end literal;.br +Delete entries from an existing archive. +.sk;.literal +-DF --difference-archive +.end literal;.br +Create an incremental backup-style archive, where the resulting archive +will contain all new and changed files since the original archive was +created. For this to work, the input file list and current directory +must be the same as during the original Zip operation. +.sk +For example, if the existing archive was created using +.sk;.indent 10 +zip foo_full.zip [.foo...]*.* +.sk +from just above the foo directory, then the command (also from just +above the foo directory): +.sk;.indent 10 +zip foo_full.zip [.foo...]*.* -DF -O foo_incr.zip +.sk +creates the archive foo_incr.zip with just the files not in foo_full.zip +and the files where the size or date-time of the files does not match +that in foo_full.zip. Note that in the "zip -DF" operation, the +original full archive is specified as the input archive, and the -O +(--output-file) option is used to specify the new (incremental) output +archive. +.sk;.literal +-FS --filesync +.end literal;.br +Delete entries in the archive that do not match files on the OS. +Normally when an archive is updated, new files are added and changed +files are updated but files that no longer exist on the OS are not +deleted from the archive. This option enables deleting of entries that +are not matched on the OS. Enabling this option should create archives +that are the same as new archives, but since existing entries are copied +instead of compressed, updating an existing archive with -FS can be much +faster than creating a new archive. If few files are being copied from +the old archive, it may be faster to create a new archive instead. +.sk +This option deletes files from the archive. If you need to preserve the +original archive, make a copy of the archive first, or use the -O +(--output) option to output the new archive to a new file. Even though +it's slower, creating a new archive with a new archive name is safer, +avoids mismatches between archive and OS paths, and is preferred. +.sk;.literal +-U --copy-entries +.end literal;.br +Select entries in an existing archive and copy them to a new archive. +Copy mode is like update mode, but entries in the existing archive are +selected by command line patterns rather than files from the file system +and it uses the -O (--output-file) option to write the resulting archive +to a new file rather than updating the existing archive, leaving the +original archive unchanged. +.sk +Normally, when updating an archive using relative file specifications +("[]", "[.xxx]", and so on), it helps to have the same default directory +as when the archive was created, but this is not a strict requirement. +.sk +Date-time information in a Zip archive may be influenced by time zone. +.!------------------------------------------------------------------------------ +.indent -4 +3 Examples +.br +When given the name of an existing archive, Zip will replace identically +named entries in the archive or add entries for new names. For example, +if foo.zip exists and contains foo/file1 and foo/file2, and the +directory [.foo] contains the files file1 and file3, then: +.sk;.indent 10 +$ zip foo [.foo...]*.* +.sk +will replace foo/file1 in foo.zip and add foo/file3 to foo.zip. After +this, foo.zip contains foo/file1, foo/file2, and foo/file3, with foo/file2 +unchanged from before. This is the default mode -u (update). +.sk +Update will add new entries to the archive and will replace +existing entries only if the modified date of the file is more recent than +the date recorded for that name in the archive. For example: +.sk;.indent 10 +$ zip -u stuff *.* +.sk +will add any new files in the current directory, and update any changed +files in the archive stuff.zip. Note that Zip will not try to pack +stuff.zip into itself when you do this. Zip avoids including its own +output files when selecting files to include in the archive, so it +should be safe, as in this case, to have the archive included in the +list of input files. +.sk +A second mode, -f (freshen), like update will only +replace entries with newer files. Unlike update, however, it will not +add files that are not already in the archive. For example: +.sk;.indent 10 +$ zip -f foo +.sk +Note that the -f option with no arguments freshens all the entries in the +archive. The same is true of -u, so "zip -u foo" and "zip -f foo" do +the same thing. +.sk +When these options are used, Zip should be run from the same directory +as when the original Zip command was run, so that the path names in the +archive will continue to agree with the path names in the file system. +Normally, it's also a good idea to keep the other options the same (-V, +-w, and the like), to keep the archive contents consistent. +.sk +The -t (--from-date) and -tt (--before-date) options can also be used +with adding, updating, or freshening to restrict further the files to be +included in the archive. For example: +.sk;.indent 10 +$ zip -rt 12071991 infamy [.FOO]*.* +.sk +will add all the files in [.FOO] and its subdirectories that were last +modified on December 7, 1991, or later to the achive infamy.zip. Dates +can be in format mmddyyyy or yyyy-mm-dd. +.sk +Also, files can be explicitly excluded using the -x option: +.sk;.indent 10 +$ zip -r foo [.FOO] -x *.obj +.sk +which will zip up the contents of [.FOO] into foo.zip but exclude all the +files that end in ".obj". +.sk +The -d (delete) mode will remove entries from an +archive. An example might be: +.sk;.indent 10 +$ zip -d foo foo/harry/*.* *.obj +.sk +which will remove all of the files that start with "foo/harry/" and all of +the files that end with ".obj" (in any path). +.sk +The last mode, -U (--copy-entries), selects entries from an existing +archive and copies them to a new archive. +.sk;.indent 10 +$ zip -U foo *.obj --out fooobj +.sk +will copy all .obj entries from foo.zip and put them in the new archive +fooobj.zip. +.sk +Note: By default, on VMS, archive name pattern matching (-R, -d, -i, -x, +and -U) is case sensitive, even when the file system is not case +sensitive (or even case preserving). This allows accurate matching of +mixed-case names in an archive which may have been created on a system +with a case sensitive file system, but it can involve extra effort on +VMS, where it may be necessary to use unnatural case names (or the same +names in multiple cases, like "*.obj *.OBJ") for this kind of pattern +matching to give the desired behavior. If completely case-blind pattern +matching behavior is desired, specify the -ic (--ignore-case) option. +.!------------------------------------------------------------------------------ +.indent -4 +2 Options_List +.br +"zip -h" provides a concise list of common command-line options. "zip +-h2" provides more details. "zip -so" provides a list of all available +options. "zip -v" shows the program version and available features. +(The list below was derived from a "zip -so" listing.) +.sk +Short-form options begin with a single hyphen ("-"). Long-form option +begin with a double hyphen ("--"), and may be abbreviated to any +unambiguous shorter string. For example: +.lm +10;.literal +-v +--verbose +--verb +.end literal;.lm -10 +.sk +To avoid confusion, if a negatable option contains an embedded hyphen +("-"), then avoid abbreviating it at the hyphen if you plan to negate +it. For example, if an option like --some-option were abbreviated to +--some-, the parser would consider that trailing hyphen to be part of +the option name, rather than as a negating trailing hyphen. This +behavior may change in the future, to interpret the trailing hyphen in +--some- to be negating. (So don't do it.) +.sk +Some options may be negated (or modified) by appending a "-": +.lm +10;.literal +-la- +--show-files- +.end literal;.lm -10 +.sk +Some options take a value, which may immediately follow the option, or +be separated by a space or "=". For example: +.lm +10;.literal +-ttmmddyyyy +-tt mmddyyyy +-tt=mmddyyyy +.end literal;.lm -10 +.sk +.lm -4;.literal + Sh Long Description +----+-------------------+-------------------------------------------------- + 0 store store (instead of compress) + 1 compress-1 compress faster (-2, -3, -4, ...) + 9 compress-9 compress better + ? show the Zip help screen + @ names-stdin read input file patterns from SYS$INPUT (1/line) + A adjust-sfx adjust self-extracting executable + b temp-path path use "path" directory for temporary files + C preserve-case preserve case of all file names added to archive + C- preserve-case- down-case all file names added to archive + C2 preserve-case-2 preserve case of ODS2 names added to archive + C2- preserve-case-2- down-case ODS2 file added to archive (default) + C5 preserve-case-5 preserve case of ODS5 names added to archive (dflt) + C5- preserve-case-5- down-case ODS5 names added to archive + c entry-comments add a comment for each entry added to archive + D no-dir-entries do not add archive entries for directories + DF difference-archive difference archive: add only changed or new files + d delete delete entries in archive + db display-bytes display running byte counts + dc display-counts display running file counts + dd display-dots display progress dots for files (dflt size = 10MB) + dg display-globaldots display progress dots for archive, not each file + ds dot-size size set progress dot interval to "size" (MB) + du display-usize display original uncompressed size for entries + dv display-volume display volume (disk) number as in_disk>out_disk + e encrypt encrypt entries, ask for password + F fix fix mostly intact archive (try F before FF) + FF fixfix salvage what can be salvaged (not as reliable) + FS filesync remove archive entries unmatched in file system + f freshen update existing entries (only changed files) + fd force-descriptors force data descriptors as if streaming + fz force-zip64 force use of Zip64 format + g grow grow existing archive (unless updating or deleting) + H show the Zip help screen + h help show the Zip help screen + h2 more-help show extended Zip help + i include pat1 [pat2 [...]] include only names matching the patterns + ic ignore-case ignore case (case-blind archive entry name matching) + J junk-sfx junk (remove) archive preamble (unzipsfx) + j junk-paths junk (don't store) directory names, only file names + k DOS-names simulate PKZIP-made archive (DOS 8.3 names) + L license show software license + l to-crlf translate end-of-lines (LF -> CRLF) + la log-append append to existing log file + lf logfile-path lfile log to log file at lfile (default: new version) + li log-info include informational messages in log + ll from-crlf translate end-of-lines (CRLF -> LF) + MM must-match input file spec must exist (wildcards must match) + m move delete files added to archive + n suffixes sfx1[:sfx2[...]] don't compress files with these suffixes + nw no-wild no wildcards during add or update + O output-file ozf use "ozf" as the output archive (dflt = inp archive) + o latest-time set archive date-time to match oldest entry + P password password encrypt with supplied "password" string + q quiet quiet operation (no info messages) + R recurse-patterns recurse into subdirs from cur dir, match names only + r recurse-paths recurse into directories from specified path pats + s split-size size split archive at "size" (K/MB) (0: don't split) + sb split-bell ring terminal bell at pause for split medium change + sc show-command show command line + sd show-debug show debug messages + sf show-files show files to process (only) + so show-options show list of all command-line options + sp split-pause pause to select split destination(s) + sv split-verbose be verbose about creating splits + T test test archive integrity (runs UnZip -T) + t from-date mmddyyyy only do files since (at or after) "mmddyyyy" + tt before-date mmddyyyy only do files before "mmddyyyy" + u update update changed files, add new files (default mode) + V VMS-portable save VMS file attributes + VV VMS-specific save VMS file attributes and all allocated blocks + v verbose verbose messages (print version info if only arg) + w VMS-versions save VMS version numbers in archive + ww VMS-dot-versions save VMS version numbers as ".nnn", not ";nnn" + X strip-extra strip all but critical extra fields + X- strip-extra- keep all extra fields + x exclude pat1 [pat2 [...]] exclude all names matching the patterns + Z compression-method mthd use compress method "mthd" (bzip2 or deflate) + z archive-comment ask for archive comment +.end literal;.lm +4 +.!------------------------------------------------------------------------------ +.indent -4 +2 Miscellaneous_Options +.sk;.literal +-D --no-dir-entries +.end literal;.br +Do not create entries in the archive for directories. By default, +directory entries are added to an archive, so that their attributes can +be saved in the archive. When an archive is created using -D, UnZip +will still create directories as needed (subject to user control), but +they will get the default attributes (date-time, permissions, ...) on +the destination system, rather than their original atributes. +.sk;.literal +-MM --must-match +.end literal;.br +All input patterns must match at least one file and all input files +found must be readable. Normally when an input pattern does not match +a file the "name not matched" warning is issued and when an input +file has been found but later is missing or not readable a "missing or +not readable" warning is issued. In either case Zip continues +creating the archive, with missing or unreadable new files being skipped +and files already in the archive remaining unchanged. After the +archive is created, if any files were not readable zip returns the OPEN +error code (18 on most systems) instead of the normal success return (0 +on most systems). With -MM, Zip exits as soon as an input pattern +is not matched (whenever the "name not matched" warning would be issued) +or when an input file is not readable. In either case Zip exits with +an OPEN error and no archive is created. +.sk +This option is useful when a known list of files is to be zipped so any +missing or unreadable files should result in an error. It may be less +useful when used with wildcards, but Zip will still exit with an error +if any input pattern doesn't match at least one file or if any +matched files are unreadable. If you want to create the archive anyway +and only need to know if files were skipped, then don't use -MM and just +check the exit status. Also, a log file (see -lf (--logfile-path)) +could be useful. +.sk;.literal +-O out_file --output-file out_file +.end literal;.br +Process the archive changes as usual, but instead of updating the +existing archive, send the output to a new archive, "out_file". The +output archive specified must be a different file from the input +archive. +.sk +This option can be used to create updated split archives. It can +also be used with -U to copy entries from an existing archive to +a new archive. See the EXAMPLES section below. +.sk +Another use is converting zip files from one split size to +another. For instance, to convert an archive with 700MB CD splits +to one with 2GB DVD splits, can use: +.sk;.indent 10 +zip -s 2g cd-split.zip --out dvd-split.zip +.sk +which uses copy mode. See -U below. Also: +.sk;.indent 10 +zip -s 0 split.zip --out unsplit.zip +.sk +will convert a split archive to a single-file archive. +.sk +Copy mode will convert stream entries (using data descriptors and which +may be incompatible with some unzip programs) to normal entries (which +should be compatible with all unzip programs), except if standard +encryption was used. For archives with encrypted entries, zipcloak +will decrypt the entries and convert them to normal entries. +.sk;.literal +-o --latest-time +.end literal;.br +Set the modification date-time of the Zip archive file to the latest +(newest) modification date-time found among the entries in the zip +archive. This can be used without any other operations, if +desired. For example: +.sk;.indent 10 +zip -o foo +.sk +will change the modification date-time of foo.zip to the latest time of +the entries in foo.zip. +.sk;.literal +-q --quiet +.end literal;.br +Quiet mode. Eliminates informational messages and comment prompts. +This mode may be useful in command procedures, or if the Zip operation +is being performed as a background task ("$ spawn/nowait zip -q foo +*.c"). +.sk +.sk;.literal +-T --test +.end literal;.br +Test the integrity of a zip archive (the new one, if -O (--output-file) +is specified). If the check fails, the old zip file is unchanged and +(with the -m option) no input files are removed. +.sk +Implementation +.br +"zip -T" actually runs an "unzip -t" command to do the testing, so UnZip +must be installed properly for this to work. +.sk;.literal +-TT unzip_cmd --unzip-command unzip_cmd +.end literal;.br +Specify the actual UnZip command, "unzip_cmd" (normally a DCL symbol) to +use for "zip -T". This can be useful if multiple versions of UnZip are +installed on a system, and the default DCL symbol "UNZIP" would run the +wrong one (or the logical name DCL$PATH would lead to the wrong one). +.sk +In "unzip_cmd", the string "{}" is replaced by the temporary name of the +archive to be tested, otherwise the name of the archive is appended +to the end of the command. The exit status is checked for success severity. +.sk;.literal +-v --verbose +.end literal;.br +Verbose mode or print diagnostic version info. +.sk +Normally, when applied to real operations, this option enables the +display of a progress indicator during compression (see -dd for more on +dots) and requests verbose diagnostic info about archive structure +oddities. +.sk +When -v is the only command line argument, a diagnostic report is +displayed, showing: +.lm +3;.br;.indent -2 +o Copyright and other legal notices +.br;.indent -2 +o Program name, version, and release date +.br;.indent -2 +o Pointers to Info-ZIP FTP and Web sites +.br;.indent -2 +o Program build information (compiler type and version, OS version, and +the compilation date +.br;.indent -2 +o Optional features enabled at compile-time +.br;.indent -2 +o Environment variable definitions (ZIP_OPTS, ZIPOPT) +.lm -3;.br +.sk +This information should be included in bug reports. +.sk;.literal +-y --symlinks +.end literal;.br +Store symbolic links as such in the Zip archive, instead of compressing +and storing the file referred to by the link. A symbolic link normally +requires less storage than the actual file, both in the archive, and on +the destination file system. +.sk +On VMS, symbolic links are supported on ODS5 disks where the C RTL +supports symbolic links. Full support for symbolic links seems to +require VMS V8.3, but a Zip program supporting symbolic links may be +built on VMS V7.3-2. +.!------------------------------------------------------------------------------ +.indent -4 +2 Progress_Display +.br +Various options control the display of progress messages during Zip +operation. +.sk;.literal +-db --display-bytes +.end literal;.br +Display running byte counts showing the bytes processed and the bytes to +go. +.sk;.literal +-dc --display-counts +.end literal;.br +Display running count of entries processed and entries to go. +.sk;.literal +-dd --display-dots +.end literal;.br +Display dots while each entry is processed (except on ports that have +their own progress indicator). See -ds below for setting dot size. The +default is a dot every 10 MB of input file processed. The -v +(--verbose) option also displays dots and used to at a higher rate than +this (at the same rate as in previous versions of Zip) but this rate has +been changed to the new 10 MB default, and is also controlled by -ds. +.sk;.literal +-dg --display-globaldots +.end literal;.br +Display progress dots for the archive instead of for each file. The +command +.sk;.indent 10 +zip -qdgds 10m +.sk +will turn off most output except dots every 10 MB. +.sk;.literal +-ds size --dot-size size +.end literal;.br +Set amount of input file processed for each dot displayed. See -dd to +enable displaying dots. Setting this option implies -dd. "size" is in +the format "nm" where n is a number and m is a multiplier. Currently +"m" can be k (KB), m (MB), g (GB), or t (TB), so if "n" is 100 and "m" +is k, "size" would be 100k which is 100KB. The default is 10MB. +.sk +The -v (--verbose) option also displays dots and used to default to a +higher rate than this (at the same rate as in previous versions of Zip) +but now the default is 10 MB and the -v dots are also controlled by this +option. A "size" of 0 turns dots off. +.sk +This option does not control the dots from the "Scanning files" message +as Zip scans for input files. The dot size for that is fixed at 2 +seconds or a fixed number of entries, whichever is longer. +.sk;.literal +-du --display-usize +.end literal;.br +Display the uncompressed size of each entry. +.sk;.literal +-dv --display-volume +.end literal;.br +Display the volume (disk) number each entry is being written to. +.!------------------------------------------------------------------------------ +.indent -4 +2 Self_Extracting_Archives +.br +A self-extracting archive (SFX) comprises a normal Zip archive appended +to a special UnZip program (such as UNZIPSFX.EXE) for the intended +target system. +.sk +The UnZip distribution includes a VMS command procedure, +[,vms]makesfx.com, which can be used directly or adapted to create an +SFX archive from a normal Zip archive. +.sk +The .ZIP file format includes offsets to data structures in the archive, +and these offsets are measured from the start of the archive file. +Appending an archive to an UnZip SFX executable effectively moves the +start of the archive file. That makes the original offsets wrong, and +that will cause the UnZip SFX program to emit warning messages when it +tries to unpack the archive. Zip -A can be used to adjust these offsets +in a self-extracting archive. For example, to adjust the offsets in +foo.sfx_exe: +.sk;.indent 10 +zip -A foo.sfx_exe +.sk +Similarly, the UnZip SFX program can be removed from a self-extracting +archive (and the offsets in the archive restored) using the -J +(--junk-sfx) option. For example: +.sk;.indent 10 +zip -J foo.sfx_exe +.sk +Note that a self-extracting archive contains a normal Zip archive, and a +normal UnZip program can be used to expand it in the normal way. You +may get a warning about extra bytes at the beginning of the archive (the +UnZip SFX program), but UnZip should work properly after that. This +allows data in a self-extracting archive to be accessed on any system, +not just the target system where its embedded UnZip SFX program runs. +.!------------------------------------------------------------------------------ +.indent -4 +2 Split_Archives +.br +Beginning with version 3.0, Zip supports split archives. A split +archive is one which is divided into multiple files, usually to allow it +to be stored on multiple storage media (floppy diskettes, CD-ROMs, or +the like) when a single medium would be too small to contain the whole +archive. (Note that split archives are not just unitary archives split +into pieces, as the .ZIP file format includes offsets to data structures +in the archive, and for a split archive these are based on the start of +each split, not on the start of the whole archive. Concatenating the +pieces will invalidate these offsets, but UnZip can usually deal with +it. Zip will usually refuse to process such a spliced archive unless +the -FF fix option is used to fix the offsets.) +.sk +For a split archive with, say, 20 split files, the files are typically +named ARCHIVE.z01, ARCHIVE.z02, ..., ARCHIVE.z19, ARCHIVE.zip, where +"ARCHIVE" is the archive name specified by the user on the Zip command +line. Note that the last split file is the ".zip" file. In contrast, +"spanned" archives are the original multi-disk archive generally +requiring floppy disks and using volume labels to store disk numbers. +Zip supports split archives but not spanned archives, though a procedure +exists for converting split archives of the right size to spanned +archives. The reverse is also true, where each file of a spanned +archive can be copied in order to files with the above names to create a +split archive. +.!------------------------------------------------------------------------------ +.indent -4 +3 Options +.br +Use "-s size" to create a split archive (and to set the split size). +The size is given as a number followed optionally by a multiplier suffix +of k (KB), m (MB, the default if no suffix is specified), g (GB), or t +(TB). (All are powers of 1024, not 1000). 64K is the minimum split +size. For example, the following command could be used to create a +split archive called "foo" from the contents of the "bar" directory with +splits of 670MB, which might be useful for burning on CDs: +.sk;.indent 10 +zip -s 670m foo [.bar...]*.* +.sk +Using -s without -sp as above creates all the splits in the directory +specified by "foo", in this case the current default directory. This +split mode updates the splits as the archive is being created, requiring +all splits to remain writable, but creates split archives that are +readable by any UnZip that supports split archives. See -sp below for +enabling split pause mode which allows splits to be written directly to +removable media. +.sk +The -sv option can be used to enable verbose splitting and display +details of how the splitting is being done. The -sb option can be used +to ring the terminal bell when Zip pauses for the next split +destination. +.sk +The -sp option can be used to pause Zip between splits to allow +changing removable media, for example, but read the descriptions and +warnings for both -s and -sp below. +.sk +Though Zip does not update split archives, Zip provides the option +-O (--output-file) to allow split archives to be updated and saved in a +new archive. For example: +.sk;.indent 10 +zip inarchive.zip foo.c bar.c -O outarchive.zip +.sk +reads archive inarchive.zip, even if split, adds the files foo.c and +bar.c, and writes the resulting archive to outarchive.zip. If +inarchive.zip is split, then outarchive.zip defaults to the same split +size. Be aware that outarchive.zip and any split files that are created +with it are always overwritten without warning. This may be changed in +the future. +.!------------------------------------------------------------------------------ +.indent -4 +2 Temporary_Files +.br +When creating a new archive or normally when changing an existing +archive, Zip will write a temporary file in the archive destination +directory ("ZIxxxxxxxx", where "xxxxxxxx" is the hexadecimal process ID) +with the new contents. Then, if and when the Zip job has completed with +no errors, it will rename the temporary file to the specified archive +name (replacing the old archive, if any). +.sk +You can use the -b (--temp-path) option to specify a different path +(device and/or directory) for the temporary file, but specifying a +different device will force Zip to copy the temporary file to its final +destination instead of simply renaming it, and that copying will take +more time than renaming, especially for a large archive. For example: +.sk;.indent 10 +$ zip -b disk$scratch:[tmp] stuff * +.sk +will cause Zip to put its temporary files in the directory +"disk$scratch:[tmp]", copying the temporary file back to the current +directory as stuff.zip when it's complete. +.!------------------------------------------------------------------------------ +.indent -4 +2 Text_Files +.br +Zip offers some options to help deal with line endings in text files. +These may have limited utility on VMS. +.sk;.literal +-l --to-crlf +.end literal;.br +Translate the UNIX end-of-line character LF (CR on MAC) into the MSDOS +convention CR-LF. This option should not be used on binary files. This +option can be used on UNIX if the Zip file is intended for PKUNZIP under +MSDOS. If the input files already contain CR-LF, this option adds an +extra CR. This ensure that "unzip -a" on Unix will get back an exact +copy of the original file, to undo the effect of "zip -l". See -ll +below for the binary checks. +.sk;.literal +-ll --from-crlf +.end literal;.br +Translate the MSDOS end-of-line CR LF into UNIX LF (CR on MAC). This +option should not be used on binary files. This option can be used on +MSDOS if the Zip archive is intended for UnZip under UNIX. +.sk +For both -l and -ll, if the file is converted and the file is later +determined to be binary, a warning is issued and the file is probably +corrupted. If Zip with -l or -ll detects binary (non-text) in the first +buffer read from a file, it issues a warning and skips line-ending +conversion on the file, avoiding corruption. This check seems to catch +all binary files tested, but the original check remains and if a +converted file is later determined to be binary, that warning is still +issued. The algorithm now being used for binary detection should allow +line-ending conversion of text files in UTF-8 and similar encodings. +.!------------------------------------------------------------------------------ +.indent -4 +2 VMS_Specifics +.br +VMS File Attributes +.sk;.literal +-V --VMS-portable +-VV --VMS-specific +.end literal;.br +The -V and -VV options cause Zip to store VMS file atributes (such as +file organization, record format, carriage control, and so on) in +VMS-specific "extra fields" in an archive along with the usual data. +These extra fields are ignored on non-VMS systems, but on a VMS system, +they allow UnZip to restore the files with their VMS attributes intact. +.sk +With -V, Zip ignores any data in the file after the end-of-file (EOF) +point (defined by FAT$L_EFBLK and FAT$W_FFBYTE), which works well for +well-formed files (that is, those with no valid data beyond EOF). +Portable-format files (Stream_LF, fixed-512) archived with -V should be +extracted properly on a non-VMS system. Files with more complex +structures, such as indexed files and files with embedded byte counts +or other such data may be of limited use on other systems. (UnZip on +non-VMS systems may be able to extract various VMS-format text files, +however.) +.sk +With -VV, Zip processes all allocated blocks for the file (including +those beyond EOF). When extracted on a VMS system, the original file +should be reproduced with as much fidelity as possible, but on a non-VMS +system, most files will be seen as corrupt because of the data from +beyond EOF. +.sk +VMS File Version Numbers +.sk;.literal +-w --VMS-versions +-ww --VMS-dot-versions +.end literal;.br +By default, for compatibility with non-VMS systems, Zip strips VMS file +version numbers from the names stored in an archive. The -w +(--VMS-versions) option causes Zip to retain file version numbers on +names in an archive. Without -w, a version number wildcard (";*") can +cause errors when multiple versions of a single file are treated as +multiple files with the same name. +.sk +For better compatibility with non-VMS systems where semi-colons are less +popular in file names, the -ww (--VMS-dot-versions) option stores the +file version numbers with a dot (".nnn") instead of a semi-colon +(";nnn"). +.!------------------------------------------------------------------------------ +.indent -4 +2 Copyright_and_License +.br +Zip has an option to display its copyright and license. +.sk;.literal +-L --license +.end literal;.br +The license is reproduced below. +.sk.lm +3 +This is version 2007-Mar-4 of the Info-ZIP license. The definitive +version of this document should be available at +ftp://ftp.info-zip.org/pub/infozip/license.html indefinitely and a copy +at http://www.info-zip.org/pub/infozip/license.html. +.lm -3;.sk +-------------------------------------------------------- +.sk +Copyright (c) 1990-2007 Info-ZIP. All rights reserved. +.sk +For the purposes of this copyright and license, "Info-ZIP" is defined as +the following set of individuals: +.sk;.lm +3 + Mark Adler, John Bush, Karl Davis, Harald Denker, Jean-Michel Dubois, + Jean-loup Gailly, Hunter Goatley, Ed Gordon, Ian Gorman, Chris Herborth, + Dirk Haase, Greg Hartwig, Robert Heath, Jonathan Hudson, Paul Kienitz, + David Kirschbaum, Johnny Lee, Onno van der Linden, Igor Mandrichenko, + Steve P. Miller, Sergio Monesi, Keith Owens, George Petrov, Greg Roelofs, + Kai Uwe Rommel, Steve Salisbury, Dave Smith, Steven M. Schweda, + Christian Spieler, Cosmin Truta, Antoine Verheijen, Paul von Behren, + Rich Wales, Mike White. +.lm -3;.sk +This software is provided "as is," without warranty of any kind, express +or implied. In no event shall Info-ZIP or its contributors be held +liable for any direct, indirect, incidental, special or consequential +damages arising out of the use of or inability to use this software. +.sk +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the above disclaimer and the following restrictions: +.sk;.lm +7;.indent -4 + 1. Redistributions of source code (in whole or in part) must retain + the above copyright notice, definition, disclaimer, and this list + of conditions. +.sk;.indent -4 + 2. Redistributions in binary form (compiled executables and libraries) + must reproduce the above copyright notice, definition, disclaimer, + and this list of conditions in documentation and/or other materials + provided with the distribution. The sole exception to this condition + is redistribution of a standard UnZipSFX binary (including SFXWiz) as + part of a self-extracting archive; that is permitted without inclusion + of this license, as long as the normal SFX banner has not been removed + from the binary or disabled. +.sk;.indent -4 + 3. Altered versions -- including, but not limited to, ports to new operating + systems, existing ports with new graphical interfaces, versions with + modified or added functionality, and dynamic, shared, or static library + versions not from Info-ZIP -- must be plainly marked as such and must not + be misrepresented as being the original source or, if binaries, + compiled from the original source. Such altered versions also must not + be misrepresented as being Info-ZIP releases -- including, but not + limited to, labeling of the altered versions with the names "Info-ZIP" + (or any variation thereof, including, but not limited to, different + capitalizations), "Pocket UnZip," "WiZ" or "MacZip" without the + explicit permission of Info-ZIP. Such altered versions are further + prohibited from misrepresentative use of the Zip-Bugs or Info-ZIP + e-mail addresses or the Info-ZIP URL(s), such as to imply Info-ZIP + will provide support for the altered versions. +.sk;.indent -4 + 4. Info-ZIP retains the right to use the names "Info-ZIP", "Zip", + "UnZip", "UnZipSFX", "WiZ", "Pocket UnZip", "Pocket Zip", and + "MacZip" for its own source and binary releases. +.lm -7;.sk +.!------------------------------------------------------------------------------ +.indent -4 +2 Acknowledgements +.br + Thanks to R. P. Byrne for his Shrink.Pas program, which + inspired this project, and from which the shrink algorithm + was stolen; to Phil Katz for placing in the public domain + the zip file format, compression format, and .ZIP filename + extension, and for accepting minor changes to the file + format; to Steve Burg for clarifications on the deflate + format; to Haruhiko Okumura and Leonid Broukhis for providing + some useful ideas for the compression algorithm; to + Keith Petersen, Rich Wales, Hunter Goatley and Mark Adler + for providing a mailing list and ftp site for the Info-ZIP + group to use; and most importantly, to the Info-ZIP group + itself (listed in the file infozip.who) without whose + tireless testing and bug-fixing efforts a portable zip + would not have been possible. Finally we should thank + (blame) the first Info-ZIP moderator, David Kirschbaum, + for getting us into this mess in the first place. +.!------------------------------------------------------------------------------ +.indent -4 +2 Bugs +.br +All bug reports, patches, or suggestions should go to zip-bugs via the +web site contact form at http://www.Info-ZIP.org. Patches should be +sent as unified or context diffs only (diff -u or diff -c). +.sk +Any bug report should include the Zip version, any special compilation +options (see "zip -v" report), the host system type and operating system +version, and any other relevant information (compiler version, lunar +phase, ...). +.!------------------------------------------------------------------------------ diff --git a/samples/RUNOFF/contributing.rnh b/samples/RUNOFF/contributing.rnh new file mode 100644 index 00000000..cbd5090e --- /dev/null +++ b/samples/RUNOFF/contributing.rnh @@ -0,0 +1,324 @@ +.na +.ll 72 +.pl 90 +.m1 4 +.m2 4 +.m3 6 +.m4 6 +.sp 8 +.ds +.ce +CONTRIBUTING TO LINGUIST +.sp +.ce +by +.ce +GITHUB +.sp +.ce +and the +.sp +.ce +OPEN SOURCE COMMUNITY +.sp +.bp +.sp 5 +.ce +_I_N_T_R_O_D_U_C_T_I_O_N: +.sp + Hi there! We're thrilled that you'd like to contribute to this +project. Your help is essential for keeping it great. This project +adheres to the Contributor Covenant Code of Conduct. By participating, +you are expected to uphold this code. +.br +The majority of contributions won't need to touch any Ruby code at all. +.sp 5 +.ce +_A_d_d_i_n_g _a_n _e_x_t_e_n_s_i_o_n _t_o _a +_l_a_n_g_u_a_g_e +.sp + We try only to add new extensions once they have some usage on +GitHub. In most cases we prefer that extensions be in use in hundreds of +repositories before supporting them in Linguist. +.sp +To add support for a new extension: +.sp +.in 5 +.un 5 +1. Add your extension to the language entry in +_l_a_n_g_u_a_g_e_s_._y_m_l, keeping the extensions in +alphabetical order. +.br +.un 5 +2. Add at least one sample for your extension to the samples directory +in the correct subdirectory. +.br +.un 5 +3. Open a pull request, linking to a GitHub search result showing +in-the-wild usage. +.in 0 +.sp +In addition, if this extension is already listed in +_l_a_n_g_u_a_g_e_s_._y_m_l then sometimes a few more steps +will need to be taken: +.sp +.in 5 +.un 5 +1. Make sure that example .yourextension files are present in the +samples directory for each language that uses .yourextension. +.br +.un 5 +2. Test the performance of the Bayesian classifier with a relatively +large number (1000s) of sample .yourextension files. (ping @arfon or +@bkeepers to help with this) to ensure we're not misclassifying files. +.br +.un 5 +3. If the Bayesian classifier does a bad job with the sample files +then a heuristic may need to be written to help. +.in 0 +.sp 5 +.ce +_A_d_d_i_n_g _a _l_a_n_g_u_a_g_e +.sp + We try only to add languages once they have some usage on GitHub. +In most cases we prefer that each new extension be in use in hundreds of +repositories before supporting them in Linguist. +.sp +To add support for a new language: +.in 5 +.un 5 +1. Add an entry for your language to +_l_a_n_g_u_a_g_e_s_._y_m_l. +.br +.un 5 +2. Add a grammar for your language. Please only add grammars that have +a license that permits redistribution. +.br +.in +5 +.un 5 +i. Add your grammar as a submodule: +.br +.in +4 +git submodule add +https://github.com/Alhadis/language-roff +vendor/grammars/language-roff +.in -4 +.un 5 +ii. Add your grammar to grammars.yml: +.br +.in +4 +script/convert-grammars --add vendor/grammars/MyGrammar +.in -4 +.un 5 +iii. Download the license for the grammar by running script/licensed. +Be careful to only commit the file for the new grammar, as this script +may update licenses for other grammars as well. +.br +.in -5 +.un 5 +3. Add samples for your language to the samples directory in the +correct subdirectory. +.br +.un 5 +4. Open a pull request, linking to a GitHub search result showing +in-the-wild usage. +.br +.in 0 +.sp +In addition, if your new language defines an extension that's already +listed in _l_a_n_g_u_a_g_e_s_._y_m_l (such as `.foo`) then +sometimes a few more steps will need to be taken: +.sp +.in +5 +.un 5 +1. Make sure that example .foo files are present in the samples +directory for each language that uses .foo. +.br +.un 5 +2. Test the performance of the Bayesian classifier with a relatively +large number (1000s) of sample `.foo` files. (ping @arfon or @bkeepers +to help with this) to ensure we're not misclassifying files. +.br +.un 5 +3. If the Bayesian classifier does a bad job with the sample .foo +files then a heuristic may need to be written to help. +.br +.in 0 +.sp +Remember, the goal here is to try and avoid false positives! +.sp 2 +.ce +_F_i_x_i_n_g _a _m_i_s_c_l_a_s_s_i_f_i_e_d +_l_a_n_g_u_a_g_e +.br + Most languages are detected by their file extension defined in +_l_a_n_g_u_a_g_e_s_._y_m_l. For disambiguating between +files with common extensions, linguist applies some heuristics and a +statistical classifier. This process can help differentiate between, +for example, .h files which could be either C, C++, or Obj-C. +.sp + Misclassifications can often be solved by either adding a new +filename or extension for the language or adding more samples to make +the classifier smarter. +.sp +.m4 -2 +.ce +_F_i_x_i_n_g _s_y_n_t_a_x +_h_i_g_h_l_i_g_h_t_i_n_g +.br + Syntax highlighting in GitHub is performed using +TextMate-compatible grammars. These are the same grammars that TextMate, +Sublime Text and Atom use. Every language in languages.yml is mapped to +its corresponding TM `scope`. This scope will be used when picking up a +grammar for highlighting. +.sp + Assuming your code is being detected as the right language, in most +cases this is due to a bug in the language grammar rather than a bug in +Linguist. _g_r_a_m_m_a_r_s_._y_m_l lists all the grammars +we use for syntax highlighting on github.com. Find the one corresponding +to your code's programming language and submit a bug report upstream. +.sp +If you can, try to reproduce the highlighting problem in the text editor +that the grammar is designed for (TextMate, Sublime Text, or Atom) and +include that information in your bug report. +.sp + You can also try to fix the bug yourself and submit a Pull Request. +TextMate's documentation offers a good introduction on how to work with +TextMate-compatible grammars. You can test grammars using Lightshow. +.sp + Once the bug has been fixed upstream, we'll pick it up for GitHub +in the next release of Linguist. +.sp 2 +.ce +_T_e_s_t_i_n_g +.br + For development you are going to want to checkout out the source. +To get it, clone the repo and run Bundler to install its dependencies. +.sp +.in 4 +git clone https://github.com/github/linguist.git +.br +cd linguist/ +.br +script/bootstrap +.br +.in 0 +.sp +To run the tests: +.sp +.in 4 + bundle exec rake test +.in 0 +.sp + Sometimes getting the tests running can be too much work, especially +if you don't have much Ruby experience. It's okay: be lazy and let our +build bot Travis run the tests for you. Just open a pull request and the +bot will start cranking away. +.sp +.ce +_M_a_i_n_t_a_i_n_e_r_s +.br +Linguist is maintained with love by: +.sp +.in -2 +- @arfon (GitHub Staff) +.br +- @larsbrinkhoff +.br +- @pchaigno +.in 0 +.br +.sp +As Linguist is a production dependency for GitHub we have a couple of +workflow restrictions: +.sp +.in -2 +- Anyone with commit rights can merge Pull Requests provided that there +is a :+1: from a GitHub member of staff +.br +- Releases are performed by GitHub staff so we can ensure GitHub.com +always stays up to date with the latest release of Linguist and there +are no regressions in production. +.in 0 +.sp +.ce +_R_e_l_e_a_s_i_n_g +.sp +If you are the current maintainer of this gem: +.sp +.in 5 +.ul 5 +1. Create a branch for the release: +.sp +.in +2 +git checkout -b cut-release-vxx.xx.xx +.in -2 +.sp +.ul 5 +2. Make sure your local dependencies are up to date: +.sp +.in +2 +script/bootstrap +.in -2 +.sp +.ul 5 +3. If grammar submodules have not been updated recently, update them: +.sp +.in +2 +git submodule update --remote _&_& git commit -a +.in -2 +.sp +.ul 5 +4. Ensure that samples are updated: +.sp +.in +2 +bundle exec rake samples +.in -2 +.sp +5. Ensure that tests are green: +.sp +.in +2 +bundle exec rake test +.in -2 +.sp +.ul 5 +6. Bump gem version in lib/linguist/version.rb +.br +.ul 5 +7. Make a PR to github/linguist +.br +.ul 5 +8. Build a local gem: `bundle exec rake build_gem` +.br +.ul 5 +9. Test the gem: +.sp +.in +5 +.un 5 +i. Bump the Gemfile and Gemfile.lock versions for an app which relies +on this gem +.un 5 +ii. Install the new gem locally +.un 5 +iii. Test behaviour locally, branch deploy, whatever needs to happen. +.br +.in -5 +.sp +.ul 5 +10. Merge github/linguist PR +.sp +.ul 5 +11. Tag and push: +.sp +.in +2 +git tag vx.xx.xx; +.br +git push --tags +.in -2 +.sp +12. Push to rubygems.org +.br +.in +2 +gem push github-linguist-3.0.0.gem +.in -2 +.sp 2 diff --git a/samples/RUNOFF/longlib.rno b/samples/RUNOFF/longlib.rno new file mode 100644 index 00000000..5049f8ae --- /dev/null +++ b/samples/RUNOFF/longlib.rno @@ -0,0 +1,8644 @@ +.! documentation for the LONGLIB graphics routines and library +.! *** LAST REVISED ON 16-MAR-1988 08:22:32.49 +.! *** SOURCE FILE: [DL.GRAPHICS.LONGLIB]LONGLIB.RNO +.lm0.rm66.ps59,66 +- +.s12 +.flags index ~ +.c;The LONGLIB Graphics Library +.s2 +.c;Version 5.1 +.s3 +.flags substitute +.c;$$Month#$$Day,#$$Year +.no flags substitute +.no flags accept +.s5 +.c;David Long +.s1 +.c;Jet Propulsion Laboratory +.c;4800 Oak Grove Drive +.c;Pasadena, California 91109 + +.pg +.! note: TOC stuff is for VMS 3.x and is not required for VMS 4.0 +.style headers 6 +.send TOC .layout 1,3 +.send TOC .rm 70 +.send TOC .display number rl +.send TOC .c;Table of Contents +.send TOC .sk + +.require "LONGLIB.RNT" +.display number d +.lm0.rm66.ps59,66 + +.pg.f.j +.s3 +.CHAPTER Introduction + +.hl 1 General +.p +This manual was prepared to document the LONGLIB graphics library. +This latest revision of the library has been extensively modified though +every effort has been made to make any changes or additions to the library +compatible with previous versions of the LONGLIB graphics library. +It is anticipated that additional MASTER subroutines will be incorporated +in the future as they are needed. +.p +The LONGLIB graphics library is a set of FORTRAN subroutines for vector +plotting (line graphics). The library is similar to CALCOMP; +however, a great many extensions +are incorporated into the LONGLIB library including viewport +clipping, plot rotation, etc. In addition, +the LONGLIB library includes a large set of routines +for such things as 3-d plotting (with hidden line removal), extended character +sets, MASTER routines, graphics input routines, map routines, etc. +.p +The LONGLIB library is designed with three internal packages for plotting +on 3 major classes of output graphics devices: graphics terminals, +Ramtek display screens, and hardcopy devices via metafiles. +A large variety of graphics terminals are supported. Graphics output +to each type of device is discussed below. LONGLIB achieves virtual +output device independence by using only a minimum of low-level commands. +These include: initialization, a screen clear/new page command, +and drawing a vector. In addition, line types and color are utilized if +available. Graphics terminal and Ramtek output also support additional +features. Hardcopy devices which require rasterization are also supported +using the Metafile. +.p +The library is principally designed for vector (i.e. line plotting). +Lines are drawn by specifying the movement of an "electronic pen". +The color, width, and pattern of up/down motions in a line (the +line type) may be specified. The library consists of various subroutines which, +when called by a user written program, will produce line drawings on the desired +graphics device(s). The system is interactive in the sense that +the user can see and modify plots immediately (on screen devices). +The library can also produce a ~metafile which can then be processed by +programs supplied with the LONGLIB library to produce +hardcopy output on a variety of hardcopy devices. +Provisions have been incorporated for device-dependent graphics input to a +program (see ~CURSOR routines). +.p +The library is designed with several levels of graphics routine users in mind. +For the user who simply wants to obtain a plot of an array of data with a +minimum of effort, the ~MASTER routines offer a simple solution. These routines +handle opening/closing the plot package, scaling, and axis generation, etc, +a wide variety of formats. +For the user interested in more elaborate plots, access to several levels +of the plotting routines are provided. +.x LINSEQ +.x line type +.x color +.p +The LONGLIB graphics library supports both line type (such as +pen width and dot-dash patterns) and color attributes. In general, these +attributes are device dependent and specific line types or colors used on +one plotting device may appear differently on a second device. +Typically, line width is simulated for graphics terminals while line +typing relies on hardware support. A routine for software generation +of line types (LINSEQ) has been provided. + +.hl1 Machine Dependence +.x machine dependent +.p +LONGLIB was developed in a ~VAX/VMS environment and is written exclusively +in FORTRAN. While some machine-specific routines have been retained, +the present version of the library has been made as ~FORTRAN-77 compatible +as practical. Where the code is not FORTRAN-77 compatible, it is so noted +in the source code. These exceptions +were made for efficiency's sake and can be easily be modified or +be left out of the final library. The largest FORTRAN-77 incompatibilities +(outside of the Ramtek packages) occur when treating ~character ~string data +(see notes below). +.p +The auxilary, MASTER, and 3d plotting routines are FORTRAN-77 compatible +with a few minor exceptions (e.g. ~INTEGER*2 is used to save space +and some routine names exceed 6 characters). These exceptions +are noted in the source code file headers. +Routines in ~RAMLIB and ~REFLIB tend to be very machine specific +and may require extensive modification for use on other machines. +Unless specificially stated, integers are all assumed to be the standard +default machine length. On the ~VAX this is INTEGER*4. A 2's complement +representation is assumed for negative integers when specifying the +line type bit pattern (various routines and programs) and in storing the +pen motion data in the routines SYMBOL, SYM3D, and SYM3DH. +.x INTEGER*4 +.p +Some machine dependent constructs are used in the library for detection +of missing (and/or default) parameters (mainly in SYMBOL, NUMBER, +and AXIS ROUTINES). These can easily be modifed and/or adapted for +other machines. +.p +Note that when a subroutine is called with a Hollerith constant, +CALL SUB('string'), +~VAX ~FORTRAN passes the string as a ~BYTE array of ascii values. (see the +VAX FORTRAN User's Guide). ~CHARACTER variables are passed using a +different mechanism and can not be substituted. +If you wish to use a CHARACTER variable, use the %REF() function. i.e., +use CALL SUB(%REF(CHARACTER_VARIABLE)). +.x %REF() +.x character +.x byte +.p +The ~VAX extended ~FORTRAN data type "BYTE" (for an 8 bit variable) is used +in the REF and Ramtek library package. The terminal output +is via a WRITE(*,) command. +The ~cursor routines CURMOTION, CURRECT, CURBAND use the machine dependent +routine ~INXTCHR to read escape sequences from the terminal. +Note, however, that the library can be used without these cursor routines. +.x %loc() +.P +A ~VAX routine %LOC() is used in ~MVAX5D and ~VAX5D to determine the +address of an array. These routines may be modified or deleted as desired. +.p +The library contains files for VAX environment help libraries, etc. These +files can be deleted if not used. + + +.hl1 Using Longlib with Graphics Terminals +.p +One of three internal, separate packages used by LONGLIB is the +terminal screen graphics package. +The LONGLIB graphics library supports a variety of graphics ~terminal +devices which use ~Tektronix graphics formats including: +.x Selanar +.x vt100 +.x vt125 +.x vt240 +.s1 +.ls0 +.le;VT100 equipped with a Selanar GR100 or GR100+ +(Selanar Corporation, Santa Clara, Ca.) +.le;VT125 (VT100 + retrographics) +.le;VT240 and compatibles +.le;VT220 equipped with a Selanar SG220 +.le;Tektronix 4010/4014 and compatibles +.le;Tektronix 4107/4109 and compatibles +.le;Graphon GO-235 +.els +.s1 +.x PLOTVT +.x vtplot +.x newvpen +.x newvcol +Other graphics terminals can be used by appropriate modification of the +terminal driver routines (CTERM, VTPLOT, NEWVPEN, NEWVCOL). The routines +~FRAME and ~VPLOTS will also need to be modified. +Escape sequences need for terminal initialization and mode switching are +handled in the subroutine CTERM. +When plotting is not done to the terminal ~CTERM and other terminal +specific routines are +a dummy call. Note: plotting to the terminal is done by accumulating +a set of connected line segments created by ~PLOT or PLOTVT. +The line segments +are output to ~terminal only when the buffer length of 32 is exceeded or +a "pen up" occurs. +Consequently, a "pen up" should be issued to force all stored plot segments +to be output to the terminal prior to viewing screen. +.p +It is assumed that all terminals are configured in a standard fashion. +Because of the wide variety of terminal types, the specific settings +will not be given in this document. +.p +In designing the terminal driver routines, the design philosophy has been +to take advantage of the capability that many graphics terminals have to +display both text and graphics independently on the screen. That is, +the text and graphics "screens" can be independently cleared, etc. +This feature is heavily exploited in this library. +Of course not all terminals support this feature. +Terminals such as the VT240 and Tektronix 4010's do not support this feature. +In this case, the ~CTERM routine operates somewhat differently in that +it sets the terminal to graphics mode and leaves it there. +.p +Note that in the VAX environment, the SET TERM options of the terminal +driver must be properly configured. For example, +you must execute a SET TERM/FORM while in ~DCL to enable the screen clear +command to work properly. This permits a form feed to pass through to the +terminal. The NO ESCAPE qualifier should also be set to read from the +terminal. +.p +A command file, LONGLOC:CLEAR.COM, +has been provided which, when executed, will clear the screen of a VT100 +equipped with a ~Selanar card and set the ~VT100 into text mode. A simliar +routine for a ~VT125 (TCLEAR.COM) and a VT220 (VCLEAR.COM) is also provided. +These reset the graphics mode back to terminal mode and clear the screens. +The are very helpful during program development. +.p +LONGLIB also supports color on graphics terminals which permit color +plotting. + +.hl 2 Terminal Specific Application Notes +.p +The following sections describe the operation of the LONGLIB graphics +routines with some specific graphics terminal types. This list is +not comprehensive. + +.hl 3 VT100 (w/Selanar Graphics Cards) +.p +A reference to a VT100 indicates a VT100 equipped with a Selanar +equipped (GR100, or GR100+) VT100. +A SG100 equipped VT100 has three modes: the terminal (VT100) mode, the Selanar +terminal mode, and the Selanar graphics mode. The routine ~CTERM is used +to switch the terminal between modes. A call to ~FRAME +will set the mode to the Selanar terminal mode. Whenever a line is +plotted to the screen the mode is change to Selanar graphics and then +back to the Selanar terminal mode. If a program error occurs when the terminal +is in the Selanar graphics mode, it is possible to not see +any output. Running the ~CLEAR command file will reset the mode back +to terminal. The Selanar card does not provide linetypes or XOR capability +in the 4010 operation mode. + +.hl 3 VT125 +.p +A ~VT100 upgraded with the DEC upgrage package to a VT125 has two +modes used by the LONGLIB library: the normal terminal mode, and the +Tektronix 4010 graphics mode. Both text and graphics can be displayed +on the same screen but independently manipulated by swithing between +modes. +Running the ~TCLEAR command file will reset the mode back to terminal. + +.hl3 VT240 +.p +Unlike other terminals, the ~VT240 when switched between terminal modes +clears the screen. Thus CTERM sets the terminal mode to the Tektronix +4010 mode when terminal graphics are initiated. The mode is not changed. +Limited linetypes are supported though XOR plot mode is not. + +.hl 3 VT220 (w/Selanar Graphics Card) +.p +Reference to a ~VT220 terminal is intended to indicate a VT220 terminal +equipped with a Selanar SG220 graphics upgrade board. +The SG220 board operates through the VT220's printer port. In +addition, it uses some of the keys on the VT220 keyboard. It is possible +to enable the graphics board when the printer port is disabled. This causes +some of the keys (notably the keypad and cursor keys) to not work for editing, +etc. To correct this, deselect the graphics board using CNTRL-SELECT. +.p +In order for the graphics board to plot graphics commands from the library +routines, the printer port must be +in the controller mode and the board enabled. All this is automatically +handled by the LONGLIB graphics library routines. Note, however, that +you will need to use the CTERM commands correctly to obtain proper operation. +.p +The DCL command file ~VCLEAR will reset printer port, clear the graphics +card and terminal the screens under most situations. +.x getcursor +.p +When using GETCURSOR, a large cross-hair will appear on the screen. +Use the cursor keys and the shift key to move the intersection point to +the desired location and press a key. This ends the graphics input. +The cross-hair will disappear, there will be a pause, and the program +will continue. NOTE: DON'T USE THE RETURN KEY TO END GRAPHICS INPUT AS +THIS WILL CAUSE THE PROGRAM TO NOT READ THE LOCATION AND MESS UP YOUR +TYPE-AHEAD BUFFER. +.p +The SG220 board stores the starting and ending points of each vector in memory +then dynamically redraws the screen for each refresh (this is how it can do +zooming and windowing). However, this also limits the number of vectors +that can be drawn on the screen at once. +If a very large number of vectors are plotted, a zoom in/out may cause +a portion of them to not reappear. +.p +Note: Since the actual SG220 screen resolution is only 832x350 +and the board is emulating a Tektronix 4014 (4096x3200) there is some +quantization error associated with the cross-hair operation. +.p +Note: When the manual zoom in/out feature is used +the cross-hair cursor does not work properly. The cross-hair is initially +plotted then erased. When you move the cross-hair, it is replotted. +A copy of the cross-hair stays at the start location. Otherwise, it is +useable. + +.hl 3 Tektronix 4010/4014 Compatible Terminals +.x 4010 +.x 4014 +.p +A generic ~Tektronix 4010/4014 compatible terminal is defined in LONGLIB. +Linetypes are supported. +Since most ~Tektronix 4010/4014 compatible terminals do not support +dual text/graphics screens, this feature +is unavailable. + +.hl 3 Tektronix 4107/4109 Compatible Terminals +.x 4107 +.x 4109 +.p +The ~Tektronix 4107/4109 terminals support a dual (text and graphics) +screen mode which is exploited by LONGLIB. Most of the advanced features +available on these terminals are not exploited. Color and linetypes +are supported. The command file ~TEKCLR (executed from DCL) +can be used to clear the screen +and reset the terminal into the ANSI mode. + +.hl 3 Graphon Terminals +.p +The ~Graphon GO-235 is a terminal compatible with a VT100/VT200 and +Tektronix 4014. It permits both text and graphics on the same screen +in separate planes when properly configured. This configuration is +assumed by the LONGLIB graphics library. The Graphon terminal supports +linetypes, graphics input, and XOR plot mode. +A command file GCLEAR (executed +from DCL) is provided to clear the screen and reset the text mode. + +.hl1 The LONGLIB Metafile (Hardcopy Output) +.p +The second internal package used by LONGLIB is the ~metafile or +printer history file package. +The library can optionally produce a plot metafile containing +scaled, clipped pen motion commands. This "history" file +can be processed by other programs to produce hardcopy output on the +appropriate device. Using the ~REPLOT program, the plot history file can +be redisplayed on a screen device. Raster scan converter programs produce +a dot-image printable file from the metafile for printing to a dot matrix +printer. Other metafile processing programs convert the LONGLIB metafile +to other graphics description languages including POSTSCRIPT, HPGL, QUIC, etc. +.x postscript +.x hpgl +.x quic +.x stripping +.x strips +.p +Many of the LONGLIB metafile processing programs permit "striping" of the +graphics image. When the graphics image contained in the LONGLIB metafile +exceeds the size of a single page (or whatever) of the output device, the +the metafile image is "cut" into "strips" which fit on the output page. +Then each page is output. Normally, blank pages are suppressed. At the +same time redundant pen motions, changes, etc. are filtered out. + +.hl 2 Dot Matrix Printers +.x raster scan +.x dot matrix printers +.p +Dot matrix printers, in general, require graphics data in a bit-image +image format. This requires converting the LONGLIB metafile pen +motion file into a bit-image file using a raster scan process. +Using one of the supplied raster scan converter programs, the LONGLIB +metafile can be processed to produce a printable file of graphics for +several types of dot matrix printers. The raster scan converter programs +supports linetypes and widths. Currently, raster scan +converter programs which including "stripping" exist for the following +printers: +.s1 +.ls0 +.le;Printronix +.le;Trilog TIP-300 +.le;DEC LA50 (or compatible) +.els +.p +The raster scan converter programs using "stripping" with a strip +size which depends on the printer. Ordinarily the strip is 56.5 by +13.2 inches (or the width of the printer page). +To generate a raster scan data file suitable for printing on a +dot matrix printer from the vector plot command file, the +raster scan converter program must be used. Versions of this +program exist for ~LA50 printers (LA50), ~Printronix printers +(PRNTRX), and ~Trilog Printers (TRILGLO or TRILGHI--see below). +.p +Two raster scan programs have been provided for the +~Trilog printer to take advantage of its higher printing resolution. +~TRILGLO prints the same resolution on the Trilog printer as on the +Printronix printer. ~TRILGHI plots at almost twice the across-the-page +resolution and the same down-the-page resolution. Execution time is longer +for the high resolution program. +.x raster scan conversion +.p +An example of the use of the TRILGLO program in the ~VAX environment +follows. The LONGLIB metafile input is FOR003.DAT. The output +is OUT.LIS. +.lit + + $ TRILGLO :== $LONGLOC:TRILGLO + $ TRILGLO FOR003.dat ! run raster scan converter + $ print/que=Trilog OUT.LIS ! print output + +.end lit +.p +~VAX ~DCL command files in the directory pointed to by the logical name +LONGLOC: contain command files for execution of these commands. +(PLOT183.COM = printronix printer, PLOTLO.COM = trilog printer lo-res +PLOTHI.COM = trilog printer hi-res). + +.hl 3 Subprocesses +.p +Two subroutines have been provided to spawn a subprocess from +a FORTRAN program (in a ~VAX ~VMS environment) to execute the raster scan +converter programs. + +.hl4 SUBROUTINE PSUBPRO +.lit +CALL PSUBPRO(i,opt,ip) + +i (I): raster scan conversion program type + = 0 printronix printer + = 1 low res trilog printer + = 2 hi res trilog printer +opt (I): concurrent process option + = 0 wait for completion + = 1 no wait +ip (I): print flag + = 0 do not print + = 1 print + +.end lit +~PSUBPRO creates a ~subprocess using ~SUBPROC to run the raster scan conversion +program. PSUBPRO should be used with FOR003.dat file after the plot package +has been closed. The output is OUT.LIS which can be printed if desired. +The command files used are located in LONGLOC:. + +.hl 4 SUBROUTINE SUBPROC +.lit +CALL SUBPROC(in,out,i) + +in (C) : input command file name (CHARACTER variable) +out (C) : output log file (CHARACTER variable) +i (I) : concurrent processing option + = 0 wait for completion + = 1 no wait +.end lit +.p +~SUBPROC creates a ~subprocess which executes the command file IN. The output +is places in the file OUT (if OUT is NL: the output is discarded). + +.hl2 HPGL Compatible Pen Plotter +.x pen plotter +.p +Metafile conversion programs which convert the LONGLIB metafile into +an HPGL (~Hewlett-Packard graphics language) command data file +are included in LONGLIB. Three programs are available, HPGL, HPGL2, +and HPGLS. +.p +~HPGL reads the LONGLIB metafile, processes it into appropriate commands +and sends the commands to the terminal printer port (either a VT100 or VT220 +compatible terminal or a VT100 equipped with a Selanar GR100 graphics board) +to which is connected +an HPGL-compatible pen plotter. No "stripping" of the image is done. +The user is prompted for page changes. +Pen changes on the plotter occur in response to a color change in the +metafile. Line types are supported but line widths are ignored. +.p +~HPGL2 reads the LONGLIB metafile and produces a separate output file of HPGL +commands for each page of LONGLIB metafile input. HPGL2 does not +include "stripping" of the image. HPGL2 plots all of the vectors of a +given color before changing +pens. Line types are supported but line widths are ignored. +.p +~HPGLS is similar to HPGL2 but includes stripping of the image. +HPGL2 produces a separate output file of HPGL commands for each strip +and page of LONGLIB metafile input. +.p +An example of the use of the HPGL2 program in the ~VAX environment +follows. The LONGLIB metafile input is FOR003.DAT. The output +is a file, OUT.LIS which can then be sent to an HPGL-compatible plotter. +.lit + + $ HPGL2 :== $LONGLOC:HPGL2 + $ HPGL2 FOR003.dat ! run HPGL conversion program + ! several out.lis files may be produced + $ print/que=HPGL out.lis;* ! send output file(s) to plotter +.end lit + +.hl2 QMS QUIC Laser Printer +.p +Three programs, LASER, LASERS, and RLASER, are included to convert the +LONGLIB metafile into a printable file in the ~QMS ~QUIC laser printer +control language. +Line width and line types are supported though color is not. +Programs LASERS and RLASER "strip" the metafile into 8.5 by 11 page strips +while LASER does not do stripping. +~LASER and ~LASERS produce +a full size, normal orientation output, while ~RLASER scales the output +by 3/4 and rotates the page -90 deg. +.p +An example of the use of the LASER program in the ~VAX environment +follows. The LONGLIB metafile input is FOR003.DAT. The output +is OUT.LIS. +.lit + + $ QMS :== $LONGLOC:LASER + $ QMS FOR003.dat ! run QMS metafile conversion + $ print/que=QMSLASER OUT.LIS ! print output to printer +.end lit + +.hl2 PostScript +.x applewriter +.p +A program titled ~POSTSCRIPT is included which will convert the LONGLIB +meta file into a PostScript page language format. This can then be printed +to PostScript compatible printer (such as an AppleWriter). No "strips" +are used. Linetypes and width are supported. Input color changes +are output as grey tones. +.p +An example of the use of the POSTSCRIPT program in the ~VAX environment +follows. The LONGLIB metafile input is FOR003.DAT. The output +is OUT.LIS. +.lit + + $ POST :== $LONGLOC:POSTSCRIPT + $ POST FOR003.dat ! run POSTSCRIPT conversion + $ print/que=POSTSCRIPT OUT.LIS ! print output to printer +.end lit + + +.hl 2 Plotting the LONGLIB Metafile to a Screen Device +.p +A program ~REPLOT has been provided which will read the LONGLIB ~metafile +created by an eariler program and plot the file to a screen +device (terminal or Ramtek). This program may be run from DCL in the +VAX environment by: +.lit + + $ REPLOT :== $LONGLOC:REPLOT + $ REPLOT + +.end lit +Note that the default meta file name is FOR003.DAT. + +.hl1 Plotting on the RAMTEK Screen Graphics Device +.x ramtek emulation +.x ref +.p +The third internal package (which will not be available in some +installations) used by LONGLIB is the ~Ramtek Screen display package. +The plotting device is the Ramtek family of displays. +Currently, only some (but not all) of the +functions of the Ramtek 9460 (1280x1024) or 9050 (512x512) +Ramtek screen display are supported. +The Ramtek screen display can be replaced by the +Ramtek Emulation File (REF) package which simulates the Ramtek display +as an internal image array. The LONGLIB library can be configured without +the Ramtek package. +.x rplots +.x PLOTRM +.p +The Ramtek package is initialized by a call to ~FRAME (which calls RPLOTS). +When the Ramtek package is not being used, calls to Ramtek routines +are dummy calls. Note: plotting to the Ramtek is done by accumulating +a sequence of connected line segments (defined by ~PLOT or PLOTRM) +in a storage buffer. The line segments are output to the +~Ramtek only when the buffer length of 128 is exceeded or a "pen up" occurs. +Consequently, a final "pen up" should be issued to make all plot segments +are output to the display prior to viewing screen. +.p +The current version of the software drivers for the Ramtek display are +machine specific to VAX/VMS. The ~REF subpackage uses some ~VAX FORTRAN +specific constructs (for efficiency) but could easily be modified for +other machines. +.x vax/vms +.p +~Ramtek display drivers expects the logical name "RM" be assigned to Ramtek +device (example: assign RMA0: RM:). +When the Ramtek device supports multiple diplays, interaction between the +displays complicates matters. To distiguish between different displays on +the same device it is suggested that the 0th device be named xxx0:, second +device xxx1:, etc. +~Color plotting is done on the Ramtek using the previously loaded color table. +The LONGLIB "color" is the color table index. +The default Ramtek color table index is 255. The main LONGLIB package +uses only vector plotting. However, auxilary routines have been included +which permit writing image mode data to the Ramtek (or REF) and for +color table manipulation (see RMWRITEWORD or RMWRITECOL). +.x RMWRITEWORD +.x RMWRITECOL +.p +The Ramtek supports line types and scale factors but simulates line widths. + +.hl2 Ramtek Emulation File Plotting +.x ramtek emulation file +.x REF +.p +When a Ramtek display is not available or +for off-line plotting to a "simulated" Ramtek device, a set of routines +known as the ~Ramtek Emulation File (REF) routines can be used. +These routines replace the Ramtek communications routines (RAMLIB) in +a version of the LONGLIB graphics library named LONGLIBR.OLB. This software +emulates many (but not all) of the important functions of the Ramtek +communication routines to a 9460 or 9050 Ramtek +display using an internal byte array. +.p + +.hl 3 Using the REF Routines +.x RMWRITEWORD +.p +To use the REF routines, link to the LONGLIBR version of the LONGLIB library, +and plot to the Ramtek device. +The REF routines use a 1280x1024 BYTE array as the simulated Ramtek +display. Each byte of the array stores the color table index for each +pixel of the simulated Ramtek display. An empty "screen" consists +of all zeros. When a line is drawn to the +display using ~PLOT or ~PLOTRM the appropriate pixel bytes are set +to the line color. REF routines also permit image mode writing/reading +of horizontal or vertical lines of bytes (see RMWRITEWORD, for example). +When the plot package is closed (by a call to PLOTND) the user will be +prompted to output the internal BYTE array to a specific +device (a graphics terminal, a metafile, or a special REF file). To +avoid the interative prompt, the user can call ~REFDIS (with its appropriate +arguments) prior to the ~PLOTND call. This will disable the prompts. +See REFDIS for additional details. +.p +Note: the Ramtek color table routines and cursor routines are dummy calls +when using the REF routine library. + +.hl3 REF File Output +.p +The REF file consists of a direct access file with a record length of +one horizontal line of pixels. The number of records and record size +depends on the type of Ramtek chosen (RECL=1280, 1024 records for the +large Ramtek and RECL=512, 512 records for the small Ramtek). +REFDIS places each horizontal line of the output array into each +record of the REF file. +The REF file can subsequently be read by the ~REFTERM program and +plotted to the "real" Ramtek device. To produce a hardcopy output +of the REF file on a ~QMS laser printer, the program ~REFLAS reads +the file and produces a simulated gray scale image with 4 grey levels. +REFLAS prompts the user for the appropriate inputs. In the ~VAX/VMS +environment, the program ~REFLAS2 can be used. REFLAS2 provides significantly +faster run times by using the VAX paging utility and downloadable fonts. + +.hl3 REF Terminal or Metafile Output +.p +When outputing the byte array data to a terminal or printer history file, +the array is converted to a series of horizontal vectors. As the array +scanned left to right, top to bottom, all ajacent pixels of the same color +are combined into a single vector. When a pixel of a different color is +encountered the vector is output. Pixels of color "0" (background) are +not output. +See REFDIS for additional details. + + +.hl 1 Library Location +.p +All LONGLIB libraries, source files, and support programs are located in +the same directory. In the ~VAX environment, +The logical name ~LONGLOC: should be assigned to be this directory, i.e., +.lit + + $ assign disk:[directory] LONGLOC: +.end lit +.p +The LONGLIB object library is self contained. In order to link to the +normal library use the command (see also the shareable image library +section below), +.lit + + $ link ,LONGLOC:LONGLIB/LIB + +.end lit +If your installation has a Ramtek display, this link command will include +the Ramtek display routines. If your installation does not have a Ramtek +display, this link command will include only dummy routines for Ramtek +routines. In order to link to the REF version the library (which is normally +available on every installation) use the LONGLIBR.OLB object library, +.lit + + $ link ,LONGLOC:LONGLIBR/LIB +.end lit + +.hl 2 LONGLIB Source Code +.p +.x source code +.x FORTRAN +.X C +The source code for LONGLIB is all in FORTRAN and is included +in the distribution package. +Source code may be found in the following files: +.lit + +LONGLIB.FOR (device dependent routines) +AUXLIB.FOR (auxilary device independent routines) +MLIB.FOR (MASTER routines) +MLIB2.FOR (more MASTER routines) +HIDELIB.FOR (3-d hidden line routines) +LONGLIB3D.FOR (3-d w/no hidden lines) +RAMLIB.FOR (Ramtek communication code) +MAPLIB.FOR (map routines) +CURSORLIB.FOR (cursor routines) +REFLIB.FOR (Ramtek emulation file routines) +etc. +.end lit +.p +In addition, the LONGLIB support program such as the example programs, +metafile processing programs, etc., are located in LONGLOC:. + +.hl1 User Notes -- VAX/VMS Environment +.p +In the ~VAX/VMS environment LONGLIB provides an on-line help library +accessable from either a user program or DCL as well as a shareable +image library. + +.hl2 Using the LONGLIB VAX/VMS On-line HELP Library +.x help library +.p +In the ~VAX/VMS environment an on-line ~help library is available in addition to this +documentation. The On-line help library can be accessed from ~VAX DCL by, +.lit + + $ HELP @LONGLIB +or + $ HELP @LONGLOC:LONGLIB.HLB + +.end lit +.x helpme +A subroutine for accessing the library is also included +in the LONGLIB package HELPME. From a user program calling HELPME with +a ~CHARACTER string corresponding to the initial help string will call +the VAX librarian for an interactive search through the LONGLIB help library. + +.hl2 Using the LONGLIB VAX/VMS Shareable Image Library +.p +A shareable image library for the ~VAX/VMS may be created for the LONGLIB +graphics library. To obtain the most advantage from using the shareable +image library, the library must be "installed" by the system manager. +Not all installations will have an installed LONGLIB library. +Linking to the shareable image library +(LONGLIB.EXE rather than LONGLIB.OLB) produces executable files which +are small and run faster. +The main difference is in how they are linked. To link to the "normal" +library, +.lit + + $ LINK your_file_name.OBJ,LONGLIB/LIB + +.end lit +To link to the shareable image library you have to use a linker option +file: +.lit + + $ LINK your_file_name.OPT/OPT + +where your_file_name.OPT contains: + + your_file_name.obj,LONGLIB/SHARE + +or you may use the longlib linker option file: + + $ LINK your_file_name,LONGLIB/OPT + +.end lit +This second option for the linker option file is the easiest to use. +Note that the LONGLIB/OPT should be last on the link list. On most +installations, the REF version of the library, LONGLIBR, is not installed +as a shareable image library. +.p +Although the linking is somewhat more complex, the shareable image file +does allow program using the graphics library to run slightly faster and +the executeable to be significantly smaller. +.p +The shareable image library is designed to be upwardly compatible. + +.hl1 Disclaimer +.p +LONGLIB is very powerful graphics package for line-graphics. +Unfortunately, +the desire to maintain compatibility with earilier LONGLIB versions +has resulted in less than optimal design decisions. There are, however, +some incompatibilities with earlier versions of LONGLIB; notably +the color array used in AXIS, AXIS2, and AXIS, the working space +specifications of PLT3D and NXTVU, and metafile internal format which +results in the fact that previous metafile processing programs will +not work with new metafiles and vice versa. +.p +LONGLIB was developed in the ~VAX ~VMS environment. +With the possible exception of the Ramtek package routines, every +attempt has been to keep LONGLIB FORTRAN-77 compatible and machine +independent with the exceptions previously noted. No claim is made +regarding the transportability of LONGLIB to non-VAX machines. It is +felt, however, that only small modifications would be required. +.p +As with any software system, there may be bugs in either the documentation +or software though every attempt to eliminate them has been made. + +.CHAPTER Programming Examples +.p +In this chapter several ~examples of using some of the basic plotting +routines of this library are included. The ~VAX environment permits +the linking of object code segments compiled from different languages. +Thus, examples for both ~FORTRAN and ~C routines are shown. + +.hl1 FORTRAN Programming Examples +.p +For the user interested in obtaining very simple plots of curves without +being concerned with the details of LONGLIB, the ~MASTER routines provide +the most simple approach. Greater control of the output plot can +be obtained by customizing user version of MASTER-like routines from +the auxilary routines. + +.hl2 Simple MASTER Routine Example +.p +A very simple example of using the ~MASTER routines of this library is shown +below. For more detailed examples see the following sections. +.p +This example plots a +damped sine wave on both the terminal screen, the Ramtek (in color), +and the LONGLIB metafile. +The master routine ~PLOTSC handles all graphics intialization and +closing. (See the chapter on MASTER routines for additional details). +.TP 16 +.lit + + DIMENSION X(100),Y(100) + DATA P,U,PL,A,B,PHI/112,85,25.,.013,.3/ + DATA PI/3.141593/ +C FILL DATA ARRAYS + DO 10 I=1,100 + X(I)=I-1 + Y(I)=SIN((I-1)*PI/A+PHI)*EXP(-I*B) + 10 CONTINUE +C CALL LONGLIB PLOTTING ROUTINE TO PLOT CURVE. +C OUTPUT ONLY 35 OF THE 100 POINTS ON A 6X5 PLOT WITH TITLE +C AND A GRID. iflag IS SET TO PROMPT FOR A SCREEN OUTPUT DEVICE. +C NOTE THAT WHEN A MASTER ROUTINE INITIALIZES LONGLIB, A +C METAFILE IS ALWAYS PRODUCED. + CALL PLOTSC(X,Y,100,5,6.,5.,'X TITLE',7,'Y TITLE',7, + 1 'TOP TITLE',-10) + STOP + END + +.end lit + +.hl2 Lower Level Routines +.p +An example of using the auxilary routines of LONGLIB library from +~FORTRAN is illustrated below. +An example for using this library from ~C follows. +.p +This example plots a damped sine wave on both the terminal screen, +the Ramtek (in color), and the LONGLIB metafile. No MASTER +routines are used. +.lit + + PROGRAM DEMO + DIMENSION X(100),Y(100),ICOL(3) + DATA P,U,A,B,PHI/112,85,25.,.013,.3/ +C ICOL IS THE COLOR ARRAY FOR AXES + DATA PI/3.141593/,ICOL/1,2,3,4/ +C FILL DATA ARRAYS WITH Y=F(X) + DO 10 I=1,100 + X(I)=I-1 + Y(I)=SIN((I-1)*PI/A+PHI)*EXP(-I*B) + 10 CONTINUE +C INITIALIZE LONGLIB WITH SCREEN PROMPT OPTION +C AND CREATE METAFILE TO FORTRAN UNIT 3. + CALL FRAME(3,0,2.,2.,1.) +C COMPUTE SCALING FACTORS FOR X AND Y + CALL SCALE(X,8.,100,1,1,XMIN,DX) + CALL SCALE(Y,6.,100,1,1,YMIN,DY) + Y0=-YMIN/DY +C PLOT COORDINATE AXISES WITH COLOR OPTION ENABLED + CALL AXIS(0.,Y0,'X-AXIS',-6-100000,20.,0., + 1 XMIN,DX,N1,N2,ICOL) + CALL AXIS(0.,0.,'SINE',4+100000,17.,90., + 1 YMIN,DY,N1,N2,ICOL) +C SET LINE COLOR + CALL PLOT(5.,0.,0) +C PLOT DATA POINTS AS A LINE WITH SYMBOLS + CALL LINE(X,Y,100,1,5,2,1,1,XMIN,DX,YMIN,DY) +C PICK UP PEN AT END OF LINE (FORCES OUTPUT TO SCREENS) + CALL PLOT(0.,0.,3) +C PROMPT FOR SCREEN CLEAR ON RAMTEK/TERMINAL + CALL CTERM(2) + CALL RTERM(2) +C CLOSE LONGLIB + CALL PLOTND + STOP + END +.end lit + +.hl 1 C Language Programming Example +.x c language +The following is an illustration of how to use lower level LONGLIB +routines to produce a plot from ~VAX C. +.tp15 +.lit + +/* Example in VAX C */ + +main +{ + real x[100],y[100],dx,xmin,dy,ymin; + real exp(),sin(),y0; + int icol[4] = 1 , 2, 3, 4; + int i,n1,n2; + real pi = 3.141592654; + real p = 112., u = 85., a = 25., b = .013, phi = .3; + + for (i = 1; i < 100 ; i++) { + x[i] = i - 1; + y[i] = sin( (i-1) * pi / a + phi) * exp(-i * b); + } + frame(&3,&-3,&0.,&0.,&1.); /* Initialize */ + scale(x,&8.,&100,&1,&1,&xmin,&dx); + scale(y,&6.,&100,&1,&1,&ymin,&dy); + y0 = -ymin / dy; + plot(&2.,&2.,&-3); /* new origin */ + axis(&0.,&y0,"X-AXIS",&-6-100000,&20.,&0.,&xmin,&dx,&n1,&n2,icol); + axis(&0.,&0.,"SINE",&4+100000,&17.,&90.&ymin,&dy,&n1,&n2,icol); + plot(&4.,&0.,&0); /* new color */ + line(x,y,&100,&1,&5,&2,&1,&1,&xmin,&dx,&ymin,&dy); + plot(&0.,3&0.,&3) /* pen up */ + cterm(&2); /* ask if screen clear */ + plotnd; /* terminate plotting */ + +} +.end lit + +.hl1 MASTER Routine Examples (FORTRAN) +.P +The subsections that follow illustrate additional examples of how to use +MASTER routines from FORTAN. + +.hl2 Adding Additional Annotation to a MASTER Routine Plot +.X PLOTSC +.x plottests +.p +The following is an ~example of using a MASTER +subroutine more than once and/or adding additional text or +another plotting line and/or two MASTER subroutines: (see also the +program PLOTTESTS) +.TP16 +.S1 +.lit + ... +C INCLUDE PLOTSC ROUTINE COMMON BLOCK WHICH RETURNS +C SCALE FACTORS USED IN PLOTTING + COMMON /CPLOTSC/XMR,DXR,YMR,DYR + ... +C CALL PLOTSC WITH -10000 iflag < 0 TO INITIALIZE LONGLIB +C BEFORE CALL BUT NOT CLOSE LONGLIB AFTER CALL +C SET iflag TO PROMPT FOR SCREEN DEVICE TYPE WITH TICKED GRID + CALL PLOTSC(X,Y,25,4,8.,6.,'X AXIS',6, + 1 'Y AXIS',6,'TITLE',-5,ICOL) +C PUT GRAPHICS TERMINAL IN GRAPHICS MODE + CALL CTERM(-1) +C PLOT ADDITIONAL TEXT AFTER PLOT TITLE + CALL SYMBOL(999.,999.,0.15,' TEXT',0.,5,-1) +C PLOT ADDITIONAL ANNOTATION ABOVE PLOT + CALL SYMBOL(0.0,6.5,0.15,'NUMBER=',0.,7,-1) +C ADD NUMBER AFTER ANNOTATION WITH 3 DIGITS AFTER DECIMAL PT. + CALL NUMBER(999.0,999.0,0.15,3.1415,0.,3,-1) +C CHANGE LINE TYPE TO DOTTED + CALL NEWPEN(1) +C ADD ANOTHER LINE OF DATA ON PLOT USING PLOTSC SCALE FACTORS + CALL LINE(X,Y2,N,1,0,0,1,1,XMR,DXR,YMR,DYR) + ... +C ASK IF SCREEN CLEAR ON TERMINAL (METAFILE NOT AFFECTED) + CALL CTERM(2) + CALL PLOTND + ... +.end lit + +.hl2 Using Multiple MASTER Routines in the Same Program +.x plottests +.p +The following is an ~example of how to use several MASTER +subroutines in the same program. (see also the program PLOTTESTS) +The basic idea is to use the first call to a MASTER routine to +initialize the LONGLIB graphics library. On later calls to MASTER +routines you must use "iflag" to instruct the routine NOT to +re-initialize LONGLIB. The last call to a MASTER routine closes +LONGLIB. +.x PLOTLG +.x PLOTSC +.tp16 +.S1 +.lit +C FIRST CALL TO MASTER ROUTINE, SET -10000 < iflag < 0 +C TO INITIALIZE LONGLIB BUT NOT CLOSE IT +C SET iflag TO PROMPT FOR SCREEN DEVICE TYPE WITH +C AXIS ON TOP AND SIDES AND NO GRID + CALL PLOTSC(X,Y,N,-1,...) + ... +C SECOND CALL TO MASTER ROUTINE, SET iflag < -10000 TO +C PREVENT INITIALIZING LONGLIB OR CLOSING IT +C SET iflag TO PRODUCE AXIS TICKED GRID (SINCE +C LONGLIB OPEN, NO PROMPT FOR SCREEN DEVICE) + CALL PLOTSC(X,Y,N,-10004,...) + ... +C LAST CALL TO MASTER ROUTINE, SET iflag > 10000 TO +C PREVENT INITIALIZING LONGLIB AND CLOSE IT AFTER PLOTTING +C SET iflag TO PRODUCE AXIS TICKED GRID AND LOG/LOG FORM +C (SINCE LONGLIB OPEN, NO PROMPT FOR SCREEN DEVICE) + CALL PLOTLG(X,Y,N,10053,...) +.end lit + +.HL2 MASTER Routine Color Example +.x PLOTSC +.p +The following is a very elaborate example of how to use color in a particular +MASTER routine (PLOTSC). +.tp16 +.s1 +.lit +C DIMENSION AND LOAD COLOR ARRAY + DIMENSION ICOL(6) + DATA ICOL/1,2,3,4,5,6/ + ... +C CALL PLOTSC WITH NUMBER OF TITLE CHARACTERS NEGATIVE TO +C USE COLOR ARRAY. SET iflag TO INITIALIZE/CLOSE LONGLIB +C SET iflag TO PRODUCE AXIS TICKED GRID + CALL PLOTSC(X,Y,25,4,8.,6.,'X AXIS',6, + 1 'Y AXIS',6,'TITLE',-5,ICOL) + ... +.end lit + +.PG +.HL2 Using Multiple MASTER Plots on Same Page/Screen +.x PLOTSC +.p +The following is a very elaborate example of how to to place several +MASTER routine plots on the same Ramtek and terminal screen but different +metafile pages. +.tp16 +.s1 +.lit +C OPEN LONGLIB OUTSIDE OF MASTER ROUTINE +C SELECT BOTH TERMINAL AND RAMTEK SCREEN OUTPUT WITH NO +C SCREEN CLEAR ON RAMTEK OR TERMINAL + CALL FRAME(3,-3,1.,1.,1.) +C CHANGE COLOR AND ADD A SEPARATE PLOT TITLE + CALL PLOT(7.,0.,0) + CALL SYMBOL(6.,11.5,.3,'TITLE',0.,5,-1) +C CHANGE ORIGIN AND SHRINK SUBSEQUENT PLOTS ON RAMTEK/TERMINAL +C BUT NOT METAFILE + CALL PLOT(1.,1.,-3) + CALL VFACTOR(.5) + CALL RFACTOR(.5) +C LOOP TO PLOT FOUR MASTER PLOTS ON ONE SCREEN + DO 10 I=1,4 +C CALL PLOTSC WITH iflag < 10000 TO NOT INITIALIZE +C LONGLIB OR CLOSE IT AFTER PLOT +C SET iflag TO PRODUCE AXIS TICKED GRID +C (SINCE LONGLIB OPEN, NO PROMPT FOR SCREEN DEVICE) + CALL PLOTSC(X,Y,25,-10004,8.,6.,'X AXIS',6, + 1 'Y AXIS',6,'TITLE',5) +C MOVE ONLY RAMTEK AND TERMINAL ORIGINS BUT NOT METAFILE + CALL PLOTRM(0.,2.*5.,-3) + CALL PLOTVT(0.,2.*5.,-3) + IF (I.EQ.2) CALL PLOTRM(11.,-20.,-3) + IF (I.EQ.2) CALL PLOTVT(11.,-20.,-3) +C NEWPAGE ON METAFILE (DOES NOT AFFECT TERMINAL/RAMTEK) + CALL NEWPAGE +10 CONTINUE + ... +C PROMPT FOR SCREEN CLEAR ON RAMTEK/TERMINAL + CALL CTERM(2) + CALL RTERM(2) +C CLOSE LONGLIB + CALL PLOTND + ... +.end lit + + +.CHAPTER Description of Plotting Routines +.p +This chapter details the central LONGLIB graphics library routines. +A brief description of each routine is shown along with an example +of its call and a description of the required parameters. +Optional parameters are shown in <> brackets. +.p +The name of each parameter is followed by a letter indicating +the variable type. Unless otherwise specified, integers are the +default integer length of the machine (which is ~INTEGER*4 on the VAX). +.x byte +.x integer +.x real +.x character +.x logical +.LIT + + B = BYTE array string (see notes in section 1.2) + I = INTEGER + R = REAL + C = CHARACTER + L = LOGICAL + +.end lit + +NOTE: In ~VAX ~FORTRAN, +when a subroutine is called with a Hollerith constant such +as 'string', CALL SUB(... ,'string', ...), +VAX FORTRAN passes the string as a +BYTE array of ~ASCII values. A CHARACTER variable can not be substituted. +If you wish to use a CHARACTER variable, use %REF() to convert the +CHARACTER variable to a BYTE array, i.e., +call SUB(..., %REF(CHARACTER_VARIABLE), ...). +.x %REF() +.p +Lengths are given in the standard plot units of inches. The routine +~FACTOR can be used to change the plot unit length. Angles are specified +in degrees counter-clockwise from the x axis. +.p +Unless specifically +noted all parameters passed into a routine via the call statement will +be used on a "read-only" basis, i.e., they will not be modified by the +routine. + +.hl1 SUBROUTINE ABSPLT +.p +The routine ~ABSPLT changes the ABSOLUTE (versus relative as in PLOT) +rotation angle and scale factor of the metafile, terminal, and ~ramtek +plot routines to the values specified. Normally, the routine ~PLOT should be +used to change the origin, rotation angle, or scale factor. This routine +is provided for a skilled user to use in error recovery. Note, however, +that no error checking is provided in ABSPLT. +.lit + +CALL ABSPLT (x,y,a,z) + +x,y (R): coordinates of new absolute origin (in inches) +a (R): new absolute angle CCW from horizontal in degrees +z (R): new absolute scale factor +.end lit + +.hl1 SUBROUTINE ARROW +.p +~ARROW plots a vector arrow at any desired point and with any desired +angle. The type of arrowhead drawn may be selected. +.lit + +CALL ARROW (x,y,al,a,p,b) + +x,y (R): location coordinates for vector-arrow tail +al (R): length of arrow in plot units + if al=0, only a single point at (x,y) is output +a (R): angle from horizontal at which the arrow is to be drawn + (deg counterclockwise) +p (R): length of arrowhead in plot units + > 0 open arrowhead ( --> ) + = 0 no arrowhead + < 0 closed arrowhead ( -|> ) +b (R): angle between arrowhead side and arrow line (deg) +.end lit + +.hl 1 SUBROUTINE AXIS +.p +~AXIS plots a single coordinate axis with numeric labels at any desired +location and angle. The routine has to be +called separately for the x and y axis. A possible exponent +is determined and placed at the end of the axis title in the form +of 10**n. In order to leave room for the labelling the +axis should be removed at least by 3/4 inch from the edge of the plotter page. +The length of the axis should be integer-valued. The (i)th (i=0 to ml-1) +axis major tick is labeled with the value, xm+dx*i. +For a log axis see LGAXS. +.lit + +CALL AXIS (x,y,s,n,al,a,xm,dx<,nm,ml<,ic>>) + +x,y (R): location of starting point of the axis +s (B): alpha string containing the axis title +n (I): number of characters in the string s + > 0 : axis labelling on positive side (anti-clockwise) + < 0 : axis labelling on negative side (clockwise) + (100's digit) = 0 : coordinate line, ticks and labels drawn + = 1 : line and ticks only--no labeling + (1000's digit) = 0 : numeric labels paralel to axis line + = 1 : numeric labels orthogonal to axis line + (10000's digit) = 0 : additional optional parameters ignored + = 1 : additional optional parameters used + (100000's digit) = 0 : color list ignored + = 1 : color list used +al (R): length of axis in plot units (real number, integer-valued) + > 0 : tick marks placed on same side of axis as title + = 0 : no action (return with no plotting) + < 0 : tick marks placed on opposite side of axis from title +a (R): angle at which the coordinate axis is to be drawn +xm (R): value of first marking on the axis +dx (R): increment for numeric axis labels +(NOTE: the following optional parameters are needed only if + the magnitude of n is > 10000) +mn (I): minor tick marks between labeled major ticks + if not specified, 0 is used +ml (I): number of labeled major tick marks + if not specified, int(l) is used +ic (I): array of color values, if color not enabled, + current color is unchanged + ic(1) : color value for axis line and ticks + ic(2) : color value for numbers on axis + ic(3) : color value for axis label + (color upon return if no exponent plotted) + ic(4) : color for auto exponent scale + (color upon return if exponent shown) +.end lit + +.hl1 SUBROUTINE AXIS2 +.p +~AXIS2 is similar to AXIS but allows additional flexibility to draw +different tick sizes and types. +Optionally, a possible exponent +is determined and placed at the end of the axis title in the form +of 10**n. In order to leave room for the labelling the +axis should be removed at least by 3/4 inch from the edge of the plotter page. +The length of the axis should be integer-valued. The (i)th (i=0 to ml-1) +axis major tick is labeled with the value, xm+dx*i. +AXIS2 plots a coordinate axis and its markings at any desired location +and angle. +For a log axis see LGAXS. +.lit + +CALL AXIS2 (x,y,s,n,al,a,xm,dx<,nm,nn,ml,ts,nd,sm<,ic>>) + +x,y (R): location of starting point of the axis +s (B): alpha string containing the axis title +n (I): number of characters in the string + > 0 : axis labelling on positive side (anti-clockwise) + < 0 : axis labelling on negative side (clockwise) + (100's digit) = 0 : coordinate line, ticks and labels drawn + = 1 : line and ticks only--no labeling + (1000's digit) = 0 : numeric labels paralel to axis line + = 1 : numeric labels orthogonal to axis line + (10000's digit) = 0 : optional parameters ignored + = 1 : optional parameters used + (100000's digit) = 0 : color list ignored + = 1 : color list used +al (R): length of axis in plot units (real number, integer-valued) + > 0 : tick marks placed on same side of axis as title + = 0 : no action (return with no plotting) + < 0 : tick marks placed on opposite side of axis from title +a (R): angle at which the axis is to be drawn +xm (R): value of first marking on the axis +dx (R): increment for the axis markings +(NOTE: the following optional paramters are needed only if + the magnitude of n is > 10000) +nm (I): number of minor tick marks between major ticks, + if not specified, 0 is used +nn (I): nn-th minor tick is high-lited in length, if + not specified, 0 is used (none) +ml (I): number of labeled major tick marks, if not specified + then one major tick per inch is used + < 0 use following additional optional parameters used + > 0 use following additional parameters ignored +(NOTE: the following optional paramters are needed only if + the magnitude of n is > 10000 and ml < 0) +ts (R): character size of title and numbers, if not + specified, 0.15 is used + > 0 auto exponent scaling (x10 to power) is enabled + < 0 auto exponent scaling (x10 to power) disabled +nd (I): number of digits to right of decimal point, if not + specified 1 is used +sm (R): major tick length, if not specified 0.1 is used + note that minor tick length is 1/2 major tick length +ic (I): array of color indexes for axis colors + ic(1) : color value for axis line and ticks + ic(2) : color value for numbers on axis + ic(3) : color value for axis label + (color upon return if no exponent plotted) + ic(4) : color for auto exponent scale + (color upon return if exponent shown) +.end lit + +.hl 1 SUBROUTINE AXIS3 +.p +~AXIS3 plots a single axis and its markings at any desired location and +angle. Optionally, a possible exponent +is determined and placed at the end of the axis title in the form +of 10**n. The length of the axis can take any value. The (i)th (i=0 to ml-1) +axis major tick is labeled with the value, xm+i*(xx-xm)/le. +This version of axis is more flexible than other versions +and permits specifying the axis number labeling format. +For a log axis see LGAXS. +.lit + +CALL AXIS3 (x,y,s,n,al,a,xm,xx,t,c,f,ic) + +x,y (R): starting location of the axis +s (B): alpha string containing the axis title +n (I): number of characters in the string + > 0 : axis labelling on positive side (anti-clockwise) + < 0 : axis labelling on negative side (clockwise) + (100's digit) = 0 : coordinate line, ticks and labels drawn + = 1 : line and ticks only--no labeling + (1000's digit) = 0 : numeric labels paralel to axis line + = 1 : numeric labels orthogonal to axis line + (100000's digit) = 0 : color list ignored + = 1 : color list used +al (R): length of axis + > 0 : tick marks placed on same side of axis as title + = 0 : no action + < 0 : tick marks placed on opposite side of axis from title +a (R): angle at which the axis is to be drawn +xm (R): value of first marking on the axis +xx (R): value of last marking on the axis +t (R): number of tick marks + specification is coded in the form MMM.mmss where + MMM is the number of major tick marks ( MMM > 0), mm is + the number of minor tick marks between major tick marks + (100 > mm => 0), and ss is the number of subminor tick + marks between minor tick marks (100 > ss => 0). + (example 1.0102 produces I_._._i_._._I) +c (R): size of characters + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +f (R): axis number label format (see NUMBER) + Note: if an integer -1 is passed in place of f, AXIS3 + will used f=1003.00 if autoscaling is enabled. If an + integer 0=a1) + if a2-a1=360 a full circle is used otherwise + the area is a pie segment +l (I): shade format control + = -3 : clear area and outline + = -2 : clear area + = -1 : clear outline + = 0 : no action + = 1 : draw outline + = 2 : shade area + = 3 : shade area and outline +d (R): distance between shading lines +t (R): angle of shading lines in degrees +w (R): working array dimensioned at least 3*n where + n=int((a2-a1)/(180*atan(s/r)/pi)+1) +m1 (R): line type of shading + < 0 : shading done with current line type + => 0 : new line type (see NEWPEN) +m2 (R): line type for area outline + < 0 : use prior line type + => 0 : new line type (see NEWPEN) +.end lit + +.hl1 SUBROUTINE CTERM +.p +~CTERM is the central subroutine for controling the state of the graphics +terminal. It is used to switch a graphics terminal +in and out of the graphics and text modes. It is a dummy call when not in +~terminal plotting mode. Note that not all options are available on all +terminals. Results of operation of this routine is thus terminal dependent. +In some cases the graphics and text modes are the same while in others, +the mode is switched only at init/de-init. +See the introduction to the documentation under terminal types. +.p +Note: for CTERM(2), the user will be prompted for a "clear screen". +The reply may be "Y" for yes, "N" for no (the default), "Q" (quit), +"S" (skip one), "P" (pass many), or "D" (dump). "Y" and "N" clear +the screen as indicated and the program continues normally. +A reply of "Q" permanently disables terminal screen plotting until +the package is reinitialized by FRAME. A replot of "S" disables +screen plotting until the next CTERM(2) call whereupon the +"clear screen" prompt reappears as before. A reply of "P" is similar +to "S", but the user will be prompted for the number of ~CTERM(2) calls +to pass before reissuing the prompt. In this manner multiple terminal +screen "pages" can be skipped. A reply of "D" will enable a dump +of the screen to the attached terminal printer (if supported on the +particular terminal/printer). Note that during a skip that any changes +of origin by PLOT, scale factors by FACTOR or VFACTOR, or pen color +or linetype will NOT take place. +.lit + +CALL CTERM (iarg) + +iarg (I): terminal operation code + = 0 : initialize graphics mode on terminal + = 1 : return terminal from graphics to text mode + =-1 : return terminal text to graphics mode + = 2 : return terminal to text mode, and prompt + user for clear screen (see note above) + =-2 : return terminal to text mode, clear graphics screen + = 3 : clear text screen, leave in text mode + =-3 : clear graphics screen, leave in terminal mode + = 4 : dump graphics screen to printer + =-4 : clear text, graphics, leave in graphics mode + = 5 : turn off graphics screen, return to text mode + =-5 : turn on graphics screen, return to graphics mode + = 6 : toggle reverse video + = 8 : de-initialize graphics terminal +.end lit + +.hl 1 SUBROUTINE DASHL +.p +.x software line type +.x line type +~DASHL plots a software-generated dashed ~line through the coordinate points +stored in x and y. See also LINE. +.lit + +CALL DASHL (x,y,n,k,j,l,ix,iy,xm,dx,ym,dy) + +Parameter list description same as LINE. +.end lit + +.hl SUBROUTINE ELLIPSE +.p +~ELLIPSE will plot all or part of a parametric ellipse of the form, +.lit + + (x,y) = (maj*cos(t), min*sin(t)) + +.end lit +where maj and min are the major and minor ellipse axes, respectively +and where t is the parametric angle specification. Part of the ellipse +can be plotted by specifying only part of the range of t. +The major axis center line is offset by the angle am. +The angles ast and aend define the starting and ending +angles for t. Note that aend should be greater than ast. +The ellipse is approximated by short, straight line segments. The number +and length of the segments depend on the size of the ellipse. +.lit + +CALL ELLIPSE (x,y,maj,min,am,ast,aend) + +x,y (R): center of ellipse (halfway between foci) +maj (R): length of semi-major axis (distance between center and + curve through one focus) +min (R): length of minor axis (distance between center and + curve perpendicular to semi-major axis) +am (R): angle of semi-major axis from horizontal + (deg counter-clockwise) +ast (R): start angle of curve from semi-major axis + (deg counter-clockwise) +aend (R): end angle of curve from semi-major axis + (deg counter-clockwise) note: aend > ast +.end lit + +.hl SUBROUTINE FACTOR +.p +Positional information is usually expressed in inches. A conversion ~factor +can be given for other units, such as "cm". The new coordinate values are +derived from the product "fac*x" where x is the input value. +A negative value or zero resets the +scaling factor to unity. Note that the initial factor can be specified +in FRAME. The subroutine ~FACTOR calls PFACTOR, RFACTOR, and VFACTOR which +change the scale factors for the metafile, Ramtek, and terminal +packages, respectively. These routines can be called separately to +affect only the scale factor of the particular package. +.x FRAME +.x PFACTOR +.x RFACTOR +.x VFACTOR +.lit + +CALL FACTOR (fac) + +fac (R): new conversion factor for coordinate values (all packages) + <= 0 : scale factor reset to unity + > 0 : new scale factor +.end lit + +.hl SUBROUTINE FRAME +.p +.x Selanar +.x vt100 +.x vt125 +.x vt240 +.x vt220 +.x Tektronix 4010/4014 +.x Tektronix 4107/4109 +~FRAME initializes the graphics metafile/terminal/Ramtek software and +resets internal variables. This routine is usually the first LONGLIB +routine called (also see ~PLOTS which calls FRAME). FRAME must be activated +before plotting calls are issued by the user program. FRAME should +normally be called only once in a program. MASTER routines optionally +handle the FRAME call. +.p +FRAME intializes the graphics output device packages. The FORTRAN +unit number used for the LONGLIB metafile can be specified. Normally, +unit 3 is used. If unit 0 is specified, FRAME will prompt the user +for a yes/no response to create a metafile. A negative unit number +disables the metafile package. All calls to metafile routines (such +as PPLOT) are dummy calls when the metafile package is disabled. +.p +FRAME also initializes the screen graphics device. A screen device +code is used to determine whether the Ramtek or Terminal screen device +packages are open. If a negative value for the screen device code +is used the screen device is not cleared prior to use, otherwise it is. +If the screen device code is +/- 4, no screen device package is used and +all calls to screen +specific routines (such as PLOTRM or PLOTVT) are dummy calls. +If a screen device code of 0 is used, the user is prompted for +a screen device to use. The screen devices may then be selected using +a character code. +A reply of "?" will list the available options. +.p +FRAME also intializes the origin and scale factor for plotting. +The default origin on the ~terminal and the ~Ramtek is the lower +left of screen (0.,0.). The +X axis runs horzontally, while the Y axis runs vertically. The +default origin on the printer is the upper left corner of page. +The X axis runs vertically down page, while the Y axis runs +horizontally across the page. +.p +When the ~Ramtek Screen device is selected, FRAME opens a +communications channel to the Ramtek. +If no channel is available or the Ramtek is in use an +error message is typed and the calling program is terminated. +.lit + +CALL FRAME (pl,id,vpx,vpy,zom) + +pl (I): Fortran file unit number (normally 3) used for LONGLIB + Metafile. If pl < 0 then no metafile is generated. + If pl = 0 then the user will be prompted for a yes/no + metafile. In this case unit number used will be 3. +id (I): Screen device code number. + < 0 : Do not clear Ramtek/terminal screens prior to use. + > 0 : Clear Ramtek/terminal screens prior to use. + = 0 : Prompts user for which screen device to use. + A ? response will list the available devices. + = 1 : Use VT100 as Screen Output (only) (Selanar GR100) + = 2 : Use Ramtek as Screen Output (only). + = 3 : Use both Ramtek and VT100 as Screen Output. + = 4 : Do not produce Screen output. + = 5 : Use VT125 as Screen Output (only) + = 6 : Use VT100 as Screen Output (only) (Selanar GR100) + = 8 : Use VT240 as Screen Output (only) + = 9 : Use VT220 as Screen Output (only) (Selanar SG220) + =10 : Use Tektronix 4010/4014 as Screen Output + =11 : Use Tektronix 4107/4109 as Screen Output + (color Tektronix) + =12 : Use Graph-On GO-235 as Screen Output +vpx, (R): relative x,y offset of the bottom left hand corner of +vpy the screen/page. Equivalent to PLOT(vpx,vpy,-3). +zom (R): The value of 'zom' scale factor. (see FACTOR) +.end lit + +.hl 1 SUBROUTINE GRID +.x LGRID +.p +~GRID plots a ~Cartesian grid or solid lines or ticks at +grid intersections. See also LGRID. +.lit + +CALL GRID (x,y,dx,dy,nx,ny) + +x,y (R): coordinates in the bottom left corner of grid +dx,dy (R): spacing of grid lines in x and y directions +nx,ny (I): number of grids in x and y direction + if nx > 0 and ny > 0 then solid grid plotted + if nx < 0 or ny < 0 then tick grid plotted + if nx < 0 and ny < 0 then boxed tick grid plotted +.end lit + +.hl1 SUBROUTINE HLT3D +.p +.x PLT3D +.x 2-d surface plotting +~HLT3D plots a 2 dimensional array to produce a 2-d histogram similar +to PLT3D. Hidden lines are supressed. +Transformation from the array indices (i,j) to (x,y,z) is: +.lit + + x = xl * .5 * float(2*j-n-1)/float(n-1) + y = yl * .5 * float(2*i-m-1)/float(m-1) + z = zs * (a(i,j) + z0) + +Thus, + + (1,1) is (-xl/2,-yl/2) (m,1) is (-xl/2,+yl/2) + (1,n) is (+xl/2,-yl/2) (m,n) is (+xl/2,+yl/2) + + xplotted = x*cos(az) - y*sin(az) + x0 + yplotted = x*sin(az)*sin(al) + y*sin(az)*sin(al) + z*cos(al) + y0 +.end lit +.p +The common block ~PLT3B returns these ~transformation parameters so +that the plotted location (xp,yp) of the corner of the cube corresponding +to the point (i,j,zr) may be computed as: +.lit + + xp = a1 * j + a2 * i + a3 + yp = b1 * j + b2 * i + b3 * zr + b4 +.end lit +.p +The dimension of the working array is dependent on the +surface complexity -- the greater the surface complexity, the greater +l2 must be. As a minimum, l2 > 4*min(m,n). See also ~NXTVU and PLT3D. +.x PLT3D +.lit + +CALL HLT3D (a,md,nd,m,n,w,l,w2,l2,al,az,xl,x0,yl,y0,zs,z0,ierr) + +a (R): array of values to be plotted dimensioned a(md,nd) +md,nd (I): array dimensions +m,n (I): size of data in array to be plotted +w (R): dummy variable so that call is compatible with PLT3D +l (I): dummy variable so that call is compatible with PLT3D +w2 (R): working storage array dimensioned w2(l2) +l2 (I): working storage array dimension (see note) +al (R): viewing altitude angle (deg) +az (R): viewing azimuth angle (deg) +xl,yl (R): length of unprojected axes in plot units +x0,y0 (R): plot origin in plot units +zs (R): z coordinate scale factor +z0 (R): z coordinate offset +ierr (I): (returned) error code + = 0 : ok + = 1 : l2 not large enough in NXTVU + +COMMON /PLT3B/ a1,a2,a3,b1,b2,b3,b4 +.end lit + +.hl 1 SUBROUTINE HELPME +.p +~HELPME calls the ~VAX ~VMS interactive ~help utility for the LONGLIB help +library with an initial help request string. The librarian is interactive +so that the user is prompted for additional input until a control-Z +is typed at which point control is returned to the calling program. +.lit + +CALL HELPME(s) + +s (C): initial help request string +.end lit + +.hl 1 SUBROUTINE JPLTAG +.p +~JPLTAG plots the JPL logo (JPL). Optionally, it can produce only a line +outline or fill the outline with a line pattern using SHADE. +.lit + +CALL JPLTAG (x,y,h,a,i,d,m,sa,w) + +x,y (R): coordinates of the lower left corner of the initial j +h (R): letter height in plot units +a (R): angle of baseline relative to horizontal +i (I): option flag + (1's digit) = 0 no action + = 1 draw outline only + = 2 draw shading only + = 3 shade area and draw outline + (10's digit) = pen color (if = 0, pen color is not changed) +d (R): distance between shading lines +m (I): shading line type + => 0 line type (see NEWPEN) +sa (R): angle of shading lines +w (R): working array dimensioned at least w(56+54*H) +.end lit + +.hl 1 SUBROUTINE LGAXS +.p +~LGAXS plots a single ~logarithmic coordinate ~axis. Complete +decades are produced. See also ~AXIS and LGLIN. +.x LGLIN +.lit + +CALL LGAXS (x,y,s,n,al,a,nmin,dx<,ic>) + +x,y (R): location starting point of the axis +s (B): axis label string +n (I): number of characters in string + > 0 : label on positive side + < 0 : label on negative side + (100's digit) = 0 : coordinate line, ticks and labels drawn + = 1 : line and ticks only--no labeling + (1000's digit) = 0 : numeric labels paralel to axis line + = 1 : numeric labels orthogonal to axis line + (10000's digit) = 0 : color list ignored + = 1 : color list used +al (R): length of axis + > 0 : axis ticks placed on same side of axis as title + = 0 : no action (return with no plotting) + < 0 : ticks placed on opposite side of axis from title +a (R): angle at which the axis should be plotted +nmin (R): number to be printed at the first axis tick (power of ten) +dx (R): scaling factor in the form dx=(nmax-nmin)/l where + nmax, nmin are the exponent powers at the start + and end of the axis +ic (I): color array (required if mag(n)>10000)) + ic(1) : color for axis line and ticks + ic(2) : color for numbers + ic(3) : color for axis title +.end lit + +.hl 1 SUBROUTINE LGLIN +.x LINE +.p +~LGLIN plots a solid curve through a set of values from x to y. +Either x or y or both may in the process be converted to +~logarithmic form. Symbols may be used at selected intervals. +(see also ~SCALG and LINE). The plotted x values are computed according to, +.lit + + for logarithmic scaling, + + xplotted= (alog10(abs(x(i))+1.e-38)-xm)/dx + + for linear scaling, + + xplotted= (x(i)-xm)/dx + +.end lit +and similarily for y. +.lit + +CALL LGLIN (x,y,n,k,j,l,lg,ix,iy,xm,dx,ym,dy) + +x (R): array containing the x coordinates +y (R): array containing the y coordinates +n (I): number of data points in x and y + (the number of data points in x,y must be equal) +k (I): take every first (k=1), second (k=2) value etc. + (normally k=1) +j (I): plotting symbol spacing flag + > 0 : symbol is plotted at every jth plotted point + connected by lines + = 0 : no symbols, lines only + < 0 : symbol is plotted at every abs(j)th plotted point + with no connecting lines +l (I): plot symbol number (see SYMBOL) +lg (I): log option + = - 2 : x and y are plotted using logarithmic scaling + = - 1 : x logarithmic, y linear + = 1 : x linear, y logarithmic +ix,iy (I): start index if arrays (normally ix,iy=1) +xm (R): minimum value scale factor for x array +dx (R): increment scale factors for x array +ym (R): minimum value scale factor for y array +dy (R): increment scale factors for y array +.end lit + +.hl1 SUBROUTINE LGRID +.p +~LGRID plots a ~logarithmic or linear ~grid using solid lines, +dotted lines, or ticks. See also GRID. +.lit + +CALL LGRID (x,y,dx,dy,nx,ny,i) + +x,y (R): location coordinates for the bottom-left corner of grid +dx,dy (R): spacing of major grid lines in x and y directions +nx (I): number of major grid lines in x direction + < 0 : log spacing of minor lines + > 0 : no minor lines/ticks +ny (I): number of major grid lines in y direction + < 0 : log spacing of minor lines + > 0 : no minor lines/ticks +i (I): option flag + = 0 : solid major/minor lines + = 1 : dotted major/minor lines + = 2 : solid major lines with minor ticks +.end lit + +.hl1 SUBROUTINE LINE +.p +~LINE plots a solid curve through a set of coordinate pairs +stored in two arrays. Symbols may be inserted at selected +intervals and points of curves may be skipped. +The coordinates are calculated as follows: +.lit + + xplotted(i)=(x(i)-xm)/dx, i=ix to n, step k + yplotted(m)=(y(m)-ym)/dy, m=iy to n, step k + +.end lit +The routine ~SCALE may be used to compute the scale factors xm, dx, +ym, and dy from the x and y arrays. +.lit + +CALL LINE (x,y,n,k,j,l,ix,iy,xm,dx,ym,dy) + +x (R): array containing the x coordinates +y (R): array containing the y coordinates +n (I): number of data points in x and y + (the number of data points in x, y should be equal) +k (I): plot every first (k=1), second (k=2) value etc + (normally k=1) +j (I): plotting symbol spacing flag + > 0 : symbol is plotted at every jth plotted point + connected by lines + = 0 : no symbols, lines only + < 0 : symbol is plotted at every abs(j)th plotted point + with no connecting lines +l (I): plot symbol number (see SYMBOL) +ix,iy (I): starting indexs in array (normally ix,iy=1) +xm (R): minimum value scale factor for x array +dx (R): increment scale factors for x array +ym (R): minimum value scale factor for y array +dy (R): increment scale factors for y array +.end lit + +.hl1 SUBROUTINE LINSEQ +.x line type +.x software line type +.p +~LINSEQ plots line curves using software generated line types. +Cubic spline interpolation is used in the generation of the specified +long dash/short dash sequence. The cubic spline "smoothing" prior +to plotting may also be specified. Closed curves and loops are permitted. +A word of caution: due to the limitations of cubic splines, the +plotted curve may not exactly represent the underlying function. +The code used by this routine is an adaptation of the ~COSMIC routine +LAR-11123. +.p +LINSEQ can be used to plot the same curve at different locations +by first calling LINSEQ with the desired data, then calling LINSEQ +again with n set to zero and h changed. +.lit + +CALL LINSEQ (x,y,z,n,ns,h,s,l1,l2,l3,l4,l5) + +x (R): array containing the x coordinates +y (R): array containing the y coordinates +z (R): working array dimensioned at least z(3*n+3) +n (I): number of points in x,y arrays + if n=0 then arc parameters from the last + call to LINESEQ are used again + (used to replot the same curve at different location) +ns (I): number of smoothing passes (normally 0) +h (R): x axis plotting offset (normally 0). Setting h <> 0 + and n=0 permits replotting last curve, shifted right + the specifed amount. +s (R): approximate interval between interpolated points on + curve. Actual interval is internally computed. + If s<0 pre-interpolation to 2*n-1 points is done. +l1-l5 (I): dash pattern control flags + l1 = Number of INTERVALS BETWEEN dashes + l2 = Number of LONG dashes per CYCLE + l3 = Number of INTERVALS per LONG dash + l4 = Number of SHORT dashes per CYCLE + l5 = Number of INTERVALS per SHORT dash +Note: if l1=0, l2-l5 are ignored and a solid curve is drawn + if l4=0, l5 is ignored. All dashes same length. +.end lit + +.hl SUBROUTINE NEWPAGE +.p +.x form feed +.x page +~NEWPAGE inserts a change page command into the LONGLIB metafile. The +hardcopy conversion program use the change page command to issue a form +feed to the metafile output. Note that NEWPAGE only affects the metafile page +and does not change origin, etc. +It is a dummy call for ~Ramtek or ~terminal plotting. This command is +equivalent to CALL PLOT(0.,0.,10). +.lit + +CALL NEWPAGE + (no arguments) +.end lit + +.hl1 SUBROUTINE NEWPEN +.p +.x line type +.x ppen +.x rmpen +.x vpen +~NEWPEN calls PPEN, RMPEN, and VPEN which +change the hardware line type and/or width of the plotting +line for subsequent plotting on the metafile, Ramtek, and terminal +output devices. +The precise effects depend on the particular graphics device. There are +10 standard line types which are shown in the last chapter. The output device +will use the nearest hardware-supported line type to the standard line +type. Some +devices support additional types including permitting a specification +of the scale factor of the line type (the length of the dot/dash pattern). +If a device does not support line types, the default type is used. +Line widths are not support on the Ramtek packages and are simulated +in softwared for the terminal. The metafile package supports all features +although the metafile processing programs may only use the +features supported by the particular hardcopy graphics output device. +Default line type is a solid line of width 1 dot. +.lit + +CALL NEWPEN (i) + +i (I): selects a line type for all additional plotting + for all output devices + < 0 : resets line type to solid line of unit width. + = 0 : line type 0 no change in line width + > 0 : line type and width changed according to, + (1's digit) : line type (0-9) + (10's digit) : line width (1-7) (value of 0 does not change width) + (100's digit) : line type pattern scaling (1-7) (0 is no change) +.end lit + +.hl1 SUBROUTINE NUMBER +.p +~NUMBER plots a floating point number in a specified format using +a fortran format-like specification. It also permits +free-format and exponential notation formats. The number is converted +to an ~ASCII string plotted at a specified location and baseline angle +using SYMBOL. The following table illustrates the dependence of the output +string on the type (integer/real) and value of the parameter e. The table +shows the output for an input f=103.356 and i=-1. +.tp 17 +.lit + + Output integer e real e + -------- ---------- -------- + 103 -1 1003.0 + 103. 0 0.0 + 103. 0 3.00 + x103.36 7.02 + 103.36 2 0.02 + 103.356000 6 10.06 + xx103 1005.0 + ** 1002.0 (format overflow) + x103.4 6.01 + *.**** 6.04 (format overflow) + .103E+02 -8.03 + *.*** -5.03 (format overflow) + +note: x=space, * indicates overflow +.end lit + +.lit + +CALL NUMBER (x,y,h,f,a,e,i) + +x,y (R): location position (x,y returned if i=-2 or -3) + If x=999 then x is continued from lower right of + prior call to SYMBOL or NUMBER. If y=999 then + y is continued. +h (R): size (height) of digits +f (R): floating point number to be plotted +a (R): baseline angle at which to plot +e (R): output format (e=n.j) + (similar to format statement Fn.j) + n is the total number of characters (max 18) + including the decimal point and j is a two digit number + specifying the number of digits to the right of + the decimal point (to get F6.4 use e=6.04) + if e < 0 number is plotted in exponential notation. + if e = 0 then number is output in free format + if n = 0 then number is output in free format + integer with no decimal point shown + The number will be shown as an m digit integer + if using e=1000+m. +NOTE for VAX usage: if an integer in the range (-1 to 12) is passed + for e, NUMBER detects and uses the integer value + to specify a free-format specifying + the number of digits to the right of the decimal point. + a -1 inhibits decimal point +i (I): centering flag (see SYMBOL) + = -3 : same as -2 but string is not plotted and + last position is not affected + = -2 : same as -1 but returns end point in x,y + = -1 : (x,y) is lower left corner of plotted array + = 0 : (x,y) is center of plotted array + = 1 : (x,y) is lower right corner of plotted array + = 2 : no action +.end lit + +.hl SUBROUTINE PFACTOR +.p +~PFACTOR is called by ~FACTOR to change the input scale conversion factor +for the LONGLIB metafile package. It may be called separately if desired. +Only the metafile plotting package +is affected. The routines ~RFACTOR and ~VFACTOR may be separately +called to change the input scale conversion factor on the Ramtek and +terminal packages, respectively. See FACTOR. +.lit + +CALL PFACTOR (fac) + +fac (R): new conversion factor for coordinate values + (only the metafile scaling is affected) + <= 0 : scale factor reset to unity + > 0 : new scale factor +.end lit + +.hl1 SUBROUTINE PLOT +.x view port +.x origin +.x plotting window +.x PLOTRM +.x PPLOT +.x PLOTVT +.p +~PLOT is the central routine for controlling the motion of the electronic +pen for all LONGLIB graphics device packages. +PLOT calls the Ramtek, metafile and terminal PLOT routines PLOTRM, PPLOT, PLOTVT +based on the graphics devices initialized by FRAME. These individual +"package PLOT" routines can be called separately if desired to affect +only the particular package. Via these package-specific plot routines +PLOT can moves the pen, change the origin or +pen color, issue a page change command, etc. +A relative rotation angle for all successive plotting may also be specified. +LONGLIB defines a +plotting ~window or viewport, the size of which is device dependent, within +which pen motions are clipped. The viewport may be set to an arbitrary +size within the device plotting window (e.g. terminal screen). An attempt to +make the viewport bigger than the device output will force the viewport +to be the device output window (this is the default). +.lit + +CALL PLOT (x,y,i) + +x,y (R): coordinate values +i (I): plot function parameter + = 0: color control + x is the new line color + if x < 0 the screen is cleared + if x >= 0 then plotting angle becomes y + = 2: draw to (x,y) with 'pen down' + = -2: same as i=2. (x,y) becomes new origin + = 3: move to (x,y) with 'pen up' + = -3: same as i=3. (x,y) becomes new origin + = 4: upper right corner of viewport set to (x,y) + = -4: lower left corner of viewport set to (x,y) + = 5: pick pen up at last point + = 9: erase to (x,y) (plot with color 0) + = -9: erase to (x,y) (x,y) becomes new origin + = 10: issue change page command to metafile + = 11: end plot (close LONGLIB) + =999: end plot (close LONGLIB) +.end lit + +.hl1 SUBROUTINE PLOTND +.p +~PLOTND is used to signal LONGLIB that all plotting is complete. It +sends the final output buffers to the respective graphics devices, closes +files and channels, and resets the terminal to the normal ~text mode. PLOTND +is equivalent to a CALL PLOT(0.,0.,11) command. +.lit + +CALL PLOTND + (no arguments) +.end lit + +.hl1 SUBROUTINE PLOTS +.p +~PLOTS initializes the LONGLIB graphics package via a call to FRAME. +PLOTS provides compatibility with existing CALCOMP or PLOTS-10 compatible +code. It simply calls ~FRAME with argurments which cause FRAME to prompt +for optional usage of the Longlib meta file output and a graphics +screen. For new code use FRAME. +.lit + +CALL PLOTS (...) + +(arguments are ignored) +.end lit + +.hl1 SUBROUTINE PLOTRM +.p +~PLOTRM is the central routine for controlling the plotting of lines to +the Ramtek or REF package. PLOTRM is called by the ~PLOT routine but +can be called separately. Any call to PLOTRM when the Ramtek package +is not initialized is a dummy call. Options for PLOTRM are similar +to PLOT (see documentation on PLOT). +An attempt to make the viewport bigger than the Ramtek screen window +will force the viewport to be the size of the Ramtek screen window +(this is the default). Typically the Ramtek screen window is +either 13.75 or 11 by 11 inches depending on the type (1280x1024 and +512x512, respectively), with the lower +left corner at (0,0) and the upper right corner at (13.75,11). +.lit + +CALL PLOTRM (x,y,i) + +x,y (R): coordinate values +i (I): plot function parameter + = 0: Ramtek color control + x is the Ramtek color table index + if x < 0 the Ramtek screen is cleared + if x >= 0 then rotation angle becomes y + = 2: Ramtek draw to (x,y) with 'pen down' + = -2: same as i=2. point (x,y) becomes new origin + = 3: Ramtek move to (x,y) with 'pen up' + = -3: same as i=3. Point (x,y) becomes new origin + = 4: upper right corner of viewport set to (x,y) + = -4: lower left corner of viewport set to (x,y) + = 5: pick pen up at last point + = 9: draw to (x,y) 'pen down' color 0 (erase) + = -9: same as i=9. Point (x,y) becomes new origin + = 11: end plot (close Ramtek package) + =999: end plot (close Ramtek package) +.end lit + +.hl1 SUBROUTINE PLOTVT +.p +~PLOTVT is the central routine for controlling the plotting of lines to +the terminal screen device REF package. PLOTVT is called by the ~PLOT +routine but +can be called separately. Any call to PLOTVT when the terminal package +is not initialized is a dummy call. Options for PLOTVT are similar +to PLOT (see documentation on PLOT). +An attempt to make the viewport bigger than the terminal screen window +will force the viewport to be the size of the terminal screen window +(this is the default). Typically the terminal screen window is +9.5 by either 9.5 or 7.2 inches (depending on the terminal) with the lower +left corner at (0,0) and the upper right corner at (9.5,9.5). +.lit + +CALL PLOTVT (x,y,i) + +x,y (R): coordinate values +i (I): plot function parameter + = 0: if x < 0 the terminal graphics screen is cleared + if x >= 0 then rotation angle becomes y + if x = 0 set terminal to erase mode plotting + if x <> 0 and x <> 999 set line color to x + if x = 999 set terminal to XOR mode plotting + (only if terminal has capability) + = 2: draw to (x,y) with 'pen down' on terminal + = -2: same as i=2. Point (x,y) becomes new origin + = 3: move to (x,y) with 'pen up' on terminal + = -3: same as i=3. Point (x,y) becomes new origin + = 5: pick pen up at last point + = 4: upper right corner of viewport set to (x,y) + = -4: lower left corner of viewport set to (x,y) + = 9: erase to (x,y) on terminal (if supported) + = -9: same as i=9. Point (x,y) becomes new origin + = 11: end plot (close terminal package) + =999: end plot (close terminal package) +.end lit + +.hl1 SUBROUTINE PLRAX +.p +.x polar axis +~PLRAX plots a circular ~axis for plotting in polar form. A series +of concentric circles are drawn around (x,y) at increasing radi +to the maximum radius. Provisions are included for half circle, +quarter circle, etc. Labeling of starting points and ending points +may be changed. +.lit + +CALL PLRAX (x,y,r,as,ae,a0,a1) + +x (R): x coordinate of center of polar axis +y (R): y coordinate of center of polar axis +r (R): radius of polar axis in plot units +as (R): starting angle of axis in degrees from horizontal +ae (R): ending angle of axis in degrees from horizontal + Note: as=0 and ae=360 yields full circle axis +a0 (R): number label of starting angle +a1 (R): number label of ending angle + Note: if a0=a1 then angles are not labeled. +.end lit + +.hl1 SUBROUTINE PLRLN +.p +.x polar line +~PLRLN plots a solid curve through the set of coordinate points +in polar form stored in r and t arrays. Symbols may be inserted +at selected intervals. Angle values stored in the t array are +in degrees referenced to horizontal. Coordinates are calculated +as follows: +.lit + r=(r-rmin)/dr + xplotted=r*cos(t*pi/180) + yplotted=r*sin(t*pi/180) + +.end lit +.lit + +CALL PLRLN (r,t,n,j,l,ir,rmin,dr) + +r (R): array of radial values to be plotted +t (R): array of angle values +n (I): number of points to plot +j (I): plotting symbol option flag + > 0 : symbol plotted every jth point with connecting lines + = 0 : line plotted only with no symbols + < 0 : symbols plotted only, no connecting line +l (I): symbol number (see SYMBOL) +ir (I): start index in r and t arrays +rmin (R): minimum radius scale factor +dr (R): scale factor +.end lit + +.hl1 SUBROUTINE PLT3D +.p +.x 2-d surface plotting +~PLT3D plots a 2 dimensional array as a surface scribed with a +linear grid parallel to the x and y axes, i.e., a mesh. +Hidden lines are supressed. +Transformation from the array indices (i,j) to (x,y,z) is: +.lit + + x = xl * .5 * float(2*j-n-1)/float(n-1) + y = yl * .5 * float(2*i-m-1)/float(m-1) + z = zs * (a(i,j) + z0) + +Thus, + + (1,1) is (-xl/2,-yl/2) (m,1) is (-xl/2,+yl/2) + (1,n) is (+xl/2,-yl/2) (m,n) is (+xl/2,+yl/2) + + xplotted = x*cos(az) - y*sin(az) + x0 + yplotted = x*sin(az)*sin(al) + y*sin(az)*sin(al) + z*cos(al)+y0 +.end lit +.p +The common block ~PLT3B returns these ~transformation parameters so +that the plotted location (xp,yp) of a point (i,j,zr) may be computed as: +.lit + + xp = a1 * j + a2 * i + a3 + yp = b1 * j + b2 * i + b3 * zr + b4 +.end lit +.p +The dimension of the second set of working arrays is dependent on the +surface complexity -- the greater the surface complexity, the greater +l2 must be. As a minimum, l2 > l. See also ~NXTVU and HLT3D. +.x HLT3D +.lit + +CALL PLT3D (a,md,nd,m,n,w,l,w2,l2,al,az,xl,x0,yl,y0,zs,z0,ierr) + +a (R): array of values to be plotted dimensioned a(md,nd) +md,nd (I): array dimensions +m,n (I): size of data in array to be plotted +w (R): working array dimensioned w(l) l=>4*min(m,n) +l (I): working array dimension +w2 (R): working storage array dimensioned w2(l2) +l2 (I): working storage array dimension (see note) +al (R): viewing altitude angle +az (R): viewing azimuth angle +xl,yl (R): length of unprojected axes (plot units) +x0,y0 (R): plot origin +zs (R): z coordinate scale factor +z0 (R): z coordinate offset +ierr (I): (returned) error code + = 0 : ok + = 1 : l2 not large enough in NXTVU + = 2 : l not large enough + +COMMON /PLT3B/ a1,a2,a3,b1,b2,b3,b4 +.end lit + +.hl 1 SUBROUTINE PPLOT +.p +~PPLOT is the central routine for controlling the plotting of lines to +the LONGLIB metafile package. PPLOT is called by the ~PLOT +routine but +can be called separately. Any call to PPLOT when the metafile package +is not initialized is a dummy call. Options for PPLOT are similar +to PLOT (see documentation on PLOT). +An attempt to make the viewport bigger than the metafile plotting window +will force the viewport to be the size of the metafile plotting window +(this is the default). +The metafile plotting window is 56.5 by 56.5 inches with the lower +left corner at (0,0) and the upper right corner at (56.5,56.5). +Since most hardcopy devices can not produce such a large output page, +the LONGLIB metafile processor programs which convert the metafile to +an output file, "strips" the metafile window into separate, overlapping output +pages. Only non-blank page strips are output to the device. +.lit + +CALL PPLOT (x,y,i) + +x,y (R): coordinate values +i (I): plot function parameter + = 0: line color control + x is the new line color + if x >= 0 then plotting angle becomes y + = 2: draw to (x,y) with 'pen down' + = -2: same as i=2. (x,y) becomes new origin + = 3: move to (x,y) with 'pen up' + = -3: same as i=3. (x,y) becomes new origin + = 4: upper right corner of viewport set to (x,y) + = -4: lower left corner of viewport set to (x,y) + = 5: pick pen up at last point + = 9: erase to (x,y) + = -9: erase to (x,y), (x,y) becomes new origin + = 10: issue change page command to metafile + = 11: end plot (close metafile package) + =999: end plot (close metafile package) +.end lit + +.hl1 SUBROUTINE PPEN +.p +.x line type +.x rmpen +.x vpen +~PPEN is called by ~NEWPEN to change the hardware line type and/or width of +the plotting line for subsequent plotting on the metafile. It may be +called separately to change only the metafile line type. +Ramtek and terminal output device line types may be changed using +RMPEN and VPEN, respectively. While the metafile output device supports +line types, widths and type scale factors (the length of the linetype +dot/dash pattern), the programs which process the LONGLIB metafile into +the output format required by the hardcopy device may not support all +features. The precise effects depend on the particular graphics device. +Raster scan converter programs for dot matrix printers support all options +and the 10 standard line types shown in the last chapter. On other +hardcopy devices, the metafile processing program uses the +the nearest hardware-supported line type to the standard line +type. Line widths are defined in terms of the minimum line widths. +The default line type is a solid line of width 1 dot. +.lit + +CALL PPEN (i) + +i (I): selects a line type for all additional plotting + to the LONGLIB metafile + < 0 : resets line type to solid line of unit width. + = 0 : line type 0 no change in line width + > 0 : line type and width changed according to, + (1's digit) : line type (0-9) + (10's digit) : line width (1-7) (value of 0 does not change width) + (100's digit) : line type pattern scaling (1-7) (0 is no change) +.end lit + +.hl1 SUBROUTINE RECT +.p +~RECT plots a rectangle defined by the lower left and upper right hand +corners. The pen moves UP to lower left hand of the rectangle, plots +the rectangle, and leaves the pen DOWN at the lower left corner. +.lit + +CALL RECT (x1,y1,x2,y2) + +x1,y1 (R): lower left hand corner coordinates +x2,y2 (R): upper right hand corner coordinates +.end lit + +.hl1 SUBROUTINE RESPL +.P +~RESPL performs a penup, then restores the current plotting origin, color, +line type, scale, and plotting angle saved by the ~SAVPL command. In conjunction +with ~SAVPL (which saves a previous condition) context changes can be easily +made. RESPL calls ~PRESPL (metafile restore), ~RRESPL +(Ramtek restore), and ~VRESPL (terminal restore) +which can be independently used if desired. If the stack is empty, +no restore occurs. (NOTE: graphics devices must be in the graphics +mode when this routine is executed). When using PRESPL, RRESPL, or VRESPL +a pen up operation should be executed imediately prior to the call. +.lit + +CALL RESPL + (no arguments) +.end lit + +.hl SUBROUTINE RFACTOR +.p +~RFACTOR is called by ~FACTOR to change the input scale conversion factor +for the LONGLIB metafile package. It can be called separately if desired. +Only the Ramtek plotting package +is affected. The routines ~PFACTOR and ~VFACTOR may be separately +called to change the input scale conversion factor on the metafile and +terminal packages, respectively. See FACTOR. +.lit + +CALL RFACTOR (fac) + +fac (R): new conversion factor for coordinate values + (only the Ramtek scaling is affected) + <= 0 : scale factor reset to unity + > 0 : new scale factor +.end lit + + +.hl1 SUBROUTINE RMPEN +.p +.x line type +.x ppen +.x vpen +~RMPEN is called by ~NEWPEN to change the hardware line type and/or width of +the plotting line for subsequent plotting on the Ramtek. It may be +called separately to change only the Ramtek line type. +Metafile and terminal output device line types may be changed using +PPEN and VPEN, respectively. While the Ramtek output device supports +line types and type scale factors (the length of the linetype +dot/dash pattern) it does not support line widths in hardware. +The default line type is a solid line of width 1 dot. +.lit + +CALL RMPEN (i) + +i (I): selects a line type for all additional plotting + to the LONGLIB Ramtek + < 0 : resets line type to solid line of unit width. + = 0 : line type 0 no change in line width + > 0 : line type and width changed according to, + (1's digit) : line type (0-9) + (10's digit) : line width (0-7) (ignored) + (100's digit) : line type pattern scaling (1-7) (0 is no change) +.end lit + +.hl1 SUBROUTINE RTERM +.x REFDIS +.p +~RTERM is designed to be similar to the ~CTERM routine but for use with the +Ramtek. It is a dummy call when not in ~Ramtek plotting mode. When using +the ~REF package, it calls REFDIS. +.lit + +CALL RTERM (iarg) + +iarg (I): operation code + = 0 : clear Ramtek screen + = 2 : ask if clear screen desired. + reply should be: "Y" or "N". Default is "N". + NOTE: a reply of "Q" will execute RTERM(3). + a reply of "S" will close channel and stop + Ramtek plotting until next RTERM(2) (see CTERM) + =-2 : clear Ramtek screen + = 3 : close Ramtek plotting (closes old channel) + =-3 : reopen Ramtek plotting (opens new channel--does + not reinitalize Ramtek plotting package) + =-4 : clear Ramtek screen +.end lit + +.hl1 SUBROUTINE SAVPL +.P +~SAVPL performs a penup, then stores the current plotting origin, color, +line type, scale, etc. on a stack which will store up six calls. +In conjunction +with ~RESPL (which restores previous condition) context changes can be easily +made. SAVPL calls ~PSAVPL (metafile save), ~RSAVPL +(Ramtek save), and ~VSAVPL (terminal save) +which can be independently used if desired. When the stack is +full no save is performed. +.lit + +CALL SAVPL +.end lit + +.hl1 SUBROUTINE SCALE +.x LINE +.p +~SCALE calculates the minimum and a scaled (smoothed) increment from +an array of values. The maximum and minimum of the array are computed +and the difference is divided by a length parameter. The resulting +values are "smoothed" so that numeric labels appear "nice" when labeled at +xm and at one inch increments. +The smoothed numbers are taken from the set of values 1,2,4,5,8 * 10n +that equals or is smaller than the true value. SCALE is useful +in determaning the scale factors for LINE. It is used extensively +in the MASTER routines. SCALE is not very intelligent and does not +always make good choices. SCALE selects xm and dx so that the plotted +x values may be computed using the following formula such that if +x=xm, xplotted=0 and if x=xlen*dx+xm, xplotted=xlen. +.lit + + xplotted = ( x - xm ) / dx + +.end lit +.lit + +CALL SCALE (x,xlen,n,k,ix,xm,dx) + +x (R): array of data points from which scale is determined +xlen (R): scale length +n (I): number of data points in x (n>1) +k (I): use every first (k=1) value, second (k=2) value, etc. + normally k=1. +ix (I): first data point index for x (normally ix=1) +xm (R): contains smoothed minimum after the call (returned) +dx (R): contains smoothed increment after call (returned) +.end lit + +.hl1 SUBROUTINE SCALG +.x LGLIN +.p +~SCALG calculates a scaled minimum and increment factor similar +to ~SCALE but uses the log (actually alog10(abs(val)+1.e-38)) +of the input array. See also SCALE and LGLIN. +SCALG selects xm and dx so that the plotted +x values may be computed using the following formula such that if +alog10(abs(x)+1.e-38)=xm then xplotted=0 and if +alog10(abs(x)+1.e-38)=xlen*dx+xm then xplotted=xlen. +.lit + + xplotted = ( alog10(abs(x)+1.e-38) - xm ) / dx + +.end lit +.lit + +CALL SCALG (x,xlen,n,k,ix,xm,dx) + +x (R): array of data points from which scale is determined +xlen (R): length +n (I): number of data points in x (n>1) +k (I): use every first (k=1) value, second (k=2) value, etc. + normally k=1 +ix (I): first data point index for x (normally ix=1) +xm (R): contains smoothed minimum after the call (returned) +dx (R): contains smoothed increment after call (returned) +.end lit + +.hl1 SUBROUTINE SHADE +.p +The ~SHADE subroutine fills in the ~area inclosed by the line defined +by the x and y arrays with equally spaced lines at a given angle using +a specified line type. The first and last +point of the x and y array are assumed to be connected. +.lit + +CALL SHADE (x,y,n,i,l,d,t,w,ma,xm,dx,ym,dy) + +x (R): array of x values +y (R): array of y values +n (I): number of points in array +i (I): increment between points +l (I): shade format control + = -3 : clear area and outline + = -2 : clear area + = -1 : clear outline + = 0 : no action + = 1 : draw outline + = 2 : shade area + = 3 : shade area and outline +d (R): distance between shading lines +t (R): angle of shading lines in degrees +w (R): working array dimensioned at least 3*n +ma (R): line type of shading + => 0 : line type (see NEWPEN) +xm (R): minmum scale factor for x (see LINE) +dx (R): x increment scale factor +ym (R): minmum scale factor for y +dy (R): y increment scale factor +.end lit + +.hl1 SUBROUTINE SYMBOL +.p +The ~SYMBOL routine plots an ~ASCII string. Upper and lower +case ~characters can be plotted as well as special plotting +symbols and characters. A list of symbols is shown in the last +chapter. +The plotting symbols 0 to 16 are centered vertically and horizontally, +while other symbols have a reference point on the lower left edge +of the character. Hence, i=-1 should be used for centered plot symbols +0 thru 16. +The number of characters in the input string which should be plotted +can be specified. +If an ASCII null (0) is encountered in the string beyond the +first position, the routine terminates. +.p +The string can be plotted left-justified, centered, or right-justified. +When the string is left-justified, the location of the end of the +plotted string can be optionally returned. The length of the +plotted string can be computed by calling SYMBOL first with i=-3 +and computing the difference between the start and ending points of the +string. +.p +More elaborate characters and different fonts +may be obtained using SYMS. ~MASTER routines, ~AXIS routines, and ~NUMBER +all use ~SYMBOL characters. If the user desires to use ~SYMS in place +of SYMBOL throughout a program, the user can add the following routine +to the program. The subroutine should be titled SYMBOL with the +arguments described below. This routine +simply passes the arguments (in the same order) to SYMS. +.lit + + SUBROUTINE SYMBOL(x,y,h,s,a,n,i) ! symbol replacement + INTEGER S(1) + A = SYMS(x,y,h,s,a,n,i) ! call syms + RETURN + END +.end lit +.x %REF() +.x descriptor +.p +Note: ~VAX ~FORTRAN ~CHARACTER types +can not be used directly since calling subroutines with CHARACTER types +is done by DESCRIPTOR. Use ~BYTE or ~INTEGER arrays for s or use %REF() +for character variables, i.e., call SYMBOL(0., 0., .25, %REF(S), 0., 10,-1). +See the section on machine dependency. +.lit + +CALL SYMBOL (x,y,h,s,a,n,i) + +x,y (R): location position (x,y returned if i=-2 or -3) + If x=999 then x continued from last position in + prior SYMBOL or NUMBER call. If y=999 then y continued. +h (R): height of the string to be printed +s (B): alpha string containing the text to be plotted +a (R): angle at which the string is to be plotted +n (I): number of characters in string s to plot + = -2 : draws pen down to (x,y) before symbol plotted + = -1 : plots a single symbol + > 0 : number of characters to plot +i (I): location flag + = -3 : same as -2 but string is not plotted and + last position is not affected + = -2 : same as -1 but returns end point in x,y + = -1 : (x,y) is lower left corner of plotted string + = 0 : (x,y) is center of plotted array + = 1 : (x,y) is lower right corner of plotted string + = 2 : no action +.end lit + +.hl1 REAL FUNCTION SYMS +.p +.x character plots +~SYMS is similar to SYMBOL in that it will plot +an ~ASCII string (i.e. a byte array). However, SYMS provides additional +math and plotting symbols as well as several character fonts (including +~Greek characters). SYMS has several additional enhancements to permit +complicated equations to be plotted. All but the 9th font have variable +width characters. Several fonts are designed to produce solid characters +when the plotting scale is small. +The number of characters in the input string s plotted and/or +interpreted can be specified. +If an ASCII null (0) is encountered in the string after the +first position, the routine terminates. +.p +The ASCII character "|" (decimal 124) is used as a control character to +change fonts or subscripting options. The character following the +"|" character is used according to the following table: +.s3 +.tp 30 +.c;SYMS Options +.lit + + ASCII Character Decimal Effect +________________ _________ ________ + + 0-9 48-57 Change to font (0-9) + W 87 Move forward one space + X 88 Move forward 1/2 space + Y 89 Move backward one space + Z 90 Move backward 1/2 space + [ 91 Reset to default + \ 92 Begin subscripting + ] 93 "Back up" one character + ^ 94 Begin superscripting + _ 95 Un sub/super + ` 96 Change scale (requires + another character-- "+" + indicates increase size by 2, + "-" indicates shrink by 1/2. + a 97 Begin over printing + b 98 Begin under printing + +.end lit +The number of characters in the string should include control characters. +.p +The width of one space is moved when moving forward or backward. +"Back up" returns the positioning to the start of the last character. +Up to 6 "back up" commands can be issued. Super/sub scripting can be +done recursively. Only one level is "popped off" by the +un-sub/super command. Scale changes require an additional character +(either a "+" or "-" to indicate the direction). Over/under printing +permit summation and integral limits to be added. Available fonts are listed +in the following Table: +.tp 15 +.s2 +.x character fonts +.c;Fonts Available in SYMS +.lit + + Font Characters Description + ______ ____________ _____________ + + 0 [default] ASCII 0-31 Plotting Symbols + ASCII 32-127 Simplex font--variable width + 1 ASCII 32-127 Roman + 2 ASCII 64-127 Greek Simplex + 3 ASCII 32-127 Roman Italic + 4 ASCII 32-127 Duplex bold + 5 ASCII 64-127 Special math symbols + 6 ASCII 32-127 Greek bold + 7 ASCII 32-127 Simplex Italic + 8 ASCII 32-127 Crude Simplex--fixed width +.end lit +.p +For example, the following summation using Greek characters, a +~math symbol, and a super scripted variable can be wrtten: +.TP7 +.lit + + alph string = 'A = |6R a|^2|_|]|]|]|]|b|1|2n=1|]|]|]|_|a|5K' + + infinity 2 + A = SIGMA alpha + zeta=1 + +.end lit +.p +Note: SYMS can be called as a real function. The returned value +is the final length of the plotted string. When i=2 no plotting +is done but the length is returned. When i=-2 the string is plotted +and the lower left corner of the next character position after +the end of the string is returned in x,y. +.p +Note: VAX FORTRAN CHARACTER types +can not be used directly since calling subroutines with CHARACTER types +is done by DESCRIPTOR. Use BYTE or INTEGER arrays for s or use %REF() +for character variables, i.e., call SYMS(0., 0., .25, %REF(S), 0., 10, -1). +See the section on machine dependency. +.lit + +rlen = SYMS (x,y,h,s,a,n,i) + +x,y (R): string position (x,y returned if i=-2 or i=-3) + If x=999 then x is continued from last position in + prior SYMS call. If y=999 then y continued. +h (R): height of the string to be printed +s (B): alpha array containing the text to be plotted +a (R): angle at which the string is to be plotted +n (I): number of characters in string s +i (I): centering flag + = -3 : same as -2 but string is not plotted and + last position is not affected + = -2 : same as -1 but returns end point in x,y + = -1 : (x,y) is lower left corner of plotted string + = 0 : (x,y) is center of plotted array + = 1 : (x,y) is lower right corner of plotted string + = 2 : no plotting, plotted length of string returned + +rlen (R): (returned) length of plotted text string +.end lit + +.hl1 REAL FUNCTION SYMSS +.p +.x character plots +~SYMSS is identical to SYMS except that it plots "smoothed" characters +using the software linetype generation routine LINSEQ. +Smoothing improves the appearance of most of the fonts +when the characters are plotted at large scale. See ~SYMS and ~LINSEQ for +additional details. +.lit + +rlen = SYMSS (x,y,h,s,a,n,i,al,l1,l2,l3,l4,l5) + +x,y (R): string position (x,y returned if i=-2 or i-3) + If x=999 then x continued from from last position in + prior SYMS call. If y=999 then y continued. +h (R): height of the string to be printed +s (B): alpha array containing the text to be plotted +a (R): angle at which the string is to be plotted +n (I): number of characters in string s +i (I): centering flag + = -3 : same as -2 but string is not plotted and + last position is not affected + = -2 : same as -1 but returns end point in x,y + = -1 : (x,y) is lower left corner of plotted array + = 0 : (x,y) is center of plotted array + = 1 : (x,y) is lower right corner of plotted array + = 2 : no plotting, plotted length of string returned +al (R): smoothed arc length (typically 0.05 to 0.01) +l1-5 (I): LINSEQ arc type, use l1=0 for a solid line. + +rlen (R): (returned) length of plotted text string +.end lit + +.hl SUBROUTINE VFACTOR +.p +~VFACTOR is called by ~FACTOR to change the input scale conversion factor +for the LONGLIB metafile package. It may be called separately if desired. +Only the terminal plotting package +is affected. The routines ~PFACTOR and ~RFACTOR may be separately +called to change the input scale conversion factor on the metafile and +Ramtek packages, respectively. See FACTOR. +.lit + +CALL VFACTOR (fac) + +fac (R): new conversion factor for coordinate values + (only the terminal scaling is affected) + <= 0 : reset scale factor to unity + > 0 : new scale factor +.end lit + +.hl1 SUBROUTINE VPEN +.p +.x line type +.x rmpen +.x ppen +~VPEN is called by ~NEWPEN to change the hardware line type and/or width of +the plotting line for subsequent plotting on the terminal screen device. +It may be called separately to change only the terminal line type. +Metafile and Ramtek and terminal output device line types may be changed +separatly using PPEN and RMPEN, respectively. While the terminal output +device driver supports line types in hardware, line widths are supported in +software by outputing multiple single-width lines offset by one pixel. +Line type scale factors (the length of the linetype +dot/dash pattern) are not used. Not all terminals support all +standard line types. If a particular terminal does not support the +requested line type, normally a solid line is used. +The default line type is a solid line of width 1 dot. +.lit + +CALL VPEN (i) + +i (I): selects a line type for all additional plotting + to the terminal screen output device + < 0 : resets line type to solid line of unit width. + = 0 : line type 0 no change in line width + > 0 : line type and width changed according to, + (1's digit) : line type (0-9) + (10's digit) : line width (1-7) (0 value does not change width) + (100's digit) : line type pattern scaling (ignored) +.end lit + +.hl1 SUBROUTINE WHERE +.p +~WHERE returns the location from the last call to PLOT. +The Zoom scale factor value is returned from the LONGLIB graphics device +packages in the priority order: ~terminal if open or ~Ramtek if open or +else from the metafile. Does nothing when no device is open. +.lit + +CALL WHERE (x,y,z) + +x,y (R): (returned) values of x,y from last call to plot +z (R): (returned) zoom value. +.end lit + +.hl1 SUBROUTINE WHEREPR +.p +~WHEREPR returns information on the metafile plotting parameters. If lu <= 0 +then metafile has not been initialized. A routine ~FIXPR0 (which +has the same parameters) may be used +to set these variables to absolute values without error checking. +.lit + +CALL WHEREPR (x,y,ax,ay,z,a,rx,ry,lu,m,iw,ic) + +x,y (R): (returned) current origin +ax,ay (R): (returned) last scaled and shifted origin point +z (R): (returned) current zoom scale factor +a (R): (returned) current plotting angle +rx,ry (R): (returned) resolution of metafile +lu (I): (returned) FORTRAN file output unit number + (if lu <= 0 metafile package not initialized) +m (I): (returned) current line type +iw (I): (returned) current line width +ic (I): (returned) current line color +.end lit + +.hl1 SUBROUTINE WHERERM +.p +~WHERERM returns information on the ~Ramtek plotting parameters. If c <= 0 +then ramtek has not been initialized. A routine ~FIXRM0 (with +same parameters) may be used +to set these variables to absolute values without error checking. +.lit + +CALL WHERERM (x,y,z,a,rx,ry,nt,ns,i,ic) + +x,y (R): (returned) current origin +z (R): (returned) current zoom scale factor +a (R): (returned) current plotting angle +rx,ry (R): (returned) current pixel resolution +nt (I): (returned) current line bit pixel pattern +ns (I): (returned) current line bit scale factor +i (I): (returned) Ramtek color +ic (I): (returned) Ramtek channel + (if ic <= 0 ramtek is not initialized) +.end lit + +.hl1 SUBROUTINE WHEREVT +.x Selanar +.x vt100 +.x vt125 +.x vt240 +.x vt220 +.p +~WHEREVT returns information on the ~terminal plotting parameters. If nv <= 0 +then terminal graphics have not been initialized. A routine +~FIXVT0 (with same arguments) may be used to set these variables to +~absolute values without error checking. +.lit + +CALL WHEREVT (x,y,z,a,rx,ry,iv,ns,it,iw,ic) + +x,y (R): (returned) current origin +z (R): (returned) current zoom scale factor +a (R): (returned) current plotting angle +rx,ry (R): (returned) current pixel resolution +iv (I): (returned) terminal code + (if nv <= 0 terminal is not initialized) +ms (I): (returned) internal terminal-type code + = 1 VT100 with Selanar GR100 + = 2 VT125 + = 3 VT240 + = 4 VT220 with Selanar GR220 + = 5 Tektronix 4010 + = 6 Tektronix 4109 + = 7 Graphon GO-235 +it (I): (returned) current line type +iw (I): (returned) current line width +ic (I): (returned) current line color +.end lit + +.CHAPTER Description of 3-d Plotting Routines +.x 3-d plotting +.p +The following paragraphs contain detailed descriptions of the subroutines +included in the LONGLIB library for 3-d plotting. For added flexibility, +two distinct families of 3-d plotting routines have been provided. +One family is designed for plotting with hidden line removal; +the other family is more flexible but does not perform hidden line removal. +Both options assume that ~FRAME has already been called, i.e. the plot +package is already opened. The 3-d routines call ~PLOT as output so +that the 2-d plot origin, scaling, rotation, etc. are used in addition +to any 3-d operations. +.p +The nominal Z axis of the 3-d plot packages for plotted objects runs out +of the screen. The X and Y axes are defined as before. +.p +.x hidden line removal +Two separate, independent 3-d packages exist. These are identified by +the initialization routines used for each package. The hidden line +removal package is ~INIT3DH and is a modification of the ~COSMIC hidden +line code package (ARC-11446). The other is INIT3D. ~INIT3D does +not perform any hidden line removal. These package differ not only in +hidden line removal but also in speed of operation and memory requirements. +The packages are completely independent. Only routines designed for a +particular package will work with that package. It is possible to +use both simultaneously. + +.hl 1 INIT3D Routines +.p +The INIT3D 3d plotting package permits 3-d plotting but does not include +hidden line removal. +The family of routines used with ~INIT3D include: +.s1 +.ls0 +.le;PLOT3D -- the central plot routine for INIT3D +.le;AXIS3D -- plots axes using PLOT3D, NUM3D, and SYM3D +.le;NUM3D -- plots numbers using PLOT3D +.le;SYM3D -- plots symbols using PLOT3D +.le;WHERE3D -- returns the screen coordinates of the last point +drawn by PLOT3D. +.els +.p +The ~INIT3D family of 3-d plotting routines are desiged to plot +wireframe line plots with no hidden line removal. Memory requirements +are modest and plotting is more rapid than for the ~INIT3DH routines. +For an example of the use of the INIT3D package see the ~EXAMP3D +program included with the LONGLIB graphics library. + +.hl2 SUBROUTINE INIT3D +.p +~INIT3D sets the ~absolute origin, rotations, and ~scale ~factor of +the 3-d package. These functions are distinct from the functions of +PLOT. INIT3D may be called at any time to reset these functions without +closing the plot package. The plot package must be opened with ~FRAME +prior to the call to INIT3D. +.lit + +CALL INIT3D (x,y,z,xa,ya,za,t,ds,sf,i) + +x,y,z (R): coordinates of view point (looking from) +xa,ya,za (R): coordinates of center point (looking to) +t (R): rotation angle around line from (x,y,z) to + (xa,ya,za) in degrees CCW. +ds (R): perspective scale factor (image size/viewing distance) +sf (R): relative scale factor +i (I): plotting flag ( -1 = do not plot, scaling only) +.end lit + +.hl2 SUBROUTINE AXIS3D +.x AXIS3 +.x PLOT3D +.x NUM3D +.x SYM3D +.p +~AXIS3D plots an axis and its markings in 3-d. In order to draw a +coordinate system, the routine has to be called separately for the x, +y, and z axis. A possible exponent is determined and placed behind the +axis label in the form of 10**n in the auto scaling mode (see AXIS3). +AXIS3D calls PLOT3D, NUM3D, and SYM3D. See also AXIS3. +.lit + +CALL AXIS3D (x,y,x,a,b,g,s,n,ale,xm,xx,t,c,f) + +x,y,z (R): location of start of axis +a,b (R): angles from the x-y, x-z planes (in deg) of the ray + from (x,y,z) along the character string +g (R): angle of rotation about the ray defined by a,b (deg) +s (B): alpha string containing the axis title +n (I): number of characters in the string + > 0 : axis labelling on positive side (anti-clockwise) + < 0 : axis labelling on negative side (clockwise) + (100's digit) = 0 : axis is labeled + = 1 : line and ticks only--no labeling +ale (R): length of axis + < 0 : tick marks placed on same side of axis as title + = 0 : no action + < 0 : tick marks placed opposite side of axis from title +xm (R): value of first marking on the axis +xx (R): value of last marking on the axis +t (R): number of tick marks + specification is coded in the form MMM.mmss where + MMM is the number of major tick marks ( MMM > 0), mm is + the number of minor tick marks between major tick marks + (100 > mm => 0), and ss is the number of subminor tick + marks between minor tick marks (100 > ss => 0). + (example 1.0102 produces I_._._i_._._I) +c (R): size of characters + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +f (R): number label format (see NUMBER) +.end lit + +.hl2 SUBROUTINE NUM3D +.x number +.x plot3d +.p +~NUM3D plots a floating point number (see NUMBER) in 3-d using +PLOT3D. The symbols are plotted in the plane defined by a,b,g. +.lit + +CALL NUM3D (x,y,z,a,b,g,f,e) + +x,y,z (R): lower-left corner of string + If x=999, y=999, z=999 then string is continued from + lower right of previous SYM3D or NUM3D call +a,b (R): angles from the x-y, x-z planes (in deg) of the ray + from (x,y,z) along the base of the character string +g (R): angle of rotation about the ray defined by a,b (deg) +h (R): height of the number to be plotted +f (R): number to be plotted +e (R): format of number representation n.j + (see NUMBER for detailed description) +.end lit + +.hl2 SUBROUTINE PLOT3D +.x CPLOT3D +.p +~PLOT3D is the 3-d version of PLOT. A relative ~rotation matrix and +~origin is maintained (separate from viewing matrix and PLOT parameters). +By setting the plotting option flag i in ~INIT3D to -1, plotting will be +inhibited. A common block, CPLOT3D, returns a 4 element vector V +with the screen transformed coordinates. +PLOT3D transforms the 3d input coordinates +to 2d coordinates, clips to a 3d clipping window, and calls ~PLOT with +the 2d coordinates screen coordinates of the visible line segments. +.x screen coordinates +.lit + +CALL PLOT3D (x,y,z,i) + +x,y,z (R): coordinates of point (in 3 space) +i (I): plot function parameter + = 0: color control + x is the line color + if x < 0 the screen is cleared + if x >= 0 2d plot angle (PLOT) becomes y + = -1: change relative scale factor by x + = 1: change relative rotation matrix + rotate x degrees CCW around x axis + rotate y degrees CCW around y axis + rotate z degrees CCW around z axis + = 2: draw to (x,y,z) with 'pen down' + = -2: same as i=2. (x,y,z) becomes new origin + = 3: move to (x,y,z) with 'pen up' + = -3: same as i=3. (x,y,z) becomes new origin + = 9: erase to (x,y,z) (erase is color 0) + = -9: same as i=9. (x,y,z) becomes new origin + +common /CPLOT3D/V(4) : returned screen coordinates (x,y) of last + call to PLOT3D v(1)=x, v(2)=y +.end lit + +.hl2 SUBROUTINE SYM3D +.x SYMBOL +.p +~SYM3D plots an ~ASCII string (see SYMBOL) in 3-d using +PLOT3D. The ~symbols are plotted in the plane defined by a,b,g. +.lit + +CALL SYM3D (x,y,z,a,b,g,s,n) + +x,y,z (R): lower-left corner of string + If x=999, y=999, z=999 then string is continued from + lower right of previous SYM3D or NUM3D call +a,b (R): angles from the x-y, x-z planes (in deg) of the ray + from (x,y,z) along the base of the character string +g (R): angle of rotation about the ray defined by a,b (deg) +h (R): height of the string to be plotted +s (B): alpha array containing the text to be plotted (byte array) +n (I): number of characters in string s +.end lit + +.hl2 SUBROUTINE WHERE3D +.p +~WHERE3D returns the 2d screen coordinates of the last line drawn using +PLOT3D. +.lit + +CALL WHERE3D (x,y) + +x,y (R): (returned) screen coordinates of last point +.end lit + +.hl1 INIT3DH Routines +.p +The family of plotting routines included in the hidden line 3-d +packge INIT3DH include: +.s1 +.ls0 +.le;PLT3DH -- the central visible line plot routine for INIT3DH +.le;SKETCH -- the central hidden line plot routine for INIT3DH +.le;AXIS3DH -- plots axes using PLT3DH or SKETCH +.le;CUBE -- plots the polygons of the sides of a "cube" +.le;SYM3DH -- plots symbols using PLT3DH or SKETCH +.le;WHERE3H -- returns the screen coordinates of the last PLT3DH call +.le;XFRM3D -- transforms a point (x,y,z) into the perspective point +defined by INIT3D. +.els +.x hidden line removal +.p +The central hidden line plot routine SKETCH is an adaptation of the +~COSMIC routine ARC-11446 hidden line code. It has been modified +and extended for additional features. The INIT3DH can be used either +with or without the hidden line removal. However, the memory and +computational requirements for hidden line removal can be large for +complicated scenes. Essentially, planar polygons are defined and +entered into the SKETCH internal list. Upon the last call to +~SKETCH the visible lines are plotted using PLOT. Line segments can also be +entered into the SKETCH list prior to the last call. They will not +"hide" any other lines but can be hidden by planes. The SKETCH +routine can be set to plot both visible and invisible lines. +~PLT3DH does not use SKETCH. Lines plotted with PLT3DH will always +be visible. The auxilary routines (NUM3DH, AXIS3DH, and SYM3DH) +have options to either use ~SKETCH or PLT3DH. +.p +For an example of the use of the ~INIT3DH package see the ~EXAMP3DH +program included with the LONGLIB graphics library package +or see the ~MASTER routines TRIG3DH, HIST3D, or T3DH. +.x TRIG3DH +.x T3DH +.x HIST3D + +.hl2 SUBROUTINE INIT3DH +.p +.x hidden line removal +~INIT3DH sets the relative ~origin and ~scale ~factor of the 3-d +package which includes hidden line removal. These functions are distinct +from the functions of PLOT or PLOT3D. INIT3DH may be called at any time +to reset these functions without closing the plot package. However, a +call to INIT3DH resets the internal SKETCH list of polygons. The plot +package must be opened with FRAME prior to a call INIT3DH. INIT3DH must +be called prior to SKETCH or PLT3DH. ~SKETCH uses an internal common +block for storage of its internal list. The user is required to provide +sufficient common block storage space. This common block is defined: +.lit + + COMMON /GO/ ISIZE, WORK(ISIZE) +where + ISIZE >=(25 + 5*MNE + 4*(2+MNE+2*MNH))*NPOLYS + MNE = maximum number of edges per polygon + MNH = maximum number of edges per polygon + NPOLYS= maximum number of polygons + +.end lit +If SKETCH is not used, this common block need not be dimensioned. +Note that ISIZE must be given a value in the user's code. +.p +The angles ya,ro,pi are defined as the sequence of rotations ya-ro-pi +(yaw, roll, and pitch) +where ya is the angle or rotation about the z axis (positive is +from x to y). ro is the angle of rotation about the x axis +(positive is from y to z). pi is the angle of roation about the y +axis (positive is from z to x). +.lit + +CALL INIT3DH (x,y,z,ya,ro,pi,zom,ds,mne,mnh) + +x,y,z (R): coordinates of relative origin +ya,ro,pi (R): yaw, roll, pitch angles (Eulerian) in degrees + (see above for angle definitions) +zom (R): relative scale factor +ds (R): viewing distance (9999. = infinity or no pespective) +mne,mnh (I): maximum number of edges and holes on one polygon +.end lit + + +.hl2 SUBROUTINE AXIS3DH +.x SKETCH +.x NUM3DH +.x SYM3DH +.x hidden line removal +.x AXIS3 +.p +~AXIS3DH plots an axis and its markings in 3-d. In order to draw a +coordinate system, the routine has to be called separately for the x, +y, and z axis. A possible exponent is determined and placed behind the +axis labelling in the form of 10**n in the auto scaling mode. AXIS3DH +calls ~PLT3DH or SKETCH, NUM3DH, and SYM3DH. See AXIS3. +.lit + +CALL AXIS3DH (x,y,x,a,b,g,s,n,ale,xm,xx,t,c,f,i) + +x,y,z (R): location of start of axis +a,b (R): angles from the x-y, x-z planes (in deg) of the ray + from (x,y,z) along the character string +g (R): angle of rotation about the ray defined by a,b (deg) +s (B): alpha string containing the axis title +n (I): number of characters in the string + > 0 : axis label on positive side (anti-clockwise) + < 0 : axis label on negative side (clockwise) + (100's digit) = 0 : labeled axis + = 1 : line and ticks only--no labeling +ale (R): length of axis + > 0 : tick marks placed same side of axis as title + = 0 : no action + < 0 : tick marks placed opposite side of axis from title +xm (R): value of first marking on the axis +xx (R): value of last marking on the axis +t (R): number of tick marks + specification is coded in the form MMM.mmss where + MMM is the number of major tick marks ( MMM > 0), mm is + the number of minor tick marks between major tick marks + (100 > mm => 0), and ss is the number of subminor tick + marks between minor tick marks (100 > ss => 0). + (example 1.0102 produces I_._._i_._._I) +c (R): size of characters + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +f (R): number label format (see NUMBER) +i (I): hidden line option flag + = 0 : use PLT3DH + = 1 : use SKETCH +.end lit + + +.hl2 SUBROUTINE CUBE +.p +~CUBE plots the 6 surface polygons of a 3-d "cube" into the +~INIT3DH 3-d plotting package. Either ~SKETCH or ~PLT3DH may be used. +.lit + +CALL CUBE (x1,x2,y1,y2,z1,z2,i,h) + +x1,y1,z1 (R): corner of cube +x2,y2,z2 (R): oposite corner of "cube" from corner 1 +i (I): SKETCH flag for last SKETCH call in routine + Note: (returned) value is the SKETCH return +h (L): hide flag + = .TRUE. SKETCH routine used + = .FALSE. PLT3DH routine used +.end lit + +.hl2 SUBROUTINE NUM3DH +.p +.x SKETCH +.x number +.x hidden line removal +~NUM3D plots a floating point number (see NUMBER) in 3-d using either +~PLT3DH or SKETCH. The symbols are plotted in the plane defined by a,b,g. +.lit + +CALL NUM3DH (x,y,z,a,b,g,f,e,i) + +x,y,z (R): lower-left corner of string + If x=999, y=999, z=999 then string is continued from + lower right of previous SYM3DH or NUM3DH call +a,b (R): angles from the x-y, x-z planes (in deg) of the ray + from (x,y,z) along the base of the character string +g (R): angle of rotation about the ray defined by a,b (deg) +h (R): height of the number to be plotted +f (R): alpha array containing the text to be plotted (byte array) +e (R): format of number representation n.j + (see NUMBER) +i (I): hidden line option flag + = 0 : use PLT3DH + = 1 : use SKETCH +.end lit + +.hl2 SUBROUTINE PLT3DH +.p +.x hidden line removal +~PLT3DH is a routine which operates in a similar as PLOT but in 3-d. +It is, however, independent of PLOT3D. A relative ~origin is +maintained (separate from the PLOT routine parameters) which is +initalized by INIT3DH. PLT3DH calls PLOT after transforming (x,y,z). +PLT3DH is also independent of the ~SKETCH routine. Lines plotted with +PLT3DH are always completely visible. +To use the hidden line removal SKETCH must be used. +.lit + +CALL PLT3DH (x,y,z,i) + +x,y,z (R): coordinates of point (in 3 space) +i (I): plot function parameter + = 0: line color control + x is the line color + if x < 0 screen is cleared + if x >= 0 plotting angle (in PLOT) becomes y + = 2: draw to (x,y,z) with 'pen down' + = -2: same as i=2. Point (x,y,z) becomes new origin + = 3: move to (x,y,z) with 'pen up' + = -3: same as i=3. Point (x,y,z) becomes new origin + = 9: erase to (x,y,z) (erase on Ramtek is color 0) + = -9: erase to (x,y,z) becomes new origin +.end lit + +.hl2 SUBROUTINE SKETCH +.p +.x hidden line removal +~SKETCH is the central plot routine for hidden line removal 3-d plotting. +SKETCH is called for each ~polygon or line segment. Each polygon or +line segment is described by a set of points in (x,y,z) arrays. +For polygons, +these should be in either clockwise or counter-clockwise direction with +the last point equal to the first. Holes in polygons are created by +continuing the last outer edge point (which is also the first outer edge +point) to the inner hole edges and back. The option flag, i, should be 0 +for all but the last polygon. When i=0, SKETCH stores the input polygons. +When i is set to be 1, the resulting scene visible lines are computed and +plotted by calls to PLOT. This process may take considerable cpu time +as well as memory storage space when the number of polygons is large. +The maximum number of edges of a polygon is 160. +.p +Note that SKETCH requires a large working area in a named ~COMMON area +described in INIT3DH. Note SKETCH will fail if the memory limits are +exceeded. For the most part an error flag will be set. Ocassionally, +the scene will be corrupted when the memory limits are exceeded without +the error flag being set. +.lit + +CALL SKETCH (x,y,z,np,i) + +x,y,z (R): arrays contain polygon edges (max 160) +np (I): number of points in x,y, and z +i (I): option flag. Should be 0 for all input polygons + except the last, when it should be 1. + + (Note: if i+10 is used for i then the first z value + is used for all (x,y) points.) + + i set to -1 (returned) if a memory error occurs +.end lit + +.hl2 SUBROUTINE SYM3DH +.x SKETCH +.x SYMBOL +.x hidden line removal +.p +~SYM3DH plots an ASCII string (see SYMBOL) in 3-d using either ~PLT3DH +or SKETCH. The symbols are plotted in the plane defined by a,b,g. +.lit + +CALL SYM3DH (x,y,z,a,b,g,s,n,i) + +x,y,z (R): lower-left corner of string + If x=999, y=999, z=999 then string is continued from + lower right of previous SYM3DH or NUM3DH call +a,b (R): angles from the x-y, x-z planes (in deg) of the ray + from (x,y,z) along the base of the character string +g (R): angle of rotation about the ray defined by a,b (deg) +h (R): height of the string to be plotted in plot units +s (B): alpha array containing the text to be plotted +n (I): number of characters in string s +i (I): hidden line option flag + = 0 : use PLT3DH + = 1 : use SKETCH +.end lit + +.hl2 SUBROUTINE WHERE3H +.x PLT3DH +.p +~WHERE3H returns the 2d screen coordinates of the last point in a call to +PLT3DH. +.lit + +CALL WHERE3H (x,y) + +x,y (R): screen coordinates of last point of call to PLT3DH +.end lit + +.hl2 SUBROUTINE XFRM3D +.p +~XFRM3D uses the same scaling and origin as PLT3DH and SKETCH to +transform a 3-d points to screen (PLOT) coordinates. +.lit + +CALL XFRM3D (x,y,z,x1,y1,z1) + +x,y,z (R): input coordinates of point (in 3 space) +x1,y1,z1 (R): (returned) transformed coordinates of point (in 3 space) +.end lit + + +.CHAPTER Cursor Routines +.x INXTCHR +.p +The routines described in this chapter provide interactive cursor control. +When supported by the terminal, the Tektronix Graphics Inputs (GIN), +BITCURSOR or GETCURSOR, routines can be used. If the terminal has +a VT100-compatible text mode, the routines CURMOTION, CURRECT, and CURBAND, +can be used to simulate a GIN device. These routines use the VT100 +keypad and cursor keys. They rely on a machine-dependent routine +(INXTCHR) to read escape characters from the terminal. CURMOTION, +CURRECT, and CURBAND return the internal screen "resolution" used +in computing the location of the cursor. This may not correspond to the +actual hardware resolution of the terminal screen. +.p +The routine CURLOCATE provides +a technique for placing a fixed "cursor mark" on the screen. +.p +A program CURTEST is provided to test and evaluate these cursor routines. + +.hl1 SUBROUTINE BITCURSOR +.x cursor +.x graphics tablet +.x bit pad one +.x vt125 +.p +~BITCURSOR moves a cross-hair cursor on a VT100 equipped with a retro-graphics +card (VT125) and a BIT PAD ONE graphics tablet. The VT125 is used in the +Tek 4010 mode with a graphics point returned when a key is pressed on the +bit pad puck (or stylus). +.lit + +CALL BITCURSOR (x,y,k,rx,ry) + +x,y (R): (returned) selected cursor position (in plot units) +k (I): (returned) key code + = 0 (Z) key pressed on bit pad puck + = 1 (1) key pressed on bit pad puck + = 2 (2) key pressed on bit pad puck + = 3 (3) key pressed on bit pad puck +rx (R): resolution of screen in x direction (returned) +ry (R): resolution of screen in y direction (returned) +.end lit + +.x cursor +.hl1 SUBROUTINE CURLOCATE +.p +~CURLOCATE produces a simulated "x" cursor mark on the screen graphics +device (~Ramtek or ~terminal device) +When only the metafile is initialized a call to CURLOCATE is a dummy call. +The terminal takes precidence over the Ramtek when both are in use. +Erasure of cursor on requires the correct location where it was first plotted. +CURLOCATE uses the ~XOR capbility of graphics terminal to place and +remove the cursor. If the terminal has neither erase or XOR capability, +the graphics cursor can not be erased without clearing the entire screen. +If the (x,y) position is off the screen, the cursor will be located on +closest edge of the screen to the desired point. +.lit + +CALL CURLOCATE (x,y,n,ir) + +x,y (R): cursor position +n (I): cursor number/size (0-4) + < 0 erase cursor + > 0 locate cursor +ir (I): Ramtek cursor control (recognized if Ramtek is output) + = 0 Ramtek cursor device used + = 1 plotted Ramtek cursor mark used +.end lit + +.hl1 SUBROUTINE CURMOTION +.p +~CURMOTION produces a graphics ~cursor on the ~Ramtek or ~terminal +When no screen devices are initialized a call to CURMOTION is a dummy call. +Terminal is used in preference to Ramtek. +This routine is supported only on terminals which can emulate the VT100 +numeric keypad. The terminal text cursor and VT100 numeric keypad +keys are used to move the graphics cursor to a desired location and +a return function key is pressed to select the cursor location. Only +, , PF keys and the numeric key pad keys will be recognized +as return command keys. PF1 changes the cursor step movement size in three +sizes. As this happens the cursor changes sizes on the screen. +The cursor position is typed to the terminal when the Ramtek is used. +The cursor is moved in multiples of the pixel resolution. The +formula below shows the conversion. All other PF keys and the numeric +key pad keys will return the arguments shown below. Other keys are +not recognized. NOTE: The input buffer is 128 characters. If you exceed +this buffer the program may bomb. Each cursor key input uses 3 characters. +.lit + + pixel number = (scalefactor * x + origin)/pixelresolution + +.end lit +.lit +CALL CURMOTION (x,y,is,rx,ry) + +x,y (R): (returned) selected cursor position +is (I): (returned) status flag + < 0 error + = 0 return key pressed + = 1 space key pressed + = 2,3,4 PF2,PF3,PF4 keys on VT100 pressed + = 10...19 VT100 numeric key pad keys 0...9 pressed + = 20 numeric key pad period key pressed + = 21 numeric key pad enter key pressed + = 22 numeric key pad comma key pressed + = 23 numeric key pad dash key pressed +rx (B): resolution of screen in x direction (returned) +ry (R): resolution of screen in y direction (returned) +.end lit + +.hl1 SUBROUTINE CURBAND +.p +CURBAND is similar to the ~CURMOTION subroutine except that two +lines are "rubber banded" with the simulated cursor motion. This +routine is supported only on terminals which can emulate the VT100 +numeric keypad. The line segment rubberbanding can be disabled if desired. +.lit + +CALL CURBAND (x,y,is,rx,ry,x1,y2,x2,y2) + +x,y (R): (returned) selected cursor position +is (I): (returned) status flag + < 0 error + = 0 return key pressed + = 1 space key pressed + = 2,3,4 PF2,PF3,PF4 keys on VT100 pressed + = 10...19 VT100 numeric key pad keys 0...9 pressed + = 20 numeric key pad period key pressed + = 21 numeric key pad enter key pressed + = 22 numeric key pad comma key pressed + = 23 numeric key pad dash key pressed +rx (R): resolution of screen in x direction (returned) +ry (R): resolution of screen in y direction (returned) +x1,y1 (R): starting point of rubber banded line 1 + if x1=999, this line segment is not used +x2,y2 (R): starting point of rubber banded line 2 + if x2=999, this line segment is not used +.end lit + +.hl 1 SUBROUTINE CURRECT +.p +~CURRECT is similar to the ~CURBAND subroutine except that a +~rectangle is moved with cursor motion. This +routine is supported only on terminals which can emulate the VT100 +numeric keypad. +.lit + +CALL CURRECT (x,y,is,rx,ry,x1,y2,x2,y2) + +x,y (R): (returned) selected cursor position/start position +is (I): (returned) status flag + < 0 error + = 0 return key pressed + = 1 space key pressed + = 2,3,4 PF2,PF3,PF4 keys on VT100 pressed + = 10...19 VT100 numeric key pad keys 0...9 pressed + = 20 numeric key pad period key pressed + = 21 numeric key pad enter key pressed + = 22 numeric key pad comma key pressed + = 23 numeric key pad dash key pressed +rx (R): resolution of screen in x direction (returned) +ry (R): resolution of screen in y direction (returned) +x1,y1 (R): lower left corner of rectangle +x2,y2 (R): upper right corner of rectangle +.end lit + +.hl SUBROUTINE GETCURSOR +.p +~GETCURSOR inquires the ~Tektronix GIN device for the location +pointed to by the GIN device. Return code is screen device +dependent. This routine is does support all screen devices. When +a device is not supported, the routine returns without doing anything. +Screen device must be in the graphics mode. +GETCURSOR assumes that the ~GIN terminator is a CR (carriage return). +Note: When using an Alpha +key for the return status DO NOT use the key as this will prevent +the correct reading of the returned data. +.lit + +CALL GETCURSOR (x,y,k,rx,ry) + +x,y (R): (returned) cross-hair location (in LONGLIB coordinates) +k (I): (returned) GIN status code return (ascii code) +rx (R): resolution of screen in x direction (returned) +ry (R): resolution of screen in y direction (returned) +.end lit + +.CHAPTER MAP SUBROUTINES + +.x map routines +.x earth.dat +.x lndsea1.dat +.p +LONGLIB also supports the plotting of maps of the physical earth's surface +by providing map routines. +Two data files (EARTH.DAT and LNDSEA1.DAT) are included in the LONGLIB +graphics library package. EARTH.DAT contains the digitized locations of +the edges of the earth's landmasses. It forms the basis of a set of +EARTH OUTLINE map routines discussed below. LNDSEA1.DAT contains a bit map +of land/sea areas. It forms the basis of the LAND AREA map routines discusses +in the second section. +.p +Note: these routines assume that the plot package has already been opened. + +.hl 1 EARTH OUTLINE MAPS +.p +To date only a small number of routines have been generated for using this data +file but more will be added in the future. Current routines allow for +plotting the ~earth outline map in 3d or in a linear projection. +.p +A data file (EARTH.DAT) which contains a ~map of the land/ocean interface +and a set of routines to access this data has been included in the LONGLIB +graphics library. The data file (of unknown origin) contains a list of +latitudes and longitudes of the land/ocean edges at about a 10 km resolution. +It is only a geographic map and does not contain political boundries. +Although imperfect, it is more than adequate for map drawing, etc. +Due to the high resolution, the EARTH.DAT file contains a lot of pen +motions, requiring a long plotting time. +.p +Fortran file unit 2 should be reserved for accessing the map data +file by these routines. The logical name ~LONGLOC: must be assigned +to be the location of the EARTH.DAT file. +.p +Routines using the land outline file include those for plotting on +3d spheres, flat surfaces, etc. + +.hl 2 SUBROUTINE EARTH3D +.p +~EARTH3D permits 3d plotting of the earth land map. This routine +uses the ~INIT3D and ~PLOT3D 3d graphics package. It will plot the +entire earth map with the option of either a spherical earth or +an ellipsoidal earth. The radius may be specified. The transformation +from a latitude/longitude pair (a,b) in radians on the earth's suface to the +3d plotting vector v is: +.lit + + rad = r * (1 - f*sin(a)) + call sprect1(v,b,a-pi/2,rad) + call plot3d(v(1),v(2),v(3),2) +where + pi = 3.141592654 + v is dimensioned v(3) +.end lit +.lit + +CALL EARTH3D(r,f) + +r (R): nominal earth radius (in plotting units) +f (R): earth flatness + = 0 for spherical earth + = 3.3528132e-3 for an ellipsoidal earth +.end lit + +.hl 2 SUBROUTINE LANDMAP +.x projection +.p +~LANDMAP plots the earth land map using a linear projection. The latitude +and longitude are assumed to be a linear grid on a flat surface. +This routine will plot the entire map surface. Use +of the PLOT routine clipping option will permit plotting only limited +of the map surface if desired. The transformation of a latitude/longitude +pair (a,b) in degrees to an (x,y) pair for plotting is: +.lit + + x = (b - s) * long / 360 + y = (a + 90) * lat / 180 +.end lit +.lit + +CALL LANDMAP(alat,along,s) + +alat,along (R): latitude, longitude scale factor (degrees/plot unit) +s (R): longitude of left-mode edge of map (-180 to +180) +.end lit + +.hl 2 SUBROUTINE POLARMAP +.x projection +.p +~POLARMAP plots the earth land map using a polar projection. The latitude +is plotted as a linear radius. This routine will plot the entire northern +or southern hemisphere. The transformation from a visible point (in the +appropriate hemisphere) latitude/longitude pair (a,b) in degrees to a +plotted (x,y) pair is: +.lit + + a = b * sgn(r) + a + x = cos( a * pi / 180) * r / 90 + x0 + y = sin( a * pi / 180) * r / 90 + y0 +where + pi = 3.141592654 +.end lit +.lit + +CALL POLARMAP(x0,y0,r,a) + +x0,y0 (R): pole location (in plot units) +r (R): radius of equator (in plot units) + > northern hemisphere + < southern hemisphere +a (R): angle of prime meridian from horizontal (deg CCW) +.end lit + +.hl 2 SUBROUTINE SPRECT1 +.p +~SPRECT1 converts a ~spherical coordinate value (in a latitude/longitude +style spherical system) to ~rectangular coordinates. +The transformation from a latitude/longitude pair (a,b) in degrees to a +rectangular (x,y) pair is: +.lit + + a = b * sgn(r) + a + x = cos( a * pi / 180) * r / 90 + x0 + y = sin( a * pi / 180) * r / 90 + y0 +where + pi = 3.141592654 +.end lit +.lit + +CALL SPRECT1(v,t,p,r) + +v (R): output vector containing rectangular (z,y,z) coordinates + dimensioned v(3) (returned) +t (R): theta (longitude) angle (rad) +p (R): phi (latitude) angle (rad) +r (R): radius +.end lit + +.HL1 Land Area Map Routines +.x LNDSEA +.p +The LNDSEA1.DAT file contains a bit ~map of the land/sea area of the earth. +Using the file, a specified point of latitude and longitude can be +determined to be land or sea. +A routine, LNDSEA, opens the file and provides a flag to indicate +if the specified point is land or sea. +.p +Fortran file unit 1 should be reserved for accessing the map data +file by these routines. The logical name ~LONGLOC: must be assigned +to be the directory containing the LNDSEA1.DAT file. + +.hl 2 LNDSEA1.DAT Format +.p +The LNDSEA1.DAT is a direct access file is a world land/sea map +quantized to every 1/12 degree of +both latitude and longitude. An individual bit is used to indicate whether +a particular point is land or sea. The data is stored as 648 records +each of which contains all of the data for a 10 degree by 10 degree square. +Each record consists of 14400 (120*120) bits stored 30 bits per word +(4 words per each 1/12 degree strip of data). +The first word of the record indicates whether the entire 10 by 10 square +is all land or water using the following definition: +.lit + + -1 : square contains both land and sea + 0 : square contains all land + 1 : square contains all water + +.end lit +The next 4 words in each record are the bits for the bottom 1/12 degree +(lowest latitude) row of the 10 degree by 10 degree square with +longitude bins left to right. For each bit a 0 indicates land and a +1 indicates water. The records are ordered: +.lit + + record # Latitude range Longitude range +_________ _______________ _________________ + + 1 -90 to -80 0 to 10 + 2 -90 to -80 10 to 20 + . . . + 35 -90 to -80 340 to 350 + 36 -90 to -80 350 to 360 + 37 -80 to -70 0 to 10 + 38 -80 to -70 10 to 20 + . . . + 648 80 to 90 350 to 360 +.end lit +.p +See the source code for ~LNDSEA function for additional information. + +.hl 2 SUBROUTINE BITMAP +.x projection +.p +~BITMAP plots a land area by testing each point of the area using LNDSEA. +The plotting area is segmented into (nx X ny) regions. Each point is tested +for the presence of land/sea. For each resolutoin line of latitude, +a horizontal line is drawn through all points that are land (or sea as desired). +A linear projection is used. The latitude +and longitude are assumed to be a linear grid on a flat surface. +This routine will plot the entire map surface. Use +of the PLOT routine clipping option will permit plotting only limited +of the map surface if desired. The transformation of a latitude/longitude +pair (a,b) in degrees to an (x,y) pair for plotting is: +.lit + + x = (b - s) * along / 360 + y = (a + 90) * alat / 180 +.end lit +.lit + +CALL BITMAP(alat,along,s,nx,ny,i) + +alat,along (R): latitude, longitude axis length (plot units) +s (R): longitude of left-mode edge of map (-180 to +180) +nx,ny (I): x,y resolution specified as the number of lat/longs + to test for land/sea +i (I): plot flag + = 0 plot land area + = 1 plot sea area +.end lit + +.hl 2 INTEGER FUNCTION LNDSEA +.x projection +.p +~LNDSEA tests the point (lat, long) for land/sea using the LNDSEA1.DAT file. +It returns a 0 for land, 1 for sea. Uses Fortran file unit 1. +.lit + +iflag = LNDSEA(alat,along) + +alat (R): latitude (-90. to +90. degrees) +along (R): longitude (0. to +360. degrees) +iflag (I): land/sea flag (returned) + = -1 : error + = 0 : land + = 1 : sea (ocean, lake, sea) +.end lit + + +.chapter MASTER Subroutines + +.p +By popular request, a set of the most commonly used general-purpose +subroutines for complete function plots, charts, etc., +were included in the LONGLIB graphics library. +These subroutines are called "MASTER" Subroutines. +Each of these subroutines is self contained. When called, it +will initialize the plotting package, plot the required data, +and close the plotting package. Normally, +only one ~MASTER subroutine is called in a program. +However, options are available for +multiple calls to MASTER subroutines. +When the LONGLIB is initialized by a MASTER subroutine (which calls FRAME) +a metafile using Fortran file unit 3 is always created. +.p +Programming examples using MASTER routines are given in the chapter +on programming examples. +.p +To call a MASTER subroutine more than once in +a program the option flag must be set negative for all calls +but the last one which should be positive. (See also the PLOTTESTS program.) +To use more than one MASTER subroutine in a program: +.ls.dle'(',,')' +.le; On first MASTER subroutine call +set the option flag negative--this does not close plot package. +.le; on all additional calls to +MASTER subroutines set the option negative and greater than 10000--this +prevents re-opening plot package and does not close it. +.le; On the last call to a MASTER subroutine set option flag positive +but greater than zero--this closes plot package. +.els +.p +In summary, when LONGLIB is already open set the magnitude of the option flag +to greater than 10000. To prevent closing the plot package set option +flag negative. +When the plot package is closed in a MASTER subroutine CTERM(-2) is used +to ask if a termina lscreen clear (terminal plotting only) should be done. +MASTER subroutines always return the terminal to the text mode after call. +When color options are enabled, the color marked "(return)" is +the color in current use after call. +.p +Note: when passing varables ~ASCII strings do not use ~VAX ~FORTRAN +~CHARACTER data type. Use ~BYTE data type arrays or use %REF(). See +the comments under the section on machine dependency and the introduction +to the plot routine section. +.x common block +.p +Most MASTER subroutines have +~common blocks with the same name prefixed with the letter +"C" which contain the scaling information used to plot +the data line. This can be useful for plotting additional annotations, +etc. +.p +The following pages document the currently defined MASTER Subroutines. +Additional subroutines may be added as suggested by the users. + +.hl1 MASTER Routine Index +.p +The sections that follow detail each MASTER routine. A brief index +of the capabilities of each Master routine is given below. To select +a MASTER routine, determine the category of plotting needed and +look at the available MASTER routine capabilities. For general purpose +line plotting where flexibility in specifying the axes, +the routine GLPLOT is recommended. + +.tp4 +.hl 2 Pie Chart +.ls0 +.le; PICHRT +.els + +.tp4 +.hl 2 Bar Chart +.ls0 +.le; BARCHR (can fill area between lines) +.els + +.tp4 +.hl 2 Single linear/linear line +.ls0 +.le; PLOTSC (simple) +.le; GLPLOT (flexible axis specification) +.le; PLOTLGXL (allows log lines, software line types) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 Two linear/linear lines on the same plot +.ls0 +.le; PLOTSC2 (simple) +.le; GLPLOT (flexible axis specification) +.le; PLOTLG2 (allows log lines) +.le; PLOTLGX (allows log lines, flexible axis specification) +.le; PLOTLGXL (allows log lines, software line types) +.le; BARCHR (can fill area between lines) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 Multiple linear/linear lines on the same plot +.ls0 +.le; GLPLOT (more complex but flexible axis specification) +.le; PLOTLGX (allows log lines, flexible axis specification) +.le; PLOTLGXL (software line types) +.le; SEISPL (special options) +.le; SPLOTS (can show error bars) +.le; SPLOTSX (can show error bars with flexible axis) +.le; BARCHR (can fill area between lines) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 Multiple log/linear or log/log lines on the same plot +.ls0 +.le; PLOTLG (relatively simple) +.le; PLOTLGX (more complex, flexible axis specification) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 Scatter plot +.ls0 +.le; SCATPL +.le; SPLOTS (can show error bars) +.le; SPLOTSX (can show error bars with flexible axis) +.le; SEISPL (special options) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 1-d Histogram +.ls0 +.le; PHIST (can show mean/standard deviation) +.le; BARCHR (bar chart) +.els + +.tp4 +.hl2 Lines/points with error bars +.ls0 +.le; SPLOTS (simple) +.le; SPLOTSX (flexible axis specification) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 Special plot formats +.ls0 +.le; SEISPL (forms used in seismic data plots) +.le; BARCHR (bar chart) +.le; PICHRT (pie chart) +.le; LSPLOT (options via array) +.els + +.tp4 +.hl2 Contour Plot with equally spaced data +.ls0 +.le; CNTRLN (simple, robust) +.le; LCNTR (simple, less-robust, contour line types and labels) +.els + +.tp4 +.hl2 Contour Plot with unequally spaced data +.ls0 +.le;CNTLN (triangulates points then contours) +.els + +.tp4 +.hl2 3-d Surface slices +.ls0 +.le; VAX3D (simple) +.le; VAX3DX (more complex, with flexible axis specification) +.els + +.tp4 +.hl2 3-d Surface mesh (no hidden line removal): +.ls0 +.le; MESH3D (simple) +.le; MESH3DX (more complex, with flexible axis specification) +.els + +.tp4 +.hl2 3-d Surface mesh (hidden line removal) +.ls0 +.le; MVAX3D (simple) +.le; MVAX3DX (more complex, with flexible axis specification) +.els + +.tp4 +.hl2 3-d Surface mesh with contour plot (hidden line removal) +.ls0 +.le; CVAX3D (simple) +.le; CVAX3DX (more complex, with flexible axis specification) +.els + +.tp4 +.hl2 3-d Surface triangular mesh (hidden line removal) +.ls0 +.le; T3DH (uses INIT3DH) +.els + +.tp4 +.hl2 Unequally sampled 3-d Surface (hidden line removal): +.ls0 +.le; TRIG3DH (uses INIT3DH) +.els + +.tp4 +.hl2 3-d Histogram with hidden line removal +.ls0 +.le; HIST3D (uses INIT3DH) +.le; MVAX3D (simple) +.le; MVAX3DX (more complex, with flexible axis specification) +.le; CVAX3D (simple, can include contour plot) +.le; CVAX3DX (with flexible axis specification, with contour plot) +.els + +.tp4 +.hl2 3-d Contour Plot with equally spaced data (no hidden line removal) +.ls0 +.le; CNT3D (simple, robust) +.le; CNT3DX (more complex, with flexible axis specification) +.els + +.tp4 +.hl2 4/5-d Surface plots: +.ls0 +.le; VAX5D (slices) +.le; MVAX5D (mesh/histogram with hidden line removal) +.els + + +.pg +.hl1 SUBROUTINE BARCHR +.p +~BARCHR plots a bar chart with optionally shaded bar segments and +descriptive legends. In addition, multiple lines with shading between +lines can be plotted. Legend can be automatically placed +or the user can specify the location of the legend. In the bar chart +mode, bars can run vertically or horizontally. +b(i,j) specifies the ith bar and jth segment of bar (or horizontal line +depending on iflag option). Top of jth segment or height of jth line +is computed from: +.lit + + j + yplotted = ylen * (Sum b(i,k) - bm)/(bx-bm) + k=1 +.end lit +.lit + +CALL BARCHR(b,nb,ns,sh,iflag,xl,yl,bm,bx,f,nd,sp,sl,nsl,bl,nbl,cs + t,nt,bt,nbt,lt,nlt,tcs,a,d,>) + +b (R): bar data array dimensioned b(nb,ns) +nb (I): number of bars/number of points in each line +ns (I): number of segments in each bar/number of lines +sh (I): shade option for segment/area between lines + dimensioned sh(ns) + sh shade pattern + ____ _________________________ + 0 no shading + 1 -45 deg solid lines + 2 horizontal solid lines + 3 +45 deg solid lines + 4 vertical deg solid lines + 5 -45 deg dotted lines + 6 horizontal dotted lines + 7 +45 deg dotted lines + 8 vertical deg dotted lines + 9 +/- 45 deg dotted lines + 10 vertical/horizontal dotted lines + 11 +/- 45 deg solid lines + 12 vertical/horizontal solid lines +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : color array not used + = 2 : color array used + (10's) = 0 : bar chart with vertical bars + = 1 : bar chart with horzontal bars + = 2 : multiple line chart + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +xlen (R): length of horizontal axis + < 0 : chart is enclosed in a box + > 0 : only bottom and left axes plotted +ylen (R): length of vertical axis +bm,bx (R): minimum and maximum values to be shown on chart + note: if bx=bm, values computed from b array will be used +f (R): format for numeric labels on axis (see NUMBER) +nd (I): number of divsions of bar length axis + < 0 : division lines shown on chart + = 0 : no division lines or numeric labels + > 0 : division lines shown +sp (R): width of bar (ignored for line plot) + = 0 : auto scaling with evenly spaced bars + > 0 : bars grouped in groups of int(sp). Each + bar has width frac(sp). +sl (C): segment legend labels (CHARACTER data type) + dimensioned sl(ns) +nsl (I): number of characters to use in plotting sl's + = 0 : no label plotted +bl (C): bar labels (CHARACTER data type) dimensioned bl(nb) +nbl (I): number of characters to use in plotting bl's + = 0 : no label plotted +cs (R): legend/bar label character height +t (B): title string placed on top of chart +nt (I): number of characters in t + = 0 : no label plotted +bt (B): title string placed at base of bars +nbt (I): number of characters in bt + = 0 : bt not plotted +lt (B): title string placed on bar length axis +nlt (I): number of characters in lt + = 0 : lt not plotted +tcs (R): height of title strings +a (R): legend location/shading box size dimensioned a(3) + a(1) : legend box size + < 0 : legend placed to right of chart, a(2) + and a(3) are not used + = 0 : no legend + > 0 : a(2) and a(3) used to locate legend + a(2) : x position of lower left corner of legend + a(3) : y position of lower left corner of legend +d (R): distance between shading lines + < 0 : line width array used + > 0 : line width array not used +ip (I): line width array (used only if d<0) + p(1) : axis line width + p(2) : division line width + p(3) : bar outline/data line width + p(4) : labeling line width + p(5) : title line width (bt,lt) + p(6) : title line width (t) +ic (I): color array (used only if mod(|iflag|,10)=2) + c(1) : t title color (return) + c(2) : bt title color + c(3) : lt title color + c(4) : axis numberic label colors + c(5) : sl label color + c(6) : bl label color + c(7) : segment 1 color + c(8) : segment 2 color + ... ... +.end lit + +.pg +.hl 1 SUBROUTINE CNT3D +.p +CNT3D plots a simple 3-d contour of equally spaced points with no hidden +line removal. (see CNT3DX) +~CNT3D calls CNT3DX using default axis parameters to simplify calling +procedure. +.lit + +CALL CNT3D(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,nl,as,ae,ie,iflag,iax, + ,l>>>) + +See CNT3DX for parameter description. + (iax is limited to a single digit value) +.end lit +.hl 1 SUBROUTINE CNT3DX +.p +.x 3-d contour plot +~CNT3DX is a simple 3-d contour plotting routine. A 3-d surface is +contoured by plotting slices through the surface parallel to the x-z plane +of the surface which have the same y value. The input consists of a 2 +dimensional grid of y values. For each contour level the input array +is scanned cell-by-cell. A segment of the contour is determined by linearily +interpolating the edges of the square formed by 4 adjacent points (a cell). +For example, if the current contour value is 1, and y(1,1)=0, y(1,2)=2, +y(2,2)=3, and y(1,2)=4, a contour line is assumed to exist for this +cell as shown: +.lit + + y(1,2) y(2,2) + * * + + + + \ + * + * + y(1,1) y(1,2) + +.end lit +This line segment is plotted using the same approach as ~VAX3DX. +No hidden line removal is provided. The calling sequence is nearly +identical for both CNT3DX and VAX3DX. The height of plotted contours +relative to the y axis is calibrated to z axis so that scale can be +taken from the plot. No perspective is used. Options exist to vary +the plotting angle and to plot axes. Contour values can be +distinguished by color and/or line type. +.p +Origin of the plot is in the lower-left corner. The x axis runs +plotted left to right along the plot bottom. The y axis is plotted +as a vertical displacement offset by the z axis value. The z axis appears +to point into the screen. This gives the illusion of depth in the plot. +See AXIS2 for detailed discription of axis parameters. +.p +The pathological case of two contour lines within a cell may case the +routine to incorrectly trace the contour through that cell. +.lit + +CALL CNT3DX(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,nl,as,ae,ie,iflag,iax, + ,l>>>) + +d (R): array of y values dimensioned d(ndx,ndz) +ndx,ndz (I): x and z dimensions of d array +nx,nz (I): x and z sizes of surface to plot d array +a (R): angle of x axis from horizontal 0-85 degrees +b (R): angle of z axis from horizontal 0-90 degrees + note: origin d(1,1) is in lower-left corner + x axis runs left to right on screen + y axis runs up to down on screen + z axis appears to run into the screen but is angled + to the right +xh,yh,zh (R): length of each axis +nl (I): number of uniformly spaced contour levels, + < 0 : max and min of v are used for as, ae + (j)th contour is (j-1)*(ae-as)/(nl-1)+as + = 0 : int(ae) specifies the number of contour values + where as is an array of the contour values + > 0 : number of uniformly space contour levels, + (j)th contour is (j-1)*(ae-as)/(nl-1)+as +as (R): first contour level (nl > 0) + array of contour levels (nl=0) dimensioned as(int(ae)) +ae (R): last contour level (nl > 0) + number of contour levels in as (nl=0) ae>0 +ie (I): contour edge option flag + < 0 contour edge added when surface below contour + = 0 no contour edges added + > 0 contour edge added when surface above contour +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) >10000: do not initialize LONGLIB before plotting + (1's digit) = 1 : ignor color and line type arrays + 2 : use color array but not line type array + 3 : ignore color array, use line type array + 4 : use color and line type arrays + (10's digit)= 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axis, using input scale factors dm and dx + = 0 : do not plot axis, optional axis parameters not used + input scaling is computed from input array + > 0 : plot axis, using scaling computed from input array, + need optional axis parameters + (1's digit) = 1 : Plot actual max/min or input values for Y axis + = 2 : Plot smoothed values for Y axis + (10's digit) = 0 : Use default axis type + = 1 : Use input AXIS2-type axis parameters +(NOTE: the following optional parameters are used only if iax<0 or + mod(iflag,10)=1) +xt (B): title of x axis (width) +nxt (I): number of characters in xt + = 0 : no axis plotted + > 0 : normal +xs,xe (R): starting and ending values displayed on x axis +(see AXIS2 for detailed description of axis parameters) +nmx (I): number of minor ticks between major ticks on x axis +nnx (I): highlight length of nnx-th minor tick on x axis +mlx (I): number of major tick marks on x axis +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndx (I): number of digits to right of decimal point on x axis +smx (R): major tick length on x axis +yt (B): title of y axis (depth) +nyt (I): number of characters in yt + = 0 : no y axis plotted + > 0 : normal +nmy (I): number of minor ticks between major ticks on y axis +nny (I): highlight length of nny-th minor tick on y axis +mly (I): number of major tick marks on y axis +tsy (R): size of title and numbers on y axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndy (I): number of digits to right of decimal point on y axis +smy (R): major tick length on y axis +zt (B): title of z axis (height) +nzt (I): number of characters in zt + = 0 : no z axis plotted + > 0 : normal +ze,ze (R): starting and ending valued displayed on z axis +nmz (I): number of minor ticks between major ticks on z axis +nnz (I): highlight length of nnz-th minor tick on z axis +mlz (I): number of major tick marks on z axis +tsz (R): size of title and numbers on z axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndz (I): number of digits to right of decimal point on z axis +smz (R): major tick length on z axis +(NOTE: the following are required only if iax<0 or mod(iflag,10)<>0) +dm,dx (R): minimum and maximum values of d array +(NOTE: the following is required only if mod(iflag,10) <> 0) +ic (I): color array + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for contour line 1 + ic(6) : color for contour line 2, etc. + ... ... +l (I): contour linetype list +.end lit + +.pg +.hl1 SUBROUTINE CNTLN +.p +.x contour plot +~CNTLN plots a contour plot of a randomly scatted set of points in +three dimensions. It uses INIT3dH +The input consists of a list of triplets of a surface +value. The triplets are triangulated using ~TRIANGC and contours +determined by linearily interpolating the edges of the triangles. +The contour values may be uniformly spaced between the starting +and end values or from a list. Other than color, the +sequence of plotting (min to max), and line typing of various contour +lines, no contour line identification scheme is provided. Caution +should be excercised when interpreting plot since the distribution of +input points may affect the placement of the contour lines. +.lit + +CALL CNTLN(x,y,z,n,xl,yl,iflag,nc,c,ia,xt,nxt,tx,sx,fx, + yt,nyt,ty,sy,fy,t,nt,xm,xx,ym,yx<<,ic>,l>) + +x,y,z (R): array of point triplets (x,y,z) +n (I): number of points +xl (R): x axis length in inches +yl (R): y axis length in inches +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) >10000: do not initialize LONGLIB before plotting + (1's digit) = 1 : do not use color or line type arrays + = 2 : use color but not line type array + = 3 : do not use color but use line type array + = 4 : use both color and line type arrays + (10's digit) = 0 : just x,y labeled axes + = 1 : axes and axis line/ticks on top and sides + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +nc (I): number of contour levels + < 0 : c(1) is the minimum contour level and c(2) is + the contour step size, abs(nc) levels plotted + > 0 : c contains contours levels, c dimensioned c(nc) +c (R): list of contour levels +ia (I): axis option flag + < 0 : do not plot axes + > 0 : plot axes + (1's digit) = 1 : plot y axis using max/min of y array + = 2 : plot y axis using max/min of y array + smoothed by SCALE + = 3 : plot y axis using input max/min + = 4 : plot y axis using input max/min + smoothed by SCALE + (10's digit) = 1 : plot x axis using max/min of x array + = 2 : plot x axis using max/min of x array + smoothed by SCALE + = 3 : plot x axis using input max/min + = 4 : plot x axis using input max/min + smoothed by SCALE + (100's digit) = 0 : normal contouring + = 1 : show triangulation used without contours +xt (B): x axis title string +nxt (I): number of characters in title + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +tx (R): number and pattern of axis ticks (see AXIS3) +sx (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fx (R): format of axis number labeling (see AXIS3) +yt (B): y axis title string +nyt (I): number of characters in title + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +ty (R): number and pattern of axis ticks (see AXIS3) +sy (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fy (R): format of axis number labeling (see AXIS3) +t (B): plot title string +nt (I): number of characters in t (limited to 99 characters) + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x axis +xx (R): maximum value of x axis +ym (R): minimum value of y axis +yx (R): maximum value of y axis +ic (I): color list (optionally used) + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color contour (1) + ic(6) : color contour (2), etc. + ... ... +l (I): line type list for contours (optionally used) + +common /ccntrplt/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE CNTRPLT +.p +.x contour plot +~CNTRPLT plots a contour plot of a uniformly sampled 2-d input +array. The input consists of a 2 dimensional grid of y values. For each +contour level the array is scanned cell by cell. +A contour segment is determined by linearily interpolating the edges of the +square formed by 4 adjacent points (a cell). For example, if the current +contour value is 1, and y(1,1)=0, y(1,2)=2, y(2,2)=3, and y(1,2)=4, +a contour line is assumed to exist for this cell as shown: +.lit + + y(1,2) y(2,2) + * * + + + + \ + * + * + y(1,1) y(1,2) + +.end lit +The contour values are uniformly spaced between the input starting +and end values or automatically selected values. Other than color, the +sequence of plotting (min to max), and line typing of various contour +lines, no contour line identification scheme is +provided. Log axes are available but data points are plotted using +linear positioning. (Note: common block scale factors will be log values +if the log axes are selected.) +.p +The pathological case of two contour lines within a cell may case the +routine to incorrectly trace the contour through that cell. +.lit + +CALL CNTRPLT(v,ndx,ndy,nx,ny,nl,as,ae,iflag,xl,yl,xt,nxt,yt,nyt, + t,nt,xm,xx,ym,yx<<,ic>,l>) + +v (R): 2-d array dimensioned v(ndx,ndy) +ndx,ndy (I): dimensions of v data array +nx,ny (I): number of points in each array dimension +nl (I): number of uniformly spaced contour levels, + < 0 : max and min of v are used for as, ae + (j)th contour is (j-1)*(ae-as)/(nl-1)+as + = 0 : int(ae) specifies the number of contour values + where as is an array of the contour values + > 0 : number of uniformly space contour levels, + (j)th contour is (j-1)*(ae-as)/(nl-1)+as +as (R): first contour level (nl > 0) + array of contour levels (nl=0) dimensioned as(int(ae)) +ae (R): last contour level (nl > 0) + number of contour levels in as (nl=0) ae>0 +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) >10000: do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : plot box with axis tick marks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : plot ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +xl (R): x axis length in inches (integer-valued) + > 0 : use input scaling in xm,xx for axis + < 0 : use smoothed input scaling in xm,xx for axis +yl (R): y axis length in inches (integer valued) + > 0 : use input scaling in ym,yx for axis + < 0 : use smoothed input scaling in ym,yx for axis +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string +nt (I): number of characters in t (limited to 99 characters) + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x axis (will be smoothed for xl < 0) +xx (R): maximum value of x axis (will be smoothed for xl < 0) +ym (R): minimum value of y axis (will be smoothed for yl < 0) +yx (R): maximum value of y axis (will be smoothed for yl < 0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color array + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponent + ic(6) : color for title (return) + ic(7) : color for contour line 1 + ic(8) : color for contour line 2 + ic(9) : etc. ... +l (I): line type list for contours (required only if |nt|/100>0) + +common /ccntrplt/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl 1 SUBROUTINE CVAX3D +.p +CVAX3D plots a 3d surface with hidden line removal using either +a mesh or a histogram. Optionally, a contour plot can be included +beneath the surface. The vertical space may be specified. +See CVAX3DX. +~CVAX3D calls CVAX3DX using default axis parameters to simplify the calling +procedure. +.lit + +CALL CVAX3D(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag, + iax,ds,nc,cv,icl,nm,il,ip, + >>) +.end lit + +.hl 1 SUBROUTINE CVAX3DX +.p +.x 2-d surface plot +~CVAX3DX plots a 3-d surface with hidden lines removed using ~PLT3D to +produce a mesh surface or ~HLT3D to produce a 2-d histogram with an optional +contour plot made ~GCONTR and plotted on a plane paralell to the surface +plane. Axes and a back panel can be optionally plotted. Optionally, +a path surface may be plotted which connects the surface and contour plots +over a users specified path. The 3d surface is plotted in a manner similar +to MVAX3DX. The visible upper side of the surface and the visible lower +side of the surface can be optionally shown using different colors and +line types. +.x MVAX3DX +.p +Origin of the plot is in the upper-left corner. The x axis runs +left to right along the plot bottom. The y axis is plotted +as a vertical displacement offset by the z axis value. The z axis appears +to point out of the screen. The contour plot is plotted below the surface +with a user-specified vertical spacing. The contour plot plane is plotted +paralell to the z=0 plane of the surface with the (i,j) indicies of the +surface and contour plot aligned vertically. The user may specify a +"path" using "pen" motions. The path is plotted as a curve along the +surface and the contour plot plane with vertical lines at the corresponding +indicies. No hidden line removal is used for the path. The path permits +the user to specify a cut plane to enhance the interpretation of the +plot. The path is specified as a sequence of pen motion commands and +index points of the form, +.TP 8 +.lit + + ip(1) = 1st path command + ip(2) = 1st i index + ip(3) = 1st j index + ip(4) = 2n path command + ip(5) = 2nd i index + ip(6) = 2nd j index + ... etc. + +.end lit +Path commands are interpreted according to: +.TP 9 +.lit + + path command action + ______________ ___________________________ + + 0 end of path specification + (indicies ignored) + 3 start path at these indicies + 2 continue path though indicies + +.end lit +The path specificiation should start with a path command of 3 +and end with 0. Note that several paths can be specified by +using several path command 3's. +.P +CVAX3DX contains an internal working storage array for use by GCONTR and +PLT3D. The buffer length is sufficient for most surfaces. However, for +very complex surfaces the buffer length may be exceeded. When this occurs +an error message is written to the terminal and the routine terminates. +.lit + +CALL CVAX3DX(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag, + iax,ds,nc,cv,icl,nm,il,ip, + >>) + +d (R): array of y values dimensioned d(ndx,ndz) +ndx,ndz (I): x and z dimensions of d array +nx,nz (I): x and z sizes of surface to plot d array +a (R): angle of x axis from horizontal 0-85 degrees +b (R): angle of z axis from horizontal 0-90 degrees + note: origin (1,1) is in upper-left corner + x axis runs left-to-right + y axis runs down-to-up + z axis appears to run outof page screen but + is angled to the right +xh,yh,zh (R): length of each axis +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 2 : use color array (need all parameters) + = 1 : do not use color array + (10's digit) = 0 : plot surface as a mesh (PLT3D) + = 1 : plot surface as 2-d historgram (HLT3D) + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axis, using input scale factors dm and dx + = 0 : do not plot axis, axis parameters (xt...dx) not used + scaling derived from d array is used + > 0 : plot axis, using scaling derived from d array, only + axis parameters xt thru ze required. + (1's digit) = 1 : plot actual max/min or input values for Y axis + = 2 : plot smoothed values for Y axis + (10's digit) = 0 : plot contour, surface axes with back panel + = 1 : plot contour, surface axes w/o back panel + = 2 : plot contour axes w/o surface axes, back panel + = 3 : plot surface axes w/o back panel, contour axes + = 4 : plot surface axes, back panel w/o contour axes + (100's digit) = 0 : use default axis type + = 1 : use input AXIS3 parameters +ds (R): vertical spacing between contour plane and minimum + value of a plane +nc (I): number of contours + < 0 : iabs(nc) contours plotted, the (j)th contour + is (max(a)-min(a))/(iabs(nc)-1). values used + are returned in cv + > 0 : contours specified in cv used +cv (R): contour level array dimensioned dv(iabs(nc) +icl (I): contour labeling option + < 0 : label with contour value (number with n digits + to the right of the decimal point) + = 0 : no labels on contours + > 0 : label contours with ASCII characters (nl <= 26) +nm (I): minimum line segments before contour labeled + < 0 : line type array used + > 0 : line type array not used +il (I): array of line types dimensioned il(iabs(nc)+2) + il(1) = underside of surface + il(2) = path line + il(3) = contour line 1 + il(4) = contour line 2 + ... (solid line type on return) +ip (I): path specification array (see notes above) + if ip(1) = 0, remainder of array ignored +(NOTE: following optional axis paramters are used only if + iax<0 or mod(iflag,10)=1) +xt (B): title of x axis (width) +nxt (I): number of characters in xt + = 0 : no axis plotted + > 0 : normal +xs,xe (R): starting and ending values displayed on x axis +xap (R): axis tick pattern (see AXIS3) +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fdx (R): axis number label format (see AXIS3) +yt (B): title of y axis (height) +nyt (I): number of characters in yt + = 0 : no y axis plotted + > 0 : normal +yap (R): axis tick pattern (see AXIS3) +tsy (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fdy (R): axis number label format (see AXIS3) +zt (B): title of z axis (depth) +nzt (I): number of characters in zt + = 0 : no z axis plotted + > 0 : normal +ze,ze (R): starting and ending valued displayed on z axis +zap (R): axis tick pattern (see AXIS3) +tsz (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fdz (R): axis number label format (see AXIS3) +(NOTE: the following are required only if iax<0 or mod(iflag,10)=1) +dm,dx (R): minimum and maximum scale values for d array +ic (I): color list + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for upper surface + ic(6) : color for lower surface + ic(7) : color for contour 1 + ic(8) : color for contour 2 + ... ... + (color for last contour on return) +.end lit + +.pg +.hl1 SUBROUTINE GLPLOT +.p +~GLPLOT plots the curve defined in x,y with ~log and/or ~linear scaling +including appropriate axes and plot title. Various options select the +format of the axes plotting. This subroutine is designed to plot one +or more +y value curves simultaneously. This subroutine permits axis parameter +flexibility (AXIS3) and dimensioning for y array. GLPLOT is a good +general purpose plotting routine. +.lit + +CALL GLPLOT(x,y,nld,npd,nl,np,iflag,isym,xl,yl,xt,xc,xf,xtitle,nxt, + yt,yc,yf,ytitle,nyt,t,nt,,l>>) + +x (R): array of x values dimensioned at least x(np) +y (R): array of y values dimensioned y(npd,nld) +nld (I): dimension of y (number of lines dimensioned) +npd (I): dimension of y (number of points dimensioned) +nl (I): number of data lines to plot from y array +np (I): number of points per line +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) >10000: do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : plot ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +isym (I): plot a symbol every isym'th point + < 0 : symbols only plotted, no line + = 0 : no symbols, line only + > 0 : symbol plotted every isym'th point +xl (R): x axis length in inches + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (R): x axis tick mark pattern (see AXIS3) +xc (R): x axis character size + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +xf (R): x axis number label format (see AXIS3) +xtitle(B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (R): y axis tick mark pattern (see AXIS3) +yc (R): x axis character size + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +yf (R): y axis number label format (see AXIS3) +ytitle(B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color list + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponent + ic(6) : color for title (return) + ic(7) : color for plotted line 1 + ic(8) : color for plotted line 2 + ic(9) : etc. +l (I): line type of data lines list (required only if |nt|/100>0) + +common /cglplot/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE HIST3D +.p +.x surface plot +~HIST3D plots a 2-d histogram as square columns plotted as z values +from the x,y plane with hidden line removal. +The input consists of the values of the z axis for +each (x,y) point on the plane. Each square grid is plotted as two triangles +using either ~SKETCH or ~PLT3DH permitting hidden line removal if desired. +HIST3D calls ~INIT3DH to initialize the 3-d hidden line package. Default +space is provided in the INIT3DH common block. The ISIZE variable will +be reset to the internal size if its value is smaller than the internal +size. Sufficient space in the internal common block +is provided for reasonably complex surfaces. +.lit + +CALL HIST3D(z,ndx,ndy,nx,ny,s,p,t,dv,zref,xl,yl,zl,iflag,ia, + xt,nxt,tx,sx,gx,fx, + yt,nyt,ty,sy,gy,fy, + zt,nzt,tz,sz,gz,fz, + xm,xx,ym,yx,zm,zx<,ic>) + +z (R): array of z values +ndx,ndy(I): dimensions of z array +nx,ny (I): number of points in each dimension to use of z array +s,p,t (R): yaw,roll,pitch angles of axes (see INIT3DH) +dv (R): perspective scale factor for INIT3DH + < 0 : no hidden lines in SKETCH, INIT3DH called + = 0 : INIT3DH not called to initialize 3d package, + (INIT3DH previously called) + > 0 : hidden lines in SKETCH, INIT3DH called + = 9999 : no perspective in INIT3DH +zref (R): reference value from which columns are drawn from +xl (R): x axis length in inches +yl (R): y axis length in inches +zl (R): z axis length in inches +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : do not use color array + = 2 : use color array + (10's digit) = 0 : hidden line removal for surface only + = 1 : hidden line removal for axis and surface + = 2 : no hidden line removal (SKETCH not used) + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +ia (I): axis option flag + < 0 : plot axis use input z axis scale + = 0 : do not plot axes + > 0 : plot axis use computed z axis scale + (1's digit) = 1 : plot y axis using input scale + = 2 : plot y axis using input, smoothed scale + (10's digit) = 1 : plot x axis using input scale + = 2 : plot x axis using input, smoothed scale +xt (B): x axis title string +nxt (I): number of characters in x axis title + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +tx (R): number and pattern of axis ticks (see AXIS3) +sx (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gx (R): rotation angle for x axis (see AXIS3DH) +fx (R): format of axis number labeling (see AXIS3) +yt (B): y axis title string +nyt (I): number of characters in y axis title + < 0 : axis ticks on top of axis + = 0 : no axis + > 0 : axis ticks on bottom of axis (normal) +ty (R): number and pattern of axis ticks (see AXIS3) +sy (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gy (R): rotation angle for y axis (see AXIS3DH) +fy (R): format of axis number labeling (see AXIS3) +zt (B): z axis title string +nzt (I): number of characters in z axis title + < 0 : axis ticks on top of axis + = 0 : no axis + > 0 : axis ticks on bottom of axis (normal) +tz (R): number and pattern of axis ticks (see AXIS3) +sz (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gz (R): rotation angle for z axis (see AXIS3DH) +fz (R): format of axis number labeling (see AXIS3) +xm,xx (R): minimum, maximum value displayed on x axis +ym,yx (R): minimum, maximum value displayed on y axis +zm,zx (R): minimum, maximum value of z axis (required if ia < 0) +ic (I): color list (required if 1's digit of iflag=2) + ic(1) : color for axes + ic(2) : color for surface +.end lit + +.pg +.hl1 SUBROUTINE LCNTR +.p +.x contour plot +~LCNTR plots a contour plot of a uniformly sampled 2-d input array. +LCNTR is similar to CNTRPLT but permits hardware line types. +The input consists of a 2 dimensional grid of v values. A +contour is determined by linearily interpolating the edges of the square +formed by 4 adjacent points (see CNTRPLT). LCNTR connects the line segments +of constant contour before plotting and can optionally label the contour lines +with alphabetic codes or the numerical value of the contour. +Log axes are available but data points are plotted using +linear positioning. (Note: common block scale factors will be log values +if the log axes are selected.) +.p +When the contour levels are input (nl>0), contours can be suppressed +in a region by setting the value of the input array greater than 1.E20. +LCNTR uses the contouring routine GCONTR. +.x GCONTR +.lit + +CALL LCNTR(v,ndx,ndy,nx,ny,nl,cl,n,m,iflag,iw,xl,yl,xt,nxt,yt,nyt, + t,nt,xm,xx,ym,yx<<,ic>,l>) + +v (R): 2-d array of values dimensioned v(ndx,ndy) +ndx,ndy (I): dimensions of data array +nx,ny (I): number of points in each array dimension +nl (I): number of uniformly spaced contour levels, + < 0 : max and min of v are used to define contours. + the (j)th contour is computed from max,min of + input array according to, + (j-1)*(max(v)-min(v))/(nl-1)+min(v) + > 0 : number of contour levels specified in cl +cl (R): array of contour levels dimensioned cl(nl) + if nl < 0 contour levels used are (returned) in cl +n (I): contour labeling option + < 0 label with contour value (number with n digits + to the right of the decimal point) + = 0 no labels on contours + > 0 label contours with ASCII characters (nl <= 26) +m (I): minimum line segments before contour labeled (m > 1) +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) >10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : plot ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iw (I): working array dimensioned at least (2*nx*ny+1)/31 +xl (R): x axis length in inches (integer valued) + > 0 : use input scaling in xm,xx for axis + < 0 : use smoothed input scaling in xm,xx for axis +yl (R): y axis length in inches (integer valued) + > 0 : use input scaling in ym,yx for axis + < 0 : use smoothed input scaling in ym,yx for axis +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string +nt (I): number of characters in t (limited to 99 characters) + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): input minimum value of x axis +xx (R): input maximum value of x axis +ym (R): input minimum value of y axis +yx (R): input maximum value of y axis +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color array + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponent + ic(6) : color for title (return) + ic(7) : color for contour line 1 + ic(8) : color for contour line 2 + ic(9) : etc. +l (I): line type list for contours (required if |nt|/100>0) + +common /ccntrplt/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl 1 SUBROUTINE LSPLOT +.p +~LSPLOT is a general single/multiple data line routine for plotting +lines or scatterplots. Optionally, error bars and symbols can be +added. LSPLOT differs in philosophy from most other LONGLIB MASTER +routines in that plotting options are passed via an option array routine. +The routine is designed to produce a reasonable plot with the option +array set to all zeros. The output format is changed by initializing +selected array elements to the values described below. +This permits simple but flexible specification of the plot format. +.lit + +CALL LSPLOT(x,y,ndp,ndl,iflag,f,c,nc) + +x (R): x input array dimensioned x(ndp,ndl). Depending + on option selected, x need only be dimensioned + x(ndp) -- this is the default option. +y (R): y input array dimensioned y(ndp,ndl). If + ndl=1 then y may dimensioned y(ndp) +ndp (I): number of data points/line dimension +ndl (I): number of data lines dimension +iflag (I): LONGLIB option flag (one's digit arbitrary) + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) >10000 : do not initialize LONGLIB before plotting + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +f (R): option array dimensioned at least f(53) + (described below) +c (C): array of strings dimensioned C(3+ndl) + c(1) : x axis title + c(2) : y axis title + c(3) : top title + c(4) : line 1 legend (optionally used) + c(5) : line 2 legend (optionally used) + ... ... +nc (I): array of string lengths dimensioned nc(3+ndl) + nc(1) : number of characters to use in C(1) + nc(2) : number of characters to use in C(2) + ... ... +.end lit +.p +The array elements of the option array f are interpretted according +to the following table. Some parameters have default values (shown +in square brackets). These are used when the input value is zero. +A simple plot may be produced by setting all the elements of f to +zero. Note that user specified input scaling factors should be +powers of ten when the log axis specification is selected. An optional +legend may be plotted. The legend consists of a column +of line/simple examples (if selected) and input text. +.tp 8 +.lit + + array range of + index values action for each value + ------- -------- ------------------------ + + 1 0<=.<=ndp number of points/line to plot [ndp]: 0=ndp used + 2 0<=.<=ndl number of lines to plot [nl]: 0=ndl used + 3 -1/0/1 x scale: 0=auto,smoothed; 1=auto,nosmooth; -1=user + 4 xmin user supplied scale value (used if f(3)<0) + 5 xmax user supplied scale value (used if f(3)<0) + 6 -1/0/1 y scale: 0=auto,smoothed; 1=auto,nosmooth; -1=user + 7 ymin user supplied scale value (used if f(6)<0) + 8 ymax user supplied scale value (used if f(6)<0) + 9 0/1 x value usage: 0=first line of x data array + used for all y lines; 1=lines of x,y paired + 10 0/1 connect plotted points: 0=yes; 1=no + 11 >=0 symbol plotted every ()th point: 0=no symbols + 12 >=0 line symbol size [0.1]: 0=use default + 13 >=0 symbol number for first data line, each line + then uses next symbol in sequence + 14 8<.<8 error bar option (see below): 0=no error bars + 16 >=0 error bar size [0.1]: 0=default used + 17 0/1 vertical line from points to reference value: + 0=no; 1=yes + 18 rval reference value + 19 -1/0/1 x axis type: 0=linear; 1=log axis, -1=no axis + 20 -1/0/1 y axis type: 0=linear; 1=log axis, -1=no axis + 21 >=0 x axis length [7.0]: 0=default used + 22 >=0 y axis length [5.0]: 0=default used + 23 >=0 x axis tick pattern (see axis3) [7.00]: 0=default + 24 >=0 y axis tick pattern (see axis3) [5.00]: 0=default + 25 0/1 x axis title side of axis: 0=below; 1=above + 26 0/1 y axis title side of axis: 0=left; 1=right + 27 0/1 x axis auto exponent enable: 0=enable; 1=disable + 28 0/1 y axis auto exponent enable: 0=enable; 1=disable + 29 0/1 x axis tick side: 0=below; 1=above + 30 0/1 y axis tick side: 0=left; 1=right + 31 0/1 x axis number orientation: 0=horizontal; 1=vertical + 32 0/1 y axis number orientation: 0=vertical; 1=horizontal + 33 0/1 x axis numbers/title: 0=shown; 1=not shown + 34 0/1 y axis numbers/title: 0=shown; 1=not shown + 35 0/1 use x=log10(abs(x values)+1.e-34): 0=no; 1=yes + 36 0/1 use y=log10(abs(y values)+1.e-34): 0=no; 1=yes + 37 -1/0/1 add mirror x axis: 0=no; 1=w/labels; -1:w/o labels + 38 -1/0/1 add mirror y axis: 0=no; 1=w/labels; -1:w/o labels + (mirrored axes placed on opposite from normal axis) + 39 >=0 x axis label size [0.15]: 0=use default + 40 >=0 y axis label size [0.15]: 0=use default + 41 >=0 top title character size [0.18]: 0=use default + 42 0/1/2/3 grid: 0=no grid; 1=solid; 2=dotted; 3=ticked + 43 -1/0/1 legend: 0=no legend; 1=right side; -1=user locate + 44 xval user specified lower-left corner of legend + 45 yval user specified lower-left corner of legend + 46 0/1 show plot symbol on legend: 0=no; 1=yes + 47 0/1 show line segment on legend: 0=no; 1=yes + 48 >=0 legend character height [0.12]: 0=use default + 49 >=0 legend line segment length [0.5]: 0=use default + 50 -1/0/1 top title justify: 0=center; -1:left; 1:right + 51 0/1 plot horizontal reference line: 0=no; 1=yes + 52 0/1 use linetype array values: 0=no; 1=yes + 53 0/1 use color array values: 0=no; 1=yes + 54 >=0 color index #1: 0=color value 1 used + 55 >=0 linetype index #1 + 56 >=0 color index #2: 0=color value 1 used + 57 >=0 linetype index #2 + ... ... ... etc ... +.end lit +.p +The optional error bar specification, when non-zero, changes +interpretation of lines. The first line (and every third line) +conidered a "center" line. The second line specifies the relative +error (to be added to the first line) used for plotting the tops +of the error bars. The third line is used similarily to locate +the bottoms of the error bars. When the error bar specification +is negative the center line points are marked with a special "x" +(in addition to any other option). The absolution value of the +specifiation determines the type of error bar according to the +following table. +.tp10 +.lit + +value type of error bar +------ --------------------------------------------------- + 1 line connecting relative errors + 2 1 + horizontal bars at relative errs + 3 1 + vertical bars at relative errs + 4 double line connecting rel. errs+horizontal bars + 5 double line connecting rel. errs+vertical bars + 6 vertical rectangle w/top and bottom rel. errs + 7 rectangle with corners at relative errors +.end lit +.p +The color and line type index (when enabled) are used according to the +following table. +.tp12 +.lit + + index # color usage linetype usage +--------- ------------- ---------------- + 1 x axis x axis + 2 x axis numbers y axis + 3 x axis title title + 4 x axis exponent legend titles + 5 y axis reference line + 6 y axis numbers error bars + 7 y axis title line #1 linetype + 8 y axis exponent line #2 linetype + 9 title etc. + 10 legend titles ... + 11 reference line ... + 12 grid ... + 13 line #1 color ... + 14 line #2 color ... +... ... etc. ... ... +.end lit + +.pg +.hl 1 SUBROUTINE MESH3D +.p +MESH3D plots a 2-d surface as 3d mesh using the same techniques +as ~VAX3D but without hidden line removal. +~MESH3D calls MESH3DX using default axis parameters to simplify +the calling procedure. +.lit + +CALL MESH3D(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag,iax,>>) + +See MESH3DX for parameter description. + (iax is limited to a single digit value) +.end lit +.hl 1 SUBROUTINE MESH3DX +.p +.x VAX3DX +.x 2-d surface plot +~MESH3DX is a simple 3-d surface plotting routine. A 3-d surface is +plotted as a simple mesh grid. The plotting method is similar to +VAX3DX. No hidden line removal is done. +The height of plotted surface relative to its y axis value +is calibrated to z axis. No perspective is used. +Options exist to varying the plotting angle and to plot axes. +.p +Origin of the plot is in the lower-left corner. The x axis runs +plotted left to right along the plot bottom. The y axis is plotted +as a vertical displacement offset by the z axis value. The z axis +appears to point into the screen. This gives the illusion of depth. +.lit + +CALL MESH3DX(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag,iax, + >>) + +d (R): array of y values dimensioned d(ndx,ndz) +ndx,ndz (I): x and z dimensions of d array +nx,nz (I): x and z sizes of surface to plot d array +a (R): angle of x axis from horizontal 0-85 degrees +b (R): angle of z axis from horizontal 0-90 degrees + note: origin (1,1) is in lower-left corner + x axis runs left to right on screen + y axis runs up to down on screen + z axis appears to run into the screen but + is angled to the right +xh,yh,zh (R): length of each axis +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) >10000: do not initialize LONGLIB before plotting + (1's digit) = 2 : use color array (need all parameters) + = 1 : do not use color array + (10's digit) = 0 : Plot sides + = 1 : Do not plot sides + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axes, using input scale factors dm and dx + = 0 : axes not plotted, parameters (yt...dx) not used. + scaling derived from d array is used + > 0 : plot axes, use max and min of d array to compute + dm and dx, need axis parameters yt thru ze + (1's digit) = 1 : Plot actual max/min or input values for Y axis + = 2 : Plot smoothed values for Y axis + (10's digit) = 0 : Use default axis type + = 1 : Use input AXIS2-type axis parameters +(NOTE: the following optional paramters are used only if + iax < 0 or mod(iflag,10)=1) +xt (B): title of x axis (width) +nxt (I): number of characters in xt + = 0 : no axis plotted + > 0 : axis plotted +xs,xe (R): starting and ending values displayed on x axis +(see AXIS2 for detailed description of axis parameters) +nmx (I): number of minor ticks between major ticks on x axis +nnx (I): highlight length of nnx-th minor tick on x axis +mlx (I): number of major tick marks on x axis +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndx (I): number of digits to right of decimal point on x axis +smx (R): major tick length on x axis +yt (B): title of y axis (depth) +nyt (I): number of characters in yt + = 0 : no y axis plotted + > 0 : normal +nmy (I): number of minor ticks between major ticks on y axis +nny (I): highlight length of nny-th minor tick on y axis +mly (I): number of major tick marks on y axis +tsy (R): size of title and numbers on y axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndy (I): number of digits to right of decimal point on y axis +smy (R): major tick length on y axis +zt (B): title of z axis (height) +nzt (I): number of characters in zt + = 0 : no z axis plotted + > 0 : normal +ze,ze (R): starting and ending valued displayed on z axis +nmz (I): number of minor ticks between major ticks on z axis +nnz (I): highlight length of nnz-th minor tick on z axis +mlz (I): number of major tick marks on z axis +tsz (R): size of title and numbers on z axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndz (I): number of digits to right of decimal point on z axis +smz (R): major tick length on z axis +(NOTE: the following optional parameters are required if + iax < 0 or mod(iflag,10)=1) +dm,dx (R): minimum and maximum scale values for d array +ic (I): color list + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for plot surface (return) +.end lit + +.pg +.hl 1 SUBROUTINE MVAX3D +.p +MVAX3D plots a 3d mesh surface or 2-d histogram with hidden line removal. +See MVAX3DX. The calling format is similar to VAX3D. +~MVAX3D calls ~MVAX3DX using default axis parameters to simplify calling +procedure. +.lit + +CALL MVAX3D(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag,iax,>>) +.end lit + +.hl 1 SUBROUTINE MVAX3DX +.p +.x 2-d surface plot +~MVAX3DX is a 3-d surface plotting routine which plots a +3-d surface as mesh with hidden lines removed using the ~PLT3D routine +or a 2-d histogram with hidden lines removed using the ~HLT3D routin. +Axes and a axis back panel can be optionally plotted as well. +The upper side of the visible surface can be shown with optional side +plates on the mesh surface. +If the side plates are not used or for histogram plotting, the lower side of the +visible surface may be displayed in different colors or using a dotted line. +.p +Origin of the plot is in the upper-left corner. The x axis runs +left to right along the plot bottom. The y axis is plotted +as a vertical displacement offset by the z axis value. The z axis appears +to point out of the screen. +.P +MVAX3DX contains an internal working storage array for use by +PLT3D and HLT3D. The buffer length is sufficient for most surfaces. +However, for +very complex surfaces the buffer length may be exceeded. When this occurs +an error message is written to the terminal and the routine terminates. +.lit + +CALL MVAX3DX(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag,iax, + >>) + +d (R): array of y values dimensioned d(ndx,ndz) +ndx,ndz (I): x and z dimensions of d array +nx,nz (I): x and z sizes of surface to plot d array +a (R): angle of x axis from horizontal 0-85 degrees +b (R): angle of z axis from horizontal 0-90 degrees + note: origin (1,1) is in upper-left corner + x axis runs left-to-right + y axis runs down-to-up + z axis appears to run outof page screen but + is angled to the right +xh,yh,zh (R): length of each axis +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 2 : use color array (need all parameters) + = 1 : do not use color array + (10's digit) = 0 : mesh surface w/side panels, lower side of + surface not shown + = 1 : mesh surface w/no side panels, lower side of + surface shown using dotted lines + = 2 : mesh surface w/no side panels, lower side of + surface shown using solid lines + = 3 : mesh surface w/no side panels, lower side of + surface not shown + = 4 : histogram surface, lower side of surface + shown using dotted lines + = 5 : histogram surface, lower side of surface + shown using solid lines + = 6 : histogram surface, lower side of surface + shown using solid lines + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axes, using input scale factors dm and dx + = 0 : no axes plotted, parameters (xt...dx) not used. + scaling derived from d array is used + > 0 : plot axes, use scaling derived from d array, only + axis parameters xt thru ze required. + (1's digit) = 1 : Plot actual max/min or input values for Y axis + = 2 : Plot smoothed values for Y axis + (10's digit) = 0 : Use default axis type + = 1 : Use input AXIS3 parameters + (100's digit) = 0 : Do not plot backplane + = 1 : Plot backplane +(NOTE: following optional axis paramters are used only if + iax<0 or mod(iflag,10)=1) +xt (B): title of x axis (width) +nxt (I): number of characters in xt + = 0 : no axis plotted + > 0 : normal +xs,xe (R): starting and ending values displayed on x axis +xap (R): axis tick pattern (see AXIS3) +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fdx (R): axis number label format (see AXIS3) +yt (B): title of y axis (height) +nyt (I): number of characters in yt + = 0 : no y axis plotted + > 0 : normal +yap (R): axis tick pattern (see AXIS3) +tsy (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fdy (R): axis number label format (see AXIS3) +zt (B): title of z axis (depth) +nzt (I): number of characters in zt + = 0 : no z axis plotted + > 0 : normal +ze,ze (R): starting and ending valued displayed on z axis +zap (R): axis tick pattern (see AXIS3) +tsz (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +fdz (R): axis number label format (see AXIS3) +(NOTE: the following optional parameters are required if + iax<0 or mod(iflag,10)=1) +dm,dx (R): minimum and maximum scale values for d array +ic (I): color list + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for plot surface (return) +.end lit + +.pg +.hl 1 SUBROUTINE MVAX5D +.p +.x 5-d surface +.x 4-d surface plot +.x MVAX3D +~MVAX5D plots a 4 or 5-d surface by plotting slices through the 3rd and +4th dimensions in a 2-d array of of 3-d plots. Each 3-d surface +plots d(*) as a function of 2 of the dimensions using MVAX3D. +.p +Origin of the plot is in the lower-left corner. The X axis runs +left to right along the subplot bottom. The Y axis is plotted out +the page of the subplot (see MVAX3D). +The Z axis runs left to right in subplots +with the W axis vertical subplots. +.tp 8 +.lit + + ^ W d + | | + | |__X + | / + | Y + ----------> Z +.end lit +.p +Since the subplots may runoff the edge of the plotting page, the routine +includes a page size option to issue a NEWPAGE and plot the additional +subplots on separate pages. A shrinking factor is included to shrink the +subplots. +Labeling of the W and Z axis is due in the lower right hand corner. +Each subplot is further tagged with the corresponding W and Z axis +value. A multiple page plot can be pasted together to form a large +representation of a 5-d (or 4-d) surface. +.lit + +CALL MVAX5D(d,nd,n,a,b,iflag,iax,iform,w,xh,yh,zh,ph,pl,fac,iw,iz, + st,en,t1,nt1,t2,nt2,t3,nt3,t4,nt4,dt,ndt,>) + +d (R): array to plot dimensioned d(nd(1),nd(2),nd(3),nd(4)) +nd (I): array of containing dimensions of d array +n (I): array of number of points in each dimension to plot +a,b (R): angles a,b for MVAX3D subplot +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 2 : use color array (need all parameters) + = 1 : do not use color array + (10's digit) = 0 : mesh surface w/side panels, lower side of + surface not shown + = 1 : mesh surface w/no side panels, lower side of + surface shown using dotted lines + = 2 : mesh surface w/no side panels, lower side of + surface shown using solid lines + = 3 : mesh surface w/no side panels, lower side of + surface not shown + = 4 : histogram surface, lower side of surface + shown using dotted lines + = 5 : histogram surface, lower side of surface + shown using solid lines + = 6 : histogram surface, lower side of surface + shown using solid lines + (100's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axes, use input scale factors dm and dx + = 0 : no axes plotted, parameters (xt...dx) not used. + scaling derived from d array + > 0 : plot axes, scaling derived from d array, only + axis parameters xt thru ze required. + (1's digit) = 1 : Plot actual max/min or input values for Y axis + = 2 : Plot smoothed values for Y axis + (10's digit) = 0 : Axes plotted for all subplots + = 1 : Axes plotted only for first subplot +iform (I): plot format code + selects which dimension of d array is to become + which output axis + + plot axis plot axis +Code X Y Z W Code X Y Z W +_____ ____________ _____ ____________ + 1 input: 1 2 3 4 13 3 1 2 4 + 2 dimen- 1 2 4 3 14 3 1 4 2 + 3 sion 1 4 2 3 15 3 2 1 4 + 4 number 1 4 3 2 16 3 2 4 1 + 5 1 3 2 4 17 3 4 1 2 + 6 1 3 4 2 18 3 4 2 1 + 7 2 1 3 4 19 4 1 2 3 + 8 2 1 4 3 20 4 1 3 2 + 9 2 4 3 1 21 4 2 1 3 + 10 2 4 1 3 22 4 2 3 1 + 11 2 3 4 1 23 4 3 1 2 + 12 2 3 1 4 24 4 3 2 1 + +w (R): working array dimensioned at least n(x)*n(y) +xh,yh,zh (R): length of each axis of MVAX3D subplot +ph,pl (R): page height, length when multiple pages required +fac (R): shrink factor for subplots (2 == FACTOR(1/2)) +iw,iz (I): plot every iw'th and iz'th subplots +(NOTE: the axis titles, number of characters, start/stop + values are permuted along with d array dimensions) +st,en (R): arrays containing axes start and end values +t1 (B): title corresponding to 1st dimension of d +nt1 (I): number of characters in title t1 + = 0 : no axis plotted + > 0 : axis plotted +t2 (B): title corresponding to 2st dimension of d +nt2 (I): number of characters in title t2 + = 0 : no axis plotted + > 0 : axis plotted +t3 (B): title corresponding to 3rd dimension of d +nt3 (I): number of characters in title t3 + = 0 : no axis plotted + > 0 : axis plotted +t4 (B): title corresponding to 4th dimension of d +nt4 (I): number of characters in title t4 + = 0 : no axis plotted + > 0 : axis plotted +t5 (B): title corresponding to 5th dimension of d +nt5 (I): number of characters in title t5 + = 0 : no axis plotted + > 0 : axis plotted +(NOTE: the following optional parameters are required if + iax<0 or mod(iflag,10)=1) +dm,dx (R): minimum and maximum scale values of plot +ic (I): color array + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for plot surface (return) +.end lit + +.pg +.hl1 SUBROUTINE PHIST +.p +~PHIST is a generalized ~histogram plotting program with various +plot format controls. Shading may done under the histogram columns. +The histogram height may be plotted on top of each histogram column +vertically. The mean and +/- sigma variations may be indicated on the +plot output. Note: PHIST does not do the histogramming. This is left +to the user. +.lit + +CALL PHIST(a,n,t,nt,xl,yl,s,ns,xt,nxt,xm,xx,ax, + iflag,ishad,am,as<,ic>) + +a (R): array of heights of histogram columns +n (I): number of points in a array to plot +t (B): title string +nt (I): number of characters in t + = 0 : no title + < 0 : use color array +xl (R): length of x axis in inches (integer-valued real number) +yl (R): length of y axis in inches (integer-valued real number) +s (B): subtitle string +ns (I): number of characters in s +xt (B): x axis title +nxt (I): number of characters in xt +xm (R): minimum value displayed on x axis +xx (R): maximum value displayed on x axis +ax (R): maximum value of a +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting +(1's digit) = 2 : plot number value of column on top of column + = 1 : no numeric values on top of histogram columns + = 0 : no axis or title (histogram columns only) +(10's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +ishad (I): shade option flag + < 0 : shade with solid line + = 0 : no shading + > 0 : shade with line of type ishad +am (R): mean value of histogram to plot (in relation to xm,xx) +as (R): standard deviation of histogram to plot + < 0 : neither mean nor sigma values indicated on plot + = 0 : only mean value indicated on plot + > 0 : mean and +/- sigma values indicated on plot +ic (I): color list + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for mean label + ic(6) : color for sigma label + ic(7) : color for title + ic(8) : color for subtitle + ic(9) : color for histogram columns (return) + +common /cphist/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE PICHRT +.p +~PICHRT plots a circular pie chart with optionally shaded wedges, and +descriptive legends. One or more of the slices may be "exploded" outward +from the pie chart center for emphasis. The chart legend can be character +labels only or can include shade legends. Labels can be automatically placed +around the pie chart or located at the bottom of the page. Optionally, the +user can specify the locations of the legends. +.lit + +CALL PICHRT(x,y,r,d,iflag,as,ae,n,a,sh,iw,l,nl,cs,sl, + t,nt,tcs,d,>) + +x,y (R): location of pie chart center +r (R): radius of pie chart segments (r>0) +d (R): distance from chart center for "exploded" segments +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : color array not used + = 2 : color array used + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +as (R): starting angle of first segment +n (I): number of segments (n>0) +a (R): array of segment sizes (angular width of jth segment + is a(j)*360/(Sum a(i),i=1,N)) +sh (R): shade option for each pie segment + sh shade pattern + ____ _________________________ + 0 no shading + 1 -45 deg solid lines + 2 horizontal solid lines + 3 +45 deg solid lines + 4 vertical deg solid lines + 5 -45 deg dotted lines + 6 horizontal dotted lines + 7 +45 deg dotted lines + 8 vertical deg dotted lines + 9 +/- 45 deg dotted lines + 10 vertical/horizontal dotted lines + 11 +/- 45 deg solid lines + 12 vertical/horizontal solid lines +iw (I): array of segment outline linewidths (1-9) +l (C): array of segment labels for legend (CHARACTER) +nc (I): maximum number of characters in legend string +cs (R): legend character height +sl (R): legend shaded box size + < 98: legend located below chart w/o box + < 0 : legend located below chart with shaded box + = 0 : no legend + > 0 : legend located around chart with shaded box + > 98: legend located around chart w/o box +t (B): chart title string +nt (I): number of characters in t + < 1 : no title plotted +tcs (R): chart title string height +d (R): distance between shading lines +p (R): array containing locations of lower-left corner + of legend box/string (used only if tc < 0) +ic (I): color array (used only if mod(|iflag|,10)=2) + ic(1) : title color (return) + ic(2) : legend string color + ic(3) : segment 1 color + ic(4) : segment 2 color + ... ... +.end lit + +.pg +.hl1 SUBROUTINE PLOTLG +.p +~PLOTLG is a very simple routine which +plots a single curve defined in x,y with ~log and/or ~linear +scaling including appropriate axes and plot title. Various options +select the format of plotting and type of grid. +.lit + +CALL PLOTLG(x,y,n,iflag,xl,yl,xt,nxt,yt,nyt,t,nt, + ,l>>) + +x (R): array of x values +y (R): array of y values +n (I): number of points in x array +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : ticked cartesian grid, box w/axis ticks + = 6 : plot without box or grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +xl (R): x axis length in inches (integer-valued) + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches (integer-valued) + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: optional color array required if nt<0 or |nt|/100>0) +ic (I): color array + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for plotted line + ic(7) : color for title (return) +(NOTE: optional line type array only required if |nt|/100>0) +l (I): line type of data line + if |nt|/100 > 0 : use line type list + +common /cplotlg/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE PLOTLG2 +.p +~PLOTLG2 is a simple routine to +plot multiple curves defined in x,y in ~log and/or ~linear +scaling including appropriate axes and plot title. Various options +select the format of plotting. This subroutine is designed to plot +many y value curves which may be distinguished by color and/or line +type. This routine is similar to ~PLOTLGX but uses a simpler +axis specification. +.lit + +CALL PLOTLG2(x,y,nl,np,iflag,isym,xl,yl,xt,nxt,yt,nyt,t,nt,,l>>) + +x (R): array of x values +y (R): array of y values dimensioned y(np,nl) +nl (I): number of data lines to plot from y array +np (I): number of points in x array +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +isym (I): plot a symbol every isym'th point + < 0 : symbols only plotted, no line + = 0 : no symbols, line only + > 0 : symbol plotted every isym'th point +xl (R): x axis length in inches (integer-valued) + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches (integer-valued) + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color list + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for title (return) + ic(7) : color for plotted line 1 + ic(8) : color for plotted line 2 + ic(9) : etc. +(NOTE: line type list required only if |nt|/100>0) +l (I): line type for data lines list + +common /cplotlg2/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit +.pg +.hl1 SUBROUTINE PLOTLGL +.x PLOTLGX +.x linseq +.p +~PLOTLGL plots multiple curves defined in x,y with ~log and/or ~linear +scaling including appropriate axes and plot title using software line +types (LINSEQ). It is similar in character to PLOTLGX. Various options +may be used select the format of plotting. This routine may be used +to plot many y value curves simultaneously with the curves distinguished +by symbols, color, and/or line type. This subroutine permits axis +parameter flexibility and dimensioning for the y array values. +.p +NOTE: the values in the x and y arrays are modified. Upon return they +contain their original contents scaled by xm,dx,ym,dy (see LINE). +.lit + +CALL PLOTLGL(x,y,w,nld,npd,nl,np,iflag,isym,xl,yl,ns,s,l, + nmx,nnx,mlx,tsx,ndx,smx, + nmy,nny,mly,tsy,ndy,smy, + xt,nxt,yt,nyt,t,nt,>) + +x (R): array of x values dimensioned at least x(np) +y (R): array of y values dimensioned y(npd,nld) +w (R): working array dimensioned at least d(3*np+3) +nld (I): dimension of y array (lines) +npd (I): dimension of y array (points) +nl (I): number of data lines to plot from y array +np (I): number of points per data line +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +isym (I): plot a symbol every isym'th point + < 0 : symbols only plotted, no line + = 0 : no symbols, line only + > 0 : symbol plotted every isym'th point +xl (R): x axis length in inches + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +ns (I): smoothing passes (normally zero--see LINSEQ) +s (R): nominal interval length (see LINSEQ) +l (I): linetype array dimensioned l(5*np) (see LINSEQ) + l(1): l1 for line 1 + l(2): l2 for line 1 + ... + l(5): l5 for line 1 + l(6): l1 for line 2 + l(7): l2 for line 2 + ... +(see AXIS2 for detailed description of axis parameters) +nmx (I): number of minor ticks between major ticks on x axis +nnx (I): highlight length of nnx-th minor tick on x axis +mlx (I): number of major tick marks on x axis +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndx (I): number of digits to right of decimal point on x axis +smx (R): major tick length on x axis +nmy (I): number of minor ticks between major ticks on y axis +nny (I): highlight length of nny-th minor tick on y axis +mly (I): number of major tick marks on y axis +tsy (R): size of title and numbers on y axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndy (I): number of digits to right of decimal point on y axis +smy (R): major tick length on y axis +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: color array required if nt < 0) +ic (I): color array + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for title (return) + ic(7) : color for plotted line 1 + ic(8) : color for plotted line 2 + ic(9) : etc. + +common /cplotlgl/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE PLOTLGX +.p +~PLOTLGX is a routine for +ploting multiple curves defined in x,y with ~log and/or ~linear +scaling including appropriate axes and plot title. Various options +may be used select the format of plotting. This routine may be used +to plot many y value curves simultaneously with the curves distinguished +by symbols, color, and/or line type. This subroutine permits axis +parameter flexibility and dimensioning for the y array values. +.lit + +CALL PLOTLGX(x,y,nld,npd,nl,np,iflag,isym,xl,yl, + nmx,nnx,mlx,tsx,ndx,smx, + nmy,nny,mly,tsy,ndy,smy, + xt,nxt,yt,nyt,t,nt,,l>>) + +x (R): array of x values dimensioned at least x(np) +y (R): array of y values dimensioned y(npd,nld) +nld (I): dimension of y array (lines) +npd (I): dimension of y array (points) +nl (I): number of data lines to plot from y array +np (I): number of points per line +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : plot ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +isym (I): plot a symbol every isym'th point + < 0 : symbols only plotted, no line + = 0 : no symbols, line only + > 0 : symbol plotted every isym'th point +xl (R): x axis length in inches + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +(see AXIS2 for detailed description of axis parameters) +nmx (I): number of minor ticks between major ticks on x axis +nnx (I): highlight length of nnx-th minor tick on x axis +mlx (I): number of major tick marks on x axis +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndx (I): number of digits to right of decimal point on x axis +smx (R): major tick length on x axis +nmy (I): number of minor ticks between major ticks on y axis +nny (I): highlight length of nny-th minor tick on y axis +mly (I): number of major tick marks on y axis +tsy (R): size of title and numbers on y axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndy (I): number of digits to right of decimal point on y axis +smy (R): major tick length on y axis +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color list + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for title (return) + ic(7) : color for plotted line 1 + ic(8) : color for plotted line 2 + ic(9) : etc. +l (I): data line type list (required only if |nt|/100 > 0) + +common /cplotlgx/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + + +.pg +.hl1 SUBROUTINE PLOTSC +.p +~PLOTSC is a very basic routine which plots the curve defined +in x,y with axes and a plot title. Various options select the format +of the plot. +.lit + +CALL PLOTSC(x,y,n,iflag,xl,yl,xt,nxt,yt,nyt,t,nt, + ,l>>) + +x (R): array of x values +y (R): array of y values +n (I): number of points in x array +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting +(magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 0 : no axis or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked grid without box + = 4 : plot ticked grid with box + = 5 : ticked grid and box with axis tick marks + = 6 : plot without box or grid + (10's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +xl (R): x axis length in inches (integer valued) + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches (integer valued) + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color array + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for plotted line + ic(7) : color for title (return) +l (I): data line type (required if nt < 0 or |nt|/100 > 0) + +common /cplotsc/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl 1 SUBROUTINE PLOTSC2 +.x LINE +.x DASHL +.p +~PLOTSC2 plots two curves defined by the x,y and x,y2 arrays with +axes and a plot title. An auto-scaling option scales the axes to +place both curves within the axes. Curves are distinguished by line +type. The y curve uses a solid line (LINE) while the y2 curve uses a dashed +line (DASHL). Various options select the format of plotting. +.lit + +CALL PLOTSC2(x,y,y2,n,iflag,xl,yl,xt,nxt,yt,nyt,t,nt, + ,l>>) + +x (R): array of x values +y (R): array of y values (plotted solid) +y2 (R): second array of y values (plotted dashed) +n (I): number of points in x array +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) >10000 : do not initialize LONGLIB before plotting + (1's digit) = 0 : no axis or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked grid without box + = 4 : plot ticked grid with box + = 5 : plot ticked grid and box with axis tick marks + = 6 : plot without grid or box + (1's digit) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +xl (R): x axis length in inches (integer valued) + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches (integer valued) + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string (limited to 99 characters) +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array + if |nt|/100 > 0 : use line type list +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl, yl or nt<0) +yx (R): maximum value of y array (required if xl, yl or nt<0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color list + ic(1) : color for grid + ic(2) : color for axis line + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color for plotted line 1 + ic(6) : color for plotted line 2 + ic(7) : color for title (return) +l (I): data line type list (required only if |nt|/100 > 0) + +common /cplotsc2/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl 1 SUBROUTINE SCATPL +.p +.x scatter plot +~SCATPL plots data point pairs (x,y) in a scatter plot format using +~log and/or ~linear scaling including appropriate axes and plot title. +Several different sets of data may be plotted on the same plot by +specifying different plotting symbols for each set of data points. +Various options select the format of plotting. If nl=1 then the x +and y arrays may be 1d arrays. +.lit + +CALL SCATPL(x,y,nl,np,iflag,nsym,s,xl,yl,xt,nxt,yt,nyt, + t,nt,>) + +x (R): array of x values dimensioned x(np,nl) +y (R): array of y values dimensioned y(np,nl) +nl (I): number of symbol types (if nl=1, x,y may be 1d arrays) +np (I): number of data point pairs (x,y) of same symbol type +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : plot ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +nsym (I): array of symbols numbers dimensioned nsym(nl) + nsym(n) < 0 : dots only plotted, no symbols line n + nsym(n) >= 0 : plot symbol number for line n +s (R): size of symbols (if s <= 0, 0.1 is used) +xl (R): x axis length in inches (integer-valued) + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches (integer-valued) + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl,yl or nt<0) +yx (R): maximum value of y array (required if xl,yl or nt<0) +(NOTE: color array required if nt < 0 or |nt|/100 >0) +ic (I): color list + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for title (return) + ic(7) : color for plotted line 1 + ic(8) : color for plotted line 2 + ic(9) : etc. + +common /cscatpl/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl 1 SUBROUTINE SEISPL +.x seismic plotting +~SEISPL allows for plotting data in the special formats often used in seismic +data processing using ~log and/or ~linear axis scaling. Appropriate +axes and plot titles may be included. The plotting format may be +selected by the value of ntype. Possible plotting formats include: +multiple "shaded" waveforms, connected lines, vertical line plots, etc. +Each line may be offset from the previous line by a specified value for +presentation on the plot (z array). A line may be added to indicate +the zero value, etc. If nl=1 then the x and y arrays +may be 1d arrays. +.lit + +CALL SEISPL(x,y,z,nld,npd,nl,np,iflag,ntype,size,zref,xl,yl, + xt,nxt,yt,nyt,t,nt,>) + +x (R): array of x values dimensioned x(npd) +y (R): array of y values dimensioned y(npd,nld) +z (R): array of y-offset values dimensioned z(nl). Y value is + offset by the z value before plotting. When using log + plotting note that offset occurs after taking logs. +nld (I): dimension of y array +npd (I): dimension of x,y arrays +nl (I): number of lines plotted (if nl=1, x,y may be 1d arrays) +np (I): number of data points to plot per line +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : plot ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +ntype (I): plot format control + < 0 : line with zref plotted + = 0 : symbols only + > 0 : line without zref plotted + (magnitude) = 1 : symbols only plotted + = 2 : points only plotted + = 3 : connected points plotted + = 4 : vertical lines from points to zref line plotted + = 5 : vertical lines plus symbol at point plotted + = 6 : vertical lines and connected points plotted + = 7 : connected points and lines on + side of zref + = 8 : connected points and lines on - side of zref + = 9 : area between connected points and zref filled + = 10 : positive area filled + = 11 : negative area filled +size (R): size of symbols (ntype : 0,1,4) + spacing between area fill lines (ntype : 9,10,11) + < 0 : indicates center line to be dotted + > 0 : indicates center line solid (if plotted) +zref (R): offset added to all z values +xl (R): x axis length in inches + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl,yl or nt<0) +yx (R): maximum value of y array (required if xl,yl or nt<0) +(NOTE: color array required if nt < 0) +ic (I): color array + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for title (return) + ic(7) : color for plotted line 1 + ic(8) : color for plotted line 2 + ic(9) : etc. + +common /cseispl/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE SPLOTS +.p +SPLOTS plots points and/or curves defined by x,y pairs in log and/or +linear scaling with option error bars. +~SPLOTS calls SPLOTSX and is provided to simplify axis specification. +.lit + +CALL SPLOTS(x,y,nld,npd,nl,np,iflag,nopt,as,xl,yl, + xt,nxt,yt,nyt,t,nt,>) + +see SPLOTSX for variable description + +common /csplots/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.hl1 SUBROUTINE SPLOTSX +.x error bars +.p +Appropriate axes and plot title may be included. +Various options select the plotting format of plotting. Possible plot +formats include scatter plots, connected line points with error bars +shown, points with error bars, a displacement line from x axis, etc. +.p +This subroutine may be used to plot several sets of curves. For a given +set (or line) of points, the upper error bar value may be given in the +next set (or line) of points. The lower error bar value may be given in +the following set (or line). When the error bar option is used, the value +of nl should be the number of points sets (or lines) to be plotted not +including the error bar sets. This subroutine permits axis parameter +flexibility and dimensioning for y array. +.lit + +CALL SPLOTSX(x,y,nld,npd,nl,np,iflag,nopt,as,xl,yl, + nmx,nnx,mlx,tsx,ndx,smx,nmy,nny,mly,tsy,ndy,smy, + xt,nxt,yt,nyt,t,nt,>) + +x (R): array of x values dimensioned at least x(np) +y (R): array of y values dimensioned y(npd,nld) +npd (I): dimension of y +nld (I): dimension of y +nl (I): number of y lines to plot (see note below) +np (I): number of points per line +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : plot x linear, y logarithmic (base 10) + = 2 : plot x logarithmic, y linear + = 3 : plot x logarithmic, y logarithmic + = 4 : plot x linear, y linear + (10's digit) = 0 : no axes or title plotted + = 1 : axes with axis line/ticks on top and sides + = 2 : plot solid cartesian grid + = 3 : plot ticked cartesian grid without box + = 4 : plot ticked cartesian grid with box + = 5 : ticked cartesian grid, box w/axis ticks + = 6 : plot without box or cartesian grid + = 7 : plot solid logarithmic grid + = 8 : plot dotted logarithmic grid + = 9 : plot ticked logarithmic grid + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +nopt (I): option flag + (1's digit) = 0 : disconnected points + = 1 : connected points + = 2 : disconnected symbols + = 3 : connected symbols + = 4 : vertical line from point to x axis + = 5 : connect points, add vertical line from each + data point to x axis + = 6 : symbol plus vertical line from point to x axis + (10's digit) = 0 : no error bars + = 1 : error bars (see above) + = 2 : error bars witout end bars (see above) + (100's) > 0 : every (*) point shown with a symbol + (0 equivalent to 1) +as (R): size of plotted symbol and/or error bar +xl (R): x axis length in inches + < 0 : use input scaling in xm,xx + > 0 : use auto scaling computed from input array +yl (R): y axis length in inches + < 0 : use input scaling in ym,yx + > 0 : use auto scaling computed from input array +(see AXIS2 for detailed description of axis parameters) +nmx (I): number of minor ticks between major ticks on x axis +nnx (I): highlight length of nnx-th minor tick on x axis +mlx (I): number of major tick marks on x axis +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndx (I): number of digits to right of decimal point on x axis +smx (R): major tick length on x axis +nmy (I): number of minor ticks between major ticks on y axis +nny (I): highlight length of nny-th minor tick on y axis +mly (I): number of major tick marks on y axis +tsy (R): size of title and numbers on y axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndy (I): number of digits to right of decimal point on y axis +smy (R): major tick length on y axis +xt (B): x axis title string +nxt (I): number of characters in xt + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +yt (B): y axis title string +nyt (I): number of characters in yt + < 0 : axis ticks on right of y axis + = 0 : no axis + > 0 : axis ticks on left of y axis (normal) +t (B): plot title string +nt (I): number of characters in t + < 0 : use color array + = 0 : no title + > 0 : do not use color array +xm (R): minimum value of x array (required if xl or nt < 0) +xx (R): maximum value of x array (required if xl or nt < 0) +ym (R): minimum value of y array (required if xl,yl or nt<0) +yx (R): maximum value of y array (required if xl,yl or nt<0) +(NOTE: color array required if nt < 0) +ic (I): color list + ic(1) : color for grid + ic(2) : color for axis lines + ic(3) : color for axis numbers + ic(4) : color for axis titles + ic(5) : color for axis exponents + ic(6) : color for title (return) + ic(7) : color for points in line 1 + ic(8) : color for symbols/error bars line 1 + ic(9) : color for points in line 2 + ic(10): color for symbols/error bars line 2 + ic(11): etc. + +common /csplotsx/xmr,dxr,ymr,dyr + +xmr (R): returned value of xmin +dxr (R): returned value of scale factor (xmax-xmin)/xlen +ymr (R): returned value of ymin +dyr (R): returned value of scale factor (ymax-ymin)/ylen +.end lit + +.pg +.hl1 SUBROUTINE T3DH +.p +.x surface plot +~T3DH plots a 3-d surface defined on a uniformly spaced 2-d grid in +the x,y plane using a triangular mesh with hidden line removal. The +surface can be viewed from any angle. +The input consists of the values of the z axis for each +(x,y) point on the plane. Each square grid is plotted as two triangles +using either ~SKETCH or ~PLT3DH permitting hidden line removal if desired. +T3DH calls ~INIT3DH to initialize the 3-d hidden line package. Default +space is provided in the INIT3DH common block. The ISIZE variable will +be reset to the internal size if its value is smaller than the internal +size. Sufficient space is provided for very complex surfaces. +.lit + +CALL T3DH(z,ndx,ndy,nx,ny,s,p,t,dv,xl,yl,zl,iflag,ia, + xt,nxt,xm,xx,tx,sx,gx,fx, + yt,nyt,ym,yy,ty,sy,gy,fy, + zt,nzt,tz,sz,gz,fz,zm,zx<,ic>) + +z (R): array of z values +ndx,ndy(I): dimensions of z array +nx,ny (I): number of points in each dimension to use of z array +s,p,t (R): yaw,roll,pitch angles of axes (see INIT3DH) +dv (R): perspective scale factor for INIT3DH + < 0 : no hidden lines in SKETCH, INIT3DH called + = 0 : INIT3DH not called to initialize 3d package, + (INIT3DH previously called) + > 0 : hidden lines in SKETCH, INIT3DH called + = 9999 : no perspective in INIT3DH +xl (R): x axis length in inches +yl (R): y axis length in inches +zl (R): z axis length in inches +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : do not use color array + = 2 : use color array + (10's digit) = 0 : hidden line removal for surface only + = 1 : hidden line removal for axis and surface + = 2 : no hidden line removal (SKETCH not used) + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +ia (I): axis option flag + < 0 : plot axis use input z axis scale + = 0 : do not plot axes + > 0 : plot axis use computed z axis scale + (1's digit) = 1 : plot y axis using input scale + = 2 : plot y axis using input, smoothed scale + (10's digit) = 1 : plot x axis using input scale + = 2 : plot x axis using input, smoothed scale +xt (B): x axis title string +nxt (I): number of characters in x axis title + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +tx (R): number and pattern of axis ticks (see AXIS3) +sx (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gx (R): rotation angle for x axis (see AXIS3DH) +fx (R): format of axis number labeling (see AXIS3) +yt (B): y axis title string +nyt (I): number of characters in y axis title + < 0 : axis ticks on top of axis + = 0 : no axis + > 0 : axis ticks on bottom of axis (normal) +ty (R): number and pattern of axis ticks (see AXIS3) +sy (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gy (R): rotation angle for y axis (see AXIS3DH) +fy (R): format of axis number labeling (see AXIS3) +zt (B): z axis title string +nzt (I): number of characters in z axis title + < 0 : axis ticks on top of axis + = 0 : no axis + > 0 : axis ticks on bottom of axis (normal) +tz (R): number and pattern of axis ticks (see AXIS3) +sz (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gz (R): rotation angle for z axis (see AXIS3DH) +fz (R): format of axis number labeling (see AXIS3) +xm,ym (R): minimum value displayed on each axis +xx,yx (R): maximum value displayed on each axis +zm (R): minimum value of z axis (required if ia < 0) +zx (R): maximum value of z axis (required if ia < 0) +ic (I): color array (required if 1's digit of iflag=2) + ic(1) : color of axis + ic(2) : surface color +.end lit + +.pg +.hl1 SUBROUTINE TRIG3DH +.p +.x surface plot +.x triangc +~TRIG3DH plots a 3-d surface specified by randomly scatted set of points +as a triangular mesh with hidden line removal. The surface may be +viewed from any angle. +The input consists of a list of triplets defining the surface. +The triplets are triangulated using TRIANGC. Each triangle is +plotted using either ~SKETCH or ~PLT3DH permitting hidden line +removal if desired. TRIG3DH calls ~INIT3DH to initialize the +3-d hidden line package. Default space is provided in the INIT3DH +common block. The ISIZE variable will be reset to the internal +size if its value is smaller than the internal size. Sufficient +space is provided for very complex surfaces. +.lit + +CALL TRIG3DH(x,y,z,n,s,p,t,dv,xl,yl,zl,iflag,ia, + xt,nxt,tx,sx,gx,fx, + yt,nyt,ty,sy,gy,fy, + zt,nzt,tz,sz,gz,fz, + xm,xx,ym,yx,zm,zx<,ic>) + +x,y,z (R): array of point triplets (x,y,z) +n (I): number of points +s,p,t (R): yaw,roll,pitch angles of axes (see INIT3DH) +dv (R): perspective scale factor for INIT3DH + < 0 : no hidden lines in SKETCH, INIT3DH called + = 0 : INIT3DH not called to initialize 3d package, + (INIT3DH previously called) + > 0 : hidden lines in SKETCH, INIT3DH called + = 9999 : no perspective in INIT3DH +xl (R): x axis length in inches +yl (R): y axis length in inches +zl (R): z axis length in inches +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 1 : do not use color array + = 2 : use color array + (10's digit) = 0 : hidden line removal for surface only + = 1 : hidden line removal for axis and surface + = 2 : no hidden line removal (SKETCH not used) + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +ia (I): axis option flag + < 0 : do not plot axes + > 0 : plot axes according to the code, + (1's digit) = 1 : plot z axis using computed scale + = 2 : plot z axis using computed, smoothed scale + = 3 : plot z axis using input scale + input scale variables required + = 4 : plot z axis using input, smoothed scale + (100's digit) = 1 : plot y axis using computed scale + = 2 : plot y axis using computed, smoothed scale + = 3 : plot y axis using input scale + input scale variables required + = 4 : plot y axis using input, smoothed scale + (100's digit) = 1 : plot x axis using computed scale + = 2 : plot x axis using computed, smoothed scale + = 3 : plot x axis using input scale + input scale variables required + = 4 : plot x axis using input, smoothed scale +xt (B): x axis title string +nxt (I): number of characters in x axis title + < 0 : axis ticks on top of x axis + = 0 : no axis + > 0 : axis ticks on bottom of x axis (normal) +tx (R): number and pattern of axis ticks (see AXIS3) +sx (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gx (R): rotation angle for x axis (see AXIS3DH) +fx (R): format of axis number labeling (see AXIS3) +yt (B): y axis title string +nyt (I): number of characters in y axis title + < 0 : axis ticks on top of axis + = 0 : no axis + > 0 : axis ticks on bottom of axis (normal) +ty (R): number and pattern of axis ticks (see AXIS3) +sy (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gy (R): rotation angle for y axis (see AXIS3DH) +fy (R): format of axis number labeling (see AXIS3) +zt (B): z axis title string +nzt (I): number of characters in z axis title + < 0 : axis ticks on top of axis + = 0 : no axis + > 0 : axis ticks on bottom of axis (normal) +tz (R): number and pattern of axis ticks (see AXIS3) +sz (R): size of axis labeling (see AXIS3) + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +gz (R): rotation angle for z axis (see AXIS3DH) +fz (R): format of axis number labeling (see AXIS3) +xm,xx (R): minimum, maximum value of x axis +ym,yx (R): minimum, maximum value of y axis +zm,zx (R): minimum, maximum value of z axis +ic (I): color array (required if 1's digit of iflag=2) + ic(1) : color of axis + ic(2) : surface color +.end lit + +.pg +.hl 1 SUBROUTINE VAX3D +.p +VAX3D plots a 3-d surface by plotting 2-d slices of the surface paralel +to the x-z plane with hidden line removal. See VAX3DX. +~VAX3D calls VAX3DX using default axis parameters to simplify calling +procedure. +.lit + +CALL VAX3D(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag,iax,>>) + +See VAX3DX for parameter description. + (iax is limited to a single digit) +.end lit + +.hl 1 SUBROUTINE VAX3DX +.p +.x 2-d surface plot +~VAX3DX is a simple 3-d surface plotting routine. A 3-d surface is +plotted by plotting slices through the surface which are parallel to +the x-y plane. The y value of the surface at the intersection +of the slice plane and the y value plotted. Hidden lines are supressed, +giving the illusion of a 3 dimensional surface. The height of plotted +surface relative to its y axis value is calibrated to x and z axis. No +perspective is used. Options exist to varying the plotting angle and +to plot axes. +.p +Origin of the plot is in the lower-left corner. The x axis runs +left to right along the plot bottom. The y axis is plotted +as a vertical displacement offset by the z axis value. The z axis appears +to point into the screen. This, with the hidden line removal, gives the +illusion of depth. +.P +VAX3DX contains an internal working storage arrays dimensioned sufficiently +large for most sufaces. However, for very complex surfaces, the working +storage buffer length may be exceeded. In this case +an error message is written to the terminal and the routine terminated. +.lit + +CALL VAX3DX(d,ndx,ndz,nx,nz,a,b,xh,yh,zh,iflag,iax, + >>) + +d (R): array of y values dimensioned d(ndx,ndz) +ndx,ndz (I): x and z dimensions of d array +nx,nz (I): x and z sizes of surface to plot d array +a (R): angle of x axis from horizontal 0-85 degrees +b (R): angle of z axis from horizontal 0-90 degrees + note: origin (1,1) is in lower-left corner + x axis runs left to right on screen + y axis runs up to down on screen + z axis appears to run into the screen but + is angled to the right +xh,yh,zh (R): length of each axis +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) >10000 : do not initialize LONGLIB before plotting + (1's digit) = 2 : use color array (need all parameters) + = 1 : do not use color array + (10's digit) = 0 : Plot sides + = 1 : Do not plot sides + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axes, use input scale factors dm and dx + = 0 : no axes plotted, optional parameters (xt...dx) + not used, scaling computed from input array + > 0 : plot axes, use scaling computed from input array + only axis parameters xt through smz required. + (1's digit) = 1 : Plot actual max/min or input values for Y axis + = 2 : Plot smoothed values for Y axis + (10's digit) = 0 : Use default axis type + = 1 : Use input AXIS2-type axis parameters + (nmx, nnx, mlx, tsx, ndx, etc.) +(NOTE: the following optional paramters are used if iax < 0 + or mod(iflag,10)=1) +xt (B): title of x axis (width) +nxt (I): number of characters in xt + = 0 : no axis plotted + > 0 : normal +xs,xe (R): starting and ending values displayed on x axis +(see AXIS2 for detailed description of axis parameters) +nmx (I): number of minor ticks between major ticks on x axis +nnx (I): highlight length of nnx-th minor tick on x axis +mlx (I): number of major tick marks on x axis +tsx (R): size of title and numbers on x axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndx (I): number of digits to right of decimal point on x axis +smx (R): major tick length on x axis +yt (B): title of y axis (depth) +nyt (I): number of characters in yt + = 0 : no y axis plotted + > 0 : normal +nmy (I): number of minor ticks between major ticks on y axis +nny (I): highlight length of nny-th minor tick on y axis +mly (I): number of major tick marks on y axis +tsy (R): size of title and numbers on y axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndy (I): number of digits to right of decimal point on y axis +smy (R): major tick length on y axis +zt (B): title of z axis (height) +nzt (I): number of characters in zt + = 0 : no z axis plotted + > 0 : normal +ze,ze (R): starting and ending valued displayed on z axis +nmz (I): number of minor ticks between major ticks on z axis +nnz (I): highlight length of nnz-th minor tick on z axis +mlz (I): number of major tick marks on z axis +tsz (R): size of title and numbers on z axis + < 0 auto exponent scaling (x10 to power) disabled + > 0 auto exponent scaling (x10 to power) enabled +ndz (I): number of digits to right of decimal point on z axis +smz (R): major tick length on z axis +(NOTE: the following optional parameters are required only if + iax < 0 or mod(iflag,10)=1) +dm,dx (R): minimum and maximum values of d array +(NOTE: color array required only if mod(iflag,10)=1) +ic (I): color list + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color index for lower plot surface (return) + ic(6) : color index for upper plot surface (return) +.end lit + +.pg +.hl 1 SUBROUTINE VAX5D +.p +.x 5-d surface +.x 4-d surface plot +.x VAX3D +~VAX5D plots a 4 or 5-d surface by plotting slices through the 3rd and +4th dimensions in a 2-d array of of 3-d plots. Each 3-d surface +plots d(*) as a function of 2 of the dimensions using VAX3D. +.p +Origin of the plot is in the lower-left corner. The X axis runs +left to right along the subplot bottom. The Y axis is plotted into +the page of the subplot (see VAX3D). +The Z axis runs left to right in subplots +with the W axis vertical subplots. +.tp 8 +.lit + + ^ W + | + | d Y + | |/_ X + | + ----------> Z +.end lit +.p +Since the subplots may runoff the edge of the plotting page, the routine +includes a page size option to issue a NEWPAGE and plot the additional +subplots on separate pages. A shrinking factor is included to shrink the +subplots. +Labeling of the W and Z axis is due in the lower right hand corner. +Each subplot is further tagged with the corresponding W and Z axis +value. A multiple page plot can be pasted together to form a large +representation of a 5-d (or 4-d) surface. +.lit + +CALL VAX5D(d,nd,n,a,b,iflag,iax,iform,w,xh,yh,zh,ph,pl,fac,iw,iz, + st,en,t1,nt1,t2,nt2,t3,nt3,t4,nt4,dt,ndt,>) + +d (R): array to plot dimensioned d(nd(1),nd(2),nd(3),nd(4)) +nd (I): array of dimensions of d array +n (I): array of the number of points from in dimension to plot +a,b (R): angles a,b for VAX3D subplot +iflag (I): option flag + < 0 : do not close LONGLIB after plotting + = 0 : close LONGLIB--no plot produced + > 0 : close LONGLIB after plotting + (magnitude) > 10000 : do not initialize LONGLIB before plotting + (1's digit) = 2 : use color array (need all parameters) + = 1 : do not use color array + (10's digit) = 0 : Plot sides of subplots + = 1 : Do not plot sides + (100's) = 0 : Ask which screen device to use + <> 0 : Screen Device Number (see FRAME) +iax (I): axis format control + < 0 : plot axes, use input scale factors dm and dx + = 0 : no axes plotted, optional parameters (t1...dx) + not used, scaling computed from input array + > 0 : plot axes, axis parameters t1 through nt4 used, + scaling computed from input array + (1's digit) = 1 : Plot actual max/min or input values for Y axis + = 2 : Plot SCALE smoothed values for Y axis + (10's digit) = 0 : Axes plotted for all subplots + = 1 : Axes plotted only for first subplot +iform (I): plot format code + selects which dimension of d array is to become + which output axis + + plot axis plot axis +Code X Y Z W Code X Y Z W +_____ ____________ _____ ____________ + 1 input: 1 2 3 4 13 3 1 2 4 + 2 dimen- 1 2 4 3 14 3 1 4 2 + 3 sion 1 4 2 3 15 3 2 1 4 + 4 number 1 4 3 2 16 3 2 4 1 + 4 1 4 3 2 16 3 2 4 1 + 5 1 3 2 4 17 3 4 1 2 + 6 1 3 4 2 18 3 4 2 1 + 7 2 1 3 4 19 4 1 2 3 + 8 2 1 4 3 20 4 1 3 2 + 9 2 4 3 1 21 4 2 1 3 + 10 2 4 1 3 22 4 2 3 1 + 11 2 3 4 1 23 4 3 1 2 + 12 2 3 1 4 24 4 3 2 1 + +w (R): working array dimensioned at least n(x)*n(y) +xh,yh,zh (R): length of each axis of subplot +ph,pl (R): page height, length when multiple pages required +fac (R): shrink factor for subplots (2 == FACTOR(1/2)) +iw,iz (I): plot every iw'th and iz'th subplots +st,en (R): arrays containing axes start and end values (permuted + along with d array dimensions) +(NOTE: titles/number of characters permuted with d array dimensions) +t1 (B): title corresponding to 1st dimension of d +nt1 (I): number of characters in title t1 + = 0 : no axis plotted + > 0 : axis plotted +t2 (B): title corresponding to 2st dimension of d +nt2 (I): number of characters in title t2 + = 0 : no axis plotted + > 0 : axis plotted +t3 (B): title corresponding to 3rd dimension of d +nt3 (I): number of characters in title t3 + = 0 : no axis plotted + > 0 : axis plotted +t4 (B): title corresponding to 4th dimension of d +nt4 (I): number of characters in title t4 + = 0 : no axis plotted + > 0 : axis plotted +t5 (B): title corresponding to 5th dimension of d +nt5 (I): number of characters in title t5 + = 0 : no axis plotted + > 0 : axis plotted +(NOTE: the following optional parameters are required only if + iax < 0 or mod(iflag,10) = 1) +dm,dx (R): minimum and maximum scale values for array +ic (I): color array + ic(1) : color for axis lines + ic(2) : color for axis numbers + ic(3) : color for axis titles + ic(4) : color for axis exponents + ic(5) : color index for lower plot surface (return) + ic(6) : color index for upper plot surface (return) +.end lit + +.Chapter Miscellaneous Routines +.P +The subroutines listed below are ~miscellaneous functions and +routines used by the previously described routines. These are low-level +routines documented for the use of advanced LONGLIB programers. + +.hl1 INTEGER FUNCTION IPCLIP +.p +~IPCLIP tests a point to determine if it lies in a rectangle defined by +xm,ym,xx,yx and returns an integer value indicating where point is in relation +to rectangle. The value can be easily be decoded by "anding" return +value with the binary values of 1, 2, 4, 8. +.lit + + 9 | 8 | 10 + -------------- + 1 | 0 | 2 + -------------- + 5 | 4 | 6 +.end lit +.lit + +iflag = IPCLIP(x,y,xm,ym,xx,yx) + +x,y (R): point to test +xm,ym (R): lower left corner of rectangle +xx,yx (R): upper right corner of rectangle +iflag (I): clip flag (0-10) (see above) +.end lit + +.hl1 SUBROUTINE GCONTR +.p +~GCONTR draws contour lines of a 2-d array using a technique which +produces long, connected contour lines. It assumes that the points +of the input array are equally spaced in each dimension. Several +options for contouring are provided. When cs, the label character size +is positive, the origin point (1,1) is in the +lower-left corner and the point (i,j) in the array is plotted at, +.lit + + xplot = (i-1)*xl + yplot = (j-1)*yl + +.end lit +If cs is negative, the x and y values plotted (xp,yp) for the point +(i,j) in the array are computed using +the ~PLT3D ~transformation common block ~PLT3B (see PLT3D), +.lit + + xp = a1 * (yl * j) + a2 * (xl * i) + a3 + yp = b1 * (yl * j) + b2 * (xl * i) + b4 +.end lit +where the vertical height (z) is zero. In this case, xl and yl +should be set to 1.0 and PLT3D should be called before GCONTR. +GCONTR is used in the MASTER routine ~LCNTR and CVAX3DX. +.x CVAX3DX +.lit + +CALL GCONTR(z,ndx,ndy,nx,ny,xl,yl,cv,nv,zm,iw,n,cs,m,i,ic,il) + +z (R): 2-d array of values dimensioned z(nx,ny) +ndx,ndy (I): dimensions of data array +nx,ny (I): number of points to use in array +xl,yl (R): axis length scale factors (inches/array index) +cv (R): array of contour levels dimensioned cl(nv) +nv (I): number of contour levels (note: if nv < 0 then only + one contour level is used. It will be labeled with + the abs(nv)'th symbol) +zm (R): maximum value of z for consideration. A z value which + exceeds this value will be ignored. The cell edges + which include this point will not be included in + contouring. +iw (I): workspace dimensioned at least (2*nx*ny*nv+1)/31 +n (I): contour labeling option + < 0 label with contour value (number with n digits + to the right of the decimal point) + = 0 no labelling of contours + > 0 label with alphabet (nl should be less than 26) +cs (R): size of labels + < 0 : plot contours using PLT3B transformation + xl and yl should then be set to 1.0 (see notes) + > 0 : normal location specification +m (I): minimum number of cells crossed by contour in order + for contour to be labeled +i (I): color and line type flag + = 0 color and line type arrays not used + = 1 color array used + = 2 line type array used + = 3 color and line type array used +ic (I): color list for each contour (only requied for i>0) +l (I): line type list for contours (required only for i>1) +.end lit + +.hl1 INTEGER FUNCTION INXTCHR +.x vt100 +.p +~INXTCHR returns a single key pressed on the terminal. In the VAX/VMS +environment, it will intercept all control +keys (including ) except ^Y,^T,^R,^Q,^Z,^S without echoing to the +screen. Opens a direct IO ~channel to the terminal driver using SYSQIO. +This routine is used by the ~PAUSE and ~CURMOTION routines. +.lit + +key = INXTCHR() + +key (I): (returned) terminal character (ASCII value) + if key < 0, an error reading terminal input has occured. +.end lit + +.hl1 INTEGER FUNCTION IRMCHAN +.p +.x ramopen +~IRMCHAN returns the ~channel number and the Ramtek device number +used by the plot package (as assigned +by RAMOPEN) for communicating with the Ramtek. +Returns a negative value when the Ramtek package is not initialized +or when the Ramtek channel is not yet assigned. +.lit + +ich = IRMCHAN(id) + +id (I): (returned) Ramtek device number +ich (I): (returned) Ramtek channel number + if ich <=0 the Ramtek is not is use. +.end lit + +.hl1 SUBROUTINE MATMUL4 +.p +~MATMUL4 multiplies two 4x4 matrixes A and B and sets C=AB. Does not +change the contents of A and B. +.lit + +CALL MATMUL4 (c,a,b) + +c,a,b (R): 4 x 4 matrixes +.end lit + +.hl1 SUBROUTINE MTV4 +.p +~MTV4 multiplies a 4 element row vector by a 4x4 matrix and sets V2=A V1. +.lit + +CALL MTV4 (v2,a,v1) + + +v2 (R): 4 element row vector +a (R): 4 x 4 matrix +v1 (R): 4 element row vector +.end lit + +.hl1 SUBROUTINE NXTVU +.p +.x plt3d +~NXTVU is used internally by PLT3D. NXTVU computes the maximum (or minimum) +of two piecewise linear functions: the curve specified in the input d array +and the curve stored in the working array w. +On return the new maximum (minimum) curve replaces the old in w. Any line +segments or fractions thereof above (below) the maximum (minimum) are plotted. +If iabs(i)=1 the input is copied into the working array and plotted. +Subsequent calls should use iabs(i)=2. +Using i positive computes the maximum while using i negative plots the +minimum. +.p +A grid of lines in only one dimension may be made by calling NXTVU once +for each row, adjusting the d curve to offset each row by a small +amount to give the impression of a surface. +.p +The dimension of the working arrays is dependent of the surface +complexity -- the greater the complexity the larger n2 must be. ier is +used to indicate when n2 is not large enough. As a minimum n2>2*n. +Note: w should not be modified between calls. +.lit + +CALL NXTVU (i,d,n,w,n2,ier) + +i (I): initialize code + < 0 : plot lower side of surface + => 0 : plot upper side of surface + = -1 : first call for lower surface plot + = -2 : subsequent calls for lower surface plot + = 1 : first call for upper surface plot + = 2 : subsequent calls for upper surface plot +d (R): array of (x,y) coordinate pairs dimensioned d(2*n) + d(1) = x(1) + d(2) = y(1) + d(3) = x(2) + ... +n (I): number of coordinate pairs in d array +w (R): working storage array of dimensioned d(n2) + (should not be modified between calls) +n2 (I): dimension of working array +ier (I): (returned) error code + = 0 : no error + = 1 : out of space in w +.end lit + +.hl1 SUBROUTINE PAUSE +.x INXTCHR +.p +~PAUSE prompts terminal without a CTERM(1) for a keystroke to continue. +Uses INXTCHR. +.lit + +CALL PAUSE + (no arguments) +.end lit + +.hl1 SUBROUTINE PAUSEP +.x INXTCHR +.p +~PAUSEP prompts terminal for a keystroke to continue. Includes appriate +~CTERM calls to prompt in text mode then returns terminal to plot mode. +Uses INXTCHR. +.lit + +CALL PAUSEP + (no arguments) +.end lit + + +.hl1 SUBROUTINE RAMCLOSE +.p +~RAMCLOSE closes and deassigns the ~Ramtek channel and deallocates the device. +When the ~REF routines are used, it interatively prompts for the output +device and option. ~REFDIS called prior to RAMCLOSE disables the prompting +in the REF package. Note that RAMCLOSE is call by ~PLOTRM when a +PLOTND or PLOTRM(0.,0.,11) is called. +.lit + +CALL RAMCLOSE (ic) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +.end lit + + +.hl 1 SUBROUTINE REFDIS +.p +~REFDIS is used only in the ~LONGLIBR version of the longlib graphics +library. It is a dummy call for other versions. REFDIS is a non-interactive +method of specifying the output device (REF file, terminal screen, or +LONGLIB metafile) to be used for outputing the REF bit-map Ramtek image array. +When called prior to PLOTND, it outputs the array to the device +specified in the call without user intervention. +When REFDIS is not called prior to PLOTND, PLOTND will call REFDIS and +the user will be prompted for the output device and option. +Note: REFDIS may be called multiple times to output to several devices. +.p +When the internal REF data array is output to the terminal or metafile +output each line of the internal array is scanned left to right. Connected +pixels having the same color are collected and plotted (using PLOT) to the +output device. Pixels with 0 value are not output. The pixel-to-inch +output scaling can be user selected to correspond to the actual hardware +resolution of the output device. Normal resolution for the terminal output +is 9.5/1024 inch/pixel (most terminals do not actually have this resolution). +Normal resolution for the meta file output is 1/300 inch/pixel. +Hence, at normal resolution, the 1280x1024 pixel REF array more than +fills the terminal screen. The pixel image is output with the lower-left +corner at (0,0). By changing the origin prior to call the user can +display any desired portion of the image. +.lit + +CALL REFDIS(id,ot,n,rx,ry) + +id (I): Output device + =-1 : graphics terminal number code (see FRAME) + user-specified (rx,ry) used + = 1 : graphics terminal number code (see FRAME) + default resolution used + = 2 : Ramtek emulation file (REF) + (ot = 1 : absolute file write) + (ot = 2 : write out only non-zero pixels) + (ot = 3 : write out only zero pixels) + =-3 : LONGLIB metafile output + user-specified (rx,ry) used + = 3 : LONGLIB metafile output + default resolution used +ot (I): Output option code (see above) +n (C): REF file name +rx,ry (R): user-specified output resolution (inch/pixel) +.end lit + +.hl 1 SUBROUTINE RMCLEAR +.p +~RMCLEAR clears ~Ramtek screen. +.lit + +CALL RMCLEAR (ic,ie) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMDIR +.x Ramtek image data +.p +~RMDIR sets the write direction for ~image array data on the +~Ramtek display. This routine is supported in the REF package. +.lit + +CALL RMDIR (ic,is,ie) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +is (I): scan sequence code + code pix-to-pix line-to-line + 0 L-R T-B + 1 R-L T-B + 2 L-R B-T + 3 R-L B-T + 4 T-B L-R + 5 B-T L-R + 6 T-B R-L + 7 B-T R-L +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMFNTSIZE +.p +~RMFNTSIZE changes the size of Ramtek ~text displayed on the ~Ramtek display. +Not supported in REF package. +.lit + +CALL RMFNTSIZE (ic,ih,iv,ihs,ivs,ie) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +ih,iv (I): horizontal,vertical dimension +ihs,ivs (I): horizontal,vertical spacing +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RAMOPEN +.p +~RAMOPEN (1) translates the local name "RM" to determine the ramtek device +number, (2) allocates the ramtek device, (3) assigns a channel to the Ramtek +device, and (4) opens the channel I/O. Returns the channel number or +-1 if device is not available. This is routine is called by RPLOTS which +is called by FRAME. RAMOPEN initializes the REF array. +.lit + +CALL RAMOPEN(ic,it,id,ie) + +ic (I): returned channel number +it (I): Ramtek device code input + = 1 1280x1024 Ramtek + = 2 512x512 Ramtek +id (I): returned Ramtek device number +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RAMOUT +.p +~RAMOUT outputs a command and data array to the ~Ramtek display. +(see Ramtek manual for command formats). The REF package uses RAMOUT +for a different purpose. +.lit + +CALL RAMOUT (ic,m,n,ie) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +m (B): array of bytes to output +n (I): number of bytes +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMPAN +.p +~RMPAN pans Ramtek display. Not supported in REF package. +.lit + +CALL RMPAN (ic,il,ir,ie) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +il (I): left x pixels +ir (I): right y pixels +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMPLOT +.p +~RMPLOT plots an array of connected vectors using pixel locations on Ramtek +or REF package. This routine is called by PLOTRM which is called by PLOT. +RMPLOT simulates line widths using the width information stored in an +internal common block by RMTEXTURE by replicating the line several times +with pixel offsets to produce a "thick" line. +Note: x is in pixels from right to left. y is in pixels from top of display. +.x color table +.x RMTEXTURE +.lit + +CALL RMPLOT (ic,n,ia,k,ie) + +ic (I): channel number (from RAMOPEN or IRMCHAN) +n (I): number of point pairs (<129) +ia (I): array of point pairs (in pixels) + a(1)=x1,a(2)=y1,a(3)=x2,... +k (I): color table index to use +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMREADBYTE +.x Ramtek image data +.p +~RMREADBYTE reads the ~Ramtek ~image array. Supported by REF. +.lit + +CALL RMREADBYTE (ic,a,n,ie) + +ic (I): channel number (from RAMOPEN) +a (B): (returned) image data +n (I): number of words of a to read +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMREADCOL +.x color table +.p +~RMREADCOL reads the ~Ramtek color table from the Ramtek display. +The color table is ~INTEGER*4 words. +Not supported by REF. +.lit + +CALL RMREADCOL (ic,ia,n,ie) + +ic (I): channel number (from RAMOPEN) +ia (I): (returned) color table array +n (I): number of words of a to read +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMREADCURSOR +.x curmotion +.x RMSETCURSOR +.p +~RMREADCURSOR reads the current ~Ramtek ~cursor device position. +Called by CURMOTION, etc. See RMSETCURSOR. Not supported on REF package. +.lit + +CALL RMREADCURSOR (ic,id,ix,iy,it,iv,ien,ie) + +ic (I): channel number (from RAMOPEN) +id (I): cursor device number +ix,iy (I): (returned) pixel location of cursor (pixels) +it,iv,ien (I): (returned) codes for track, visible, enter + switches, see RMSETCURSOR +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMREADWORD +.x Ramtek image data +.p +~RMREADWORD reads ~INTEGER*2 words from the ~Ramtek ~image array. +Supported by REF. +.lit + +CALL RMREADWORD (ic,id,n,ie) + +ic (I) : channel number (from RAMOPEN) +id (I*2): (returned) image data +n (I) : number of words to read +ie (I) : (returned) error code +.end lit + +.hl1 SUBROUTINE RMSETCUR +.p +.x CURLOCATE +~RMSETCUR moves specified ramtek ~cursor device to a specified position and +sets it as visible and/or blinking. Called by CURLOCATE. Not supported +by REF +.lit + +CALL RMSETCUR (ic,i,ix,iy,ib,iv,ie) + +ic (I): channel number (from RAMOPEN) +i (I): cursor device number (0-3) +ix,iy (I): pixel position of cursor (see RMPLOT) +ib (I): blink flag (1=no blink,2=blink) +iv (I): visible flag (2=visible, 0=invisible) +ie (I): returned error code +.end lit + +.hl1 SUBROUTINE RMSTART +.x Ramtek image data +.p +~RMSTART sets the start pixel of ~image mode write on the ~Ramtek display. +Supported by REF. +.lit + +CALL RMSTART (ic,ix,iy,ie) + +ic (I): channel number (from RAMOPEN) +ix,iy (I): pixel position to start next image write +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMTEXT +.p +~RMTEXT places text on ~Ramtek display using Ramtek hardware text support. +Not supported on REF. +.lit + +CALL RMTEXT (ic,icol,ix,iy,is,t,nt,ie) + +ic (I): channel number (from RAMOPEN) +icol (I): color +ix (I): x pixel location +iy (I): y pixel location +is (I): size in pixels +t (B): byte array of text +nt (I): number of bytes in the array t +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMTEXTURE +.p +~RMTEXTURE changes the bit texturing pattern for vector line drawing +on the Ramtek. Called by ~RMPEN which is called by ~NEWPEN and +also by ~CURMOTION et. al. Supported by REF. +.LIT + +CALL RMTEXTURE (ic,it,iw,is,ie) + +ic (I): opened channel number (from RAMOPEN) +it (I): line type number (0-15) +iw (I): line width used in RMPLOT (1-7) +is (I): bit width scale factor (0-15) + (0= [1 bit=1 pixel], 1=[1 bit=2 pixels], etc.) +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMWIND +.p +~RMWIND sets the ~image area of the ~Ramtek display. Supported by REF. +.lit + +CALL RMWIND (ic,ix,iy,mx,my,ie) + +ic (I): channel number (from RAMOPEN) +ix,iy (I): starting corner of image pixels (u-r corner) +mx,my (I): ending corner of image pixels (l-l corner) +ie (I): (returned) error code +.end lit +.x Ramtek image data + +.hl1 SUBROUTINE RMWRITEBYTE +.x Ramtek image data +.p +~RMWRITEBYTE write byte ~image data to the ~Ramtek image array. Supported +by REF. +.lit + +CALL RMWRITEBYTE (ic,a,n,ie) + +ic (I): channel number (from RAMOPEN) +a (B): image data +n (I): number of words of a to read +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMWRITECOL +.x color table +.p +~RMWRITECOL writes ~Ramtek color display data to the Ramtek display +color table. The color table is ~INTEGER*4 words. +Not supported by REF. +.lit + +CALL RMWRITECOL (ic,a,n,ie) + +ic (I): channel number (from RAMOPEN) +a (I): new color table array +n (I): number of words of array a +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE RMWRITEWORD +.x Ramtek image data +.p +~RMWRITEWORD writes ~INTEGER*2 ~image data to the ~Ramtek image display. +Supported by REF. +.lit + +CALL RMWRITEWORD (ic,id,n,ie) + +ic (I) : channel number (from RAMOPEN) +id (I*2): image data +n (I) : number of words to read +ie (I) : (returned) error code +.end lit + +.hl1 SUBROUTINE RMZOOM +.p +~RMZOOM zooms ~Ramtek display. Not supported by REF. +.lit + +CALL RMZOOM (ic,iz,ie) + +ic (I): channel number (from RAMOPEN) +iz (I): zoom factor in powers of 2 +ie (I): (returned) error code +.end lit + +.hl1 SUBROUTINE VTPLOT +.p +~VTPLOT plots an array of connected vectors to terminal. ~Terminal +must be in graphics mode prior to call. VTPLOT is called by ~PLOTVT +and by ~CURLOCATE and CURMOTION., et. al. An erase flag is used +to indicate whether vector string should be visible, erased, or +XOR'ed. Since not all terminal support XOR, two flags for XOR are +provided--one which if XOR is not supported writes visible vectors +with the other which erases (if supported). Line width is simulated +by replotting adjacent lines. +.lit + +CALL VTPLOT (n,m,ie,iw) + +n (I): number of point pairs in m +m (I): array of points to be connected with line + m(1)=x1,m(2)=y1,m(3)=x2,... +ie (I): erase flag (0=normal, 1=XOR (on), 2=erase, 3=XOR (off)) +iw (I): width +.end lit + + +.hl1 SUBROUTINE TRIANGC +.p +~TRIANGC triangulates a set of (x,y) points such that the boundry is a +convex polygon. This routine is an adaption of ~COSMIC routine ARC-11441. +Used by some MASTER routines. +.lit + +CALL TRIANGC(x,y,n,nt,nzz,m,i,j,ni,l,nz,ie,ibe,ite) + +x,y (R): arrays of x,y points +n (I): number of points + < 0 : ie,ibe,ite arrays not used + > 0 : ie,ibe,ite arrays used (normal) +nt (I): array of indicies of triangulated points t(nzz,3) + corner 1 of triangle K = (x,y) = (x(t(K,1),y(t(K,1))) + corner 2 of triangle K = (x,y) = (x(t(K,2),y(t(K,2))) + corner 3 of triangle K = (x,y) = (x(t(K,3),y(t(K,3))) +nzz (I): dimension of t array (>3*n) +m (I): number of triangles stored in t +i,j (I): working arrays (dimensioned i(ni),j(ni)) +ni (I): dimension of i,j arrays (ni>=n) +l (I): number of edges in ie,ibe,ite +nz (I): dimension of ie,ibe,ite array (>3*n) +note: these arrays only needed if n>0 +ie (I): array of indicies of each triangle edge ie(nz,2) +ibe (I): edge flag array dimensioned ibe(nz) + = 0 for interior edge + = 1 if ie is a boundry edge +ite (I): array of indicies of the neighbor edges of + each triangle, dimensioned ite(nz,4) +.end lit + +.hl1 REAL FUNCTION XVMUL3D +.p +~XVMUL3D returns one element of an input vector (x,y,z) multiplied by an input +rotation matrix r(4,4). +.lit + +value = XVMUL3D (n,x,y,z,v,r) + +n (I) : which coordinate value to return (1=x,2=y,3=z) +x,y,z (R) : input x,y,z +v (R) : working vector (4 elements) +r (R) : rotation matrix (4,4) +value (R) : desired element value (see n) +.end lit + +.chapter LONGLIB Library Names +.p +This chapter lists the LONGLIB graphics library subroutine names as well +as the subroutines (outside of the standard FORTRAN routines) called by +each subroutine. The calling routines (excluding MASTER routines) are +indicated as well. An asterick +indicates that the routine is documented in the documentation and may +called by the user. + +.hl 1 Subroutine Calls +.ls1 +.dle ,,'.' +.le;~ABSPLT +.br;Calls: WHEREVT, FIXVT0, WHEREPR, FIXPR0, WHERERM, FIXRM0 +.br;Called by: * +.le;~ANXTVU +.br;Calls: (none) +.br;Called by: NXTVU +.le;~ARCALC +.br;Calls: (none) +.br;Called by: LINSEQ +.le;~ARCPLT +.br;Calls: SPIFUN, PLOT, SPIDER +.br;Called by: LINSEQ +.le;~ARCSET (Entry of ARCPLT) +.br;Calls: PLOT +.br;Called by: LINSEQ +.le;~ARROW +.br;Calls: PLOT +.br;Called by: * +.le;~ASTEXIT +.br;Calls: +.br;Called by: (qio -- system routine) +.le;~ASTINTER +.br;Calls: (none) +.br;Called by: *, PLOT +.le;~AXIS +.br;Calls: PLOT, SYMBOL, NUMBER +.br;Called by: * +.le;~AXIS2 +.br;Calls: PLOT, SYMBOL, NUMBER +.br;Called by: * +.le;~AXIS3 +.br;Calls: PLOT, SYMBOL, NUMBER +.br;Called by: * +.le;~AXIS3D +.br;Calls: ROTEM, MATMUL4, PLOT3D, NUM3D, SYM3D, XVMUL3D +.br;Called by: * +.le;~AXIS3DH +.br;Calls: ROTEM, MATMUL4, PLT3D, SKETCH, NUM3DH, SYM3DH, XVMUL3D +.br;Called by: * +.le;~BARCHR +.br;Calls: FRAME, CTERM, PLOT, SYMBOL, NUMBER, PLOTND, NEWPEN, SHADE +.br;Called by: * +.le;~BITCURSOR +.br;Calls: (none) +.br;Called by: * +.le;~BITMAP +.br;Calls: PLOT, LNDSEA +.br;Called by: * +.le;~CHECK3D +.br;Calls: (none) +.br;Called by: LINHID +.le;~CHLSKYS +.br;Calls: (none) +.br;Called by: SMOOTHC +.le;~CIRCLE +.br;Calls: PLOT +.br;Called by: *, PLRAX +.le;~CLIP3D +.br;Calls: (none) +.br;Called by: IPCLP3 +.le;~CLPIT +.br;Calls: IPCLIP +.br;Called by: PLOTVT, PLOTRM, PPLOT +.le;~IPCLIP +.br;Calls: (none) +.br;Called by: CLPIT, PLOTVT, PLOTRM, PPLOT +.le;~CNCELPLT +.br;Calls: SEGCODE, POLY1INT, PLOT +.br;Called by: CNTRPLT +.le;~CNCELPLT3D +.br;Calls: SEGCODE, RVXPT3D, PLOT, POLY1INT +.br;Called by: CNT3DX +.le;~CNDRAW +.br;Calls: PLOT, NEWPEN, SYMBOL, NUMBER +.br;Called by: GCONTR +.le;~CNT3D +.br;Calls: CNT3DX +.br;Called by: * +.le;~CNT3DX +.br;Calls: SCALE, FRAME, CTERM, AXIS2, AXIS, VXPT3D, CNCELPLT3D, +TRCELPLT3D, PLOTND, NEWPEN +.br;Called by: *, CNT3D +.le;~CNTLN +.br;Calls: FRAME, CTERM, SCALE, AXIS3, PLOT, SYMBOL, CNCELPLT, +TRIANGC, INTERPC, CNTOUR, PLOTND, NEWPEN +.br;Called by: * +.le;~CNTOUR +.br;Calls: PLOT +.br;Called by: CNTLN +.le;~CNTRPLT +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, +LGAXS, AXIS, CNCELPLT, PLOTND, NEWPEN +.br;Called by: * +.le;~CSHADE +.br;Calls: PLOT, NEWPEN, PICHRT +.br;Called by: * +.le;~CTERM +.br;Calls: (none) +.br;Called by: *, PLOTVT +.le;~CUBE +.br;Calls: PLT3DH, SKETCH +.br;Called by: *, HIST3D +.le;~CURBAND +.br;Calls: RMTEXTURE, RMSETCUR, RMPLOT, INXTCHR, VTPLOT +.br;Called by: * +.le;~CURLOCATE +.br;Calls: RMSETCUR, VTPLOT +.br;Called by: * +.le;~CURMOTION +.br;Calls: INXTCHR, RMSETCUR, VTPLOT +.br;Called by: * +.le;~CURRECT +.br;Calls: RMTEXTURE, RMSETCUR, RMPLOT, INXTCHR, VTPLOT +.br;Called by: * +.le;~CVAX3D +.br;Calls: CVAX3DX +.br;Called by: * +.le;~CVAX3DX +.br;Calls: NXTVU, PLOT, FRAME, GCONTR, PLT3D, HLT3D, CTERM, AXIS3 +.br;Called by: *, CVAX3D +.le;~DASHL +.br;Calls: PLOT, SYMBOL +.br;Called by: * +.le;~DRAW3D +.br;Calls: PLOT +.br;Called by: PLOT3D +.le;~EARTH3D +.br;Calls: SPRECT1, PLOT3D +.br;Called by: * +.le;~ELLIPSE +.br;Calls: PLOT +.br;Called by: * +.le;~ENABLEAST +.br;Calls: ENAST +.br;Called by: *, FRAME +.le;~ENAST +.br;Calls: (qio system routine if control-c interrupt code is used in package) +.br;Called by: ENABLEAST +.le;~FACTOR +.br;Calls: VFACTOR, RFACTOR, PFACTOR +.br;Called by: * +.le;~FIXPR0 +.br;Calls: PPLOTP +.br;Called by: *, ABSPLT +.le;~FIXRM0 +.br;Calls: RMTEXTURE +.br;Called by: *, ABSPLT +.le;~FIXVT0 +.br;Calls: NEWVPEN +.br;Called by: *, ABSPLT +.le;~FRAME +.br;Calls: VPLOTS, RPLOTS, PPLOTS, ENABLEAST, EXIT (system routine) +.br;Called by: *, PLOTS +.le;~GCONTR +.br;Calls: CNDRAW +.br;Called by: *, LCNTR +.le;~GETCURSOR +.br;Calls: (none) +.br;Called by: * +.le;~GLPLOT +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, +LGAXS, AXIS3, LINE, LGLIN, PLOTND +.br;Called by: * +.le;~GRID +.br;Calls: PLOT +.br;Called by: * +.le;~HELPME +.br;Calls: LIB$DISPLAY_OUTPUT, LIB$STATUS +.br;Called by: * +.le;~HIST3D +.br;Calls: SCALE, FRAME, CTERM, AXIS3DH, PLT3DH, SKETCH, PLOT, +PLOTND, INIT3DH +.br;Called by: * +.le;~HLT3D +.br;Calls: NXTVU, PLOT +.br;Called by: *, CVAX3DX, MVAX3DX +.le;~HPLT +.br;Calls: PLOT +.br;Called by: LINHID +.le;~INIT3D +.br;Calls: MATMUL4, ROTEM +.br;Called by: * +.le;~INIT3DH +.br;Calls: (none) +.br;Called by: * +.le;~INTERPC +.br;Calls: (none) +.br;Called by: CNTLN +.le;~INTERSECT +.br;Calls: (none) +.br;Called by: VAX3DX +.le;~INXTCHR +.br;Calls: SYS$QIO +.br;Called by: *, PAUSE, PAUSEP, CURMOTION, CURRECT, CURBAND +.le;~IPCLP3 +.br;Calls: CLIP3D +.br;Called by: PLOT3D +.le;~IRMCHAN +.br;Calls: (none) +.br;Called by: * +.le;~ISEGCODE +.br;Calls: (none) +.br;Called by: TRCELPLT3D +.le;~ISOL3D +.br;Calls: (none) +.br;Called by: LINHID +.le;~JPLTAG +.br;Calls: SHADE, PLOT +.br;Called by: * +.le;~LANDMAP +.br;Calls: PLOT +.br;Called by: * +.le;~LCNTR +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, +LGAXS, AXIS, GCONTR, PLOTND, NEWPEN +.br;Called by: * +.le;~LCOEF +.br;Calls: (none) +.br;Called by: LINHID +.le;~LGAXS +.br;Calls: PLOT, SYMBOL, NUMBER +.br;Called by: * +.le;~LGLIN +.br;Calls: PLOT, SYMBOL +.br;Called by: * +.le;~LGRID +.br;Calls: PLOT +.br;Called by: * +.le;~LINE +.br;Calls: PLOT, SYMBOL +.br;Called by: * +.le;~LINHID +.br;Calls: LCOEF, VSRT1, VSRTR, HPLT, CHECK3D, ISOL3D, STAT3D +.br;Called by: LINHID +.le;~LINSEQ +.br;Calls: PRETRP, ARCALC, SMOOTHC, SPISET, ARCSET, ARCPLT +.br;Called by: *, SYMSS +.le;~LNDSEA +.br;Calls: (none) +.br;Called by: BITMAP +.le;~LSPLOT +.br;Calls: FRAME, CTERM, PLOTND, SYMBOL, SCALE, NEWPEN, PLOT +.br;Called by: * +.le;~MATMUL4 +.br;Calls: (none) +.br;Called by: PLOT3D, SYM3D, SYM3DH +.le;~MESH3D +.br;Calls: MESH3DX +.br;Called by: * +.le;~MESH3DX +.br;Calls: SCALE, FRAME, CTERM, VXPT3D, AXIS2, AXIS, PLOT, PLOTND +.br;Called by: *, MESH3D +.le;~MIDC +.br;Calls: (none) +.br;Called by: TRIANGC +.le;~MTV4 +.br;Calls: (none) +.br;Called by: PLOT3D, SYM3D, SYM3DH, XVMUL3D +.le;~MVAX3D +.br;Calls: MVAX3DX +.br;Called by: *, MVAX5D +.le;~MVAX3DX +.br;Calls: SCALE, FRAME, CTERM, PLT3D, HLT3D, AXIS3, PLOT, PLOTND +.br;Called by: *, MVAX3D +.le;~MVAX5D +.br;Calls: SCALE, FRAME, CTERM, RTERM, SYMBOL, NUMBER, MVAX3D, PLOT, +FACTOR, PLOTND +.br;Called by: * +.le;~NEWPAGE +.br;Calls: PPLOT +.br;Called by: * +.le;~NEWPEN +.br;Calls: RMPEN, PPEN +.br;Called by: *, CNDRAW, SHADE, CSHADE, GCONTR +.le;~NEWVCOL +.br;Calls: (none) +.br;Called by: VPLOTS, PLOTVT +.le;~NEWVPEN +.br;Calls: (none) +.br;Called by: VPEN +.le;~NUM3D +.br;Calls: SYM3D +.br;Called by: *, AXIS3D +.le;~NUM3DH +.br;Calls: SYM3DH +.br;Called by: *, AXIS3DH +.le;~NUMBER +.br;Calls: SYMBOL +.br;Called by: *, AXIS, AXIS2, AXIS3, CNDRAW +.le;~NXTVU +.br;Calls: PLOT, NXT0VU, ANXTVU +.br;Called by: *, PLT3D, HLT3D, MVAX3DX, CVAX3DX +.le;~OLDNUMB +.br;Calls: SYMBOL +.br;Called by: * +.le;~NXT0VU +.br;Calls: (none) +.br;Called by: NXTVU +.le;~PAUSE +.br;Calls: INXTCHR +.br;Called by: * +.le;~PAUSEP +.br;Calls: INXTCHR, CTERM +.br;Called by: * +.le;~PFACTOR +.br;Calls: (none) +.br;Called by: *, FACTOR +.le;~PHIST +.br;Calls: FRAME, AXIS, PLOT, SYMBOL, SHADE, RECT, PLOTND, +CTERM +.br;Called by: * +.le;~PICHRT +.br;Calls: FRAME, SYMBOL, PLOT, NEWPEN, CSHADE, SHADE, PLOTND, CTERM +.br;Called by: * +.le;~PLOT +.br;Calls: PLOTVT, PLOTRM, PPLOT, ASTINTER +.br;Called by: *, AXIS, AXIS2, AXIS3, ARROW, BITMAP, CIRCLE, CNDRAW, DASHL, +DARW3D, ELLIPSE, FRACT, GRID, HPLT, JPLTAG, LANDMAP, LGAXS, LGLIN, LGRID, +LINE, NXTVU, PLOTND, PLRAX, PLRLN, PLT3DH, POLARMAP, RECT, SHADE, SYMBOL, +SYMS, SYMSS, TRCELPLT3D, CSHADE +.le;~PLOT3D +.br;Calls: MTV4, ROTEM, MATMUL4, VCPY, DRAW3D, IPCLP3 +.br;Called by: *, AXIS3D, EARTH3D, SYM3D +.le;~PLOTLG +.br;Calls: FRAME, CTERM, NEWPAGE, SCALE, SCALG, LGRID, GRID, PLOT, +LGAXS, AXIS, LINE, LGLIN, PLOTND, SYMBOL, NEWPEN +.br;Called by: * +.le;~PLOTLG2 +.br;Calls: FRAME, CTERM, NEWPAGE, SCALE, SCALG, LGRID, GRID, PLOT, +LGAXS, AXIS, LINE, LGLIN, PLOTND, SYMBOL, NEWPEN +.br;Called by: * +.le;~PLOTLGL +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, +LGAXS, AXIS2, LINSEQ, PLOTND, SYMBOL, NEWPEN +.br;Called by: * +.le;~PLOTLGX +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, +LGAXS, AXIS2, LGLIN, LINE, PLOTND, SYMBOL, NEWPEN +.br;Called by: * +.le;~PLOTND +.br;Calls: PLOT +.br;Called by: * +.le;~PLOTRM +.br;Calls: RMCLEAR, RMPLOT, IPCLIP, RAMCLOSE, CLPIT +.br;Called by: *, PLOT +.le;~PLOTS +.br;Calls: FRAME +.br;Called by: * +.le;~PLOTSC +.br;Calls: FRAME, CTERM, NEWPAGE, SCALE, GRID, LINE, AXIS, PLOT, +LINE, SYMBOL, PLOTND, NEWPEN +.br;Called by: * +.le;~PLOTSC2 +.br;Calls: FRAME, CTERM, NEWPAGE, SCALE, GRID, LINE, AXIS, PLOT, +LINE, SYMBOL, PLOTND, NEWPEN +.br;Called by: * +.le;~PLOTVT +.br;Calls: CTERM, VTPLOT, IPCLIP, NEWVCOL, CLPIT +.br;Called by: *, PLOT +.le;~PLRAX +.br;Calls: PLOT, SYMBOL, CIRCLE +.br;Called by: * +.le;~PLRLN +.br;Calls: PLOT, SYMBOL +.br;Called by: * +.le;~PLT3D +.br;Calls: NXTVU +.br;Called by: *, MVAX3DX, CVAX3DX +.le;~PLT3DH +.br;Calls: PLOT +.br;Called by: *, SYM3DH, AXIS3DH, CUBE, T3DH, TRIG3DH, CNTOUR, HIST3D +.le;~POLARMAP +.br;Calls: PLOT +.br;Called by: * +.le;~POLY1INT +.br;Calls: (none) +.br;Called by: CENCELPLT, CNCELPLT3D +.le;~PPEN +.br;Calls: PPLOTP +.br;Called by: *, NEWPEN +.le;~PPLOT +.br;Calls: PPLOTP, IPCLIP, CLPIT +.br;Called by: *, PLOT +.le;~PPLOTP +.br;Calls: (none) +.br;Called by: NEWMSK, PPEN, PPLOT, PPLOTS +.le;~PPLOTS +.br;Calls: PPLOTP +.br;Called by: FRAME +.le;~PRESPL +.br;Calls: PPLOTP +.br;Called by: *, RESPL +.le;~PRETRP +.br;Calls: SPISET, SPIFUN +.br;Called by: LINSEQ +.le;~PSAVPL +.br;Calls: (none) +.br;Called by: *, SAVPL +.le;~PSUBPRO +.br;Calls: SUBPROC +.br;Called by: * +.le;~PXPCGT +.br;Calls: (none) +.br;Called by: SYMBOL, SYM3D, SYM3DH +.le;~RECT +.br;Calls: PLOT +.br;Called by: * +.le;~RESPL +.br;Calls: PRESPL, RRESPL, VRESPL, WHERE, PLOT +.br;Called by: * +.le;~RFACTOR +.br;Calls: (none) +.br;Called by: *, FACTOR +.le;~RAMOPEN +.br;Calls: SYS$TRANSLOG, SYS$ALLOC, SYS$DALLOC, SYS$DASSGN, SYS$ASSIGN, SYS$QIOW +.br;Called by: RPLOTS +.le;~RAMCLOSE +.br;Calls: SYS$DALLOC, SYS$DASSGN +.br;Called by: PLOTRM +.le;~RAMOUT +.br;Calls: SYS$QIOW +.br;Called by: RMSTART, RMWIND, RMPLOT, RMCLEAR, RMTEXTURE, RMZOOM, +RMPAN, RMSETCUR, RMTEXT, RMFNTSIZE +.le;~RAMOUTIN +.br;Calls: SYS$QIOW +.br;Called by: RMREADCURSOR, RMREADCOL, RMREADBYTE, RMREADWORD +.le;~REFDIS (entry of RAMCLOSE) +.br;Calls: (none) +.br;Called by: * +.le;~RMCLEAR +.br;Calls: RAMOUT +.br;Called by: PLOTRM +.le;~RMDIR +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMFNTSIZE +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMPAN +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMPLOT +.br;Calls: RAMOUT +.br;Called by: PLOTRM +.le;~RAMOUTIN +.br;Calls: SYS$QIOW +.br;Called by: RMREADBYTE, RMREADCOL, RMREADWORD +.le;~RMREADBYTE +.br;Calls: RAMOUTIN +.br;Called by: * +.le;~RMREADCOL +.br;Calls: RAMOUTIN +.br;Called by: * +.le;~RMREADCURSOR +.br;Calls: RAMOUTIN +.br;Called by: * +.le;~RMREADWORD +.br;Calls: RAMOUTIN +.br;Called by: * +.le;~RMSETCUR +.br;Calls: RAMOUT +.br;Called by: CURBAND, CURRECT, CURMOTION, CURLOCATE +.le;~RMRESET +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMSTART +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMTEXT +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMTEXTURE +.br;Calls: RAMOUT +.br;Called by: RMPEN, RPLOTS, FIXRM0, RRESPL +.le;~RMWIND +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMWRITEBYTE +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMWRITECOL +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMWRITEWORD +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMZOOM +.br;Calls: RAMOUT +.br;Called by: * +.le;~RMPEN +.br;Calls: RMTEXTURE +.br;Called by: NEWPEN +.le;~ROTEM +.br;Calls: (none) +.br;Called by: AXIS3D, INIT3D, PLOT3D, SYM3D, SYM3DH +.le;~RPLOTS +.br;Calls: PLOTRM, RMTEXTURE +.br;Called by: FRAME +.le;~RRESPL +.br;Calls: RMTEXTURE +.br;Called by: *, RESPL +.le;~RSAVPL +.br;Calls: (none) +.br;Called by: *, SAVPL +.le;~RTERM +.br;Calls: RMCLEAR, RAMCLOSE, RAMOPEN +.br;Called by: * +.le;~RVXPT3D +.br;Calls: (none) +.br;Called by: CNCELPLT3D +.le;~SAVPL +.br;Calls: PSAVPL, RSAVPL, VSAVPL, WHERE, PLOT +.br;Called by: * +.le;~SCALE +.br;Calls: (none) +.br;Called by: * +.le;~SCALG +.br;Calls: (none) +.br;Called by: * +.le;~SCATPL +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, LGAXS, +AXIS, PLOT, SYMBOL, PLOTND +.br;Called by: * +.le;~SEGCODE +.br;Calls: (none) +.br;Called by: CNCELPLT, CNCELPLT3D +.le;~SEISPL +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, LGAXS, +AXIS, PLOT, NEWPEN, SYMBOL, PLOTND +.br;Called by: * +.le;~SFPLOT +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, LGAXS, +AXIS, PLOT, NEWPEN, SYMBOL, PLOTND +.br;Called by: * +.le;~SHADE +.br;Calls: PLOT, NEWPEN +.br;Called by: *, JPLTAG +.le;~SKETCH +.br;Calls: LINHID +.br;Called by: * +.le;~SMOOTHC +.br;Calls: CHLSKYS +.br;Called by: LINSEQ +.le;~SPIDER +.br;Calls: (none) +.br;Called by: ARCPLT +.le;~SPIFUN +.br;Calls: (none) +.br;Called by: ARCPLT, PRETRP +.le;~SPISET +.br;Calls: (none) +.br;Called by: LINSEQ, PRETRP +.le;~SPLOTS +.br;Calls: SPLOTSX +.br;Called by: * +.le;~SPLOTSX +.br;Calls: FRAME, CTERM, NEWPAGE, SCALG, SCALE, LGRID, GRID, +LGAXS, AXIS2, PLOT, SYMBOL, PLOTND +.br;Called by: *, SPLOTS +.le;~SPRECT1 +.br;Calls: (none) +.br;Called by: EARTH3D +.le;~STAT3D +.br;Calls: (none) +.br;Called by: LINHID +.le;~STAT3D2 +.br;Calls: (none) +.br;Called by: LINHID +.le;~SUBPROC +.br;Calls: LIB$SPAWN, LIB$SIGNAL +.br;Called by: PSUBPRO +.le;~SYM3D +.br;Calls: PLOT3D, ROTEM, MATMUL4, MTV4, PXPCGT +.br;Called by: *, AXIS3D, NUM3D +.le;~SYM3DH +.br;Calls: MTV4, PLT3DH, PXPCGT, ROTEM, MATMUL4 +.br;Called by: *, NUM3DH, AXIS3DH +.le;~SYMBOL +.br;Calls: PLOT, PXPCGT +.br;Called by: *, AXIS, AXIS2, AXIS3, CNDRAW, DASHL, LGAXS, LGLIN, LINE, +NUMBER, OLDNUM, PLRAX +.le;~SYMS +.br;Calls: PLOT +.br;Called by: * +.le;~SYMSS +.br;Calls: PLOT, LINSEQ +.br;Called by: * +.le;~TR3DH +.br;Calls: SCALE, FRAME, CTERM, AXIS3DH, PLT3DH, SKETCH, PLOT, +PLOTND, INIT3DH +.br;Called by: * +.le;~TRCELPLT3D +.br;Calls: RVXPT3D, PLOT, ISEGCODE +.br;Called by: CNT3DX +.le;~TRIANGC +.br;Calls: MIDC +.br;Called by: *, CNTLN, TRIG3DH +.le;~TRIG3DH +.br;Calls: SCALE, FRAME, CTERM, AXIS3DH, PLT3DH, SKETCH, PLOT, +PLOTND, INIT3DH +.br;Called by: * +.le;~VAX3D +.br;Calls: VAX3DX +.br;Called by: *, VAX5D +.le;~VAX3DX +.br;Calls: SCALE, FRAME, CTERM, VXPT3D, AXIS2, AXIS, PLOT, INTERSECT, +PLOTND +.br;Called by: *, VAX3D +.le;~VAX5D +.br;Calls: SCALE, FRAME, CTERM, RTERM, SYMBOL, NUMBER, VAX3D, PLOT, +FACTOR, PLOTND +.br;Called by: * +.le;~VCPY +.br;Calls: (none) +.br;Called by: PLOT3D +.le;~VFACTOR +.br;Calls: (none) +.br;Called by: *, FACTOR +.le;~VPEN +.br;Calls: NEWVPEM +.br;Called by: NEWPEN +.le;~VPLOTS +.br;Calls: PLOTVT, NEWVPEN, NEWVCOL +.br;Called by: FRAME +.le;~VRESPL (entry of VSAVPL) +.br;Calls: NEWVPEN, PLOTVT +.br;Called by: *, SAVPL +.le;~VSAVPL +.br;Calls: (none) +.br;Called by: *, SAVPL +.le;~VSRT1 +.br;Calls: (none) +.br;Called by: LINHID +.le;~VSRTR +.br;Calls: (none) +.br;Called by: LINHID +.le;~VTPLOT +.br;Calls: (none) +.br;Called by: CURRECT, PLOTVT +.le;~VXPT3D +.br;Calls: (none) +.br;Called by: CNT3DX, VAX3DX, MESH3DX +.le;~WHERE +.br;Calls: WHEREVT, WHERERM, WHEREPR +.br;Called by: *, SAVEPL, RESPL +.le;~WHERE3D +.br;Calls: (none) +.br;Called by: * +.le;~WHERE3H +.br;Calls: (none) +.br;Called by: * +.le;~WHEREPR +.br;Calls: (none) +.br;Called by: *, WHERE +.le;~WHERERM +.br;Calls: (none) +.br;Called by: *, WHERE +.le;~WHEREVT +.br;Calls: (none) +.br;Called by: *, WHERE +.le;~XFRM3D +.br;Calls: (none) +.br;Called by: * +.le;~XVMUL3D +.br;Calls: MTV4 +.br;Called by: AXIS3D +.els + +.pg +.hl 1 Common Block Names +.p +The following is a list of all the named common block used internally +by the LONGLIB graphics library. Those marked with an asterick are documented +under the first listed routine. +and are designed to be accessable to the user. Those +unmarked are for internal use only and may change at later revisions. + +.ls1 +.dle,,'.' +.le;~VT100 -- Accessed by: BITCURSOR, CURMOTION, CURLOCATE, CURBAND, CURRECT, +GETCURSOR, FRAME, VTPLOTS, VTPLOT, CTERM, PLOTVT, WHEREVT, +VFACTOR, FACTOR, FIXVT0, WHERE, VSAVPL, VRESPL, NEWVPEN, NEWVCOL +.le;~RMTEK -- Accessed by: CURMOTION, CURLOCATE, CURBAND, CURRECT, FRAME, +PLOTRM, RPLOTS, IRMCHAN, WHERERM, RFACTOR, RMPEN, FACTOR, +FIXRM0, WHERE, RSAVPL, RRESPL +.le;~PXPCOM -- Accessed by: FRAME, PPLOT, WHEREPR, PFACTOR, +PPLOTS, PPEN, FACTOR, FIXPR0, WHERE, PSAVPL, PRESPL +.le;~RAMTEKIO -- Accessed by: RAMOPEN, RAMOUT, RAMOUTIN, RMCLEAR +.le;~CHIDE -- Accessed by: INIT3DH, PLT3DH, WHERE3H, SKETCH, LINHID +.le;~HEDG -- Accessed by: LINHID, CHECK3D +.le;~GO3 -- Accessed by: LCOEF, LINHID, STAT3D, STAT3D2, CHECK3D, ISOL3D +.le;~GO * -- Accessed by: LINHID +.le;~DAVE -- Accessed by: CHECK3D, ISOL3D, STAT3D2 +.le;~LSTPLT -- Accessed by: PLOT, WHERE +.le;~PLT3B * -- Accessed by: PLT3D, HLT3D, CNDRAW, MVAX3DX, CVAX3DX +.le;~LAST3D -- Accessed by: DRAW3D, WHERE3D +.le;~CPLOT3D -- Accessed by: INIT3D, PLOT3D +.le;~CGLPLOT * -- Accessed by: GLPLOT +.le;~CPLOTLG * -- Accessed by: PLOTLG +.le;~CPHIST * -- Accessed by: PHIST +.le;~CPLOTSC * -- Accessed by: PLOTSC +.le;~CPLOTSC2 * -- Accessed by: PLOTSC2 +.le;~LOCATE -- Accessed by: VXPT3D, VAX3DX, CNT3DX, RVXPT3D, MESH3DX +.le;~CPLOTLG * -- Accessed by: PLOTLG +.le;~CPLOTLG2 * -- Accessed by: PLOTLG2 +.le;~CPLOTLGL * -- Accessed by: PLOTLGL +.le;~CPLOTLGX * -- Accessed by: PLOTLGX +.le;~CCNTRPLT * -- Accessed by: CNTRPLT, CNTLN, LCNTR +.le;~CSPLOTS * -- Accessed by: SPLOTS +.le;~CSPLOTSX * -- Accessed by: SPLOTSX, SPLOTS +.le;~CSEISPL * -- Accessed by: SEISPL +.le;~CSCATPL * -- Accessed by: SCATPL +.le;~TT_IO -- Accessed by: INXTCHR, ICHRCHK +.le;~ASTC -- Accessed by: ASTINTER, ENAST, ASTEXIT, ENABLEAST, PLOT +.els + + + +.chapter Plot Examples and Plotting Symbols +.p +Shown in the sections that follow are outputs (and listings) of various +programs included with LONGLIB. This include programs which produce +plotting symbols and line types/widths. + +.hl1 Plotting Symbols and Character Fonts Examples +.x SYMBOLS +.x SYMS +.x SYMSS +.p +The program ~SYMBOLS was used to create a table of the +available plotting symbols and character fonts available using the +subroutines SYMBOLS, SYMS and SYMSS. These tables are shown on the +succeeding pages. A listing of SYMBOLS follows the tables. + +.pg +.hl1 Line Type/Width Examples +.x line type +.x line width +.x color +.p +The program ~LINETYPE was to create a table of the available line types, +widths, and colors for each plotting device. These are shown on the +succeding pages. A listing of LINETYPE follows the tables. + +.pg +.hl1 MASTER Routine Output Examples +.p +The program ~PLOTTESTS was used to obtain examples of some of the MASTER +routine outputs. A listing follows the output pages. + +.pg +.hl1 3-d Routine Output Examples +.p +EXAMP3D and EXAMP3DH demonstrate the 3d routines while WORLD demonstrates +the some of the 3d map capabilities. Output and listings follow. + +.pg +.hl1 Cursor Routine Test Program +.p +A listing of the program ~CURTEST follows. The program can be used +to test the operation of the graphics input cursor routines. Only a listing +is given. + +.pg +.hl1 REF Output Example +.p +This section describes an example of how the Ramtek REF subpackage can +be used to produce a grey scale "image". An example of the output image +produced by first running the example program REFTEST, outputing the result to +a REF file, then using the program ~REFLAS to produce a grey scale +image on the ~QMS laser printer. A listing of the ~REFTEST program +is also provided. Note that REFTEST must be linked to the REF version +of the library (LONGLIBR) rather than the "normal" version. Also +note that REFTEST, when linked to the "normal" LONGLIB, will produce +a color image on the Ramtek display. + +.! FOR VAX VMS 3.x REMOVE THE "!" FROM THE NEXT LINE +.!do index +.chapter INDEX +.pg diff --git a/samples/RUNOFF/mcp_help.rnh b/samples/RUNOFF/mcp_help.rnh new file mode 100644 index 00000000..3e74f780 --- /dev/null +++ b/samples/RUNOFF/mcp_help.rnh @@ -0,0 +1,1773 @@ +.!++ +.! +.! Copyright (c) 2008, Matthew Madison. +.! Copyright (c) 2012, Endless Software Solutions. +.! +.! All rights reserved. +.! +.! Redistribution and use in source and binary forms, with or without +.! modification, are permitted provided that the following conditions +.! are met: +.! +.! * Redistributions of source code must retain the above +.! copyright notice, this list of conditions and the following +.! disclaimer. +.! * Redistributions in binary form must reproduce the above +.! copyright notice, this list of conditions and the following +.! disclaimer in the documentation and/or other materials provided +.! with the distribution. +.! * Neither the name of the copyright owner nor the names of any +.! other contributors may be used to endorse or promote products +.! derived from this software without specific prior written +.! permission. +.! +.! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.! "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.! LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.! A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.! OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.! SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.! LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.! DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.! THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.! (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.! OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.! +.! NAME: MCP_HELP.RNH +.! +.! ABSTRACT: MCP help file. +.! +.! FACILITY: MX Control Program +.! +.! DESCRIPTION: +.! +.! This is the RUNOFF source for the help library for MCP. +.! To create the help library, use the following commands: +.! +.! $ RUNOFF MCP_HELP.RNH +.! $ LIB/CREATE/HELP MCP_HELPLIB MCP_HELP +.! +.! MODIFICATION HISTORY: +.! +.! 30-SEP-1990 V1.3 Madison Update for MX V1.3. +.! 04-OCT-1990 V1.3-1 Madison Further file server-related changes. +.! 05-DEC-1990 V2.1 Madison Add SET JNET. +.! 10-DEC-1990 V2.1-1 Madison New qualifiers for DEFINE LIST. +.! 12-DEC-1990 V2.1-2 Madison One more DEFINE LIST qualifier. +.! 11-FEB-1991 V2.2 Madison Various new command options. +.! 27-MAR-1991 V2.2-1 Madison Mention SHUT SMTP. +.! 07-NOV-1991 T2.4 Madison New commands. +.! 11-NOV-1991 T2.4-1 Madison Forgot QUEUE SHOW. SET JNET/LENIENT. REVIEW. +.! 05-DEC-1991 V3.0 Madison SHOW VERSION. +.! 03-JAN-1992 V3.0-1 Madison DEFINE LIST/REPLY_TO wasn't correct. +.! 14-FEB-1992 V3.1 Madison SET JNET/USERNAME. +.! 05-MAR-1992 V3.1-1 Madison SHUTDOWN, RESET changes. STATUS. +.! 13-MAR-1992 V3.1-2 Madison Forgot SET X25_SMTP. +.! 15-FEB-1993 V3.2 Goatley DEFINE LIST/FILE changes, fix typos. +.! 19-MAR-1993 V3.3 Goatley DEFINE LIST/PRIVATE, QUEUE SHOW/BRIEF. +.! 16-APR-1993 V3.3-1 Goatley SET LOCAL/MULTIPLE_FROM. +.! 7-AUG-1993 V3.4 Goatley Fix missing double "_" in qualifiers. +.! 29-AUG-1993 V3.4-1 Goatley SET LOCAL/MM_DELIVER. +.! 17-DEC-1993 V3.4-2 Goatley DEFINE LIST/STRIP=OTHER, SET LOCAL/CC. +.! 10-JAN-1994 V3.4-3 Goatley DEF LIST/CASE, - Q RECLAIM, + Q SYNCH. +.! 16-FEB-1994 V4.0 Goatley QUEUE CREATE, QUEUE EXTEND. +.! 10-DEC-1995 V4.2 Goatley /NODE, /DIGEST. +.! 7-OCT-1996 V4.3 Goatley SPAWN. +.! 14-JAN-1997 V4.4 Madison SET MLF. +.! 17-FEB-1997 V4.5 Madison DEFINE/MODIFY/REMOVE/SHOW REJECTION. +.! 02-APR-1997 V4.6 Madison LOCAL_DOMAIN, SMTP/RELAY, LIST/RECIP/HIDE. +.! 13-APR-1997 V4.6-1 Madison SET MLF/DELAY_DAYS. +.! 2-MAY-1997 V4.7 Goatley Added DEF LIST/XHEADERS, /LIST_HEADERS, /HOSTNAME +.! 5-MAY-1997 V4.7-1 Goatley Added DEF LIST/SETTINGS. +.! 4-AUG-1997 V4.7-2 Goatley Add REJECTION to SHOW. +.! 8-SEP-1997 V4.7-2 Goatley Add multiple addrs to DEFINE ALIAS. +.! 3-OCT-1997 V4.7-3 Goatley Add /CC_POST_ERRORS, /SUBJECT_PREFIX. +.! 05-OCT-1997 V4.7-4 Madison Removed REJECTION due to inclusion of REJMAN utility; +.! added SET SMTP/VALIDATE_SENDER_DOMAIN. +.! 29-OCT-1997 V4.7-5 Goatley Fix /LIST_HEADERS description. +.! 21-NOV-1997 V4.7-6 Goatley Add /QP_DECODE to SET LOCAL. +.! 19-APR-1998 V4.7-7 Madison Add SET LOCAL/DISABLE_EXQUOTA; remove /MM_DELIVER. +.! 24-APR-1998 V4.8 Madison Add SET SMTP/RBL, SET ROUTER/ACC. +.! 15-JUN-1998 V4.9 Madison Add INSIDE_NETWORK_ADDRESS settings. +.! 26-JUN-1998 V4.9-1 Madison Add /RELAY_ALLOWED to DEFINE INSIDE. +.! 03-AUG-1998 V4.9-2 Madison REMOVE INSIDE_NETWORK_ADDRESS was missing. +.! 15-AUG-1998 V4.9-3 Madison Document /RBL_CHECK=domain-name; add MODIFY INSIDE. +.! 27-AUG-1998 V4.9-4 Madison New HOLDING_QUEUE paths. +.! 30-JAN-2000 V4.9-5 Madison More holding queues. +.! 25-NOV-2000 V4.9-6 Madison list ignore flags; remove Jnet support; set local/long. +.! 22-DEC-2000 V4.10 Madison SHOW LIST/BRIEF. +.! 13-JAN-2001 V4.11 Madison QUEUE SELECT. +.! 14-FEB-2002 V4.12 Madison SET SMTP/[NO]PERCENT, regex, QUEUE DUMP. +.! 03-Feb-2008 V5.0 Madison Cleanup of obsolete keywords. +.! 12-Mar-2012 V5.1 Sneddon SET SMTP/[NO]TLS. +.!-- +.P0 +.AP +.LM1 +.RM70 +.I-1 +1 @ + @ + You can create MCP command files and execute them with the "@" +(input-indirection) function. +.NJ + Format: + @ file-spec +.J + You can use the command SHOW/OUTPUT=file/COMMAND ALL to create a command +file out of the current MX configuration, edit it outside of MCP, and then +load in the commands with @file to create a new MX configuration. +.I-1 +1 ADD + See the help text for ADD USER. +.I-1 +2 USER + ADD USER adds a username and password to the authentication database +used by the SMTP server. +.NJ + Format: + ADD USER username +.J + A username may be up to 16 characters in length, and are case-sensitive. +Use quotation marks to specify a username that contains lower-case letters. +.I-1 +3 Qualifiers +.I-1 +/PASSWORD + /PASSWORD=password-text + Specifies a password for this username. The password may be up to 64 +characters in length, and may contain any characters. To specify lower case +letters or blanks in the password, surround it with quotation marks. + If this qualifier is omitted, a default password, "PASSWORD", is assigned +to the username. +.I-1 +1 CREATE + See the help text for CREATE USER__DATABASE__FILE. +.I-1 +2 USER__DATABASE__FILE + The CREATE USER__DATABASE_FILE command creates an empty file for the SMTP +authentication database. This database is used in conjunction with the +CRAM-MD5 authentication extension (see SET SMTP/AUTHENTICATION). +.NJ + Format: + CREATE USER__DATABASE__FILE [file-spec] +.J + If a file-spec is omitted, a new (empty) version of MX__DIR:MX__USERAUTH__DB.DAT, the +standard location for the SMTP authentication database, is created. In general, +this command is used only once, to create the initial database for population using +the ADD USER command. +.I-1 +1 DEFINE + The DEFINE command is used to add new alias and path entries, +new rewrite-rules, mailing lists, and file servers, as well as identify +privileged users. +.I-1 +2 ALIAS + DEFINE ALIAS adds a new alias definition to the alias list. The +new alias always goes at the end of the list. +.NJ + Format: + DEFINE ALIAS alias real-address[,...] +.J + Real-address must be a full address, not just a username. Alias +matching is case-insensitive. If case is important in the substitution, +place quotation marks around real-address. + The maximum size of the real-address (including all addresses, if multiple +real-addresses are specified) is 255 characters. +.I-1 +2 FILE__SERVER + DEFINE FILE__SERVER is used to create a file server. +.NJ + Format: + DEFINE FILE__SERVER name +.J + The name given must be 32 characters or less in length, and should not +be the same as an existing username or mailing list. +.I-1 +3 Qualifiers +.I-1 +/BEGIN__SEND__PERIOD + /BEGIN__SEND__PERIOD=hh:mm + This qualifier identifies the hour of the day when the off-peak sending +period begins. It is only meaningful when a delay threshold is specified. +The default send period begins at 17:00. +.I-1 +/DELAY__THRESHOLD + /DELAY__THRESHOLD=size + /NODELAY__THRESHOLD + This qualifier identifies the largest size, in bytes, that a file service +response can be to be sent during prime time. Responses exceeding that size +are delayed until the off-peak sending period. /NODELAY__THRESHOLD lets +responses of any size be sent at any time. Omitting "size" sets a default +size of 16,384 bytes. +.I-1 +/DESCRIPTION + /DESCRIPTION=text + /NODESCRIPTION (default) + The /DESCRIPTION qualifier defines a brief description for the file server. +This description is added to the file server address in the +X-FileServer header on outgoing file server messages. +.I-1 +/END__SEND__PERIOD + /END__SEND__PERIOD=hh:mm + This qualifier identifies the hour of the day when the off-peak sending +period ends. It is only meaningful when a delay threshold is specified. +The default send period ends at 09:00. +.I-1 +/HOST__LIMIT + /[NO]HOST__LIMIT=n + This qualifier specifies a daily per-host byte count limit on requests +to the file server. If a requested file's size plus the current byte +count exceeds the daily limit, the file is not sent. This limit is +kept on a per-host basis. +.I-1 +/MAILING__LIST + /[NO]MAILING__LIST=list-name + This qualifier specifies that only those users who subscribe to the +specified mailing list (which must be a list on the local system) may +have access to the file server. +.I-1 +/MANAGER + /MANAGER=address + The /MANAGER qualifier identifies the address to which file service management +requests are forwarded (when sent to user {file-server-username}-Mgr). +If omitted, Postmaster on the local system is used. +.I-1 +/ROOT + /ROOT=root-spec + The /ROOT qualifier identifies the root for the file server. Root-spec +must be a rooted logical name or a device and root directory specification. +.I-1 +/SERVER__LIMIT + /[NO]SERVER__LIMIT=n + This qualifier specifies a daily server byte count limit on requests +to the file server. If a requested file's size plus the current byte +count exceeds the daily limit, the file is not sent. This limit applies +to all requests to the server. +.I-1 +/USER__LIMIT + /[NO]USER__LIMIT=n + This qualifier specifies a daily per-user byte count limit on requests +to the file server. If a requested file's size plus the current byte +count exceeds the daily limit, the file is not sent. This limit is +kept on a per-destination-user basis. +.I-1 +2 INSIDE__NETWORK__ADDRESS + The DEFINE INSIDE__NETWORK__ADDRESS command establishes an IP address or +network that is in one of the local domains, is permitted to use your SMTP +server as a relay, or to reject a particular host or network from being +considered as part of your local domain. +.NJ + Format: + DEFINE INSIDE__NETWORK__ADDRESS ip-address +.J + Inside network address definitions are only used with the SMTP server +is set to disallow relays with SET SMTP/NORELAY__ALLOWED. When at least +one inside address is defined, messages coming in via SMTP are allowed +to have recipients outside of the local domain(s) only if the sending +system's IP address is on the inside network address list. + By default, the SMTP server will still reject a message that contains +non-local addresses for both the sender and the receiver, even from +hosts on the inside network address list. You can ease that restriction +with the /RELAY__ALLOWED qualifier. +.I-1 +3 ip-address + IP address, in dotted-decimal form, of the host or network. If this is +a network address, you must also specify the /NETMASK qualifier. +.I-1 +3 Qualifiers +.I-1 +/NETMASK + /NETMASK=ip-netmask + Specifies the network mask to be applied to the address, in dotted-decimal +form. The default is 255.255.255.255, which indicates that the IP address +is for a host, not a network. +.I-1 +/REJECT + /REJECT + /NOREJECT (default) + Indicates whether relay is to be rejected from the specified +host or network. This qualifier can be used to reject SMTP relay +from particular hosts or subnetworks that are below a parent network +that is already on the inside network address list. +.I-1 +/RELAY__ALLOWED + /RELAY__ALLOWED + /NORELAY__ALLOWED (default) + Indicates that the host(s) should be allowed full relay permission; that +is, messages sent from the host(s) are allowed to contain non-local addresses +for both sender and receiver. + This qualifier is useful when your system is acting as a central mail hub, +and there are hosts on your local network that automatically forward messages +for their local users to hosts outside your domain via an alias. When such +messages are sent back to your system (as the mail hub), they will contain +non-local addresses for both the sender and the recipient. +.I-1 +2 LIST + The DEFINE LIST command is used to create a mailing list. +.NJ + Format: + DEFINE LIST listname +.J + DEFINE LIST creates three addresses on the local system: the mailing list +itself, a control address (listname-REQUEST), and a sender address +(listname-SENDER). +.I-1 +3 Qualifiers +.I-1 +/ADD__MESSAGE + /ADD__MESSAGE=fspec + /NOADD__MESSAGE (default) + The /ADD__MESSAGE qualifier is used to specify a file whose contents +are to be sent when a user subscribes to the list. If you omit +the device and directory parts of the file specification, they default +to MX__MLIST__DIR. If you omit the file type, it defaults to TXT. + If no add message is specified, the system default add message, contained +in file MX__MLIST__DIR:MLIST__ADD__MESSAGE.TXT, is used. +.I-1 +/ARCHIVE + /ARCHIVE=fspec + /NOARCHIVE (default) + The /ARCHIVE qualifier is used to establish a file into which mailing list +messages are archived. You may specify just parts of a file specification, +to allow the following defaults to take effect: +.NJ + Device, directory: MX__MLIST__DIR: + File name: same as mailing list name + File type: yyyy-mm (four-digit year, a hyphen, two-digit month) +.J + This setup allows for easy monthly disposal of the mailing list archives. +.I-1 +/CASE__SENSITIVE + /CASE__SENSITIVE (default) + /NOCASE__SENSITIVE + Enables or disables case-sensitivity with regard to mailing list +subscribers. By default, MX treats the left-hand side of subscriber +addresses in a case-sensitive manner with regard to SIGNOFF and SET +commands. If a list is defined /NOCASE__SENSITIVE, then the case of +subscriber addresses will be ignored. +.I-1 +/CC__POST__ERRORS + /CC__POST__ERRORS + /NOCC__POST__ERRORS (default) + Enables or disables copying mailing post failure messages to the /ERRORS__TO +address. By default, if a message cannot be forwarded to a list, an error +message is sent back to the sender of the message. If /CC__POST__ERRORS +is set, those error messages are also sent to the /ERRORS__TO address. +This lets the list owner see attempted posts from non-subscribers and other +posting failures. +.I-1 +/CONFIRMATION__MESSAGE + /CONFIRMATION__MESSAGE=fspec + /NOCONFIRMATION__MESSAGE (default) + The /CONFIRMATION__MESSAGE qualifier is used to specify a file whose contents +are to be sent when the mailing list processor requests confirmation of +a subscription request (see DEFINE LIST /REQUEST__CONFIRMATION). If you omit +the device and directory parts of the file specification, they default +to MX__MLIST__DIR. If you omit the file type, it defaults to TXT. + If the NO form is specified, the system default confirmation message, contained +in file MX__MLIST__DIR:MLIST__CONFIRM__MESSAGE.TXT, is used. +.I-1 +/DESCRIPTION + /DESCRIPTION=text + /NODESCRIPTION (default) + The /DESCRIPTION qualifier defines a brief description for the +mailing list. This description is added to the mailing list address in the +X-Listname header on outgoing mailing list messages. +.I-1 +/DIGEST + /DIGEST + /NODIGEST (default) + The /DIGEST qualifier enables or disables the support for digest subscribers +for the given mailing list. +.I-1 +/ERRORS__TO + /ERRORS__TO=address + This qualifier identifies the address that messages sent to the +listname-SENDER sending address (which are usually delivery error messages) +are sent. If omitted, the first owner specified with /OWNER will be +used. +.I-1 +/FORWARD__MESSAGE + /FORWARD__MESSAGE=fspec + /NOFORWARD__MESSAGE (default) + The /FORWARD__MESSAGE qualifier is used to specify a file whose contents +are to be sent when the list is set to no E (enroll) access for WORLD and +a user attempts to subscribe to the list. The message should inform the +user that the subscription request was forwarded to the mailing list's +owner. If you omit the device and +directory parts of the file specification, they default to MX__MLIST__DIR. +If you omit the file type, it defaults to TXT. + If no forward-to-owner message is specified, the system default message, +contained in file MX__MLIST__DIR:MLIST__FORWARD__MESSAGE.TXT, is used. +.I-1 +/HIDE__ERRORS__TO + /HIDE__ERRORS__TO (default) + /NOHIDE__ERRORS__TO + The /HIDE__ERRORS__TO qualifier instructs MLF to hide the error-returns +address in outbound messages to the mailing list, even when the return +address is specified with /ERRORS__TO. When /HIDE__ERRORS__TO is set on +a list, MLF uses the automatically-created owner-{listname} alias as +the envelope FROM and Errors-To address in outbound list messages. +This is the default setting. + If you have set up a special address or alias for receiving mailing +list-related error messages, and the address can be externally visible, +you should specify that address with the /ERRORS__TO qualifier and +specify /NOHIDE__ERRORS__TO to have the address you specify +appear in the envelope FROM and Errors-To headers. +.I-1 +/HOSTNAME + /HOSTNAME=hostname + /NOHOSTNAME (default) + The /HOSTNAME qualifier instructs MLF to use the supplied hostname +for all addresses generated by MLF for the mailing list. The supplied +hostname is used instead of the actual running host's name. + For example, specifying /HOSTNAME="YYZ.COM" will cause all MLF-generated +mailing list addresses to include "@YYZ.COM" instead of the actual host name. +It is assumed that MX has been properly configured to handle mail addressed +using the supplied hostname (i.e., that MX records for YYZ.COM point to +the node running MX, and that it recognizes that YYZ.COM is a LOCAL path, +etc.). +.I-1 +/IGNORE + /IGNORE=(keyword[=value],...) + The /IGNORE qualifier instructs MLF to ignore postings to the mailing list +if they match the specified criteria. The criteria keywords are +MISSING__LIST__ADDRESS and JUNK__MAIL. These keywords are negatable. By default, +no postings are ignored. + Specifying the MISSING__LIST__ADDRESS criterion causes MLF to ignore +postings to the list that do not explicitly include the list's address in either +the To: or CC: header of the message. This keyword does not take a value. + Specifying the JUNK__MAIL criterion causes MLF to ignore postings that +contain the X-Junk-Mail-Rating: header that is inserted by the heuristic +junk-mail filter in the SMTP server. This keyword takes a value: LOW, +MEDIUM, or HIGH, corresponding to the confidence level of the likelihood +that the message is junk mail, as entered in the +X-Junk-Mail-Rating: header by the SMTP server. Only those messages with +the specified or higher rating are ignored; i.e., if MEDIUM is specified +as the keyword value, only those messages with MEDIUM or HIGH ratings are +ignored. + +.I-1 +/LIST__HEADERS + /LIST__HEADERS=(keyword=value[,...]) + /NOLIST__HEADERS (default) + The /LIST__HEADERS qualifier instructs MLF to include or omit special +List-* headers that provide URLs for subscribing to a list, +unsubscribing from a list, and getting help for that list. + There are three valid keywords: SUBSCRIBE, UNSUBSCRIBE, and HELP. +All three accept values that are used in the creation of the actual headers, +which will be added to each message posted to the mailing list. However, +only HELP requires a value. If the value is omitted for SUBSCRIBE and +UNSUBSCRIBE, the proper URLs for those actions will be automatically generated +by MLF. + Clients that support these headers (both X-List-* and List-*) will provide +click buttons to perform the specified actions (usually "mailto" URLs). +.I-1 +/MAXIMUM__MESSAGE__SIZE + /MAXIMUM__MESSAGE__SIZE=size-in-Kbytes + /NOMAXIMUM__MESSAGE__SIZE (default) + Specifies a limit on the size of a message posted to the list, expressed +in kilobytes. Messages with contents (excluding headers) that exceed the +specified limit are rejected and returned to sender. + Specifying zero as the value is identical to specifying /NOMAXIMUM__MESSAGE__SIZE. +.I-1 +/NOTIFY + /NOTIFY=(type,...) + /NONOTIFY (default) + Specifies that the owner(s) of the mailing list should be sent a +notification message for control transactions. Valid type keywords are +ALL (for all transaction types), ADD, REMOVE, REQUEST, and SET. + By default, no owner notifications are sent. +.I-1 +/OWNER + /OWNER=(address[,...]) + The /OWNER qualifier identifies the address(es) of the owner(s) of the +mailing list. Messages coming to the mailing list or the listname-REQUEST +control address will be granted OWNER access to the mailing list. +.I-1 +/PRIVATE + /PRIVATE + /NOPRIVATE (default) + The /PRIVATE qualifier is used prevent a list from being displayed in +response to a LIST command sent to ListServ. The list protection mask +is not affected by this qualifier. +.I-1 +/PROTECTION + /PROTECTION=(class:code[,...]) + This qualifier allows you to grant or deny certain types of access to +various users. The protection code is of the same form as a normal VMS +file protection specification. + "Class" can be one of SYSTEM, OWNER, GROUP, or WORLD. The SYSTEM class +includes only those addresses identified as system users with DEFINE +SYSTEM__USERS. The OWNER class includes only the owners of the mailing list. +The GROUP class consists of the subscribers of the mailing list. The WORLD +class consists of those addresses that are not subscribers of the mailing +list. + "Code" can consist of the letters R,W,E, and D. R (Read or Review) access +allows the user to request a listing of the addresses on the mailing list +with the REVIEW command. W (Write) access allows the user to send a message +to the mailing list. E (Execute) access allows the user to use the automatic +subscription facility to subscribe to the mailing list (meaningful only for +the WORLD class, of course). D (Delete) access allows the user to use the +automatic subscription facility to sign off the mailing list (meaningful only +for the GROUP class). + If E access is denied to WORLD, subscription requests are forwarded to the +mailing list owner(s). If D access is denied to GROUP, signoff requests +are forwarded to the mailing list owner(s). + Note that protection codes are checked just like VMS protection codes, +so that you cannot grant some kind of access to WORLD and exclude that +access from GROUP, SYSTEM, or OWNER. Also, SYSTEM and OWNER classes are +granted CONTROL access implicitly (just as with VMS file protection), which +allows them to add and remove other users from the mailing list. +.I-1 +/RECIPIENT__MAXIMUM + /RECIPIENT__MAXIMUM=DEFAULT (default) + /RECIPEIENT__MAXIMUM=count + /NORECIPIENT__MAXIMUM + The /RECIPIENT__MAXIMUM qualifier controls how the mailing list +processor sets the maximum number of recipients per outbound message +for the list. The default setting is DEFAULT, which causes the +mailing list processor to set the maximum number based on the +SET MLF/RECIPIENT__MAXIMUM setting. You may override the SET MLF +default by specifying a number, or by specifying /NORECIPIENT__MAXIMUM, +which prevents MLF from breaking up long lists of recipients into +smaller chunks for this list. +.I-1 +/REMOVE__MESSAGE + /REMOVE__MESSAGE=fspec + /NOREMOVE__MESSAGE (default) + The /REMOVE__MESSAGE qualifier is used to specify a file whose contents +are to be sent when a user signs off of the list. If you omit +the device and directory parts of the file specification, they default +to MX__MLIST__DIR. If you omit the file type, it defaults to TXT. + If no removal message is specified, the system default removal message, +contained in file MX__MLIST__DIR:MLIST__REMOVE__MESSAGE.TXT, is used. +.I-1 +/REPLY__TO + /REPLY__TO=(kwd[,...]) + Specifies how the mailing list processor should handle Reply-To headers. +Available reply-to types are SENDER and LIST, which may be combined. +The default is +SENDER, which prevents the mailing list processor from modifying the headers. +If LIST is specified, a Reply-To header is added to list messages to re-direct +replies to the mailing list, eliminating any existing Reply-To header in the +original message. If LIST and SENDER are both specified, a Reply-To header +containing both the mailing list address and the original Reply-To address +is added to list messages (using the From address if no Reply-To header +existed in the original message). +.I-1 +/REQUEST__CONFIRMATION + /REQUEST__CONFIRMATION[=INTERVAL=delta-time] + /NOREQUEST__CONFIRMATION (default) + The /REQUEST__CONFIRMATION qualifier is used to specify whether or not +the mailing list processor should request confirmation of a subscription +request from a user being added to a list via the SUBSCRIBE or ADD list +processor command. By default, confirmations are not requested. + You can control the length of time that the mailing list processor will +wait for a subscription request to be confirmed by specifying the INTERVAL +keyword and a VMS delta-time string for its value. If not specified, +the default confirmation interval is 3 days. +.I-1 +/RETURN__ADDRESS + /RETURN__ADDRESS=address + /NORETURN__ADDRESS (default) + The /RETURN__ADDRESS qualifier is used to specify an alternate address +that is to be used as +the Reply-To address when /REPLY__TO=LIST is specified. +This qualifier is most useful when multiple lists should have a common +return address. For example, it can be used to redirect replies to a +"-Digest" list back to the non-digest address. +.I-1 +/SETTINGS + /SETTINGS=(keyword[,...]) + /SETTINGS=DEFAULT (default) + The /SETTINGS qualifier is used to override the default subscriber settings +for a list. The valid keywords are MAIL, REPRO, CONCEAL, DIGEST, POST, and +their "NO" forms. + A special keyword, DEFAULT, can be used to reset the settings +to the MLF default for a mailing list. The default settings for a list +are MAIL, REPRO, NOCONCEAL, NODIGEST, and POST. +.I-1 +/STRIP__HEADERS + /STRIP__HEADERS=(RECEIVED[,OTHER]) + /STRIP__HEADERS=(NORECEIVED,NOOTHER) (default) + The /STRIP__HEADERS qualifier is used to strip certain RFC822 headers from +messages posted to a mailing list. Currently, only the keywords RECEIVED and +OTHER (and NORECEIVED and NOOTHER) are supported. + When /STRIP__HEADERS=RECEIVED is set, the "Received:" headers are stripped from +the incoming message before it is mailed out to the list subscribers, thereby +reducing the total number of "Received:" headers in the final message. This is +especially beneficial to BITNET hosts because there can be a substantial number +of "Received:" headers added to a message that must pass through one or more +Internet/BITNET gateways. + When /STRIP__HEADERS=OTHER is set, all "other" headers are stripped from +the incoming message before it is mailed out. "Other" headers are any headers +not listed under HELP SET LOCAL/HEADERS. This includes return-receipt +headers, X-400 headers, etc. +.I-1 +/SUBJECT__PREFIX + /SUBJECT__PREFIX="string" + /NOSUBJECT__PREFIX (default) + Enables or disables the addition of a prefix to the Subject line of +messages posted to the list. By default, no prefix is added. When +the list is set to /REPLY__TO=(SENDER), a short prefix string may be +supplied to help subscribers recognize mailing list messages. The +given string is bracketed by square brackets ([]) when it is prefixed +to the subject lines. The maximum length for the prefix string is 32 +characters. Prefix strings should be kept short to avoid generating +extremely long subject lines. +.I-1 +/TEXT__ONLY + /TEXT__ONLY + /NOTEXT__ONLY (default) + The /TEXT__ONLY qualifier is used to specify whether or not the +mailing list processor should accept only those messages with plain +text content. By default, any content type is accepted for list postings. +.I-1 +/XHEADERS + /XHEADERS=("string"[,...]) + /NOXHEADERS (default) + The /XHEADERS qualifier can be used to add additional site-specific headers +to mailing list posts. For example, you can use /XHEADERS to add additional +non-standard "X-List-" headers such as "X-List-Archives". The format of the +header string is: "Keyword: text". For example, "Precedence: Bulk", which +is a non-standard header used by some mailers. + Extreme care should be taken when adding additional headers to mailing lists +to ensure that duplicate headers or improperly formatted headers +(those that don't comply with RFC 822) aren't added to mailing list posts. +.I-1 +2 LOCAL__DOMAIN + The DEFINE LOCAL__DOMAIN command adds a domain name or pattern +to the list of recognized "local" domains considered by the SMTP +server when determining relay rejection. +.NJ + Format: + DEFINE LOCAL__DOMAIN domain-name-or-pattern +.J + The LOCAL__DOMAIN list is only used when the SMTP server is set +to reject "relayed" SMTP messages with SET SMTP/NORELAY__ALLOWED. + A "relayed" message is one that originates on a remote system and +is sent to another remote recipient, using your system as an +intermediate relay. + When the SMTP server is set /NORELAY__ALLOWED, it checks the +envelope FROM and TO addresses, and if neither is local, refuses +to deliver the message. By default, any host in your local domain +(based on your TCP/IP host name and your MX host name) is considered +"local". You may use this command to add other hosts or domains +to this list. +.I-1 +3 Parameter + domain-name-or-pattern + Either a fully-qualified domain name of a single host, or a VMS-style +wildcard pattern. Host names in envelope addresses that match the +specified name or pattern will be considered local by the relay +checker. +.I-1 +2 PATH + The DEFINE PATH command is used to map a domain to a delivery path. +.NJ + Format: + DEFINE PATH domain-pat path-name +.J +.I-1 +3 Qualifiers +.I-1 +/ROUTE + /ROUTE=host-name + + Specifies the name of a host through which messages matching the domain +pattern should be routed. +.I-1 +3 domain-pat + This can be a specific domain name or a pattern containing wildcards to +match a domain name. For example: "specific.host.EDU", "*.BITNET". +.I-1 +3 path-name + This is one of DECNET__SMTP, HOLDING__QUEUE=n, LOCAL, SITE, SMTP. +You MUST have at least one LOCAL path defined; other paths will depend on the +network transports you have installed. For the HOLDING__QUEUE path, you must +specify an integer from 1 to 32 for "n". +.I-1 +2 REWRITE__RULE + The DEFINE REWRITE__RULE command establishes an address rewriting rule to +be used by the Router. +.NJ + Format: + DEFINE REWRITE__RULE old-addr new-addr +.J + When the router rewrites an address, it tries each rewrite rule, in the +order you define them, until one matches. It then applies the one rule +to that address. +.I-1 +3 Qualifiers +.I-1 +/REGEX + /REGEX + Specifies use of regular-expression matching and substitution instead +of substitution variables. +.I-1 +3 old-addr + The address-specification to be rewritten. All addresses must conform +to RFC821 and therefore will always contain a leading and closing angle +bracket. To create a substitution variable, surround the variable with +curly braces. Matching is done from right to left. Substitution variables +match all characters. + Example: <{user}@{host}.CSNET> + Substitution variables are not used with regular-expression matching +(when /REGEX is specified); instead, use subexpressions enclosed in +parentheses. +.I-1 +3 new-addr + The resulting address pattern. Substitution variables created in the +old-addr specification can be used here. + Example: <@relay.cs.net:{user}@{host}.CSNET> + When using regular-expression matching, replacements are specified +with a backslash followed by a single digit (1 through 9), representing +the 1st through the 9th matching subexpression. +.I-1 +2 SYSTEM__USERS + The DEFINE SYSTEM__USERS command identifies addresses that the mailing list +processor should treat as SYSTEM-class users for protection purposes. +.NJ + Format: + DEFINE SYSTEM__USERS address[,...] +.I-1 +1 EXIT + The EXIT command leaves MCP. If you were using MCP to edit an existing +MX configuration, a new version of the configuration file is saved before +MCP exits. If the configuration file name is unknown, you are prompted +for a file name before exiting. +.I-1 +1 HELP + The HELP command displays information on MCP commands. +.I-1 +1 MODIFY + The MODIFY command is used to change definitions of mailing lists, aliases, +paths, etc. The following MODIFY commands are supported, and take the same +qualifiers as their DEFINE counterparts (see the help information on DEFINE +for more information): +.NJ + MODIFY ALIAS alias + MODIFY FILE__SERVER fsrv-name + MODIFY INSIDE__NETWORK__ADDRESS ip-address + MODIFY LIST list-name + MODIFY PATH domain-pattern + MODIFY REWRITE__RULE lhs +.J + The MODIFY USER command is documented here. +.I-1 +2 USER + The MODIFY USER command is used to set a new password for a username in the +SMTP authentication database. +.NJ + Format: + MODIFY USER username +.J + Usernames may be up to 16 characters in length, and are case-sensitive. +.I-1 +3 Qualifiers +.I-1 +/PASSWORD + /PASSWORD=password-text + Specifies a password for this username. The password may be up to 64 +characters in length, and may contain any characters. To specify lower case +letters or blanks in the password, surround it with quotation marks. + If this qualifier is omitted, a default password, "PASSWORD", is assigned +to the username. + +.I-1 +1 QUIT + Quits out of MCP without saving the configuration. If you have changed +the configuration, QUIT will ask for confirmation before exiting. +.I-1 +1 REMOVE + The REMOVE command is used to remove an alias, mailing list, path, or +rewrite rule from the configuration. The following REMOVE commands +are supported: +.NJ + REMOVE ALIAS alias + REMOVE FILE__SERVER fsrv-name + REMOVE INSIDE__NETWORK__ADDRESS ip-address + REMOVE LIST listname + REMOVE LOCAL__DOMAIN domain-name-or-pattern + REMOVE PATH domain-spec + REMOVE REWRITE__RULE old-addr +.J + The REMOVE INSIDE__NETWORK__ADDRESS command also takes a qualifier, +/NETMASK. The combination of the IP address and the netmask must +match the combination in the inside address list. + The REMOVE USER command is documented here. +.J + The MODIFY USER command is documented here. +.I-1 +2 USER + The REMOVE USER command removes a username from the +SMTP authentication database. +.NJ + Format: + REMOVE USER username +.J + Usernames may be up to 16 characters in length, and are case-sensitive. +.I-1 +1 QUEUE + The QUEUE suite of commands is used to control the system message queue. +.I-1 +2 CANCEL + Cancels one or more messages. +.NJ + Format: + QUEUE CANCEL [entry-number,...] +.J + If you cancel the main entry for a message, all entries related to that +message will also be cancelled. If no entry numbers are specified, the +entries selected by the last QUEUE SELECT command are cancelled. +.I-1 +3 Qualifiers +.I-1 +/LOG + /LOG + /NOLOG (default) + Displays a log message for each successful operation. +.I-1 +2 COMPRESS + Shrinks the message queue file by creating a new file and renumbering +all the existing entries in the file. +.NJ + Format: + QUEUE COMPRESS/LOG +.J +.I-1 +3 Qualifiers +.I-1 +/MAXIMUM__ENTRIES + /MAXIMUM__ENTRIES=number-of-entries + Specifies the maximum number of queue entries to be allowed. MX will not +allow more entries to be added to the queue than the specified value. +MCP QUEUE EXTEND can be used to increase the number of allowed entries. + The size of the queue file in blocks is equal to the maximum number of +entries, plus 10 blocks plus whatever is added for the disk cluster. +.I-1 +/LOG + /LOG + /NOLOG (default) + Displays a log message for each successful operation. +.I-1 +2 CREATE + Creates a new, empty, MX message queue control file. +.NJ + Format: + QUEUE CREATE [filespec] +.J +.I-1 +3 Parameters + filespec + Name of the queue control file to be created. If omitted, the +default name, MX_FLQ_DIR:MX_SYSTEM_QUEUE.FLQ_CTL, is used. +.I-1 +3 Qualifiers +.I-1 +/MAXIMUM__ENTRIES + /MAXIMUM__ENTRIES=number-of-entries + Specifies the maximum number of queue entries to be allowed for the queue. +The message queue will be extended to allow the specified number of entries. + The size of the queue file in blocks is equal to the maximum number of +entries, plus 10 blocks plus whatever is added for the disk cluster. +.I-1 +2 DUMP + Dumps an enqueued message to a set of files suitable for modifying +recipient addresses and requeuing with MX_SITE_IN. +.NJ + Format: + QUEUE DUMP entry-number +.J +.I-1 +3 Qualifiers +.I-1 +/CANCEL + /CANCEL (default) + /NOCANCEL + By default, MCP cancels the queue entry for the dumped message. +Specify /NOCANCEL to keep the dumped entry in the queue. +.I-1 +/OUTPUT + /OUTPUT=file-spec + Specifies the location for the three output files generated by +this command. By default, the files are written to the current +default directory with the filename for the message text and recipient +files as ENTRY_n and the filename for the command procedure as +REQUEUE_n (where "n" is the entry number). + Do not specify a file type or version in the file specification; +QUEUE DUMP always uses the file types .MSG__TEXT, .RECIPIENTS, and .COM for +the message text, recipient, and command procedure files, respectively. +.I-1 +3 Parameter + entry-number + Queue entry number for the message to be dumped. The queue entry +must be in READY or IN-PROGRESS state. + QUEUE DUMP creates three output files for the message: one +containing the message text, one containing the list of recipients, +and a command procedure for invoking MX_SITE_IN to requeue the +message. +.I-1 +2 EXTEND + Extends the existing message queue file to allow more entries to be in +the queue at any given time. +.NJ + Format: + QUEUE EXTEND +.J +.I-1 +3 Qualifiers +.I-1 +/MAXIMUM__ENTRIES + /MAXIMUM__ENTRIES=number-of-entries + Specifies the maximum number of queue entries to be allowed. MX will not +allow more entries to be added to the queue than the specified value. +MCP QUEUE EXTEND can be used to increase the number of allowed entries. + The size of the queue file in blocks is equal to the maximum number of +entries, plus 10 blocks plus whatever is added for the disk cluster. +.I-1 +2 HOLD + Places one or more queue entries on hold. +.NJ + Format: + QUEUE HOLD [entry-number,...] +.J + This command places the specified queue entry or entries on hold, +so they will not be processed. Use the QUEUE READY command to release +the entries for processing. If no entry numbers are specified, the +entries selected by the last QUEUE SELECT command are held. +.I-1 +2 PURGE + Purges the message queue of all finished and cancelled entries. +.NJ + Format: + QUEUE PURGE +.J + The Router process automatically purges the queue of finished and cancelled +entries, periodically. This command can be used to force an immediate +purge of the queue. +.I-1 +3 Qualifiers +.I-1 +/LOG + /LOG + /NOLOG (default) + Displays a log message for each entry purged from the queue. +.I-1 +2 READY + Readies one or more queue entries for processing. +.NJ + Format: + QUEUE READY [entry-number,...] +.J + This command can be used to ready a destination-specific entry or the main +entry for a message (in which case all previous destination-specific entries +are automatically cancelled). If no entry numbers are specified, the queue +entries selected by the last QUEUE SELECT command are readied. +.I-1 +3 Qualifiers +.I-1 +/AFTER + /AFTER=date-time + Specifies a date and time after which the entry should be processed. If +not specified, the entry is readied for immediate processing. +.I-1 +/FINAL + /FINAL + /NOFINAL (default) + Sets the error count for all recipients associated with this entry +to 32767. This causes the delivery agent to process the entry +only once for each recipient. +.I-1 +/LOG + /LOG + /NOLOG (default) + Displays a log message for each successful operation. +.I-1 +2 SELECT + Selects queue entries. +.NJ + Format: + QUEUE SELECT +.J + This command builds a list of queue entries based on selection +criteria that you specify with qualifiers on the command. Subsequent +QUEUE CANCEL, HOLD, and READY commands will use this selection list +by default if you do not specify entry numbers on those commands. + You can display the selected entries with the QUEUE SHOW/SELECTED +command. +.I-1 +3 Qualifiers +.I-1 +/BEFORE + /BEFORE[=time] + Selects only those entries dated before the specified time. You can +specify time as an absolute time, a combination of absolute and delta +times, or as one of the following keywords: TODAY (default), TOMORROW, +or YESTERDAY. Specify one of the following qualifiers with the /BEFORE +qualifier to indicate the time attribute to be used as the basis for +selection: /CREATED (default), /DELAY, /EXPIRE, or /MODIFIED. +.I-1 +/CREATED + /CREATED + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /CREATED qualifier selects entries based on their +dates of creation. +.I-1 +/DELAY + /DELAY + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /DELAY qualifier selects entries based on their +delay dates. +.I-1 +/DESTINATION__AGENT + /DESTINATION__AGENT=agent + Selects only those entries that are to be or have been processed by the +specified MX agent. Valid keywords are: ROUTER, MLF, LOCAL, SMTP, SITE, +DNSMTP, and HOLDING__QUEUE=n (where n ranges from 1 to 32, +the maximum number of holding queues). HOLD1 through HOLD8 are obsolte, +but still supported for backward compatibility with prior versions of MX. +This qualifier is most useful when used with /BRIEF. +.I-1 +/EXPIRE + /EXPIRE + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /EXPIRE qualifier selects entries based on their +dates of expiration. +.I-1 +/HELD + /HELD + Selects only those entries that are in USER-HOLD or OPER-HOLD state. +.I-1 +/IN__PROGRESS + /IN__PROGRESS + Selects only entries marked as being in-progress (INPROG). +.I-1 +/MODIFIED + /MODIFIED + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /MODIFIED qualifier selects entries based on their +dates of modification. +.I-1 +/ORIGIN__AGENT + /ORIGIN__AGENT=agent + Selects only those entries that were entered into the queue by the +specified MX agent. Valid keywords are: LOCAL, SMTP, SITE, +MAIL, and DNSMTP. +.I-1 +/SINCE + /SINCE[=time] + Selects only those entries dated after the specified time. You can +specify time as an absolute time, a combination of absolute and delta +times, or as one of the following keywords: TODAY (default), TOMORROW, +or YESTERDAY. Specify one of the following qualifiers with the /SINCE +qualifier to indicate the time attribute to be used as the basis for +selection: /CREATED (default), /DELAY, /EXPIRE, or /MODIFIED. +.I-1 +/WAITING + /WAITING + Selects only those entries that are waiting for processing. +.I-1 +2 SHOW + Displays queue entries. +.NJ + Format: + QUEUE SHOW [entry-number,...] +.J + With no qualifiers, QUEUE SHOW gives a brief display for each active +(READY or IN-PROGRESS) queue entry. +.I-1 +3 Qualifiers +.I-1 +/ALL + /ALL + Causes the display of all queue entries, including those that have been +finished or cancelled. +.I-1 +/BEFORE + /BEFORE[=time] + Selects only those entries dated before the specified time. You can +specify time as an absolute time, a combination of absolute and delta +times, or as one of the following keywords: TODAY (default), TOMORROW, +or YESTERDAY. Specify one of the following qualifiers with the /BEFORE +qualifier to indicate the time attribute to be used as the basis for +selection: /CREATED (default), /DELAY, /EXPIRE, or /MODIFIED. +.I-1 +/BRIEF + /BRIEF + Causes a brief display of all queue entries, including those that have +been finished or cancelled. The information displayed +is taken only from the MX queue file and includes the target MX process +for each entry. +.I-1 +/CREATED + /CREATED + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /CREATED qualifier selects entries based on their +dates of creation. +.I-1 +/DATE + /DATE + Causes the creation and modification dates to be displayed for each queue +entry. +.I-1 +/DELAY + /DELAY + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /DELAY qualifier selects entries based on their +delay dates. +.I-1 +/DESTINATION__AGENT + /DESTINATION__AGENT=agent + Selects only those entries that are to be or have been processed by the +specified MX agent. Valid keywords are: ROUTER, MLF, LOCAL, SMTP, SITE, +DNSMTP, and HOLDING__QUEUE=n (where n ranges from 1 to 32, +the maximum number of holding queues). HOLD1 through HOLD8 are obsolte, +but still supported for backward compatibility with prior versions of MX. +This qualifier is most useful when used with /BRIEF. +.I-1 +/EXPIRE + /EXPIRE + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /EXPIRE qualifier selects entries based on their +dates of expiration. +.I-1 +/FULL + /FULL + Provides a more detailed display of each queue entry. +.I-1 +/HELD + /HELD + Selects only those entries that are in USER-HOLD or OPER-HOLD state. +.I-1 +/IN__PROGRESS + /IN__PROGRESS + Displays only entries marked as being in-progress (INPROG). +.I-1 +/MODIFIED + /MODIFIED + Modifies the time value specified with the /BEFORE or the /SINCE +qualifier. The /MODIFIED qualifier selects entries based on their +dates of modification. +.I-1 +/ORIGIN__AGENT + /ORIGIN__AGENT=agent + Selects only those entries that were entered into the queue by the +specified MX agent. Valid keywords are: LOCAL, SMTP, SITE, +MAIL, and DNSMTP. +.I-1 +/OUTPUT + /OUTPUT=file-spec + Directs the output of the command to the specified file. +.I-1 +/SELECTED + /SELECTED + Displays the entries that were selected by the last QUEUE SELECT +command. +.I-1 +/SINCE + /SINCE[=time] + Selects only those entries dated after the specified time. You can +specify time as an absolute time, a combination of absolute and delta +times, or as one of the following keywords: TODAY (default), TOMORROW, +or YESTERDAY. Specify one of the following qualifiers with the /SINCE +qualifier to indicate the time attribute to be used as the basis for +selection: /CREATED (default), /DELAY, /EXPIRE, or /MODIFIED. +.I-1 +/WAITING + /WAITING + Causes only those entries that are waiting for processing to be displayed. +.I-1 +2 STATISTICS + Displays statistics concerning the number of entries in the MX message queue. +.NJ + Format: + QUEUE STATISTICS +.J +.I-1 +2 SYNCHRONIZE + Synchronizes the message queue bitmap with the actual entries in the queue. +.NJ + Format: + QUEUE SYNCHRONIZE +.J +.I-1 +3 Qualifiers +.I-1 +/LOG + /LOG + Displays a log message about the synchronization. +.I-1 +/RESET + /RESET + Resets the "Highest entry used" counter displayed by QUEUE +STATISTICS. By default, the counter is not reset. +.I-1 +1 RESET + Sends a reset signal to one or more MX delivery agent processes, causing +them to reload their configuration information. +.NJ + Format: + RESET [agent,...] +.J + Accepted agent names are: DECNET__SMTP, LOCAL, MLF, ROUTER, SITE, +SMTP, and SMTP__SERVER. +If omitted, all agents are reset. +.I-1 +2 Qualifiers +.I-1 +/ACCOUNTING + /ACCOUNTING + Causes a new accounting file to be opened, for those agents supporting +accounting (DECNET__SMTP, LOCAL, MLF, ROUTER, and SMTP). +No reloading of configuration occurs when RESET/ACCOUNTING is used. +.I-1 +/CLUSTER + /CLUSTER + Causes the reset to affect agents cluster-wide; this is the default +behavior. Use the /NODE qualifier to restrict the reset action to +specific nodes in the cluster. +.I-1 +/NODE + /NODE[=(node[,...])] + Causes the specified agent resets to occur only on the specified nodes. +If no node names are specified, the local node is used by default. +.I-1 +1 REVIEW + Displays the subscribers of a locally-managed mailing list. +.NJ + Format: + REVIEW list-name +.J +.I-1 +2 Qualifier +.I-1 +/OUTPUT + /OUTPUT=file-spec + Directs the output of the REVIEW command to the specified file. +.I-1 +1 SAVE + Saves the current MX configuration to a file. To be used by the Router +and other processing agents, the file must be called MX__CONFIG.MXCFG and +reside in the MX__DIR directory. Alternatively, you can define the system-wide +logical name MX__CONFIG (in exec mode) to point to the real location of the +MX configuration file to be used by the processing agents. +.NJ + Format: + SAVE file-spec +.J +.I-1 +1 SET + The SET command sets flags for use by some of the delivery agents. +.NJ + Format: + SET option +.J +.I-1 +2 DECNET__SMTP + The SET DECNET__SMTP command sets flags for use by the SMTP-over-DECnet +delivery agent. +.NJ + Format: + SET DECNET__SMTP +.I-1 +3 Qualifiers +.I-1 +/ACCOUNTING + /ACCOUNTING + /NOACCOUNTING (default) +.J + Controls whether accounting records are written by the delivery agent. +If enabled, accounting records are written to the file MX__DNSMTP__ACC +(with a default directory of MX__DNSMTP__DIR: and a default type of DAT). +.I-1 +/MAXIMUM__RETRIES + /MAXIMUM__RETRIES=n + Specifies the maximum number of times the DECnet-SMTP agent should +try to deliver a message if the message cannot be delivered (due to +network failure). The default is 96. +.I-1 +/RETRY__INTERVAL + /RETRY__INTERVAL=hh:mm:ss + Specifies the minimum amount of time that should elapse between attempts +to deliver a message. The default is 00:30:00 (30 minutes). +.I-1 +2 LOCAL + The SET LOCAL command sets flags for use by the local delivery agent. +.NJ + Format: + SET LOCAL +.I-1 +3 Qualifiers +.I-1 +/ACCOUNTING + /ACCOUNTING + /NOACCOUNTING (default) +.J + Controls whether accounting records are written by the delivery agent. +If enabled, accounting records are written to the file MX__LOCAL__ACC +(with a default directory of MX__LOCAL__DIR: and a default type of DAT). +.I-1 +/CC__POSTMASTER + /CC__POSTMASTER + /NOCC__POSTMASTER + Specifies whether or not error messages resulting from LOCAL delivery +errors are mailed to the local POSTMASTER, in addition to the original +message sender. +.I-1 +/DISABLE__EXQUOTA + /DISABLE__EXQUOTA[=[NO]FATAL] + /NODISABLE__EXQUOTA + Specifies whether the EXQUOTA privilege should be disabled during +local delivery attempts. By default, EXQUOTA remains enabled during +local message delivery. Specifying /DISABLE__EXQUOTA=FATAL causes messages +that exceed the recipient's diskquota to be returned to sender immediately, +rather than going through normal retry procedures. +.I-1 +/HEADERS + /HEADERS=(TOP:([NO]hdrname[,...]),BOTTOM:([NO]hdrname[,...])) +.J + Controls the placement of message headers in local delivery of messages. +Any or all headers may be placed at the top and/or bottom of the message, +or not added to the message at all. Valid values for hdrname are: +.i+10;ALL +.i+10;BCC +.i+10;CC +.i+10;DATE +.i+10;ENCRYPTED +.i+10;FROM +.i+10;IN__REPLY__TO +.i+10;KEYWORDS +.i+10;MESSAGE__ID +.i+10;OTHER +.i+10;RECEIVED +.i+10;REFERENCES +.i+10;REPLY__TO +.i+10;RESENT__BCC +.i+10;RESENT__CC +.i+10;RESENT__DATE +.i+10;RESENT__FROM +.i+10;RESENT__MESSAGE__ID +.i+10;RESENT__REPLY__TO +.i+10;RESENT__SENDER +.i+10;RESENT__TO +.i+10;RETURN__PATH +.i+10;SENDER +.i+10;SUBJECT +.i+10;TO + The hdrname keywords may be negated. ALL specifies all headers; +NOALL specifies no headers. OTHER specifies all headers with a header +name not matching one of the other keywords. +.I-1 +/LONG__LINES + /LONG__LINES + /NOLONG__LINES (default) + Specifies that lines exceeding the MAIL-11 255 character maximum +should not be wrapped during delivery to what appears to be a +local user. This setting is disabled by default, so lines exceeding +the maximum length get wrapped at the nearest whitespace character +to the limit (if there are any). Enabling this +setting could cause mail delivery via VMS MAIL's DECnet support to +fail when MX cannot determine that a recipient is a DECnet +address. +.I-1 +/MAXIMUM__RETRIES + /MAXIMUM__RETRIES=n + Specifies the maximum number of times the local delivery agent should +try to deliver a message if the message cannot be delivered (due to +DECnet outage or locked mail file). The default is 96. +.I-1 +/MULTIPLE__FROM + /MULTIPLE__FROM (default) + /NOMULTIPLE__FROM + Controls whether or not the VMS Mail ``From:'' line on incoming +messages can contain multiple return addresses. By default, if an +RFC822 From: or Reply-To: line contains more than one address, as many +of those addresses as will fit are included on the VMS Mail ``From:'' +line (up to 255 characters). Specifying /NOMULTIPLE__FROM limits the +``From:'' line to a single address. +.I-1 +/OMIT__RESENT__HEADERS + /OMIT__RESENT_HEADERS + /NOOMIT__RESENT_HEADERS (default) + Specifies that MX forwarding using VMS Mail SET FORWARD should +omit the Resent- headers MX normally uses to detect forwarding loops. +This setting is disabled by default, and should only be enabled if +users' mail clients have trouble interpreting Resent- headers. +.I-1 +/QP__DECODE + /QP__DECODE + /NOQP__DECODE + Specifies whether or not incoming MIME quoted-printable messages are +automatically decoded by MX Local before delivery through VMS Mail. By +default, such messages are decoded. If your users read their mail via +POP or IMAP, you might want to disable the decoding to let the users' +browsers do the decoding. +.I-1 +/RETRY__INTERVAL + /RETRY__INTERVAL=hh:mm:ss + Specifies the minimum amount of time that should elapse between attempts +to deliver a message. The default is 00:30:00 (30 minutes). +.I-1 +2 MLF + The SET MLF command sets global parameters for the MLF +Mailing List/File Server agent. +.NJ + Format: + SET MLF [qualifiers] +.I-1 +3 Qualifiers +.I-1 +/DELAY__DAYS + /DELAY__DAYS=(dow[,...]) + /NODELAY__DAYS + Sets the days of the week on which all file servers' +delayed-send threshold should be honored. Defaults +to all days of the week. +.I-1 +/RECIPIENT__MAXIMUM + /RECIPIENT__MAXIMUM=number + /NORECIPIENT__MAXIMUM + Sets the maximum number of recipients per message generated +by the MLF agent. If your MLF agent services large mailing +lists with many remote subscribers, you may want to use this +setting to limit the number of recipients per message generated +by MLF. This will break up the distribution to the mailing list +into smaller chunks, allowing for more parallelism in delivery. + Setting too small a value, however, could create a lengthy backlog +in your MX message queue, depending on the number of subscribers +on your mailing list(s) and the number of messages the list receives +each day. + The default is /NORECIPIENT__MAXIMUM, which forces each incoming +mailing list message to be forwarded as just one outbound message. +.I-1 +2 ROUTER + The SET ROUTER command sets flags for use by the Router. +.NJ + Format: + SET ROUTER [qualifiers] +.I-1 +3 Qualifiers +.I-1 +/ACCOUNTING + /ACCOUNTING + /NOACCOUNTING (default) +.J + Controls whether accounting records are written by the Rourter. +If enabled, accounting records are written to the file MX__ROUTER__ACC +(with a default directory of MX__ROUTER__DIR: and a default type of DAT). + One accounting record is written for each recipient of each routed message, +either successful or unsuccessful. +.I-1 +/OMIT__VMSMAIL__SENDER + /OMIT__VMSMAIL__SENDER + /NOOMIT__VMSMAIL__SENDER (D) + Enables or disables the omission of the Sender: header for messages +sent from VMS Mail. Needed by some sites to work with other mailers that +don't adhere to RFC822. +.I-1 +/PERCENT__HACK + /PERCENT__HACK (D) + /NOPERCENT__HACK + Specify /NOPERCENT__HACK when you want to disable the automatic resolution +of percent-hacked addresses. It is enabled by default, and automatically +translates addresses of the form "user%host@localhost" to "user@host". +Percent-hack resolution may need to be disabled when you need to pass +MX mail through the VMS Mail interface and into another mail system. +.I-1 +2 SITE + The SET SITE command sets flags for use by the SITE delivery agent. +.NJ + Format: + SET SITE +.I-1 +3 Qualifiers +.I-1 +/MAXIMUM__RETRIES + /MAXIMUM__RETRIES=n + Specifies the maximum number of times the SITE agent should +try to deliver a message if the message cannot be delivered (due to +network failure). The default is 96. +.I-1 +/RETRY__INTERVAL + /RETRY__INTERVAL=hh:mm:ss + Specifies the minimum amount of time that should elapse between attempts +to deliver a message. The default is 00:30:00 (30 minutes). +.I-1 +2 SMTP + The SET SMTP command sets flags for use by the SMTP delivery agent +and SMTP server. +.NJ + Format: + SET SMTP +.I-1 +3 Qualifiers +.I-1 +/ACCOUNTING + /ACCOUNTING + /NOACCOUNTING (default) +.J + Controls whether accounting records are written by the delivery agent. +If enabled, accounting records are written to the file MX__SMTP__ACC +(with a default directory of MX__SMTP__DIR: and a default type of DAT). +.I-1 +/AUTHENTICATION + /AUTHENTICATION=(type,...) + /NOAUTHENTICATION (default) +.J + Enables or disables the authentication extension in the SMTP server. +The "type" keyword can be CRAM__MD5, which enables the use of MX's +private authentication database (see CREATE USER__DATABASE__FILE), +or PLAIN, which enables the use of the VMS user authorization file. + Specifying /NOAUTHENTICATION disables the authentication completely. +.I-1 +/DEFAULT__ROUTER + /DEFAULT__ROUTER=domain-name + Specifies the name of a host through which all SMTP-bound mail should +be sent if a host name lookup fails. +.I-1 +/DNS__RETRIES + /DNS__RETRIES=n + Specifies the maximum number of attempts to deliver a message when the +host name in a destination address cannot be resolved. The default is +12. +.I-1 +/MAXIMUM__RETRIES + /MAXIMUM__RETRIES=n + Specifies the maximum number of times the SMTP agent should +try to deliver a message if the message cannot be delivered (due to +network failure). The default is 96. +.I-1 +/PERCENT__HACK + /PERCENT__HACK (D) + /NOPERCENT__HACK + Specify /NOPERCENT__HACK when you want to reject any addresses containing +a percent-sign in the username portion of the address. Such addresses +are accepted by default. Disabling the percent hack may be necessary to +prevent other sites from using this feature to relay e-mail through your +system. +.I-1 +/RBL__CHECK + /RBL__CHECK[=(domain-name,...)] + /NORBL__CHECK (default) + Specifies whether the SMTP server should check to see if a +system connecting to it is on an Internet Realtime Blackhole List (RBL). +RBL checking is disabled by default. + You must specify one or more domain names as values for this qualifier; +consult your RBL provider for information on the domain names to use. +.I-1 +/RELAY__ALLOWED + /RELAY__ALLOWED (default) + /NORELAY__ALLOWED + Specifies whether the SMTP server will allow messages to be relayed +through your system from one outside system to another. This is +allowed by default. If you disable the relay function with +/NORELAY__ALLOWED, you may also need to tell MX which domains +it should consider "local" for the purposes of this check. See +the DEFINE LOCAL__DOMAIN command for more information. +.I-1 +/RETRY__INTERVAL + /RETRY__INTERVAL=hh:mm:ss + Specifies the minimum amount of time that should elapse between attempts +to deliver a message. The default is 00:30:00 (30 minutes). +.I-1 +/TLS + /TLS + /NOTLS (default) +.J + Controls whether SMTP_SERVER advertises and supports the STARTTLS +ESMTP command documented in RFC3207. +.I-1 +/VALIDATE__SENDER__DOMAIN + /[NO]VALIDATE__SENDER__DOMAIN + Enables or disables a check in the SMTP server on whether the +domain name appearing in an SMTP MAIL FROM command appears in the Domain Name System. +When enabled, a message from a sender whose domain name is invalid is +rejected. This setting is disabled by default. +.I-1 +/VERIFY__ALLOWED + /[NO]VERIFY__ALLOWED + Enables or disables the processing of VRFY commands by the SMTP server. +By default, VRFY is enabled. System administrators concerned about +network security should specify /NOVERIFY__ALLOWED to disable the VRFY +command in the SMTP server. +.I-1 +1 SHOW + The SHOW command displays all or part of the MX configuration. +.NJ + Format: + SHOW ALIASES [pattern] + SHOW CONFIGURATION__FILE + SHOW DECNET__SMTP + SHOW FILE__SERVER [pattern] + SHOW LISTS [pattern] + SHOW LOCAL + SHOW LOCAL__DOMAINS + SHOW PATHS [pattern] + SHOW REWRITE__RULES [pattern] + SHOW ROUTER + SHOW SITE + SHOW SMTP + SHOW SYSTEM__USERS + SHOW USERS [pattern] + SHOW VERSION + SHOW ALL +.J + Those commands taking a pattern will display all entries matching the specified +pattern, which defaults to "*". SHOW ALL displays all of the configuration +information. +.I-1 +2 Qualifiers +.I-1 +/BRIEF + /BRIEF + The /BRIEF qualifier causes SHOW to display information in an +abbreviated format. Only SHOW LISTS has a brief display; for all +other commands, the brief and full displays are identical. +.I-1 +/COMMAND + /COMMAND + /NOCOMMAND (default) + The /COMMAND qualifier causes the SHOW output to be formatted as MCP +commands, which could be executed later to reconstruct the configuration. +By default, the configuration information is displayed in a more +eye-pleasing and descriptive format. +.I-1 +/FULL + /FULL (default) + The /FULL qualifier causes SHOW to display information in its +normal, full format. Only SHOW LISTS has a brief display; for all +other commands, the brief and full displays are identical. +.I-1 +/OUTPUT + /OUTPUT=file-spec + The /OUTPUT qualifier can be used to direct the SHOW output into a file. +When used with the /COMMAND qualifier, SHOW/OUTPUT can be used to create +a command file that can be edited and then read back in with the "@" +input-indirection function to create a new configuration file from scratch. +.I-1 +1 SHUTDOWN + Sends a shutdown signal to one or more MX delivery agent processes, causing +them to exit cleanly. +.NJ + Format: + SHUTDOWN [agent,...] +.J + Accepted agent names are: DECNET__SMTP, LOCAL, MLF, ROUTER, SITE, +SMTP, SMTP__SERVER, and HOLDING__QUEUE=n (where n ranges +from 1 to 32, the maximum number of holding queues). HOLD1 through HOLD8 are +obsolete but still supported for backward compatibility with prior versions +of MX. +If omitted, all agents are shut down. +.I-1 +2 Qualifiers +.I-1 +/CLUSTER + /CLUSTER + Causes the specified agent shutdowns to occur cluster-wide. By default, +SHUTDOWN affects only agents on the local node. +.I-1 +/NODE + /NODE[=(node[,...])] + Causes the specified agent shutdowns to occur only on the specified nodes. +If no node names are specified, only agents on the local node are affected. +.I-1 +/WAIT + /WAIT + /NOWAIT (default) + Waits for the specified agent to exit before returning (up to 30 seconds). +.I-1 +1 STATUS + Displays the status of one or more MX agent processes. +.NJ + Format: + STATUS [agent,...] +.J + Accepted agent names are: DECNET__SMTP, LOCAL, MLF, ROUTER, SITE, +SMTP, SMTP__SERVER, and HOLDING__QUEUE=n (where n ranges +from 1 to 32, the maximum number of holding queues). HOLD1 through HOLD8 are +obsolete but still supported for backward compatibility with prior versions +of MX. +If omitted, status of all running agent processes is displayed. For each +process, the process ID, node name (on VMScluster systems), process name, +and agent type are displayed. +.I-1 +2 Qualifier +.I-1 +/NODE + /NODE=(node[,...]) + Causes the display of only those specified agents running on the specified +nodes. +.! +.I-1 +1 SPAWN + SPAWN is used to create a subprocess and transfer control to it. +.NJ + Format: + SPAWN [command] +.J +.I-1 +2 Parameter + command + Specifies a command line to be executed within the spawned subprocess. +If a command is given, then the spawned process will be deleted after +that command is executed. +.I-1 +2 Examples +.LITERAL + 1. prompt> SPAWN DIRECTORY + [Output of the DIRECTORY command] + . + . + . + prompt> + + The command above demonstrates spawning a subprocess to execute + a particular command. + + 2. prompt> SPAWN + sub_prompt> dir + . + . + . + + The spawned process created above will stick around until it + is explictly deleted (or its parent process is deleted). Once + you SPAWN a subprocess, you can transfer control between it and + program by using the DCL and program ATTACH commands. +.END LITERAL +.! +.I-1 +1 ATTACH + ATTACH is used to transfer control to another process in the current +process tree. +.NJ + Format: + ATTACH [process] +.J +.I-1 +2 Parameter + process + Specifies the process name of the process to which to attach. Not +required if one of the ATTACH qualifiers is used. +.I-1 +2 Qualifiers +.I-1 +/IDENTIFICATION + /IDENTIFICATION=pid + Specifies the PID of the process to which to attach. +.I-1 +/PARENT + /PARENT + Transfers control to the parent process of the process running MCP. +Returns an error if MCP is not running in a subprocess. +.I-1 +2 Examples +.LITERAL + MCP> ATTACH GOATHUNTER_1 + + The command above demonstrates attaching to the subprocess + named "GOATHUNTER_1". +.END LITERAL