3.1 vpack

The vpack program accepts a list of parameters:

vpack <file.com>  [-u]
                  [-s Source file(s)]
                  [-i IMAKE template file(s)]
                  [-b VMS build file(s)]
                  [-m UNIX make file(s)]
                  [-p PDF file(s)]
                  [-t Test file(s)]
                  [-d Documentation file(s)]
                  [-o "Other" file(s)]

The " -b" (VMS build file) and " -m" (UNIX makefile) should not be used. The " -i" (i makefile) option should be used instead. Machine-specific build files are allowed only under rare circumstances.

The " -u " option tells vpack that the module is unportable (VMS-specific), so the correct header information can be generated (the default for executing the COM file directly with no arguments is changed from "STD" to "SYS"). If vpack is used with unportable module s, "-u" must be present; for portable modules, it must not be.

If you call the vpack program with no parameters, it will report a syntax error and give the proper syntax to use.

Based on the parameters provided, the vpack program will create the new COM file (named in the first argument), read the lists of files in the order given, and append them to the new COM file. None of the source files are altered or deleted. vpack's output is the COM (ASCII) file. The vpack program requires that the COM filename be included as a parameter and also requires that at least one list of files be specified.

As an example, the command necessary to assemble the Magellan program view into a COM file is:

vpack view.com -s view.h host.c image.c overlap.c view.c
               -i view.imake
               -p view.pdf
               -t tstview.pdf tstview.scr

An include file (view.h) is considered a "source" file. Multiple file names can be separated by commas or spaces or both. If you arrange the command on several lines, you would need a continuation character appropriate for the operating system you are using.

The vpack program can be executed in two different ways. The command can be executed directly from the command line as shown above, assuming the command line is long enough to hold the entire command. It can also be executed from a repack file created by the vpack program. For example, the repack file created for the view program is as follows:

$ vpack view.com -
        -s view.h host.c image.c overlap.c view.c -
        -i view.imake -
        -p view.pdf -
        -t tstview.pdf tstview.scr
$Exit 

The preferred method for executing the vpack program also uses the repack file, but as a parameter to the program:

vpack view.repack

There is no command line length limit with this method.

The vpack program creates a COM file in the following format:

• A standard header which lists all of the available parameters and options for the COM file in the VMS environment as comments. This header also lists the version number of the vpack program which created the file and the name of the file. See below for an example of a header.
  
  
• DCL code which parses command-line options in the VMS environment and sets up the necessary conditions to execute the user's instructions. For example, if the user typed "@file.com source ", the source files from the COM file would be created.
  
  
• A repack file which can be used by the vpack program or can be used stand-alone (under VMS only) to repack the COM file after making changes to the files which comprise it.
  
  
• The various sections of files which make up the COM file: source file(s), PDF file(s), etc. Each section consists of a label header ("$Source_File:"), followed by the files within the Section .

If the COM file includes an imakefile for use with vimake, the COM file header options will include many of the options utilized by the generated build file: COMPILE, ALL, SYSTEM, CLEAN, etc.). The vpack program is designed to adjust the header options based on the type of files included.

If only source files are assembled into the COM file, then the only options listed in the header will be those which unpack the various files - such options as compiling and linking will not be included. If the COM file does not include a PDF file, then the option to unpack the PDF file is omitted from the COM file, and so on.

A typical header for the view program, is shown below. Since the view program includes source files, a PDF file, test files, and an imakefile, all of these options are listed in the header file. The various options for the COM file are only available under VMS. The options are discussed in greater detail below. For further in formation on the use of vimake and the build options, see 2 vimake.

$!**********************************************************
$!
$! Compile+link proc for MIPL module view
$! VPACK Version 1.4, Thursday, June 25, 1992, 09:41:13
$!
$! Execute by entering:		$ @view
$!
$! The primary option controls how much is to be built.
$! It must be in the first parameter. Only the capitalized 
$! letters below are necessary.
$!
$! Primary options are:
$!   COMPile     Compile the program modules
$!   ALL         Build private, unpack the PDF and DOC files.
$!   STD         Build a private, and unpack the PDF file(s).
$!   SYStem      Build the system with the CLEAN option, and
$!               unpack the PDF and DOC files.
$!   CLEAN       Clean (delete/purge) code parts, see options
$!   UNPACK      All files are created.
$!   REPACK      Only the repack file is created.
$!   SOURCE      Only the source files are created.
$!   SORC        Only the source files are created.
$!               (This parameter in for compatibility).
$!   PDF         Only the PDF file is created.
$!   TEST        Only the test files are created. 
$!   IMAKE       Only IMAKE file (w/ VIMAKE program) created.
$!   DOC         Only the documentation files are created.
$!
$!   The default is use the STD parameter if non provided.
$!
$!***********************************************************
$!
$! The secondary options modify how the primary option is performed.
$! Note that secondary options apply to particular primary options,
$! listed below. If more than one secondary is desired, separate by
$! commas so the entire list is in a single parameter.
$!
$! Secondary options are:
$! COMPile,ALL:
$!   DEBug      Compile for debug           (/debug/noopt)
$!   PROfile    Compile for PCA             (/debug)
$!   LISt       Generate a list file        (/list)
$!   LISTALL    Generate a full list        (/show=all)   (implies LIST)
$! CLEAN:
$!   OBJ        Delete object and list files, purge executable (default)
$!   SRC        Delete source and make files
$!
$!***********************************************************
$!
$ write sys$output "*** module view ***"

The following options are only available when the COM file is executed under VMS. To unpack files from the COM file in the UNIX environment, the companion program vunpack must be used.

Many of these options for build will not typically be used. The recommended way of modifying an application is to unpack it, change it, and repack the results when it's ready for delivery. The same options are available on the vimake-generated BLD file. The COM file may be edited directly without unpacking, in which case these options could be useful.

• COMPile: The compile option is only available when the program's files include an imakefile created for use with the vimake utility. This option causes the COM file to create the source file(s) and the imakefile, if necessary. vimake is called to create the appropriate VMS BLD file. The COM file then executes the BLD file to carry out the compile command. This option also has several secondary options:
  
  
• DEBug: Compile for debug ( /debug/noopt)
  
  
• PROfile: Compile for PCA ( /debug)
  
  
• LISt: Generate a list file ( /list)
  
  
• LISTALL: Generate a full list ( /show=all) (implies LIST)

If, for example, you wish to compile the modules for debugging, the appropriate syntax for executing the COM file would be:

@view comp deb 

If you wanted to generate a list file as well:

@view comp deb,list 

Secondary options are separated by commas, no spaces.

The command above would generate debuggable versions of the object file(s) for the program. To create the executable, you would still need to call the BLD file with the "LINK DEBUG" parameters.

• ALL: Builds a private version of the executable in the default directory. By default, no secondary options are used. Since the ALL option carries out the COMPILE command, it accepts the same secondary options described above. The ALL option also unpacks the PDF and documentation files and calls the BLD file to carry out additional processing of the documentation files.
  
  
• STD: Carries out the same actions as the ALL command, with the exception that documentation files are not unpacked and generated. STD is the default option for portable modules (without the " -u" flag for vpack).
  
  
• SYStem: Builds the system version of the executable and executes the CLEAN option as well. None of the secondary options are activated for the COMPILE and LINK commands, while the CLEAN command has both OBJ and SRC secondary options activated. Additionally, the PDF and documentation files are unpacked and any additional processing of the documentation files needed is carried out.

This command should only be executed by Configuration Management. This option is the default (for compatibility reasons) if the "-u" (unportable) flag is passed to vpack.

• CLEAN: Deletes and/or purges files from the disk, depending on which secondary options are selected. If the OBJ option is selected, the command deletes any object and list files and purges the executable. This is the default secondary option for the CLEAN command. If the SRC option is selected, the source, imakefile, and build file are deleted. Make sure the COM file is up to date before deleting the files that make it up.

The remaining COM file options select the files unpacked from the COM file. This gives you complete control over which files are removed from the COM file. When the files are unpacked from the COM file, the COM file itself remains unaltered.

• UNPACK: All files are created.
  
  
• REPACK: Only the repackfile is created.
  
  
• SOURCE: only the source files are created.
  
  
• PDF: Only the PDF file is created.
  
  
• TEST: Only the test files are created.
  
  
• DOC: Only the documentation files are created.
  
  
• IMAKE: Only the imakefile (used with the vimake program) is created.

Since the COM file created by vpack is an ASCII text file, it is editable by the user. We recommend you follow the normal procedure of unpacking the file(s), making and testing the necessary modifications, then using vpack to rebuild the COM file.