HP 3000 Manuals HP 3000 Manuals
VPlus VMERGE Utility User's Guide by Mike Kerwan and Rachel Schwab Commercial Systems Division Introduction This article serves two purposes: to introduce the VMERGE utility, and to provide a User's Guide with all the information you need to use VMERGE.
\ \ \ Important Details \ Please Read This "VPlus VMERGE Utility User's Guide" only appears in this 5.0 release of the Communicator. Retain this copy if you will be using VMERGE.
VMERGE is a new VPlus utility that allows you to combine two or more separately-compiled VPlus forms files into a single forms file, which may then be used with an application program to manage the entry and/or retrieval of data. Combining multiple forms files with VMERGE provides the following advantages: * Some file size limitations can be overcome. Since there are limitations on how many physical records can be placed in a VFORM file, VPlus users sometimes find that they cannot use a single forms file to hold all the forms their application requires. With VMERGE, it is possible to add more forms (from a second forms file) to the ones in the initial forms file, even if the first is at or near the maximum size. * It is sometimes easier to maintain a large forms file as several separately compiled "modules" that can then be combined with VMERGE rather than to maintain one large forms file. Overview VMERGE usually resides in PUB.SYS. It may be run on either MPE/iX or MPE V. Before VMERGE is invoked, you must specify two input forms files and one output file. The input files are specified with file equations for the formal designators VMASTER and VAUX. The output file is specified with a file equation for the formal designator VOUTPUT. VMASTER and VAUX must exist, and each may be of type VFORM (slow forms file) or VFAST (fast forms file). VOUTPUT is created by the VMERGE utility and is of type VFAST. As VMERGE runs, informative messages are presented on $STDLIST. If any problems are encountered, appropriate error messages are displayed. These message are described in the "VMERGE Messages" section in this article. Forms File Handling by FORMSPEC and VMERGE VPlus forms files exist in files with two different file codes: VFORM (slow forms file) and VFAST (fast forms file). VFORM files are created and modified with FORMSPEC. VFORM files contain the "source" for each form in the file, coded in a way that FORMSPEC can understand. When a forms file is compiled by FORMSPEC, "object" forms are added to the VFORM file. The object forms are accessed when the forms file is used with ENTRY or another application program that invokes the VPlus intrinsic functions. When you use FORMSPEC to compile a VFORM file, you may request the creation of a fast forms file. This file contains only the object forms for the forms in the specified VFORM file. Processing the VFAST file is fast because the file is smaller than its corresponding VFORM file. That is, the fast forms file does not contain source forms and, therefore, can be accessed faster. Since a fast forms file does not contain source forms, it cannot be modified by FORMSPEC. Both VFORM and VFAST files are limited in the number of records they can hold. However, the problem is more severe with VFORM files since they contain both source and object forms. Previously, the only way to create a fast forms file was by compiling a VFORM file with FORMSPEC. Consequently, you might have been unable to include forms that theoretically could have fit into a VFAST file, since the source and object forms might have been too large to fit into a VFORM file. Now, VMERGE gives you an alternate method for generating VFAST files that contain additional forms. However, VFAST files still have limited capacity, and so there are still limits on the total number of forms you can place in a forms file, even using VMERGE. Initial analysis shows that the ratio of fast form file size to slow form file size is around 1/3 to 1/10. This suggests that you can expect to combine forms from three or more nearly full (to FORMSPEC) forms files into one forms file, by using VMERGE. However, this is an estimate only, since non-typical forms files may vary considerably in their object to source ratios. Input File Compatibility Not all forms files can be successfully combined using VMERGE. The input forms files must be "compatible" in order to be combined with VMERGE. The compatibility factors are: * Form names--the same form name may not appear in both the VMASTER and the VAUX files. * Save fields--if both input files use save fields, the specifications for both files must be identical in all respects: names of save fields, lengths, data types, and initial values. The save fields must also be defined in the same order. It is permissible for one file to use save fields and the other not to do so. * Global function key labels--if both input files define global function key labels, the specifications for both files must be identical in all respects. It is permissible for one file to define global function key labels and the other not to do so. In this case, the global function key labels from the file which contains them will be retained in the output file. * Terminal selection and language id--both input files must have exactly the same set of terminals selected and the same Forms File Language specified (from FORMSPEC Terminal/Language Selection Menu). There are a number of forms file characteristics that may differ between the two input files that are not serious enough for VMERGE to consider the two files as incompatible. These include: head form name, error enhancement, window display line, error window color, and window enhancement. The characteristic found in the VMASTER file is retained in the VOUTPUT file. Application Requirements for Combined Forms Files VMERGE takes two FORMSPEC-compiled forms files specified by the VMASTER and VAUX file designators, extracts the object forms from each file, and places these forms in a VFAST file specified by the VOUTPUT file designator. Every forms file has a $HEAD form designated for it. Additionally, every form in a forms file has a "Next Form" designated for it. Next Form may be $HEAD or it may be the name of another form in the file. In order to compile a forms file, FORMSPEC requires that any form named as the $HEAD or as a Next Form exist in the file. Consequently, it is impossible for a form in the VMASTER forms file to refer to a form in the VAUX forms file as its Next Form and vice versa. Therefore, the application program used with a combined forms file must be coded to sequence among the forms in the combined forms file without depending on the Next Form designation. The Next Form designation can only be used when it and the current form originated from the same forms file. VMERGE users should be aware that VMERGE makes the $HEAD form from VMASTER the $HEAD for VOUTPUT. If data entry operators are used to seeing the $HEAD form from the VAUX file, they may be surprised if this $HEAD form is no longer what is displayed when they bring up their application. Technical Reference VMERGE normally resides in PUB.SYS; if it is moved from PUB.SYS, it must be moved to a group with "DS" capability. VMERGE is invoked with the following command: :RUN VMERGE.PUB.SYS Before invoking VMERGE, three file equations must be given. The two VMERGE input forms files are indicated by the file designators VMASTER and VAUX. VMASTER and VAUX must designate existing forms file, with file codes VFORM or VFAST. The VMASTER and VAUX files must have been compiled with a recent version of FORMSPEC. If an input file is provided that does not meet this criterion, a message is given, and VMERGE processing halts. VMERGE's output VFAST forms files is indicated by the file designator VOUTPUT. If the designated file already exists and has the file code VFAST, then it is purged and recreated by VMERGE. If the file exists but has a file code other than VFAST, the file is not purged, a warning message is given, and VMERGE halts. The files used by VMERGE are opened for exclusive use to avoid concurrent update problems. Two JCWs (job control words) are defined for use with VMERGE: VMERGETERSE and VMERGEERROR. If the user sets VMERGETERSE to 1 before running VMERGE, then the messages indicating the form names contained in the VMASTER and VAUX files are suppressed. The VMERGEERROR JCW is set by VMERGE after it runs. If VMERGE detected a severe error that prevented the VOUTPUT file from being successfully created, VMERGEERROR is set to 1. If VMERGE successfully created the VOUTPUT file, VMERGEERROR is set to 0. Example 1: Using VMERGE to Combine Forms Files Suppose your company has three distinct uses for an order form prepared by a salesperson. The order form is used in the shipping department, the billing department, and the marketing department. Currently the original order form is passed among three clerks who each enter their data using their own VPlus forms files (SHIPFF, BILLFF, and MARKETFF) that are distinct to their respective departments. Your job is to merge the forms files and fix the application program so that one clerk can enter the data for all three departments. You decide that each of the three application areas (shipping, billing, and marketing) should be selectable by pressing a function key. Once an area has been selected, processing will be performed using the same sequence as when the application for that area existed on its own. Remember that while combining the three applications into one, you will need to examine the effect of $HEAD being different from what two of the original three programs expected. Most likely, you will want to create a new form to serve as the $HEAD for the combined application. After examining and fixing the application program, you will need to look at the forms files and make them compatible, if they are not already. You will need to make sure that the save fields, if any, have distinct names and are identical in each of the forms files that uses them. Additionally, you will need to check that the global function key specifications are compatible in the three forms files. Note that in some cases incompatibilities may be so extensive that it will be impossible to merge the forms files. Next you determine what order to merge the forms files together. Suppose in this example that the marketing forms file is much more volatile than the other two. Therefore, you decide that this file should be the last one merged. You also need to decide which form your combined application should use as its $HEAD. Suppose in this example you depend on the $HEAD form from BILLFF being the $HEAD of the combined forms file. Combining the forms files is accomplished in two stages. In the first stage you enter: :FILE VMASTER=BILLFF :FILE VAUX=SHIPFF :FILE VOUTPUT=INTERFF :RUN VMERGE.PUB.SYS VMERGE creates the intermediate forms file INTERFF. In the second stage you enter: :FILE VMASTER=INTERFF :FILE VAUX=MARKETFF :FILE VOUTPUT=COMBOFF :RUN VMERGE.PUB.SYS VMERGE creates the final forms file COMBOFF. You may wish to keep the intermediate forms file, INTERFF, so you won't need to recreate it if only MARKETFF changes. Now you could test COMBOFF with your combined application program. Example 2: Using VMERGE to Divide a Forms File Another use of VMERGE is to divide an existing forms file into two or more smaller forms files. This might be desirable if different forms in the original forms file were going to be modified by different people, or if compiling the entire forms file takes a long time. When VMERGE is used to divide a file, there are few compatibility problems since the original form file is already "merged". You will have to be careful not to introduce incompatibilities (for example, refer to the $HEAD and Next Form issues discussed earlier) as a result of dividing the file. Suppose you want to remove forms F1, F2, and F3 from a forms file named BIGFF and place them into another forms file, LITTLEFF. The F1, F2, and F3 forms are changed often, and you want to separate them out in order to minimize the time it takes to recompile each time changes are made. First, you would FCOPY BIGFF to LITTLEFF by entering the following command: :FCOPY FROM=BIGFF;TO=LITTLEFF;NEW Second, you would run FORMSPEC on BIGFF to delete forms F1, F2, and F3. You would need to correct the Next Form fields for any affected forms. Third, you would probably want to make advantage of some of FORMSPEC's batch mode facilities to delete all but the F1, F2, and F3 forms from LITTLEFF (see the Deleting Forms Using FORMSPEC's Batch Mode Facilities section below). Fourth, you would compile both forms file to verify that no $HEAD or Next Form dependencies exist. The compilation for BIGFF will be lengthy, but it will only need to be done once. Fifth, you would make your changes to the forms in LITTLEFF and add additional forms that could not be put into BIGFF due to size limitations. After you had taken all these steps you could combine the two forms files with VMERGE: :FILE VMASTER=BIGFF :FILE VAUX=LITTLEFF :FILE VOUTPUT=SUPERFF :RUN VMERGE.PUB.SYS Check your application using the SUPERFF forms file. VMERGE Messages Following are the messages produced by the VMERGE utility. The cause of each, and the action you may take is also described. Message: hp32209V.UU.FF VMERGE (c) Hewlett-Packard Co. 1992 ALL RIGHTS RESERVED Cause : Header generated at the start of VMERGE processing. Action : None. ________________________________________________________________________ Message: *****Internal processing error (VM1001) Cause : An unexpected condition has been detected by VMERGE. Action : Preserve the input files for diagnosis and contact HP rep. ________________________________________________________________________ Message Begin VMERGE Processing... (VM1003) Cause : Given at the start of processing. Action : None. ________________________________________________________________________ Message: No consistency check required, AUX file is $NULL (VM1004) Cause : Self-explanatory. Action : None. ________________________________________________________________________ Message: Consistency check of MASTER and AUX files begun ...(VM1005) Cause : Self-explanatory. Action : None. ________________________________________________________________________ Message: Input files are consistent (VM1006) Cause : The consistency check of MASTER and AUX has been completed, and the files have been found consistent. Action : None. ________________________________________________________________________ Message: ***** Input files are not consistent (VM1007) Cause : The consistency check of MASTER and AUX has been completed, and the files have been found inconsistent. (Normally an explanatory message indicating why they are inconsistent will have been issued prior to this one.) The OUTPUT file will not be produced. Action : Adjust the input files to overcome the indicated inconsistency and rerun VMERGE. ________________________________________________________________________ Message: End of VMERGE Processing. (VM1009) Cause : Self-explanatory. Action : None. ________________________________________________________________________ Message: ***** Form name table could not be allocated (VM1400) Cause : An attempt to allocate an extra data segment to hold a form name table for the MASTER or AUX forms has failed. Action : Consult with your system administrator to determine why this failure occurred on your system. This is probably due to limitations on the number of Extra Data Segments that can be created in your configured environment. ________________________________________________________________________ Message: ***** Form name table overflow (VM1401) Cause : More forms have been found in the MASTER or AUX file than can be accommodated in the form name table. Action : Contact your HP rep. ________________________________________________________________________ Message: ***** Conflicting data in MASTER forms file (VM1402) Cause : Invalid or inconsistent data has been found in the MASTER file. Action : Recreate the file and rerun VMERGE. If the problem persists, contact your HP rep. ________________________________________________________________________ Message: ***** Conflicting data in AUX forms file (VM1403) Cause : Invalid or inconsistent data has been found in the AUX file. Action : Recreate the file and rerun VMERGE. If the problem persists, contact your HP rep. ________________________________________________________________________ Message: **** Error accessing table in an extra data segment (VM1404) Cause : An attempt to access data in an extra data segment was rejected by the MPE operating system. Action : Rerun VMERGE. If the problem persists, contact your HP rep. ________________________________________________________________________ Message: ***** Version of MASTER file format not supported by VMERGE (VM1500) Cause : The MASTER file was compiled with a version of FORMSPEC that is not supported by VMERGE. (Versions prior to B.03.03 are not supported.) Action : Reconstruct the file with the current version of FORMSPEC. ________________________________________________________________________ Message: ***** Version of AUX file format not supported by VMERGE (VM1501) Cause : The AUX file was compiled with a version of FORMSPEC that is not supported by VMERGE. (Versions prior to B.03.03 are not supported.) Action : Reconstruct the file with the current version of FORMSPEC. ________________________________________________________________________ Message: Warning: Error enhancement settings differ (VM1504) Cause : The error enhancement settings differ in the MASTER and AUX files. Action : None. (The value from the MASTER file is retained in OUTPUT.) ________________________________________________________________________ Message: Warning: Window display line settings differ (VM1505) Cause : The display line settings differ in the MASTER and AUX files. Action : None. (The value from the MASTER file is retained in OUTPUT.) ________________________________________________________________________ Message: Warning: Error window color settings differ (VM1506) Cause : The error window color settings differ in the MASTER and AUX files. Action : None. (The value from the MASTER file is retained in OUTPUT.) ________________________________________________________________________ Message: Warning: Window enhancement settings differ (VM1507) Cause : The window enhancement settings differ in the MASTER and AUX files. Action : None. (The value from the MASTER file is retained in OUTPUT.) ________________________________________________________________________ Message: ***** Terminal Specific settings differ (VM1508) Cause : The terminal settings differ in the MASTER and AUX files. Action : Revise the files to make them compatible and rerun the utility. ________________________________________________________________________ Message: ***** Language ID settings differ (VM1509) Cause : The language id settings differ in the MASTER and AUX files. Action : Revise the files to make them compatible and rerun the utility. ________________________________________________________________________ Message: ***** Number of databases differ (VM1510) Cause : The number of databases differ in the MASTER and AUX files. Action : Revise the files to make them compatible and rerun the utility. ________________________________________________________________________ Message: ***** Save fields specifications differ (VM1521) Cause : The save field specifications differ in the MASTER and AUX files. Action : Revise the files to make them compatible and rerun the utility. The save field specifications must be identical in all respects in both input files. ________________________________________________________________________ Message: ***** Global function key labels differ (VM1531) Cause : The global function key labels differ in the MASTER and AUX files. Action : Revise the files to make them compatible and rerun the utility. ________________________________________________________________________ Message: ***** 307x terminal settings differ (VM1541) Cause : The 307x terminal settings differ in the MASTER and AUX files. Action : Revise the files to make them compatible and rerun the utility. ________________________________________________________________________ Message: Form name "nnnnnnnnnnnnnnn" found in MASTER file (VM1601) Cause : Documents that the named form was found in the MASTER file. Action : None. ________________________________________________________________________ Message: Form name "nnnnnnnnnnnnnnn" found in AUX file (VM1603) Cause : Documents that the named form was found in the AUX file. Action : None. ________________________________________________________________________ Message: ***** MASTER and AUX contain duplicate form name(s) (VM1611) Cause : Forms with the same name were found in both the MASTER and AUX files. Action : Remove or rename the duplicate forms from one file and rerun VMERGE. ________________________________________________________________________ Message: ***** Duplicate form name: nnnnnnnnnnnnnnn (VM1612) Cause : Identifies a form name found in both the MASTER and AUX files. Action : Remove or rename the duplicate form form one file and rerun VMERGE. ________________________________________________________________________ Message: ***** Unattached messages; use fast forms files (VM1613) Cause : Messages have been found that are not associated with any form. OUTPUT file is not produced. Action : Compile the input files and produce fast forms files. Use the fast forms files as input to VMERGE. ________________________________________________________________________ Message: ***** MASTER file could not be opened (VM1700) Cause : The file designated as MASTER could not be opened. Action : Remove the impediment to opening the file and rerun VMERGE. (The file may not exist under the designated name, or may be already open for exclusive use, etc.) ________________________________________________________________________ Message: ***** Error reading MASTER file (VM1701) Cause : An error occurred in attempting to read the MASTER file. Action : Regenerate the file and rerun VMERGE. ________________________________________________________________________ Message: ***** Error in MASTER file data (VM1702) Cause : An inconsistency was found in the data in the MASTER file. Action : Recreate the file and rerun the utility. If the problem persists contact your HP rep. ________________________________________________________________________ Message: MASTER file opened (VM1703) Cause : Self-explanatory. Action : None. ________________________________________________________________________ Message: ***** MASTER file type is not VFORM or VFAST (VM1704) Cause : Self-explanatory. Action : Designate the correct file and rerun VMERGE. ________________________________________________________________________ Message: MASTER file designated as: fff...f (VM1705) Cause : Shows the full pathname of the MASTER file. Action : None. ________________________________________________________________________ Message: ***** MASTER file has not been compiled (VM1706) Cause : Self-explanatory. Action : Compile the MASTER file and rerun VMERGE. ________________________________________________________________________ Message: ***** AUX file could not be opened (VM1800) Cause : The file designated as AUX could not be opened. Action : Remove the impediment to opening the file and rerun VMERGE. (The file may not exist under the designated name or may be already open for exclusive use, etc.) ________________________________________________________________________ Message: ***** Error reading AUX file (VM1801) Cause : An error occurred in attempting to read the AUX file. Action : Regenerate the file and rerun VMERGE. ________________________________________________________________________ Message: ***** Error in AUX file data (VM1802) Cause : An inconsistency was found in the data in the AUX file. Action : Recreate the file and rerun the utility. If the problem persists contact your HP rep. ________________________________________________________________________ Message: AUX file opened (VM1803) Cause : Self-explanatory. Action : None. ________________________________________________________________________ Message: ***** AUX file type is not VFORM or VFAST (VM1804) Cause : Self-explanatory. Action : Designate the correct file and rerun VMERGE. ________________________________________________________________________ Message: AUX file designated as: fff...f (VM1805) Cause : Shows the full pathname of the AUX file. Action : None. ________________________________________________________________________ Message: ***** AUX file has not been compiled (VM1806) Cause : Self-explanatory. Action : Compile the AUX file and rerun VMERGE. ________________________________________________________________________ Message: ***** OUTPUT file could not be opened (VM1900) Cause : Self-explanatory. Action : Remove the impediment to opening the OUTPUT file and rerun VMERGE. ________________________________________________________________________ Message: **** Error writing OUTPUT file (VM1901) Cause : Self-explanatory. Action : Correct the problem that has caused the write error and rerun VMERGE. You may need to consult with your system administrator to determine the problem. ________________________________________________________________________ Message: OUTPUT file opened (VM1903) Cause : Self-explanatory. Action : None. ________________________________________________________________________ Message: ***** OUTPUT file type is not VFAST (VM1904) Cause : The file designated as OUTPUT pre-exists but is not of type VFAST. Action : This is viewed as an error since it is assumed that the user has unintentionally designated the name of a file being used for other purposes. Redesignate the OUTPUT file (or purge the old file if the name is correct) and rerun VMERGE. ________________________________________________________________________ Message: OUTPUT file designated as: fff...f (VM1905) Cause : Shows the full pathname of the OUTPUT file. Action : None. ________________________________________________________________________ Message: Error closing OUTPUT file (VM1906) Cause : Self-explanatory. Action : Correct the problem that has caused the error and rerun VMERGE. You may need to consult with your system administrator to determine the problem. ________________________________________________________________________ Message: ***** OUTPUT file purged (VM1911) Cause : Inconsistency or some other problem has prevented the OUTPUT file from being successfully generated. To avoid confusion, the file is purged. Action : Correct the underlying problem and rerun VMERGE. ________________________________________________________________________ Message: ***** OUTPUT file pre-existed and could not be purged (VM1912) Cause : An attempt to purge the existing file with the name designated for the OUTPUT file failed. Action : Make sure that the correct file name has been designated. If so, determine why it could not be purged and remove the impediment. ________________________________________________________________________ Deleting Forms Using FORMSPEC's Batch Mode Facilities Suppose you wanted to delete all forms but F1, F2, and F3 from a forms file named LITTLEFF. To accomplish this, you would take the following steps: 1. Use the FORMSPEC "FORMS" command to generate a list of forms in LITTLEFF and redirect the list to a disk file. :FILE FORMOUT;REC=-80,16,F,ASCII;DEV=DISC;TEMP :RUN FORMSPEC.PUB.SYS;INFO="$STDIN" >FILE LITTLEFF >FORMS >EXIT :SAVE FORMOUT :RENAME FORMOUT,FORMCMDS :RESET FORMOUT 2. Bring FORMCMDS into an editor. Delete all lines that do not list form names. Delete the lines listing forms F1, F2, and F3. Insert the keyword "DELETE" in front of every other form name. Delete the text remaining after the form name. 3. Add the command FILE LITTLEFF as the first line in the file. 4. Add an EXIT command as the last line in the file. 5. Keep the update FORMCMDS file and exit the editor. 6. Execute the commands in the FORMCMDS file. Note: you may want to do this within a job file.