LODL - edit program library files (Q*'s).

Syntax:

LODL [Update=]lib [edit_opt]* [list_opt]* [comm_opt]*
LODL [Update=]lib Patches=file [list_opt]*
Edit Options:
   (+|-)CLear (-)         Append=[name,name,...<]file
   Delete=name,name,...   [Include=][name,name,...<]file
   ReName=oldname>newname Replace=[name,name,...<]file
Listing Options:
   (+|-)Listing           (+|-)Patches (-)
   (+|-)Verbose (-)
Command Options:
   (+|-)ComPress (-)      (+|-)Dates (+)
   (+|-)Safely (-)        (+|-)Zdebug (-)
   Patches=file           Update=lib

Examples:

lodl /lib
lodl +clear u=/lib a=file1 a=file2 a=file3
lodl u=/lib p=file +patch
lodl u=/lib rp=name<file
lodl /lib del=x,y,z +compress

Options:

lib
is the name of a temporary or permanent program library file you want to update. This file must be random. If the library does not exist, LODL creates it, provided that you also specify the +CLear option.
Update=lib
is similar to just specifying the library name on the command line. However, when you use this form, LODL automatically checks for duplicate entries. LODL goes through each set of duplicates and deletes all but one; the one that is left is the one that came last in the library's catalog. LODL also updates the available space catalog of the library.
-Dates
strips date stamps from any modules that are added to, or replaced in a library.
Patches=file
applies patch card images from "file" to the elements of the library. No other editing or command options may be used if this option appears on the command line. See below for more about patch card files.
+Zdebug
displays various internal information. This is only intended for use by the developers maintaining LODL. +Zdebug's behavior is subject to change without notice.

Edit Options:

Edit options prescribe individual editing operations. +CLear may only be specified once; all the others may be specified as many times as appropriate. If any edit options are specified, duplicate entries are deleted as with the Update= form. In addition, LODL updates the available space catalog of the library.

Append=file
appends all the routines from "file" into the library. The file must be a Q* file. A routine may not be appended if it is already in the library.
Append=name,name,...<file
is similar to the previous form. However, it only appends the routines whose names are specified.
+CLear
clears and initializes the library. This option is required when creating a new library. If applied to an existing library, it deletes all the current contents.
Delete=name,name,...
deletes the named routines from the library. It also removes all patch card images for these routines from .GPAED (.GPAED is described later on).
ReName=oldname>newname
changes the name of a routine. Note that the options are processed in the order they appear. Thus you can change a routine's name anytime after appending (or replacing) it, but not before. This option also updates all patch card images in the .GPAED to the new name.
Replace=file
takes all the routines from "file" and uses them to replace routines of the same name that are currently in the library. There must be old routines of the same name in the library. LODL removes patch cards for replaced routines from .GPAED.
Replace=name,name,...<file
is similar to the previous option, but only replaces the named routines.
Include=file, Include=name,name,...<file
performs either an Append or Replace action, as appropriate. The "Include=" string may be omitted if the library name is specified with "Update=lib"; however, "Include=" must be specified if the "Update=" is omitted. Thus you can say either
lodl u=lib file1 file2
         or
lodl lib i=file1 i=file2

but you cannot say

lodl lib file1 file2

Command options are processed in the order they appear on the command line. The exception to this is +CLear which is always processed first, regardless of its position on the command line.

Listing Options:

Listing options control the amount of information that LODL displays.

+Listing
displays a listing of the Q* library. By default, LODL usually does not display a listing; however, if there are no non-listing options on the command line, LODL displays a listing, whether or not +Listing is specified.
+Patches
displays the card images in the .GPAED element.
+Verbose
gives a running commentary of the edit operations being performed. If you specify +Verbose with a listing, the listing also shows the location of the catalog blocks, available space blocks, and the available space.

Command Options:

Command options apply to all the operations of the LODL command.

+ComPress
compresses the library after it has been updated. In a compressed library, all catalog blocks appear at the start of the file, with one available space catalog block. Also, there is no space between the elements of the library or between catalog blocks; thus there is no available space in the library, with the possible exception of one free space following the last library element. You may not use +ComPress together with the +Safely option.
+Safely
updates the library in a way that tries to protect the library from damage if there is a system crash or some other kind of interrupt that terminates LODL abnormally. The idea is that the library is always left in a valid state between I/O operations. If there is an interruption during the update, the library continues to be usable; however, there is no way to determine which editing operations, if any, succeeded before the interruption. The available space records and the patch image element .GPAED may not be correct after an interruption. This mode of updating may require substantially more file space for the library than is strictly needed, because there must be space for both the old and new copies of the modules. Updating one module at a time can restrict this excess space to the size of the module. However, a single module can still be over 800 llinks, and the set of modules for an overlaid program can be arbitrarily large. Catalog blocks are kept contiguous, except for the first.

If neither +ComPress or +Safely is specified, LODL does a normal update. The normal update is faster than a compress update, and requires less disk space than a safe update, but there is a very small chance that a system interruption during the update could leave the library damaged. The library is not left in a compressed state, and the catalog blocks may not be contiguous.

Description:

LODL edits a program library. Program libraries are sometimes called qstar (Q*) files. A qstar file that only contains one program is sometimes called an H* file.

By default, LODL maintains date stamp information for a module in the catalog block for that module. While placing a module into a library, LODL checks the module's date stamp in the source qstar. If there is a valid date stamp, the stamp is copied. If not, LODL stamps the module with the current time. The system linkers (GELOAD, SYSEDIT, YLDA etc) and other utilities that create new qstar modules set the date stamp field to zero.

Patches:

In addition to the editing operations that affect whole modules (append, delete, rename, etc.), LODL also lets you patch individual modules.

Patch card files consist of a sequence of patch card images. The information on a patch card is split into fields beginning at specific columns:

Column 1:
An octal number of up to six octal digits. This gives the address to patch within a module.
Column 8:
Must be the word "octal".
Column 16:
A 12-digit octal number. This gives the new value to be placed into the given address.
Column 73:
The name of the module to patch. This is one-to-six characters long. If the given name is less than six characters long, it will be extended to six characters by adding spaces on the end.
Column 79:
Two blank characters. These may be omitted.

A patch card image may contain tab characters and tab stops are assumed to be set at columns 8, 16, and 73. Therefore you can use tabs to separate columns rather than spacing over the exact number of columns. If LODL finds a colon ":" character in any column before 16, it interprets all subsequent ":" characters in the line to be tab characters; thus you can use either tabs or ":" characters to delimit fields.

After applying the patches, LODL stores a copy of the patch card images in the library in an element called ".GPAED". Each image in .GPAED is followed by a "was" card which shows the original value of the word that was patched.

Unlike the other qstar patch utilities, PAED and LODLIB, you can use LODL to apply more patches to a previously patched qstar. The patch record module, .GPAED, is updated by appending data from the new patches.

Notes:

The format of a qstar file limits the size to 52428 llinks (2**18/5). Any space allocated to the file more than this will wasted.

See Also:

expl lodl batch
using LODL in batch

Copyright © 1996, Thinkage Ltd.