TOCPREVNEXTINDEX

Lund Performance Solutions


The KLONDIKE Tool
The KLONDIKE tool is used to load (i.e., fetch) data files into memory. Once loaded in memory, KLONDIKE can "freeze" that file into memory so that it is immediately accessible to the programs that require that information. Later, KLONDIKE’s "thaw" command can be used to unload the file from memory. Freezing commonly used files can have a large impact on performance.

NOTE In the text of the documentation for KLONDIKE, references made to "page" refer to a logical page of 4,096 bytes.


Operation

KLONDIKE is a tool that can be used to improve access time to objects that are loaded into memory. It does this in several ways.
You can use KLONDIKE to fetch a file into memory. What this is really doing is "pre-fetching" a file into memory. The reason for doing this is that if you know that a given operation would benefit from having its data in memory, the you can achieve performance gains by prefetching it with KLONDIKE. For example, when you compile a program, if you fetch the source into memory, then it will save the operating system the task of checking and possibly loading the source into memory.

NOTE Fetching a file into memory does not guarantee that it will stay there. On a busy system or a system without much "user memory" (see "The PAGES Tool" on page 143 for a description of user memory) the likelihood is high that your data will at least be partially swapped out before you access it. Also, on systems with low amounts of memory, it may not be possible to fetch an entire file into memory.

You can use KLONDIKE to freeze a file into memory. This is similar to fetching except a frozen file will not be swapped out like a fetched file would. KLONDIKE’s "unfreeze" or "thaw" commands will free up that frozen file. Freezing a file into memory guarantees better access to the file. Keep in mind though that you could actually reduce system performance, depending on the amount of memory in your machine, since you have in effect taken away (frozen) some of the memory that is normally available. This can lead to a situation where thrashing occurs.
KLONDIKE and PAGES are closely related in terminology. So, you may find it helpful to review the section on PAGES.

Capabilities

Program capabilities required include IA, BA, PM, DS and PH. User SM capability is required for the FREEZE and THAW commands.

Usage

To run KLONDIKE either use the supplied UDCs or use a fully-qualified RUN command.
  • UDC

  • :KLONDIKE
    Starts KLONDIKE, no parameters
    :COUNT <filename>
    Report on % of file in memory
    :FETCH <filename>
    Fetches a file into memory

  • RUN
  • :RUN KLONDIKE.PUB.LPSTOOLS;INFO=“[commands]”

    NOTE filename can be either an MPE or POSIX filename.


    Command Summary

    The following list provides a summary description of KLONDIKE commands that you can use to quickly locate the command that suits the task at hand. Detailed information on each command is provided in the next section.

    NOTE Portions of the command codes are printed in uppercase to denote the part of the command that KLONDIKE requires in order to distinguish one command from another. However, the commands themselves are not case-sensitive.


    Table 9.1 KLONDIKE commands
    Command Code
    Description
    COUNT
    Displays percentage of file in memory
    Exit
    Terminates the program
    FETCH
    Loads file into memory
    FREEZE
    Freezes file into memory
    Help
    Displays context-sensitive Help text
    Open
    Tests access to a file
    POST
    Writes file to disk
    SET/REset
    Enables or disables KLONDIKE options
    THAW
    Unfreeze file from memory (same as UNFREEZE)
    UNFREEZE
    Synonym for THAW

    Command Definitions

    Listed below are detailed descriptions of each KLONDIKE commands. Syntax is provided in some cases.

    COUNT

    The COUNT command has the following syntax:
    COUNT <filename>
    This command is used to count the number of pages of a file that are currently in memory and then displays the results on the screen. It shows the percentage of a file in memory, as well as the number of logical pages in memory. More information is displayed if the VERBOSE option is selected.

    FETCH

    This command has the following syntax:
    FETCH <filename> [[# <Pages | Bytes> | ALL]] [ <WAIT | NOWAIT> ]
    The FETCH command opens the specified file and attempts to fetch the specified number of pages (or bytes) into memory, starting at the beginning of the file.

    WAIT
    Instructs KLONDIKE to wait until all of the fetched pages are in memory before continuing.
    NOWAIT
    (default) Instructs KLONDIKE not to wait for all of the pages to be read into memory before continuing.


    NOTE Attempts to fetch more than 200 pages at a time will be broken into multiple smaller fetches automatically. This is done to prevent overloading the system with large requests.

    FREEZE

    This command has the following syntax:
    FREEZE <filename> [ALL | [# <Pages | Bytes>]]
    The FREEZE command opens the specified file and attempts to freeze the file into memory. The entire file will be frozen. A file frozen with the FREEZE command can be unfrozen with the THAW command (or its synonym, UNFREEZE).
    If a page of a file is frozen, and then updated, the data will NOT be posted to disk until sometime after the file is THAWed or until a POST command is done.

    OPEN

    The OPEN command has the following syntax:
    OPEN <filename>
    This command is used to test the access to a file.

    POST

    This command has the following syntax:
    POST <filename> [# <Pages | Bytes> | ALL] [<WAIT | NOWAIT>]
    The POST command opens the specified file and attempts to post (force a write to disk) the specified number of pages (or bytes) from memory, starting at the beginning of the file.

    WAIT
    (default) Instructs KLONDIKE to wait until all of the posted pages have been written to disk before continuing.
    NOWAIT
    Instructs KLONDIKE not to wait for all the disk writes to finish.

    SET | REset

    The SET/RESET commands are used to specify the following options. Use these options to enable or disable information-reporting features.

    PARTIAL
    SET sets the specified options to "true". RESET sets the standard options to "false".
    If PARTIAL is true, KLONDIKE will allow partial file specification for some commands like: POST, FREEZE, and FETCH.
    TIMES
    SET sets the specified options to "true". RESET sets the standard options to "false".
    If TIMES is true, KLONDIKE will report on information relating to how much cpu time & wall time were required to perform a task.
    VERBOSE
    SET sets the specified options to "true". RESET sets the standard options to "false".
    If VERBOSE is true, KLONDIKE will report more information about a file in memory than it would if VERBOSE is false.

    THAW | UNFREEZE

    These commands have the following syntax:
    THAW <filename>
    or
    UNFREEZE <filename>
    These two commands perform the exact same operation. What they do is open the specified file and unfreeze the file from memory. The entire file will be unfrozen.

    TOOLBOX STANDARDS

    The ToolBox collections from Lund Performance Solutions have a uniform user interface. As a result, in addition to the commands specific to each Toolbox tool, most tools allow the commands described in "TOOLBOX STANDARDS".

    KLONDIKE Examples

    Following are examples of the KLONDIKE tool.
    Figure 9.1 shows how the COUNT command is used and what the output looks like:


    Figure 9.1 COUNT Command
    Figure 9.2 shows the effect of the Verbose and Times options when used with FETCH:


    Figure 9.2 Verbose and Times Options
    Figure 9.3 shows how to freeze a source file into memory:


    Figure 9.3 Freezing a Source File into Memory
    Figure 9.4 uses the CPUNT command to show that, indeed, the file has been frozen into memory. Then, the THAW command is used to unfreeze the file. Finally, the COUNT command is used to verify that the file was unfrozen:


    Figure 9.4 COUNT and THAW Commands

    KLONDIKE Error Messages

    In the error messages that follow, "xxxx" refers to a number that is filled in at runtime by KLONDIKE.
    Table 9.2 KLONDIKE Error Messages
    Message
    Cause
    Action
    Attempted to fetch "xxxx" logical pages, which is illegal.
    User tried to fetch ZERO or less pages.
    KLONDIKE can only fetch a positive number of pages.
    Cannot freeze...file already has "xxxx" frozen pages.
    At least one page of the specified file is already frozen (KLONDIKE does not support partial file freezes).
    Determine who or what has frozen the file, unfreeze it, and then use KLONDIKE to freeze the file.
    File is already frozen.
    User tried to freeze a file that was previously frozen.
    KLONDIKE can only freeze a file once.
    File won’t fit in memory...won’t freeze it. Memory is only "xxxx" pages of 4,096 bytes.
    An attempt was made at freezing a file into memory that was larger than the amount of memory available on the system.
    Reduce the size of the file before freezing it.
    KLONDIKE will not freeze/thaw file in spaces $A or $B due to possible undesirable consequences.
    KLONDIKE was instructed to perform a freeze or thaw command into memory currently used by the operating system.
    No action is required, this is a warning only.
    Limiting fetch to "xxxx" logical pages (size of memory).
    User tried to fetch a file that is larger than the amount of memory on the machine.
    No action is required, this is a warning only.
    The file is not frozen...cannot unfreeze.
    User tried to unfreeze a file that was not frozen in the first place.
    Only previously frozen files can be unfrozen.

    Lund Performance Solutions
    www.lund.com
    Voice: (541) 812-7600
    Fax: (541) 81207611
    info@lund.com
    TOCPREVNEXTINDEX