Copy Link

Add to Bookmark

Report

Utility Program

eZine lover (@eZine)

Published in

Capital Gainz

· 27 Jul 2023

Chapter 18 - Utility Program

The Capital Gainz Utility Program gives you several handy features for manipulating your Capital Gainz data files. You can get to the Utility Program from Capital Gainz, or start it from the DOS command line:

        CGUTIL

Since the Utility Program's operations manipulate many files and records, the bottom half of the screen is a scrolling progress display. The top half of the screen is divided into the main menu on the left, and auxiliary menus on the right.
[[Screen not in online version of documentation.]]

===>>> You should be very careful when using the Utility Program, since it can potentially affect all of your current data. To this end, you must hit the Execute function key to begin an operation. Just filling in all the fields in a form will not start any operation.

18.1 Utility Menu

[[Screen not in online version of documentation.]]

The Utility Menu lists the available operations:

Upgrade to a New Revision - converts data files for any required file format changes between revisions.
Copy/Move Portfolios - copy or move an entire portfolio.
Copy/Move Local Securities - copy or move local securities between portfolios.
Import/Export File - import or export comma-delimited ASCII data files, or print out file formats.
Rebuild Price History - reconstruct the price history from the activity logs.
Rebuild/Pack Data Files - immediately reclaim space from deleted records.
Hide Account Numbers - blanks out the account number in securities.
Directory - change directories.
Exit - return to DOS. The Esc key will not exit from the Main Menu.

At the top of the menu, the current version number is displayed.

At the bottom, the remaining conventional memory is displayed. You are issued a warning if you get low on memory.

Function keys to the right of the screen are:

Enter - select the highlighted choice.
F2:Backup - copy the Capital Gainz data files to a diskette.
F7:Capital Gainz - go to Capital Gainz.
F9:Graphics - go to the Capital Gainz Graphics Program.
F10:GoTo DOS - suspend the Utility Program and invoke the DOS Shell.

18.2 Upgrade to a New Revision

[[Screen not in online version of documentation.]]

The Upgrade Form is automatically invoked on installation, if necessary. The fields are:

(Required) The Directory containing the data files you want to upgrade.
(Required) The Installed Revision number, which is the version number of Capital Gainz that was used to create the existing data files. The Utility Program can usually determine this number, but you should verify it. The version number is listed on the original Capital Gainz diskettes, the opening screen, and all documentation. If you specify an incorrect number, the Utility Program will fail, as it accesses the data files based on your entry.
The Current Revision, which is display-only.

Function keys listed at the bottom of the screen are:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

As the upgrade executes, status messages are displayed. Upgrades progress from revision to revision, so an upgrade from 2.1 to 3.1 will upgrade from 2.1 to 2.2, from 2.2 to 3.0, and finally from 3.0 to 3.1. Upgrading is a three step process:

Copy the existing data to temporary files, and remove the original files.
Create the new version's data files from the old version's temporary files.
Remove the old version's temporary files.

Failure during the upgrade process can leave your data files in an inconsistent state. Be sure that you have current backups of all data files before attempting an upgrade. If the upgrade fails, try to correct the error, restore your backup data files, and retry the upgrade.

18.3 Copy/Move Portfolios

[[Screen not in online version of documentation.]]

===>>> You can copy or move portfolios using the Utility Program. These functions are useful for:

Creating a new portfolio that mirrors the holdings in an existing portfolio.
Moving an old portfolio to a diskette for archival purposes.
Bringing together portfolios that you created in different directories.

[[Screen not in online version of documentation.]]

After choosing to copy or move a portfolio, the Utility Copy/Move Portfolio Form is displayed. You enter:

(Required) The Source Directory of the portfolio to be copied/moved. This is initialized to the current directory.
(Required) The Source Portfolio ID to be Copied/Moved. If you enter an invalid number, the Portfolio Lookup Table, described below, pops up.
(Required) The Destination Directory where the portfolio will be copied/moved to. This is initialized to the current directory. After entering a valid directory, the Utility Program sets the Destination Portfolio ID to the lowest unused ID in the destination directory.
(Optional) The Name of the Destination Portfolio, initialized to the name of the portfolio you are copying or moving.

After completing the form, you must choose one of the operations available via function keys:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

When you Copy or Move a portfolio, the following entire data files are copied from the source to the destination. If you specified Move, these files are then deleted from the source:

        Local Securities File for the portfolio   Open Shares  File for the      portfolio 
        Closed Shares File for the portfolio    Distributions  File  for the      portfolio

The Portfolio File's record for the portfolio moved is copied from the source to the destination. If you specified Move, the original portfolio record is deleted. If the source and destination directories are different, records from the following data files are copied from the source to the same file at the destination:

        Broker/Investment Company File     Global Securities File 
        Price History File              Security Type File

To see how the Capital Gainz data files are related, refer to Chapter 2.

18.3.1 Portfolio Lookup Table

[[Screen not in online version of documentation.]]

The Portfolio Lookup Table pops up if you enter an invalid portfolio ID. To select a portfolio ID, highlight it and hit Enter.

18.3.2 Example - Copy a Portfolio

Say you have 3 portfolios, 001, 002, and 003. You want to make a copy of portfolio 001:

        From Directory:C:\CAPGNZ           To Directory:C:\CAPGNZ 
          Portfolio:001 Dave's Portfolio          Portfolio:004       Mirror 
        Portfolio

The portfolio record is copied.
The local security, open shares, closed shares, and distribution files LSEC001, OPEN001, CLOSE001, and DISTR001 are copied to LSEC004, OPEN004, CLOSE004, and DISTR004.

18.4 Copy/Move Local Securities

[[Screen not in online version of documentation.]]

===>>> You can copy or move local securities using the Utility

Program. These functions are useful for:

Creating a new holding in a portfolio that mirrors an existing holding in another portfolio.
Moving information for an inactive local security to a portfolio on a diskette for archival purposes.
Bringing together local securities from different portfolios.

[[Screen not in online version of documentation.]]

After choosing to copy or move a local security, the Copy/Move Security Form is displayed. You enter:

(Required) The Source Directory of the portfolio containing the local security to be copied/moved. This is initialized to the current directory.
(Required) The Source Portfolio ID of the portfolio containing the local security to be copied/moved. If you enter an invalid number, the Portfolio Lookup Table, described earlier, pops up.
(Required) The Source Local Symbol of the local security to be copied/moved. If you enter an invalid symbol, the Local Security Lookup Table, described below, pops up.
(Required) The Destination Directory of the portfolio where the local security will be copied/moved to. This is initialized to the current directory.
(Required) The Destination Portfolio ID of the portfolio where the local security will be copied/moved to. You must have already created this portfolio in Capital Gainz. If you enter an invalid number, the Portfolio Lookup Table, described earlier, pops up.

After completing the form, you must choose one of the operations available via function keys:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

The Local Security File's record for the local security moved is copied from the source to the destination. If you specified Move, the original local security record is deleted. Related records from the following data files are copied from the source portfolio to the destination portfolio. If you specified Move, these records are then deleted from the source portfolio:

Open Shares File Closed Shares File Distributions File

If the source and destination directories are different, related records from the following data files are also copied from the source to the destination:

        Broker/Investment Company File     Global Securities File 
        Price History File              Security Type File

To see how the Capital Gainz data files are related, refer to Chapter 2.

18.4.1 Security Lookup Table

[[Screen not in online version of documentation.]]

The Security Lookup Table pops up if you enter an invalid local security symbol. To select a security, highlight it and hit Enter.

18.4.2 Example - Move a Local Security

Say you've sold all the shares for local security CPL, and want to move it to your inactive portfolio, portfolio 003:

        From Directory:C:\CAPGNZ           To Directory:C:\CAPGNZ 
          Portfolio:001 Dave's Portfolio          Portfolio:003  Dave's  Old Stuff 
          Local Symbol:CPL Carolina Power & Light

The local security record is copied from LSEC001 to LSEC003, and then deleted from LSEC001.
Open shares, closed shares, and distribution records for CPL are copied from OPEN001, CLOSE001, and DISTR001 to OPEN003, CLOSE003, and DISTR003, and then deleted from OPEN001, CLOSE001, and DISTR001.

18.5 Import/Export

[[Screen not in online version of documentation.]]

You can import or export comma-delimited ASCII files, or just print out the internal file format, using the Utility Program. These functions are useful for:

Printing out the Capital Gainz data file types and formats.
Exporting data to verify the contents of all fields, or to make minor changes.
Exporting data for use in another program, such as a spreadsheet.
Importing data from another program.
Exporting data from damaged data files, to salvage any non-corrupt data. You should have been performing regular backups instead.

===>>> Because Capital Gainz consists of many related data files, importing data from other programs, or exporting data to other programs, is not a simple task. It's very easy to end up with data that Capital Gainz cannot access, or to build data files with incorrect data. Be sure you thoroughly read and understand the sections on importing and exporting data below, as well as the description of the Capital Gainz data files in Chapter 2. That chapter also shows how the Capital Gainz data files are related.
[[Screen not in online version of documentation.]]

After choosing to import, export, or print a file format, the Select Data File Menu is displayed. Choose one of the displayed files to operate on. The User Settings File is a DOS file, and is not available. If you are importing or exporting data and select the Local Security, Open Shares, Closed Shares, or Distributions File, you are asked for the portfolio ID. If you leave this blank, or enter an invalid portfolio ID, the Portfolio Lookup Table, described earlier, pops up.
[[Screen not in online version of documentation.]]

After selecting a data file, you enter the following in the Import/Export Form:

The name of a file for importing from, exporting to, or printing the file format to. On import, if this file does not exist, an error is returned. On export or format printing, if this file exists it is appended to, and if it does not exist, it is created.

The date format to use, either INTERNAL or STRING, for import/export. Some Capital Gainz data files have date fields. The INTERNAL format used by Capital Gainz is a 32 bit integer containing the number of days since 1801. Since this date is not readily used outside of Capital Gainz, you have the option of using a STRING type, formatted as MM/DD/YY (i.e., 12/10/91).

Then you must choose one of the function keys:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

18.5.1 Import Comma-Delimited File

Importing data using the Utility Program is difficult due to data file relationships. For instance, if you import data into the Open Shares File:

The symbols referenced must also be imported into the Local Securities File, if they don't exist.
The data imported into the Local Securities File must have correct open shares information. Alternatively, you can use the Total function on the Capital Gainz Local Security Fixup Form.
The global symbols referenced in the Local Securities File also must be imported into the Global Securities File, if they don't exist.
The broker/investment companies referenced in the Local and Global Security Files must also be imported into the Broker/Investment Company File, if they don't exist.
The global securities' price histories also must be imported into the Price History File, if they don't exist. Or, you can use the Utility Program's Rebuild Price History function.
The global securities' types also must be imported into the Security Type File, if they don't exist.

As you can see, importing data from other programs is a tricky task. A much better use for the import function is to make minor tweaks to data files:

Export the data file.
Use an ASCII text editor to make the minor changes to the number of shares, amounts, etc.
Delete or rename the original data file.
Import the file containing the changes.

In any case, importing data is only recommended in exceptional circumstances, and even then should only be attempted by experienced users. It's too easy to end up with data that can't be accessed from the main Capital Gainz program.

18.5.2 Export Comma-Delimited File

Exporting data lets you scan the contents of your data files for minor errors. If you find any problems, then you can modify the records with a text editor and import the file. However, it's strongly recommended that you manage changes through Capital Gainz itself whenever possible.

You also can export data in order to import it into another program. Most programs that support data imports can accept comma- delimited input. Before importing the data, you may need to modify the data with a text editor.

18.5.2.1 Example - Export Data

The most common type of program that you would import data into is a spreadsheet, like As-Easy-As. This lets you further analyze your investment data, and also generate graphs (if you need more control than available in the Graphics Program). To aid in this process, the Capital Gainz data file formats can be printed to a file, and exported data is in key order. As an example, here's the steps involved in generating a line graph of prices using As-Easy-As:

Export the Price History File to PRC.EXP. Specify the STRING date format.
Use a text editor to remove all records except a single symbol's price records. For instance, get rid of all records except those where the symbol is CPL and the type is PRC.
Start up As-Easy-As.
From the / menu, choose File, Import, Values, and specify PRC.EXP as the file name. This fills in columns A, B, C, and D with the symbol, date, type, and price.
From the / menu, choose Graphics, Type, Line. For the Range, set X to the entire B column (date) and A to the entire D column (price).
Change the scales as needed. For instance, you may want A to range from 0 to 100 dollars. Also, you may want to add labels.
View the graph.

18.5.3 Print Comma-Delimited Format

This function lets you print out the field names and types in the Capital Gainz data files. This is handy when importing or exporting data.

18.6 Rebuild Price History

[[Screen not in online version of documentation.]]

You can clean out the Price History File and rebuild it based on data in the Open Shares, Closed Shares, and Distribution Files. You may want to do this if:

Your Price History File has gotten very large, and you want to trim it down.
You inadvertently deleted or changed records, and want to reset the Price History File.

From the function keys, you can:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

===>>> All price history entries that do not correspond to a buy, sell, or distribution record will be deleted. If you just want to add back some activity prices, then export the Price History File, rebuild the price history, then import the Price History File that you initially exported.

18.7 Rebuild/Pack Data Files

[[Screen not in online version of documentation.]]

===>>> Capital Gainz data files do not automatically release space for deleted records. Instead, the deleted record area is reused when you add new records. Thus, if you delete many records, then the disk space used by the file will not change. However, as you add new records, the disk space used will not increase until the number of new records exceeds the number of records deleted.

If you want to reclaim space from deleted records immediately, use the Rebuild/Pack Data Files option. From the function keys, you can:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

18.8 Hide Account Numbers

[[Screen not in online version of documentation.]]

This option blanks out the Account Number field in all local and global security records. This lets you remove sensitive data before sending it to us in order to fix or analyze a problem. Normally, you'd copy your data files to a diskette, then run the Utility Program and switch directories before executing this option. From the function keys, you can:

Execute - accept all entries and execute the indicated operation.
Exit - exit immediately, the same as hitting Esc to back out of the form.

18.8.1 Example - Hide Account Numbers

You're having some strange problems, and decide to send us your data to analyze. As a security measure, you want to mask out the account numbers.

Copy all of your data files, *.DAT and *.K01, to the disk in drive A:.
Run the Utility Program, and choose Directory. Set the directory to A:\.
Choose the Hide Account Numbers option to blank out account numbers in all the local and global securities on drive A:.
Send us the disk with the data, along with a description of the problem.

18.9 Directory

[[Screen not in online version of documentation.]]

You can change the current directory from the Utilities Menu. However, several options already allow you to specify source and destination directories.

18.10 Backup

[[Screen not in online version of documentation.]]

The Utility Program options affect many files and records, so it's a good idea to backup your data. If you answer YES, your data files are backed up to disk with the DOS COPY command, rather than the Capital Gainz Backup Command setting. The reason is that the Utility Program can move between directories, so the batch file used to backup, such as CAPGNZBU.BAT, may not be available.