RANE - editor for random object libraries.

Syntax:

rane [Update=]filename [directive]* [+Clear]
     [(+|-)Write]

Directives:

Append=[symdef_lst<]filename     +Clear
Delete=symdef_lst                      +Full
eXtract=[symdef_lst>]filename    +List
[Include=][symdef_lst<]filename  -Stop
Move=symdef_lst>symdef           +Write
Move=symdef_lst<symdef           +Verbose
Print=symdef_lst
RePlace=[symdef_lst<]filename
<directives_file

Options:

symdef_lst: is a sequence of SYMDEFs, separated by commas.
filename, Update=filename: specifies the name of the library to be edited. The form Update=filename implies +Write and conflicts with -Write. The Update=filename form is required when Include directives have the optional Include= missing. If the file already exists but is not in the proper format for a random library, RANE does not alter its contents unless you also specify +Clear.
<filename: reads directives from the named file. For more information on taking directives from a file, see "expl rane file".
>filename: writes all messages to the named file. When output is redirected to a file, RANE echoes the input directives to the file.
+Clear: ignores the old contents of the edited library. This option implies +Write and conflicts with -Write. +Clear must be specified to initialize a new library.
+Full: forces a full update. The library is copied to a work file and all subsequent changes are made to the work file. This file is copied back when editing is finished.
+List: lists the current state of the library.
-Stop: tries to continue processing directives even after an error has occurred.
+Verbose: displays modification messages.
-Write: accesses the library with read permission only. The library therefore remains unaltered. This option conflicts with +Clear.
Include=filename, Include=symdef_lst<filename, filename, symdef_lst<filename: reads routines from the library or object file specified by "filename". If you do not specify a "symdef_lst", all routines in the given file are included. If you have not specified the Update= option, you must use the Include= form of this option. If the library being edited contains SYMDEFs whose names match SYMDEFs in the library or object file that is being included, the new routines replace the old ones in the edited library. SYMDEFs that do not match ones in the library are added to the library.
Append=filename, Append=symdef_lst<filename: reads routines from the library or object file specified by "filename" and appends them to the end of the random library. If the "symdef_lst" is given, only those routines are obtained; otherwise, all routines in the file are obtained.
Delete=symdef_lst: deletes the named routines from the library.
Move=symdef_lst>symdef: moves the routines in the list, in the order specified, so that they are just AFTER the named "symdef" in the library.
Move=symdef_lst<symdef: moves the routines in the list, in the order specified, so that they are just BEFORE the named "symdef" in the library.
Print=symdef_lst: gives a detailed listing of the named decks.
Print=*: gives a detailed listing of the entire library.
eXtract=symdef_lst>filename, eXtract=filename: extracts the object modules for the named routines and puts them into the named file. If no "symdef_lst" is given, all routines are extracted.

Description:

RANE lets you edit the contents of a random object library, by appending, replacing, deleting, and moving individual object decks within the library.

The object decks are always referred to by one of their primary SYMDEFs. Decks are deleted as required to insure the uniqueness of this naming method.

Fast Update:

If the modifications to the library consist only of replacing object decks that are already present, and if +Full was not specified, RANE tries a fast update. This involves writing decks directly into the library, rather than copying the library to a work file and back. This may be undesirable in some situations; you can prevent it by specifying +Full.

RANE may give up on the fast update for various reasons. If so, RANE uses a normal update for the rest of the processing.

To allow for this updating mechanism, RANE does not collect unused space which may appear between object decks in the library, even if you aren't using a fast update.

Normal Update:

If the fast update is not used or is abandoned, RANE proceeds with a normal update, as described below.

RANE processes the directive options on the command line in the following order:

The flag options are checked and noted.
The library is accessed for read or write depending on the -Write flag.
If +Clear has been specified, the library is initialized.
Any command line Append=, Include=, Move= or Replace= options are applied to the work library in the command line order.
If there is a directives file, it is read and its directives are executed.
Any eXtract= and Print= options are then processed.
Any Delete= options are processed.
If +List was specified, RANE produces a listing of the library.
If fast update is in effect, the buffers are flushed and the library closed. If a full update is in effect, the library is rewritten from the work file.

If +Verbose is specified, the editing step produces various modification messages.

Default Options:

When only an output file (and possibly output redirection) are specified under TSS, RANE lists the contents of the library file, but does not change the file in any way.

In batch, if there is no command line, the output file defaults to file code "OT". If no options are given (or if the command line is absent), RANE assumes the options

Include=fc*r* +verbose +list

If a $SOURCE control card is found in the R* and there is a B* file code present, RANE reads object decks from the B* file until the next EOF.

Examples:

The following examples show ways that you can use RANE.

rane mylib i=b*

edits the modules in the file B* into the library "mylib". If "mylib" does not have an acceptable format, RANE does not overwrite it.

To get a listing of the contents of a library, type

rane mylib +List

to write the listing to the terminal, or

rane mylib >listfile

to write the listing into the file "listfile". In the second case you get a listing because +List is the default.

The following compresses a library that contains unused space.

rane mylib +full

Since "mylib" is used as a source of updates, the decks are trimmed properly.

To edit the library interactively, type

rane mylib <
del time,date
extract print>b*
list >listfile
<ctrl-\>

where <cntl-\> is the ASCII FS (file separator) character. This is usually generated by holding down the CTRL key and pressing "\". The above example deletes the modules "time" and "date" from the library, extracts the module "print" into a file named "b*", and produces a listing of the library contents in the file "listfile".

When a series of source modules are to be compiled into a library, the following sequence is useful.

rane mylib +clear <
!b file1 -Load
include b*
!b file2 -Load
include b*
   .
   .
   .
!b filen -Load
include b*
<ctrl-\>

Of course, any program which generates an object file can be used in the above sequence of commands.

Listing Contents:

The listing file contains three types of messages: error messages, modification messages, and library listings.

Error messages are sent to the file whenever an error occurs in editing the library. These messages are also sent to the terminal if output has been redirected.

Modification messages describe the action performed by the Update=, Delete=, Move=, and eXtract= options. These messages only occur in +Verbose mode.

Library listings are produced in response to the +List directive, and display the current contents of the work library.

Notes:

In fast update mode, unused space may appear in a library if some modules shrink. This space is not recovered by normal update. To recover the space, use the sequence described above.

In TSS, the code that writes to the library tries to protect itself from being interrupted by the BREAK key. In batch, however, the code cannot protect itself from aborts. Also because of a bug in TSS, RANE cannot protect itself against the BREAK key if it is being run inside CRUN. Should the program terminate while writing to the library, the library's contents will be (partly) destroyed.

Status Returns:

If RANE encounters an error, it turns on switch bits 18-26. In TSS, it also executes DRL T.ERR. If no errors are encountered, RANE turns off switch bits 18-25; in addition, it turns on bit 26 if the library was updated and turns off bit 26 if the library was not updated. The Gcos or TSS abort code from the slave prefix (.XABT1 or .LABRT) is placed in bits 27-35.