Librarian Program Documentation



This file lists the menus and messages displayed by the LIBRARIAN
program.  All Menu items are displayed in UPPER CASE, except areas
of the menus that depend on version, site, file system, etc. All
explanation is in lower case.  Whenever possible, menu flow is the
same as the order being read.  When this is not the case, menus are
blocked together and indented according to function. After reading
through this once, the operation of the LIBRARIAN program should be
pretty clear.

If it is not, let us know.  The easiest way to do this is to use
the EVALUATE LIBRARY option.  Mail the form output by the program,
along with any additional comments to the address listed at the end
of the form.

If you want more information on a particular option, log on and try
it out.  All the options on the FIRST menu of the LIBRARIAN program
won't change any files regardless of the options selected. On the SPECIAL
FUNCTIONS menu, the VERIFY functions are always safe to use.

The first messages issued by the Librarian are:

LOCATING: LIBRARIAN/DATA FILES and
INITIALIZING

The Librarian program looks for the GRIPLIB file structure, makes
sure all important directories are found, and checks for MASTER.LST
and MASTER.INDEX files. It also determines the platform being used
for this process and saves a directory path to the Library.

The Librarian program locates the Library using one of two environment
variables. It first checks for an environment variable called UGII_GRIPLIB.
If that variable is not defined, then it uses UGII_BASE_DIR/griplib. The
first environment variable is not used by EDS and is normally used for
relocating the Library outside of UG. The second variable is defined by
UG during install.

For more information, look at the Abstract of _GET_GRDIR.GRS in the
LIBMGR directory.

Possible error messages during this search are:
  LIBMGR DIRECTORY/NOT FOUND/ABORT which means the program
    could not find the LIBMGR directory. This means the entire
    Library was probably deleted. (Makes me wonder how you still
    had LIBRARIAN.GRX to run).
  SUPPORT DIRECTORIES/NOT FOUND means LIBRARIAN was found but at
    least one of DATA, FONTS, MAIN or SUBS was missing.
    This means the Library was either partially deleted or damaged.
  ERROR READING PLATFORM means LIBRARIAN could not tell what
    environment it is running under. If you get this error,
    contact the Librarian at the address listed in the xxx_RELEASE.DOC
    file.

GRIP Library Vx.xx
([platform])

EVALUATE LIBRARY
FONT FILE MANAGEMENT
SPECIAL FUNCTIONS

GRIP Library Vx.xx
([platform])
 
BUILD STANDARD HEADER
PROOF STANDARD HEADER
CREATE MEDIA COVER LETTER
VERIFY LIBRARIAN COMPILE/LINK
EDIT COMPANY DATA
FLUSH TEMPORARY FILES
NORMAL FUNCTIONS

The two menus above are the main Librarian menus.  The program will
alternate between these two everytime the last option is selected.
The first menu is intended for the average Unigraphics User, while
the second menu is for GRIP programmers and System Managers. The
last option on the second menu only appears if you are logged in
as MANAGER, SYSTEM or root. If you cannot get access to any of
these accounts, you can edit LIBRARIAN.GRS and set SUPERU=&YES
to bring this last option up.  Edit it back to SUPERU=&NO before
turning the Library over to the general user population.


Selecting EVALUATE LIBRARY will start this process:

  This option will verify that the company data is accurate by asking
  a series of questions about the person reviewing the Library and the
  company they work for. (For a more detailed listing of this
  information, see the EDIT COMPANY DATA description below).

  Once the Company Data is checked out, the program will display:

  PART ONE/COMPARISONS
  COMPARE NEW VERSION/TO PREVIOUS VERSION

  and then list a series of topics. The user can choose a number
  between 1 and 7 on the function keyboard to respond to each
  topic. (There are adjectives on the Dialog window to describe
  each number from 1 to 7). The menus will default to the middle
  of the scale.

  PART TWO/EVALUATION
  EVALUATE NEW VERSION/DON'T COMPARE

  Another list of adjectives will appear under each topic, this time
  with 11 choices. Select the appropriate number for each topic. The
  menu will default to a neutral number & adjective.

  Once all the topics are answered, the program outputs the evaluation
  to the Listing Window. Once the program is done, this can be printed
  or filed from the File option for this window.

Selecting FONT FILE MANAGEMENT brings up this menu:

  FONT FILE MANAGEMENT

   LIST SYSTEM FONTS
   LIST ACTIVE PART FONTS
   PLOT FONT CHARTS
   REFORMAT FONT SOURCE FIELS
   COMPARE FONTS

  LIST SYSTEM FONTS Lists the font files currently loaded into the
                    font library. System fonts that are also
                    in the Library will be flagged with an "*" character.

  PLOT FONT CHART   Plots a chart of all possible font characters for the
                    font selected under drafting, preferences, lettering.
                  
                    This option will display a message on the listing device
                    about setting the lettering font, then prompt for chart
                    settings. After these values are set and accepted, the
                    program will prompt for a plotter name. For networked
                    plotters, the proper name form is ]host:plottername.

  RE/FORMAT FONT SOURCE FILES
                    prompts for a font source directory, defaulting
                    to GRIPLIB's fonts. Next, it prompts for a list of
                    fonts to process. To format all the fonts in the
                    current directory, select the "READ NAMES..."  option.
                    
                    Finally, it asks what type of formatting is desired.
                    To get a file comparable to using ugfont -l on a 10.ugf
                    file, choose the first option. For a file to be compared
                    with an uncompiled font (ugfontc -u [name].fnx), use
                    the second option. Both of these options create an
                    output file named the same as the font source file, but
                    with an extension of ".unf". The third creates a list of
                    character definition headers, and saves it as [name].ord.
                    The last option, used on GRIPLIB fonts, reformats the
                    header of the font file from pre-v14 format into V14
                    format. In the future, this option may also "clean up"
                    a font file's format. It's output files have an extension
                    of ".ref".
  
  COMPARE FONTS     Compares font files, indicating which characters are
                    different or missing from either font file. It works
                    even if the character definition order varies between'
                    the selected font files. This was used extensively during
                    the building of the V14 font library.
                    
                    There are two modes: The first is a "manual" mode best
                    used for comparing just two font files. It asks for two
                    directories and two font files, then it compares them.
                    
                    The second mode, automatic, reads a text file for font
                    names and directories. Directory names can be specified
                    on the line by themselves, or as part of the font path
                    name. See font_compare.lst in the fonts directory for
                    an example of this file.
                    
                    At the end of a comparison, this routine will list
                    statistics related to the font files, and indicate if
                    one font is a subset of another. (All 10.ugf fonts are
                    subsets of GRIPLIB V14.0 fonts).

  Note: Since the last two font options create output files, the user running
        these routines must have write access to the font source directory.
        By default, users do NOT have write access to GRIPLIB's font directory.
        To test out these options, you will have to copy the font files to
        another directory or open up the permissions on GRIPLIB's fonts
        directory.
        
        Also, to speed up muliple comparisons between files, COMPARE FONTS
        leaves the re-ordered (sorted) copies of the font files in the
        source directory. These files, ending in ".ro.unf", can be deleted
        after comparisons are done.

  Possible error messages are: (For all of FONT MANAGEMENT)
    BLOCKFONT NOT FOUND means that BLOCKFONT was not loaded into
      the font object file.  This file MUST be loaded into the
      system-wide font table.  It is strongly recommended (for
      compatibility reasons) that blockfont be used as Font #1
      in all systems).

This ends the "Normal" functions from the first of the Main LIBRARIAN
menus.

The first option of the Special Functions menu is BUILD STANDARD HEADER:

  FILE TO SUBMIT

  asks for a source filename. You can type in a Main Program name, a
  Subroutine name or a Font File name and this option will figure out
  what type of file it is. (Even if you leave off the extension).

  If the file is a Main Program, a [name].LNK file is required to build
  the header.  This link list file can be created by:

    Go into GRADE, change directory to the location of the file you
    want to submit, compile it, then set the output to a file named
    the same as the program, but having an extension of LNK instead
    of GRS. Link the program and set the list device back to CRT.
    
    After these steps, you'll have a file containing the names of all the
    subroutines used by a program. Librarian.grs uses this to
    automatically build the REQUIRED SUBROUTINES: section of the
    header.

  If the file is a Font File, the program will read the beginning of
  the font file to determine what type of character spacing is being
  used.  This information is used to automatically build the FONT DATA:
  section of the header.

  SET KEYWORDS

  2D GEOMETRY   OFF
  3D GEOMETRY   OFF
  ANALYSIS      OFF
  DRAFTING      OFF
  FAMILY OF...  OFF
  GROUP TECH    OFF
  MANAGEMENT    OFF
  N/C & RELATED OFF
  TOOLING       OFF
  UTILITY       OFF
  RECREATIONAL  OFF
  OTHER/MISC    OFF
  SELECTION COMPLETE

  This menu is very similar to the LIST KEYWORDS menu in the PRINT
  LIBRARY ABSTRACTS option.  There are two important differences:
  the title is SET keyword instead of LIST keyword, and the choices
  toggle between OFF and ON.  When ENTRY COMPLETE is pressed, the
  settings are saved for later use in building a KEYWORDS comment
  in the file header with the selected keywords listed.

  Pressing ALT ACT at this menu will bring up a menu that controls
  the insertion of a copyright statement into the program. THIS IS
  TO BE USED FOR IN-HOUSE PROGRAMS ONLY. Do not put copyright notices on
  programs you are submitting to the Library, since the presence of
  either copyright or proprietary statements in a program will prevent
  it from being accepted in the Library.

  Next, the program will ask for information needed to build the header:

  ABSTRACT LINE #1
  ABSTRACT LINE #2
  ...(up to 20 lines)...

  REQUIRED FILE #1
  REQUIRED FILE #2
  ...(up to 10 lines)...

  CALLED BY: (Subroutines only, refers to Main program name)

  The program will then ask for information about the program's
  author and the company they work for.  For more information
  about these prompts see the EDIT COMPANY DATA description
  later in this listing.

  The program will list the finished header and ask:

  UPDATE SOURCE

   YES
   NO
   REPAINT
 
  YES retrieves the source file and attempts to add the new
      header. (Continued below)

  NO goes back to the FILE TO SUBMIT prompt.

  REPAINT displays the header again and returns to this menu.

  If YES is chosen above, the program displays:

  RETRIEVING:/[filename]

  If the program already has comments before the first statement
  (or between PROC and first statment for subroutines) the program
  asks what to do with this data:

    EXISTING HEADER

    DELETE IT
    IGNORE IT
    ABORT UPDATE

    DELETE IT deletes the old header and adds the new one.

    IGNORE IT Ignores the header, inserting the new one in front
              of the old one.

    ABORT UPDATE Stops the update process and returns to the
                 FILE TO SUBMIT menu.

  If IGNORE IT is chosen, or there is no header on the file,
  the program inserts the new header:

  UPDATING:/[name]

  The program then returns to the FILE TO SUBMIT menu.

  Possible error messages are:
    FILE NOT FOUND:/[filename] means that the source file header
      could not be read. Make sure it exists.
    NO ACCESS TO FILE:/[filename] means that the header was
      read but the file couldn't be retrieved. Check the file
      access, attempt to retrieve it in Unigraphics.
    ERROR IN FONT HEADER means the first lines of a font file
      do not conform to the standard style output by Unigraphics.
      edit the file to resemble font files already found in the
      FONTS directory.
    INCORRECT LINK LIST: [file]
      MAIN PROGRAM NAME: [name1].GRI (EXPECTED)
      MAIN PROGRAM NAME: [name2].GRI (FOUND)
      ON LINE: xxx
        This indicates that the [name].LNK file is incorrect.
        the contents of this file must be created while linking
        the main program.
    INVALID LINE: xxx
    INVALID SUBROUTINE IN LINE: xxx
      Both indicate the [name].LNK file is not in the expected
      format.  If you are running a BETA version of Unigraphics,
      re-try linking with the current version of Unigraphics.
    CANNOT READ LINK FILE means that the [name].LNK file was not
      usable. (This file is required for building headers for
      main programs.  You can create it using GRIP BATCH or
      interactive Unigraphics. See the instructions above for
      the creation of this file.
    FILING ERROR:/[filename]/ABSTRACT FILED AS:/[filename].HDR
      means that the source file could not be updated, and the
      editted header is stored in an alternate filename. You
      can merge the header in using a text editor or delete it,
      fix the source file so it can be modified and re-run this
      option.
    FILING ERROR:/[filename]/FILING ERROR:/[filename].HDR means
      the header could not be filed at all. Check the directory
      access. (You must have write access to the current
      directory).
    1RST LINE NOT PROC/[filename] means that the first executable
      line of a subroutine is not a PROC/ statement. Fix the
      subroutine or rename it to the correct name for a main
      program.
    END-OF-FILE/DURING PROCESSING: means the program never found
      any executable code in the program. Check the program for
      actual code.

The second option of the Special Functions Menu is PROOF STANDARD HEADER:

  FILE TO PROOF

  PROCESS ENTIRE DIRECTORY

  Asks for a source filename. You can type in a Main Program name, a
  Subroutine name or a Font File name and this option will figure out
  what type of file it is. (Even if you leave off the extension).

  Select PROCESS ENTIRE DIRECTORY at this point will cause the
  program to process all the source files in the current directory.
  This is most effective when you have a program that uses many
  subroutines or several source files you are planning to submit
  to the Library.

  WARNING: THE LIBRARIAN PROGRAM EDITS CALL STATEMENTS AND "CLEANS
           UP" A SOURCE FILE DURING PROOFING. IN DIRECTORY PROCESSING
           MODE, IT ALSO FILES THESE CHANGES AUTOMATICALLY.  USE A
           COPY OF YOUR FILES IN A "SCRATCH" DIRECTORY BEFORE RUNNING
           THIS OPTION IN FULL AUTO MODE!!!

  PROCESSING:/[name]

  SCANNING FILE:/[name]

  Lists the source file currently being worked on. This will just
  be a confirmation for single file processing, but is a handy
  status indicator when doing an entire directory.

  There are quite a few warning messages possible. Among the most
  popular: INVALID FILENAME CHARACTERS (the source filename and/or
  subroutine names do not meet the GRIP Library Standards. This may
  require renaming the files), FILENAME and NAME IN HEADER DO NOT
  MATCH (The name in the header is not the actual filename. Rename
  the file or edit the header) and COPYRIGHT or PROPRIETARY statement
  found (This is a legal safeguard - all files must not contain any-
  thing that indicates they are not intended as public domain. Edit
  the file or don't submit it).

  The program will list out lines that contain CALL statements, lines
  containing errors and lines containing copyright or proprietary
  statements.  CALL statements will be listed with a message of
  "-- CALL OK --" or "** FIXED **".  The program will also list
  out statistics on CALLs fixed, File I/O Statements found,
  Lines Truncated and Errors Found.

  If there were any file i/o statements found, the scan routine will
  output some additional instructions.

  If you are processing single files, and the program editted a CALL
  statement, truncated some lines, or fixed something, it will ask:

    FILE CHANGES

    YES
    NO

    YES fixes the file, NO doesn't

    FILING:/[name]

  If PROCESS ENTIRE DIRECTORY was selected above, this process will loop
  until all source files have been processed.

  When checking out a listing for errors, look for the phrase
  "-- HEADER & PROGRAM OK --" and "** HEADER/PROGRAM UNACCEPTABLE **"

  When the PROCESS ENTIRE DIRECTORY option finishes, the program will
  list how many files it processed.

  Possible error messages are:
      Most of the error messages output by BUILD STANDARD HEADER can
      also occur here. Check the error messages above for more info.
    NO FILES FOUND indicates no GRIP or Font source files were found
      in the current directory. Check your current directory via
      System Parameters.  Also, list TEXT files in the current
      directory.
    INVALID FILENAME CHARACTERS:
    [name1] =] [name2] means the filename currently being used
      for the source file does not meet GRIP Library standards.
      (See the release notes, xxx_RELEASE.DOC for more information).
    FILE AND NAME IN HEADER DO NOT MATCH:
    FILE: [name1] HEADER: [name2] means that the actual filename and
      the filename in the header are different.  Edit the header
      or rename the file so they match.
    COULD NOT FETCH:/[name] means the file could not be retrieved.
      Check file access, directory access.
    COULD NOT FILE:/[name] means the file could not be filed.
      Check file ownership, directory access.
    Error messages relating to program header itself:
      ***FIELD "[name]" IS NOT ALLOWED HERE. means the field listed
        does not make sense in this header. (For example, a font
        file should not have CALLED BY: or SUBROUTINES REQUIRED:
        fields).
      ***FIELD "[name]" NOT FOUND IN HEADER. means the field listed
        is required but not found. All main programs must list
        subroutines called, even if the entry is "NONE".
      ** HEADER INVALID/MISSING ** means the header is unreadable.
        If "PROGRAM:", "SUBROUTINE:" or "FONT FILE:" is not found,
        you'll get this error.
      ** ABORTED ** means TERMINATE was processed during list
        device output. Proofing is not complete.
      **PREMATURE END-OF-FILE** means the file ran out before the
        end-of-header was found. Make sure source file is all there.
    Error/Warning Messages relating to body of the text file:
    Most of these error messages have the form:
      * [line number] [line text] ** ERROR MESSAGE **
      [BLANK LINE] means a blank line was found. No problem.
        (some source processors don't like blank lines, though)
      [ (TRUNCATED) Trailing blanks deleted. (Makes file smaller)
      -- CALL OK -- Subroutine name was Library Standard, no fix
        required.
      ** CALL FIXED ** -- Subroutine name was editted to Library
        standard and source file needs to be renamed.
      ** TOO LONG ** -- Line longer than 80 characters. (GRIP
        compiler will error if this is a line of code). If it
        is a comment, it won't print correctly on an 80 column
        printer.
      ** COPYRIGHT FOUND **   This (and the next error) are warning
      ** PROPRIETARY FOUND ** that this file will not be accepted
        since it may be your company's property. Get permission to
        submit this file, edit these statements out and then send
        in the file.
      ?? FILE I/O STATEMENT ?? Indicates the use of a statement
        that may need modification before submission to GRIPLIB.
        If this references a file in the user's current directory,
        ignore this message. If your program reads data from a file
        supplied with the Library, modify the program using code
        similar to that found in the program ACCESS_DEMO.GRS in
        the MAIN directory.

The third option of Special Functions is CREATE MEDIA COVER LETTER.

  CREATE MEDIA COVER LETTER is used to create a paper description of
  the contents of magnetic tape.  This is needed when files are not
  submitted to the Library from the BBS.

  The program asks for the basic information about the author of the
  program, the company they work for and the system they are using.

  MEDIA TYPE asks what physical media is being used. Choices are:
    REEL 800 BPI, REEL 1600 BPI, REEL 6520 BPI, DEC - TK50, DEC - TK70,
    IBM PC - 5.25 360K, IBM PC - 5.25 1.2M, IBM PC - 3.5 720K,
    IBM PC - 1.44M, HP - 16 TRACK or HP - 32 TRACK.
  ALT ACT will allow inputting the MEDIA TYPE and FORMAT.

  MEDIA FORMAT asks how the data was put on the media. Choices are:
    DEC - BACKUP, DEC - COPY, IBM TEXT (ASCII), HP - TAR, HP - CPIO
  If ALT ACT was used above, this menu is suppressed.

  Once all the topics are answered, the program outputs the evaluation
  to the Listing Window. Once the program is done, this can be printed
  or filed from the File option for this window.


The Forth option of Special Functions is VERIFY LIBRARY COMPILE/LINK

  This options checks for successful compiling/Linking of each GRIP
  source file in the MAIN and SUBROUTINE directories. This is an easy
  way to confirm that the entire Library compiled successfully. The
  process will display the directory it is working on, and sends
  success/error messages to the current list device.

  Possible error messages are:
    **NO GRI FILE** means the Intermediate file is missing, the file
      mentioned did not compile.
    **NO GRX FILE** means the Executable file is missing, the file
      mentioned did not link.
    xxx FILES FAILED. means that many compiles and links failed.
      Note: one failed compile will cause a link error as well.
    NO FILES FOUND means that no source files were found in
      either the MAIN or SUBROUTINE directories. This means
      most of the Library may not be loaded.

  If you get any of the errors above, and both Unigraphics and
  the Library are the same version, contact the Librarian. The
  Library is checked out in the latest version of UGII before
  shipping, so these errors should not occur.

The fifth option of Special Functions is EDIT COMPANY DATA

  This option reads the current company data settings and then
  prompts for each value, defaulting to the current settings:

  NAME
  (Enter person most likely to Evaluate the Library or make
  Submissions to it)

  TITLE
  (Enter the title of the person entered in the previous menu)

  COMPANY
  (Enter company name, division, etc)

  ADDRESS LINE 1
  ADDRESS LINE 2
  ADDRESS LINE 3
  (Enter company address, city/state/zip. Two lines required, third
  optional)

  PHONE
  (Enter Phone number, extension of person entered under AUTHOR above)

  SYSTEM DESCRIPTION
  (Enter Vendor & OS of your system, ALT ACT will bring up
  a menu of common configurations).

  After you enter all this data, the program will update
  _COMPANY_DATA.GRS:

  RETRIEVING:/_COMPANY_DATA.GRS

  EDITING:/_COMPANY_DATA.GRS

  FILING:/_COMPANY_DATA.GRS

  To put these changes into effect, compile the _COMPANY_DATA.GRS
  file & Re-link LIBRARIAN.GRS. (Terminate out of LIBRARIAN,
  select COMPILE, enter _COMPANY_DATA, and press ENTRY COMPLETE.
  Continue to press ENTRY COMPLETE until LINK/ENTER PROGRAM NAME
  is displayed. Type LIBRARIAN and press ENTRY COMPLETE until
  RUN/ENTER PROGRAM NAME is displayed).

  Possible error messages are:
    FILE NOT FOUND:/_COMPANY_DATA.GRS means this file is missing or
      can't be read.
    END-OF-FILE:/_COMPANY_DATA.GRS means the program could not find
      any data statements in the program and ran out of file while
      looking.
    CAN'T FILE:/_COMPANY_DATA.GRS means the file is write-protected
      or owned by someone else.

  If you get any of the above errors, contact the Librarian. This
  file is a critical part of the Library and should have write access
  for all usernames.

The sixth option flushes temporary files from the Library,
displays any files that are not where they should be and
displays byte counts on all the directories.

  GRIP LIBRARY
  FLUSH TEMP FILES
  DELETE [MAIN] .GRX FILES      - NO
  DELETE [LIBRARIAN] .GRX FILES - NO
  SELECTION COMPLETE

  DELETE [MAIN] .GRX FILES toggles the deleting of GRIP Execution
                           files in the MAIN directory. This will
                           disable all programs in the Library
                           except the Librarian. This is normally
                           used before shipping the Library to EDS,
                           but can be used to free up 1-2 Mbytes
                           of disk in an emergency.

  DELETE [LIBRARIAN] .GRX FILES toggles the deleting of GRIP
                                Execution files in the LIBMGR
                                directory. This will disable the
                                Librarian but not any other
                                programs. This is also used prior
                                to shipping the Library.

POSSIBLE SOLUTIONS TO PROBLEMS WITH THE LIBRARIAN PROGRAM:

* Make sure the Library is fully loaded. If a filename is
  given in the error message, check for it in the LIBMGR
  directory.

* Make sure that you have access to the file in question. You must
  have read access to all the data files in LIBMGR and write
  access to _COMPANY_DATA.GRS if you are editting it. The entire
  Library should be readable from any username.

* If many programs in the MAIN directory won't link, make sure
  a GRI.SEA file exists in this directory. This file should
  contain a path to the subroutine directory, such as
  "../subroutine" or "/eds104/griplib104/subroutine"

* Make sure that you don't mix versions.  Don't overlay an old
  LIBMGR directory with a new one.  All versions of the Library
  are upwardly compatible.  While menus may move around, we will not
  attempt to remove any features from newer versions of the Library.
  (Unless, of course, they are sufficiently obsolete as to be
  useless in the current version of UG. Even if a program is
  obsoleted, it's source will be stored in a special directory
  for retrieval upon request to the Librarian).

* If all else fails, you can contact the Librarian with questions.
  If possible, use e-mail as it make it easier to document recurring
  problems with the Library. That way, we can fix it before
  the next release of Unigraphics.

WARNINGS ABOUT PROBLEMS WITH LIBRARIAN:

Due to changes in the operation of Drawings, Views, Layouts,
the FONT MANAGEMENT/PLOT FONT CHART option may not work.

There may be other problems not yet detected. Any that I find in time
will be fixed in V15 and/or uploaded to the EDS BBS.