Dokumentation zu RP (Replace)

Inhalt:

0 Haftungsausschluss

1 Programmbeschreibung
  1.1 Voraussetzungen
  1.2 Kommandozeilenparameter
    1.2.1 Suchtext, Ersatztext
    1.2.2 Dateiname
    1.2.3 Optionen
  1.3 Errorlevel

2 About...
  2.1 Bugreports/Programmautor
  2.2 aktuellste Version

3 Einsatzbeispiele
  3.1 Setzen einer Umgebungsvariablen
  3.2 Automatische Rekonfiguration von Schulungsrechnern
  3.3 Automatisches Anpassen einer HTML-Datei

4 History

5 To-Do-List

------------------------------------------------------------------------------

0 Haftungsausschluss

Die Benutzung des Programms geschieht auf Ihr eigenes Risiko. Der Autor gibt keine Garantie fuer irgendeine Funktion des vorliegenden Programms und uebernimmt kein Schadensersatz fuer Operationen, die in Zusammenhang mit diesem Programm aufgetreten sind.

So, jetzt geht's aber los:


1 Programmbeschreibung

RP (Replace) ist ein Kommandozeilenprogramm fuer DOS, das in der Lage ist, ein oder mehrere Vorkommen einer angegebenen Zeichenkette in einer Datei durch eine andere Zeichenkette zu ersetzen. Dabei sind auch binaere Such- und Ersetzungsangaben moeglich.


1.1 Voraussetzungen

ACHTUNG: Dieses Programm setzt einen Rechner mit mindestens einer 286er CPU sowie einer NPU voraus. Wenn Sie eine Version fuer einen 8088er (ja, die gips noch) oder einen PC ohne NPU benoetigen, wenden Sie sich an den Autor (s.u.).

Erforderlicher DOS-Arbeitsspeicher: ca. 100 kB. Wenn mehr da ist, verwendet RP maximal ein Segment (64kB), um Daten umherzuschaufeln.


1.2 Kommandozeilenparameter

Aufgerufen wird das Programm mit

   RP "Suchtext" "Ersatztext" Dateiname [Optionen]


1.2.1 Suchtext, Ersatztext

Dabei wird 'Suchtext' in der Datei mit dem entsprechenden 'Dateiname'n gesucht und durch den 'Ersatztext' ersetzt. Der 'Suchtext' darf nicht leer sein, der 'Ersatztext' dagegen schon. Die Anfuehrungszeichen muessen aber immer angegeben werden, auch wenn 'Ersatztext' leer ist.

Im Such- oder Ersatztext duerfen Sonderzeichen vorkommen:
- Anfuehrungsstriche (") muessen mit Escape (\) eingeleitet werden
  Beispiel: >>"ab\"cd"<< wird als >>ab"cd<< interpretiert.
- Escape muss mit Escape eingeleitet werden.
  Beispiel: >>"C:\\WIN95"<< wird als >>C:\WIN95<< interpretiert.
- beliebige Zeichen koennen mit dem Wert des Zeichensatzes angegeben werden
  und muessen mit Escape eingeleitet werden.
  - Format fuer dezimale Zahlen: ddd, d=0...9
  - Format fuer hexadezimale Zahlen: xhh, h=0...F|h=0...f<br>
  Beispiel: >>"\065\x7E"<< wird als >>A~<< interpretiert.

Umgebungsvariablen in 'Suchtext' und 'Ersatztext' werden expandiert, d.h., ein
Aufruf wie
  ----------------------------------
  SET TEST=abc
  RP "%test% "Ersatztext" Datein.ame
  ----------------------------------
haette dasselbe Ergebnis wie
  --------------------------------
  RP "abc" "Ersatztext" Datein.ame
  --------------------------------


1.2.2 Dateiname

'Dateiname' gibt den Namen der zu bearbeitenden Datei an. :-)
Joker ('?' oder '*') sind hier nicht erlaubt. Verwenden Sie statt dessen
  >>FOR %%I IN (Dateimaske) DO rp "Suchtext" "Ersatztext" %%I [Optionen]<<
(Dies gilt fuer Batch-Dateien; auf der Kommandozeile duerfen Sie nur _ein_ Prozentzeichen verwenden.)


1.2.3 Optionen

Als Optionen sind moeglich:
 /i=n      (Index) Ersetze ab dem n-ten Vorkommen, Standard i=1
 /c=n      (Count) Anzahl der Ersetzungen. n=0 ersetzt alle Vorkommen (Standard)
 /a        (All) auch schreibgeschuetzte/versteckte/Systemdateien behandeln
 /tuNurSo  Die Ersetzungen werden nur simuliert
 /v        (Verbose) Geschwaetziger Modus
 /gk       Gross- und Kleinschreibung wird *nicht* unterschieden. Erweitert
           werden die ASCII-Zeichen a..z sowie die Sonderzeichen 129, 132,
           134, 130, 147 und 164 des erweiterten IBM-Zeichensatzes,
           Codepage 850.

n ist in allen Faellen eine positive Ganzzahl vom Typ WORD. (0 <= n <= 65.535)


1.3 Errorlevel

Beim Beenden des Programms wird ein definierter ERRORLEVEL gesetzt:
- Programmbeendigung ohne Fehler
  - Ersetzung durchgefuehrt: 0
  - keine Ersetzung durchgefuehrt, weil 'Suchtext' nicht in der Datei
    'Dateiname' enthalten war: 1
- Probleme in den Argumenten der Kommandozeile
  - allgemeiner Parsing-Fehler: 3
  - ZuwenigParameter: 4
  - Suchtext ist leer: 5
  - Parameter ist unbekannt: 6
  - ein angegebener Dateiname ist unzulaessig: 9
  - (unzulaessige) Joker im Dateinamen: 10
- Hilfstext wurde angezeigt: 2
- Probleme beim Programmablauf
  - DOS meldete einen Dateifehler: 7
  - zuwenig Plattenspeicher: 8

Ich werde mich bemuehen, bei kuenftigen Erweiterungen diese Errorcodes
unveraendert zu lassen.


2 About...
2.1 Bugreports/Programmautor

Bugreports und Verbesserungsvorschlaege senden Sie bitte an:
  Matthias Stolte
  MSDatec
  33613 Bielefeld
  Albert-Schweitzer-Str. 4
  Tel: +49 521 880056, +49 177 8800560
  Fax: +49 521 880059
  ISDN-Euro-Filetransfer: +49 521 880059
  Web: http://www.msdatec.de/
  E-Mail: msdatec@msdatec.de

Ich wuerde mich ueber Ihren Kommentar freuen.



2.2 aktuellste Version

Die aktuellste Version von RP erhalten Sie auf dem EFT-Server (s. 2.1) oder aus dem Internet unter 'http://www.msdatec.de/download.htm'


3 Einsatzbeispiele

Vielleicht noch einige Beispiele, wofuer ich dieses Programm benutze. :-)


3.1 Setzen einer Umgebungsvariablen

Ein haeufiges Problem ist es, in der DOS-Umgebung Daten von einem Programm zum anderen zu bekommen, und dann womoeglich noch innerhalb von Batches. Dieses Problem loese ich mit RP, indem ich die Ausgabe des einen Programms in eine Datei schreiben lassen, unerwuenschte Teile entferne, 'SET UMGEBUNGSVARIABLENNAME=' einfuege, die Datei in *.BAT umbenenne und sie ueber CALL ausfuehren lasse.

Ein Beispiel moege das verdeutlichen: Wie bekomme ich das aktuelle Datum in eine Umgebungsvariable?
  ----------------------------------------------------
    rem Aktuelles Datum in eine Umgebungsvariable setzen. TMP sollte mit abschliessendem \ gesetzt sein.

    rem Ausgabe von DATE in eine temporaere Datei schreiben:
  echo.|date > %tmp%tmp.bat
    rem Die Textdatei sollte man sich mit einem Hexeditor ansehen und entscheiden, welche Zeichen wo entfernt und welche eingefuegt werden sollten.
    rem Unerwuenschte Textteile (auch Zeilenumbrueche) aus der
    rem Datei entfernen und 'SET DATUM=' einfuegen:
  rp "Aktuelles Datum: " "SET DATUM=" %tmp%tmp.bat
  rp "\013\010Neues Datum (TT.MM.JJ): \013\013\010" "" %tmp%tmp.bat
  rp "," ", den" %tmp%tmp.bat
    rem TMP.BAT enthaelt jetzt einen Text wie
    rem "SET DATUM=Mo, den 13.10.1997" plus einen Zeilenumbruch
    rem Nun die Umgebungsvariable durch Ausfuehren von TMP.BAT setzen:
  call %tmp%tmp.bat
    rem und wech damit:
  del %tmp%tmp.bat
    rem Kosmetik: noch ein Komma anhaengen
  set datum=%datum%,
    rem Fertig
  ----------------------------------------------------

Ein weiteres Beispiel zeigt, wie die Benutzerkennung in einem MS-LAN-Manager-kompatiblen Netzwerk (also auch der OS/2-LAN-Server) in eine Umgebungsvariable kommt (Netware bietet ja PSTATION fuer sowas):
  ----------------------------------------------------
    rem Wir brauchen NET.EXE und FIND. Ausserdem sollte TMP mit abschliessendem \ gesetzt sein.
    rem Die entsprechende Zeile aus NET CONFIG in eine Datei schreiben:
  NET Config | FIND "Benutzerkennung"  > %tmp%username.bat
    rem Zeile aendern in sowas wie 'SET USER=MATTHIAS' plus einen Zeilenumbruch
  RP "Benutzerkennung:\008\008" "set user=\010\013" %tmp%username.bat
    rem ausfuehren und loeschen...
  call %tmp%username.bat
  del %tmp%username.bat
  ----------------------------------------------------



3.2 Automatische Rekonfiguration von Schulungsrechnern

Anstatt fuer jeden Rechner eine Sicherungskopie vorzuhalten, brauche ich jetzt nur noch eine. In dieser sind an den entsprechenden Stellen Platzhalter eingebaut, die durch RP aus Umgebungsvariablen ausgetauscht werden und so die Individualisierung der Rechner wiederherstellen.

Beispiel: 
  RP "SET STATION=PC000" "SET STATION=PC%pcnr%" C:\CONFIG.SYS
So verfahre ich mit CONFIG.SYS, AUTOEXEC.BAT und diversen Windows-INIs.

Bei Windows 95 ist dieses Verfahren fuer die Registry ebenfalls verwendbar:
Hier halte ich die Registry in Textform vor, verfahre wie oben und wandele anschliessend die modifizierte Textdatei REGISTRY.TXT mit >>REGEDIT.EXE REGISTRY.TXT<< in die binaere Version um.
So sehen dann alle Konfigurationen auch nach Jahren der Anfaengerbenutzung noch identisch aus. ;-)


3.3 Automatisches Anpassen und Verkleinern einer HTML-Datei

Nicht nur das automatische Einfuegen von variablen Daten wie des Tagesdatums beispielsweise ist moeglich, sondern auch das Verkleinern der Datei. Beispielsweise schrumpft die Groesse meines 'handgeschriebenen' Inhaltsverzeichnis des EFT-Servers um mehr als 10%. Ich hoffe, meine Web-Besucher werden's mir danken...

Wie geht's? Einfach die beiliegende HTMSMALL.BAT benutzen.
Nachfolgend sind einige Routinen aus dieser Batchdatei naeher erklaert. (Die HTML-Datei wird nachfolgend >>%1<< genannt :-)

- Leerzeichen entfernen:
  Es werden ueber eine Batch-Schleife mit
    ----------------------------------------
    :nochmal
    RP "  " " " %1
    if errorlevel==1 goto LeerzeichenSindWeg
    goto nochmal
    ----------------------------------------
  alle ueberfluessigen Leerzeichen entfernt (in Browsern werden mehrere Leerzeichen immer als eines dargestellt).

- Unix-Zeilenumbruch wird mit >>rp "\013\010" "\013" %1<< erzeugt

- leere Zeilen entfernen:
    ----------------------------------
    :ZeileNochmal
    rp "\013\013" "\013" %1
    if ERRORLEVEL==1 goto ZeileIstWech
    goto ZeileNochmal
    ----------------------------------

- Sonderzeichenkonvertierung mit
    RP "" "&uuml;" %1
    RP "" "&Uuml;" %1
  usw., wobei Probleme mit den verschiedenen Zeichensaetzen von DOS und Windows auftreten koennen. Einfacher ist es dann, das Zeichen ueber seinen Code zu maskieren, also z.B. '\xFC' fuer 'ue'.

- Leerzeichen zwischen Tags loeschen mit >>rp "> <" "><" %1<<

- Leerzeichen vor TABLE-Tags loeschen:
    -----------------------------------
    :TDNochmal
    rp " <%TT%" "<%TT%" %1 /GK
    if ERRORLEVEL==1 goto TDLeerIstWech
    goto TDNochmal
    -----------------------------------
  wobei %TT% nacheinander die Werte TH, TR und TD annimmt

- Bearbeitungsdatum setzen:
  In fast jeder HTML-Datei befindet sich sowas wie "Zuletzt ueberarbeitet
  am ...". Bei mir steht dort
    "Zuletzt bearbeitet am <!--AKTUELLES TAGESDATUM-->.",
  wobei dann "<!--AKTUELLES TAGESDATUM-->" mittels
    RP "<!--AKTUELLES TAGESDATUM-->" "%datum%" %1 
  durch das aktuelle Datum ausgetauscht wird (siehe auch Beispiel 3.1).


4 History

Version 1.0:
    Release: 09.03.97, Zeitstempel 01:00
    Groesse: Vollversion: 27.088 Bytes, Shareware-Version: 29.088 Bytes
Version 1.1
    Release: am 14.03.1997, Zeitstempel 01:01
    Groesse: Vollversion 27.712 Bytes, Sharewareversion 28.624 Bytes
    Aenderungen: keine
    Zusaetze: Option -gk (Gross- und Kleinschreibung ignorieren) eingebaut
Version 1.2:
    Release: 22.06.97, Zeitstempel 01:02
    Groesse: Vollversion:  31.648 Bytes, Shareware-Version:  32.544 Bytes
    Aenderungen:
    - Kommandozeilen-Parsing jetzt durch allgemeines Modul
    - Neue DELAY-Routine verwendet
    - Kommandozeilenschalter-Einleitung von '-' in '/' geaendert
    Bugfixes:
    - "\\" gegenueber "\\\"" wird jetzt richtig behandelt.
    - begrenzende Leerzeichen in SUCHTEXT oder ERSATZTEXT werden jetzt erkannt;
    - Fehler (Feature?) in PARAMSTR() durch Einsatz eigener Kopierroutine von
      PSP:80h beseitigt.
Version 1.2.1:
    Release: 02.07.97, Zeitstempel 01:21
    Groesse: Vollversion: 34.144 Bytes, Shareware-Version: 35.072 Bytes
    Aenderungen:
    - Peinlichen Bug beseitigt: fuer Version 1.2 hatte ich zum Pruefen den Teil
      des Programms auskommentiert, der die Aenderungen tatsaechlich
      durchfuehrt...
      Nu geht's aber wieder. :-)
    - n^2-Lizenz eingefuehrt
    - Parameter /? ermoeglicht
    - Nun wird auch wieder ein richtiger temporaerer Dateiname verwendet.
Version 1.2.2:
    Release: 07.08.97, Zeitstempel 01:22
    Groesse: Vollversion: 32.800 Bytes, Shareware-Version: 33.072 Bytes
    Aenderungen:
    - laestige Wartezeit bei der Shareware-Version entfernt
    - Dokumentation strukturiert und erweitert, kleine Aenderungen in REGISTER.TXT durchgefuehrt
    Erweiterungen:
    - Pruefung auf (unzulaessige) Joker '?' und '*' im Dateinamen eingebaut
    - Falls die Verbose-Option nicht gesetzt ist, wird jetzt eine Fortschrittsanzeige nach jedem Lesevorgang/Auffinden angezeigt. Nicht, dass der geneigte Benutzer denke, das Programm sei gestorben... :-)
    - HTMSMALL.BAT zum Paket dazugelegt, HTMSMALL.REG fuer die Windows 95-Freunde...
    Bugfixes:
    - bislang keine Bugs in V1.21 gefunden...


5 To-Do-List

- Aufgrund der Laengenbeschraenkung der Kommandozeile sollte alternativ eine Dateiangabe fuer 'Suchtext' oder 'Ersatztext' moeglich sein.
- Einbau von Datums- und Uhrzeitfunktionen
- Dringend noetig: regulaere Ausdruecke, damit auch HTML-Kommentare mit RP "<!--\*-->" "" DATEI.NAME entfernt werden koennen...
