SYMPLT - MSU SYMBOL PLOTTING ROUTINE T. V. Atkinson Department of Chemistry Michigan State University East Lansing, MI 48824 1. Introduction 2. Symbols 3. Graphical Construction Space 4. Graphical Construction Size 5. Graphical Construction Placement 6. Special Characters 7. Intra String Constructions 8. Symbol Libraries 9. Exceptions 10. SYMPLT - Calling Program Interface 1.0 INTRODUCTION SYMPLT, with the aid of the auxillary routines SYMPAR and SYMGET, draws collections of symbols on any graphic device supported by the MSU CHEMISTRY graphics routine VECTOR. Most often, these symbols are characters from various type fonts and are to be used in the production of labels, legends, and other text in computer generated graphics. This document des- cribes the use of SYMPLT to produce such text and other graph- ical constructions. Such a description must take place on different levels. Advanced users may need to know how to cre- ate new symbols and make them available to SYMPLT. Others will need to know how to integrate SYMPLT with their program- ming. Finally, all users will need to know the mechanics of getting SYMPLT to produce the desired graphical constructions once a program is built and running. Some parts of this docu- SYMPLT.DOC (18-NOV-82) PAGE 2 ment pertain to the integration of SYMPLT into a program and are of little value to those users who are using existing pro- gramming. These sections will be marked (PROGRAMMERS ONLY). Those sections which pertain only to the advanced utilization of SYMPLT will be marked (ADVANCED USERS ONLY). Each symbol (actually the description of how to draw the symbol) is one entry in a symbol library. Each entry within a library is referenced by a unique 7-BIT ASCII character. Whether one or many symbols are to be drawn, SYMPLT receives a list, or string, of the characters representing the symbols to be drawn. This list is passed to SYMPLT by the calling pro- gram and is created at compile time, input by the user at run time, or otherwise created. In this document this list will be called the display list string. The collection of symbols drawn as the results of processing one display list string will be referred to as a graphical construction. One graphi- cal construction may utilize symbols from more than one symbol library. The display list strings may contain not only the ASCII codes for the symbols to be drawn but also substrings of characters that provide formatting and other control informa- tion. SYMPLT recognizes these control substrings by the syn- tactical context. The display list strings are processed se- quentially, each symbol is drawn or each control construction is executed as it is encountered in the string. There are three aspects in the use of SYMPLT. First, there are the various symbol format parameters, such as width and height, which must be set. If you are using an existing program such as MULPLT, these parameters will be input or, perhaps, set to convenient default values. Secondly, the dis- play list string must be created and passed to SYMPLT. Again, depending on the programming being used with SYMPLT, the manner of creating this string will vary. Finally, the appro- priate symbol libraries must be made available to SYMPLT. SYMPLT provides great flexibility (and hence complexity) for producing complicated graphical constructions. However, if a simple string of symbols of the same size are to be drawn, the process is straight forward. Simply set the values of the symbol parameters, and pass the string of characters to SYMPLT. When multiple lines, superscripts, subscripts, alter- nate character sets, etc. are desired, the process is more involved and close attention must be made to the contents of this document. 2.0 SYMBOLS (IN SYMBOL SPACE) (ADVANCED USERS ONLY) Each symbol consists of an ordered list of written and unwritten vectors. The vectors are defined on a grid of vary- ing size. The library format dictates that the maximum grid for symbol definition is +63 to -64 horizontally and +127 to SYMPLT.DOC (18-NOV-82) PAGE 3 -128 vertically. Thus, each symbol is defined in an individu- al coordinate space (symbol definition space). The origins of the symbol definition spaces are generally at the intersection of the symbol base line and the horizontal center line of the symbol. The symbol definition spaces have the positive y-axis pointed toward the top of the page contrary to the usual typo- graphic convention used by Hershey[1]. The Figure S.1 is an example of the symbols "B" and "j" from the library ROMSIM.SYM, a library of Hershey simplex Roman characters[1]. The end points of the vectors making up the symbols are marked with diamonds and are numbered sequentially. Figure S.1a [1] "A Contribution to Computer Typesetting Techniques: Tables of Coordinates for Hershey's Repertory of Occidental Type Fonts", N M Wolcott, J Hilsenrath, NBS Special Publication 424, 1976. SYMPLT.DOC (18-NOV-82) PAGE 4 Figure S.1b There are six features associated with every symbol. These are horizontal grid size, vertical grid size, horizontal sym- bol maximum, horizontal symbol minimum, vertical symbol mini- mum, and vertical symbol minimum, all given in units of the symbol definition space. Figure 2 shows these features for the symbols used in Figure 1. SYMPLT.DOC (18-NOV-82) PAGE 5 Figure S.2a SYMPLT.DOC (18-NOV-82) PAGE 6 Figure S.2b The inner box (solid lines) delineates the four symbol extre- ma. These will, of course, vary from symbol to symbol. Notice that horizontal space is included within the symbol ex- trema. The outer box (broken lines) delineates the definition grid for the symbol. All symbols within a given library will have the same definition grid size. 3.0 GRAPHICAL CONSTRUCTION SPACE (COLLECTIONS OF SYMBOLS) When collections of symbols are drawn, the individual symbols are scaled and translated into the graphical construc- tion coordinate space in the appropriate fashion to place the symbols in the desired position with the desired size relative to the other symbols in the construction. The origin of the constuction space is the intersection of the base line and left extreme of the first symbol drawn. The symbols are scaled so that the resultant symbols have the desired HEIGHT and WIDTH (see Figure S.2). Figure S.3 shows a collection of symbols with symbol extrema boxes for a few symbols from ROM- SYMPLT.DOC (18-NOV-82) PAGE 7 SIM. Figure S.3 As can be seen in Figure S.3, the collections of symbols can be drawn in two ways. The top line of Figure S.3 is an exam- ple of equal spacing which results in the horizontal centers of the symbols being equally separated. The second line of Figure S.3 illustrates proportional spacing. The choice between these two modes is made with the parameter IMODE(3) (MODSY3 in MULPLT Special Features). Figure S.4 SYMPLT.DOC (18-NOV-82) PAGE 8 Figure S.4 illustrates how multiple lines within a graphical construction are related. In this example, the line feed car- riage returns are accomplished by the four character substring "^M^J" (see Section 7.1.1) which occurs between the "y" and "C", the "w" and the second "C", and the "g" and the "A" in the display list string. The bottom line of Figure S.4 illus- trates the subscript and super script capability of SYMPLT. @@'SB:[10,10]ROMSIM.SYM'AaBbYy^M^JCcJjWw^M^JCc IiGg^M^JA^SW^H^D^DA S.1 NOTE The symbol libraries are maintained in SB:[10,10], where SB: is a logical device permanently assigned to the physical device containing the libraries. Any symbol can also be slanted as shown in Figure S.5 and Fig- ure S.6. The slant is controlled by the parameter SLANT. The first and fourth "A" in Figure S.5 were drawn with SLANT = 20.0 degrees. The second "A" was drawn with SLANT = 0.0 de- grees. The third "A" was drawn with SLANT = -20.0 degrees. The horizontal spacing between the extrema boxes is HSPACE. Figure S.5 4.0 GRAPHICAL CONSTRUCTION SIZE SYMPLT actually makes two complete passes through a dis- play list string. The first pass is devoted to determining the size of the construction which is necessary to map the SYMPLT.DOC (18-NOV-82) PAGE 9 graphical construction space into the physical drawing space. There is no drawing done on the first pass. The drawing is done during the second pass. The results of the sizing pass are available to the calling program through the COMMON/STRSIZ/ (See Figure S.9 and Section 10.3). Two sets of size information are supplied. The first gives the horizontal and vertical sizes of the graphical construction in graphical construction space before the rotation of SYMANG is applied. The second set gives the horizontal and vertical sizes of the rotated construction. By negating the number of characters (NCHR) in the dis- play list string in the call to SYMPLT, the calling program can cause only the sizing pass to be done. Using the result of the sizing pass as found in COMMON/STRSIZ/, decisions can be made as to the placement of graphical constructions on the drawing surface. 5.0 GRAPHICAL CONSTRUCTION PLACEMENT The graphical construction can be placed in the user coordinate space in several different ways. The choices ava- ilable allow a graphical construction to be centered horizon- tally, and/or vertically over the reference point. Or the construction can be drawn to the right or the left, above or below the reference point. Other choices also exist. The construction can also be rotated relative to the user's space. In general a point within the graphical construction is chosen and the construction is translated in such a way that this point overlaps a specified point in the user's space. The graphical construction seen in Figure S.6 will be used to il- lustrate the process of selecting the point within the con- struction which will overlay the reference point in the user's space. The symbol extrema boxes are included in a few cases to define the extremes of the graphical construction. Line S.2 shows the display list string used to create Figure S.6. SYMPLT.DOC (18-NOV-82) PAGE 10 Figure S.6 @@'SB:[10,10]ROMSIM.SYM'THE H^D3^SO^S%1+^D ion i%2s ^m^j^H%3stable in H^D%42^SO.@@'SB:[10,10]ROMBOX.SYM' /LP177000//NI1/$1+$2s$3s$42 S.2 A rectangle can be drawn which includes the graphical con- struction as shown in Figure S.7. Figure S.7 This rectangle can be further subdivided by drawing a horizon- tal and a vertical line through the center of the rectangle as seen in Figure S.8. Furthermore, a vertical line and a hori- zontal line are drawn through the origin of the graphical con- struction space, also shown in Figure S.8. SYMPLT.DOC (18-NOV-82) PAGE 11 Figure S.8 Any of the sixteen points resulting from the intersections of these lines and the sides of the rectangle can be chosen as the center of rotation for the construction. This choice is made with the parameters MODESH and MODESV. MODESH selects one of the four vertical lines of Figure S.8 and, hence, the horizontal placement of the center of rotation. MODESV se- lects one of the four horizontal lines and hence the vertical placement of the center of rotation. If MODESH and MODESV are equal to 4, the new graphical construction will continue from where the last graphical construction ended. This feature is only useful when display list strings have to be broken into parts to fit in the string buffer. Figure S.9 gives a few possible construction placements. SYMPLT.DOC (18-NOV-82) PAGE 12 Figure S.9 Figure S.9 illustrates four examples of graphic construction placement. In each case, the horizontal and vertical lines mark the user reference point over which the graphical con- struction center of rotation is placed. The dimensions illus- trate the unrotated and unrotated size information available in COMMON/STRSIZ/. Table S.1 shows the pertinent parameters used in each of these four examples. .TABLE S.1 MODESH 0 1 MODESV 0 2 SYMANG 0.0 0.0 MODESH 2 2 MODESV 2 2 SYMANG -30.0 deg. 30.0 deg 6.0 SPECIAL CHARACTERS SYMPLT.DOC (18-NOV-82) PAGE 13 6.1 SPECIAL PRINTING CHARACTERS As will be seen in the insuing discussion, the characters "^", "@", "%", "$","/", and "_" have special meanings when included in the display list string. If the actual symbols represented by these characters are desired to be drawn, these characters must be preceeded by the "_" character (underline, 137 octal). Thus "_^", "_@", "_/", "_%", "_$", and "__" must be used in place of these characters to cause their corresponding symbols to be drawn. Otherwise, the symbols indicate that a control construction is beginning. 6.2 CONTROL CHARACTERS Various formatting control commands such as line feed, carriage return, and tabs are universially assigned to some of the first 32 ASCII codes (000 to 037 OCTAL). These 32 7-BIT ASCII codes are what are usually termed "non-printing" char- acters since they generally produce no written image on the page after being processed. Most terminals provide either special keys for such characters or provide a "CONTROL" key for entering the "non-printing" characters. The characters are entered by holding the "CONTROL" key down while striking the corresponding upper case alpha key. For example, or 004 octal is entered by striking "D" while holding down the "CONTROL" key. Since these codes are util- ized by SYMPLT, and it is inconvenient to work with "non-printing" characters in FORTRAN, and to eliminate ambi- quities caused by the special uses of these characters made by different operating systems, an alternate specification is al- lowed by SYMPLT. In the display list strings for SYMPLT, such "non-printing" characters may be specified by the two char- acter sequence consisting of the character "^" followed by the upper case alpha character with the same lower 5 bits. Thus, (octal 004) becomes ^D. (octal 022) becomes ^R, etc. Such constructions allow representation of these special characters using only "printing characters". While SYMPLT will accept either the one or two character con- structions for these "non-printing" characters, best practice is the use of the two character "^" construction. 7.0 INTRA STRING CONSTRUCTIONS SYMPLT.DOC (18-NOV-82) PAGE 14 7.1 FORMAT CONTROL 7.1.1 SYMBOL INDEPENDENT CONSTRUCTIONS - The following control characters( or their alternate two character constructions) provide for an expanded format con- trol over that common to most terminals and printers. These control characters are included in the display list string of characters to be processed by SYMPLT. As SYMPLT sequentially processes the string, the control constructions are executed as they occur and perform format control analogous to that done while manually typing. Examples are found in Figures S.6 and Line S.2. TABLE S.3 SYMB ACTION DETAILS ^D 1/2 line feed The base line is decreased (moved toward the bottom of the page) by the current value of SUBSUP*HEIGHT ^S 1/2 line feed up The base line is increased (moved towards the top of the page) by the current value of SUBSUP*HEIGHT ^J line feed The base line is decreased (moved toward the bottom of the page) by the current value of VSPACE ^Q line feed up The base line is increased (moved towards the top of the page) by the current value of VSPACE ^M carriage return The horizontal cursor is moved to the initial value of the cursor. This is equivalent to returning to the left margin. ^H backspace The horizontal cursor is decreased by the current value of WIDTH plus the current value of HSPACE. This has the effect of backspacing over a space. SYMPLT.DOC (18-NOV-82) PAGE 15 7.1.2 SYMBOL DEPENDENT CONSTRUCTIONS - The following constructions allow spacing relative to a particular symbol. In each case "i" is the next drawable sym- bol and may be a single character or a more complicated con- struction involving library specifications, etc. TABLE S.2 SYMB ACTION DETAILS ^Wi space over next The horizontal cursor position character is increased by the width of the next drawable character in the string plus the current value of HSPACE. The character is not drawn. ^Bi backspace over next The horizontal cursor position character is decreased by the width of the next drawable character in the string plus the current value of HSPACE. The character is not drawn. ^Xi halfspace over next The horizontal cursor position character is increased by half the width of the next drawable character in the string. The character is not drawn. ^Yi half backspace over The horizontal cursor position next character is decreased by half the width of the next drawable character in the string plus the current value of HSPACE. The character is not drawn. 7.1.3 MARKERS - The following two character constructions provide for large moves within a graphical construction. These construc- tions are analogous to placing a "mark" on the page at the current cursor position as the display list string is being processed. At any later time in the execution of the display list string, the cursor can be returned to the "mark" from which further construction will be referenced. Markers are useful when constructing mathematical formulae or other com- plicated graphical constructions and prevent excessive back spacing, line feeding, etc. Examples of the use of markers SYMPLT.DOC (18-NOV-82) PAGE 16 are found in Figure S.6 and Line S.2. TABLE S.4 Con Name Action %1 set #1 marker Put marker #1 at the current cursor position for later return to this point. %2 set #2 marker Put marker #2 at the current cursor position for later return to this point. %3 set #3 marker Put marker #3 at the current cursor position for later return to this point. %4 set #4 marker Put marker #4 at the current cursor position for later return to this point. %5 set #5 marker Put marker #5 at the current cursor position for later return to this point. $1 return to marker #1 Put cursor at marker #1 $2 return to marker #2 Put cursor at marker #2 $3 return to marker #3 Put cursor at marker #3 $4 return to marker #4 Put cursor at marker #4 $5 return to marker #5 Put cursor at marker #5 7.2 CHANGING SYMBOL PARAMETERS Any of the six REAL symbol parameters may be changed as often as desired within the drawing of a display list string. This is acomplished with the following construction. ... /NNrrrrrrrrrrrrrrr/ ... S.3 where NN is any of the following tags and "rrr ... " is a one to fifteen digit REAL or INTEGER number. The indicated symbol SYMPLT.DOC (18-NOV-82) PAGE 17 parameter will be set to the value of "rrr ... " The leading "..." reinforce the fact that this construction will be within a display list string. TABLE S.5 TAG SYMBOL PARAMETER TO BE UPDATED WI WIDTH HE HEIGHT VD VDIST HS HSPACE SL SLANT SS SUBSUP Any of the two INTEGER symbol parameters also may be changed as often as desired within the drawing of a display list string. This is acomplished with the following construction. ... /MMoooooooo/ ... S.5 where MM is any of the following tags and "ooo ... " is any OCTAL number of 1 to 8 digits. The indicated symbol parameter will be set to the value of "ooo ... " . TABLE S.6 TAG SYMBOL PARAMETER TO BE UPDATED LI LINE PATTERN NI NIB WIDTH An example of the use of these constructions is found in Fig- ure S.6 and Line S.2. 8.0 SYMBOL LIBRARIES Symbols are collected into sets called libraries. Since each symbol is represented by a 7-BIT ASCII character, a li- brary might have a maximum of 128 symbols. However, the lower SYMPLT.DOC (18-NOV-82) PAGE 18 32 codes are reserved for format and other control resulting in a maximum library size of 96 characters. A given ASCII character can, of course, represent different symbols in dif- ferent libraries. A given symbol can also be in several dif- ferent libraries. Furthermore, such a symbol can be repre- sented by a different ASCII code in each library. The librar- ies are completely independent. There are two types(internal and external) of libraries associated with SYMPLT. Internal libraries are linked with the program as the program is built in the same sense as a subroutine. Such a library is always immediately available. External libraries reside in separate files and must be loaded into the program during execution. There are reasons for both types being used. First, the sym- bol libraries can be large (English Gothic is 8000 bytes long). Such size precludes the inclusion of all desired li- braries into one program. Secondly, new libraries can be cre- ated at any time. The external library mechanism allows the new libraries to be used immediately without rebuilding the program being used. The significance of this can be seen in the fact that MULPLT takes 30 minutes and several thousand blocks of disk space to build. 8.1 USING DIFFERENT LIBRARIES SYMPLT utilizes n+1 libraries (n = 0,1,2, ... ,9). The value of n is determined by the calling program at compile time. This value can and will vary from program to program and even from one place to another within the same program( as in MULPLT). This variation is desirable for one program may need a different set of libraries than another. In addition, more room for libraries may be available in some instances. The user must be aware of the value of n and the internal li- brary list at any particular time. Library n+1 is always the external library. Only one external library is loaded at any one time. Once loaded, an external library remains loaded until another external library is loaded. Only one library, internal or external, is active at any one time. Once acti- vated a library remains active until another is activated. The choice of which library is active is done temporarily or permanently using the "@" and "@@" constructions respectively. The following show the different forms that these construc- tions may have. ...@mABCD... S.5 ...@@mABCD... S.6 ...@'ffff...fff'ABCD... S.7 ...@@'ffff...fff'ABCD... S.8 SYMPLT.DOC (18-NOV-82) PAGE 19 ...@''ABCD... S.9 ...@@''ABCD... S.10 where m is a decimal digit, "ffff...fff" is the file specifi- cation of the file containing the external symbol library, and ABCD... is a string of characters to be drawn. The leading string of periods in the above are to reiterate that these strings will be within the display list string. The library being referenced may be changed temporarily for one character after which the previous library is reactivated. The change of active library may also be done "permanently". In this context, permanent means until changed or the next call to SYMPLT. In Line S.5, symbol "A" in library m is drawn followed by sym- bols "B", "C", and "D" from the previous library. In Line S.6, symbols "A", "B", "C", "D", ... are taken from library m. In Line S.7, symbol "A" is drawn according to the library contained in the file ffff...fff" with the remainder taken from the previous library. In Line S.8, symbol "A", "B", ... are all taken from the external library. In Line S.9, symbol "A" is taken from the last external library loaded while the remainder are drawn according to the library activated before the "@". Finally in Line S.10, all symbols shown will be drawn according to the last external library loaded. For me- aningful results, the last two forms will have to be preceeded by a Line S.7 or Line S.9, so that there will actually be a library there to be used. As an example, assume that the internal libraries are ROMSIM, GRKSIM, and PLOTSM. (A description of these libraries appears later in this document). The following string ABCD@2EFGH@@1ijklm@@'SB:[10,10]ENGGOT.SYM'mnop@0qr s@@''tuVWXYZ would result in the Figure S.10 being drawn. Figure S.10 SYMPLT.DOC (18-NOV-82) PAGE 20 8.2 SYMBOL LIBRARY CREATION (ADVANCED USERS AND PROGRAMMERS) 8.3 CURRENT SYMBOL LIBRARIES The following tables contain the symbol libraries which are currently available for use with SYMPLT. These libraries, with the exception of the library PLOTSM, contain symbols from "Hershey's Library of Occidental Fonts" [1]. The tables are organized in ASCII order. Each column contains those entries from each library which are referenced by the ASCII character with the octal code found at the top of that column. Notice also, that the first library in each table is ROMSIM which is a full 96 character ASCII set. Thus, the ROMSIM character is the ASCII character which would be entered in the display list string to reference the symbol in that column for the activat- ed library. There are three tables for the alphanumeric li- braries for the entries corresponding to the ASCII codes: 40-77, 100-137, and 140-176. There are two tables for the miscellaneous symbols corresponding to the ASCII codes: 100-137 and 140-176. SYMPLT.DOC (18-NOV-82) PAGE 21 TABLE S.7 SYMPLT.DOC (18-NOV-82) PAGE 22 TABLE S.8 SYMPLT.DOC (18-NOV-82) PAGE 23 TABLE S.9 SYMPLT.DOC (18-NOV-82) PAGE 24 TABLE S.10 SYMPLT.DOC (18-NOV-82) PAGE 25 TABLE S.11 SYMPLT.DOC (18-NOV-82) PAGE 26 8.4 SYMBOL LIBRARY FORMAT (ADVANCED USERS AND PROGRAMMERS) The format of the symbol libraries is delineated in ROMSIM.MAC, the source for the roman simplex library, and in SYMGET. The file ROMSIM.TLE can be used to assist in the cre- ation of libraries. Change all occurrences of "ROMSIM" to an appropriate name. Once the source file has been created, the file is assembled in one of two ways. MAC ROMSIM.OBJ=ROMSIM.MAC (Internal) MAC ROMSIM.SYM/EN:ABS=ROMSIM.MAC (External) The .SYM files merely have to be made available when the graphics program is to be used. The .OBJ files will be linked with the graphics program. 9.0 EXCEPTIONS Errors detected by SYMPLT and the support routines have the following general form and are reported by the routine ERRPRT. ERROR mmmmmm: tttttttttttttttt nnnnnn kkkkkk lllllll where "mmmmmm" is the module name ("SYMPLT", "SYMPAR", or "SYMGET"), for the routine reporting the error "ttt ... " is one of the following error messages. For SYMPLT and SYMPAR "nnn ... " is the octal error number and the last two argu- ments are not reported. For SYMGET "nnn ... " is the id number of the selected symbol library, "kkk ... " is the ASCII octal code for the character giving trouble, and "lll ... " is the error number. Table S.12 Table of Errors Reported by the SYMPLT Routines 1. SYMPLT - Main routine of the symbol drawing pack- age. SYMPLT does not report any errors. 2. SYMPAR - Routine to decode SYMPLT display list string, loa external symbol libraries and assist in the drawing of symbol constructions. 1. "OPENING LIB FILE" - Could not open a symbol library file before loading a symbol library. SYMPLT.DOC (18-NOV-82) PAGE 27 2. "READING LIB FILE" - Error occured while load- ing symbol library file. Attempting to load an external library that is larger than the buffer (LIBEXT) will result in this error. 3. "MISSING '2ND ' " - The specification of an external symbol library did not contain the ter- minal "'". 4. "NO TERMINAL "/" " - A "/NNrrr ... /" symbol parameter change construction did not end in a "/". 5. "ILLEGAL CP TAG " - An illegal tag was used in a "/NNrrr ... /" symbol parameter change con- struction. 6. "DECODE ERROR " - The "rrr ... " field of a "/NNrrr ... /" symbol parameter change construc- tion could not be decoded. 7. "ILLEGAL MARKER " - A reference was made to an illegal marker in a "$n" or "%n" construction. 3. SYMGET - This routine provides the interface to the symbol libraries that are resident in memory. SYMGET passes the vector lists describing the symbols back to the calling program. 1. "ILLEGAL LIBRARY " - A reference was made to a nonexistent symbol library in a "@ ... " or "@@ ... " construction. 2. "ILLEGAL CHARACT " - A reference was made to symbol that does not exist in the selected libra- ry. 3. "TOO MANY LIBR'S " - An attempt was made ini- tialize SYMGET with too many internal libraries. 10.0 SYMPLT - CALLING PROGRAM INTERFACE 10.1 SYMBOL LIBRARY INITIALIZATION The calling program determines which and how many symbol libraries are internal and the maximum size of external libra- SYMPLT.DOC (18-NOV-82) PAGE 28 ry that can be loaded at run time. These decisions are accom- plished by including the following two segments of code in the programming that will be using SYMPLT. The first two state- ments define a COMMON block used to communicate with and among the SYMPLT family of routines and allows the programmer to control size and placement of the buffer to hold the external (in the SYMPLT sense) libraries. The EXTERNAL statment, in conjunction with the call to SYMGET, identifies which symbol libraries are going to be internal (in the SYMPLT sense) and assigns the SYMPLT library id numbers. COMMON/SYMLIB/NUMEXT,MWEXTL,NBYTE,LIBNUM,LIBEXT(eeeeee) INTEGER*2 NUMEXT,NWEXTL,NBYTE,LIBNUM,LIBEXT EXTERNAL iiiiii,jjjjjj, ... ,llllll where "eee .. "is the dimension of the buffer that will con- tain any external symbol library loaded at runtime (See Sec- tion 10.3 for further discussion of these variables), "iii ... " is the name of object module containing symbol li- brary #0, "jjj ... " is the name of the object module contain- ing symbol library #1, and "lll ... " is the name of the ob- ject module containing symbol library #n. The following call to SYMGET must occur before any plotting or sizing is attempt- ed. CALL SYMGET(2,nnn,iiiiii,jjjjjj, ... ,llllll) NWEXTL = eeeeee where "2" indicates that this is an initialization call, "nnn" is the number of internal symbol libraries to be used by SYMPLT, "iii ... " is the name of object module containing symbol library #0, etc. Such control of which libraries are internal is of use in overlayed programs such as MULPLT where requirements differ in different overlays of the program. As an example the following two code seqments from MULPLT are included. The first occurs early in the PLOT phase seq- ments. This choice provided the convenience of having several internal libraries. However, there was not enough space to accomodate the large external libraries. COMMON/SYMLIB/NUMEXT,NWEXTL,NBYTE,LIBNUM,LIBEXT(1000) EXTERNAL ROMSIM,GRKSIM,PLOTSM CALL SYMGET (2,3,ROMSIM,GRKSIM,PLOTSM) NWEXTL = 1000 The second example is found in the SPECIAL FEATURE phase over- lay. This choice allows any of the libraries to be loaded but forgoes the convenience of having several internal libraries. SYMPLT.DOC (18-NOV-82) PAGE 29 Again, this compromise was necessitated by insufficient memory space to hold both a large external library and the usual internal libraries. COMMON/SYMLIB/NUMEXT,NWEXTL,NBYTE,LIBNUM,LIBEXT(4500) EXTERNAL ARROWH CALL SYMGET (2,1,ARROWH) NWEXTL = 4500 10.2 CALLING SEQUENCE SUBROUTINE SYMPLT(XI,YI,STRNG,NCHR,SYMANG,SPARAM,NIB, 1 IMODE,IERR) C================================================================== C C ARGUMENT LIST: C C XI X-COORDINATE OF THE POINT TO BE USED IN C POSITIONING THIS STRING OF SYMBOLS C C YI Y-COORDINATE " C C STRNG BYTE ARRAY CONTAINING CODES FOR THE SYMBOLS C TO BE DRAWN C C NCHR NUMBER OF CHARACTERS(CODES) IN STRNG C IF NCHR IS NEGATIVE, FIND THE PHYSICAL C SIZE OF THE STRING BUT DO NOT DRAW IT. C THE STRING DIMENSIONS ARE AVAILABLE IN C THE COMMON STRSIZ. C C SYMANG ANGLE(DEGREES). THE STRING IS ROTATED AROUND C THE POINT (XI,YI) BY THE ANGLE SYMANG. C SYMANG = 0. CAUSES THE STRINGS TO BE DRAWN C PARALLEL TO THE CURRENT X-AXIS. C C SPARAM SYMBOL PARAMETERS C C (1): SYMBOL WIDTH(INCHES) C C (2): SYMBOL HEIGHT(INCHES) C C (3): VERITCAL DISTANCE BETWEEN THE BASE OF C OF ONE LINE OF SYMBOLS TO THE BASE C OF THE NEXT LINE OF SYMBOLS C C (4): HORIZONTAL SPACE(INCHES) BETWEEN SYMBOLS C SYMPLT.DOC (18-NOV-82) PAGE 30 C (5): THE SLANT ANGLE(DEGREES) FOR THE DRAWING C OF EACH SYMBOL. C C NIB VERSATEC NIB SIZE FOR SYMBOLS C C IMODE(3) PLACEMENT CONTROL C C (1) HORIZONTAL STRING PLACEMENT CONTROL C =0 NO HORIZONTAL PLACEMENT CONTROL C =1 (XI,YI) WILL BE AT A, D, OR G C =2 (XI,YI) WILL BE AT B, E, OR H C =3 (XI,YI) WILL BE AT C, F, OR I C =4 XI WILL BE AT THE END OF THE LAST C SYMBOL DRAWN DURING THE PREVIOUS CALL C TO SYMPLT C C (2) VERTICAL STRING PLACEMENT CONTROL C =0 NO VERTICAL PLACEMENT CONTROL C =1 (XI,YI) WILL BE AT G, H, OR I C =2 (XI,YI) WILL BE AT D, E, OR F C =3 (XI,YI) WILL BE AT A, B, OR C C =4 YI WILL BE AT THE BASE LINE OF THE LAST C SYMBOL DRAWN DURING THE PREVIOUS CALL C TO SYMPLT C C (3) HORIZONTAL SPACING CONTROL C =0 PROPORTIONAL C =1 EQUAL SPACING C C IERR ERROR FLAG C =0 NO ERROR C .GT.0 IERR EQUALS THE INDEX OF THE C CHARACTER LAST PROCESSED C C================================================================== 10.3 COMMON AREAS COMMON/STRSIZ/XMIN,XMAX,YMIN,YMAX,RXMIN,RXMAX,RYMIN,RYMAX, 1 XCRSAV,YCRSAV,XCURSV,YCURSV VAR TYPE DIM Comment XMIN R*4 1 Minimum value (inches) of x (Unrotated) XMAX R*4 1 Maximum value (inches) of x (Unrotated) SYMPLT.DOC (18-NOV-82) PAGE 31 YMIN R*4 1 Minimum value (inches) of y (Unrotated) YMAX R*4 1 Maximum value (inches) of y (Unrotated) RXMIN R*4 1 Minimum value (inches) of x (Rotated) RXMIN R*4 1 Maximum value (inches) of x (Rotated) RYMIN R*4 1 Minimum value (inches) of y (Rotated) RYMAX R*4 1 Maximum value (inches) of y (Rotated) XCRSAV R*4 1 x-coor. for center of rotation YCRSAV R*4 1 y-coor. for center of rotation XCURSV R*4 1 Last value of x-cursor YCURSV R*4 1 Last value of y-cursor COMMON/SABORT/LABORT,LDUM(4) LABORT L*1 1 Asynchronous flag for terminating SYMPLT before completion. When set .TRUE. by an AST routine such as KBCHEK, SYMPLT will abort. A check of LABORT is made as each symbol is processed. LDUM L*1 4 NOT USED BY SYMPLT COMMON/ERROR/LUNEL LUNEL I*2 1 Error messages and other messages from SYMPLT are made on the logical unit number which is contained in LUNEL COMMON/SYMLIB/NUMEXT,MWEXTL,NBYTE,LIBNUM,LIBEXT(eeeeee) NUMEXT I*2 1 The library id number used for the external library (tended by SYMGET) SYMPLT.DOC (18-NOV-82) PAGE 32 NWEXTL I*2 1 The size (words) of the buffer LIBEXT used to hold the external libraries. NBYTE I*2 1 The size (bytes) of the external symbol libraruy currently loaded in LIBEXT (tended by SYMPAR and SYMGET) LIBNUM I*2 1 The id number of the currently selected library. (tended by SYMPAR and SYMGET) LIBEXT I*2 eeeeee A buffer to hold external libraries. In addition, the COMMON areas used by VECTOR must be han- dled appropriately. This is true even when SYMPLT is the only MSU graphics routine used directly by the user. See VECTOR.DOC for their discussion.