Parameter der Dokumentation in VBA 

Das in dieser Lektion vermittelte Verständnis von Parameterbeschreibungen aus der Dokumentation erschließt die Möglichkeit zum Nutzung einer Vielzahl vordefinierter Funktionen.

Typerwartungen

Der Aufrufausdruck »VBA.Math.Sqr( 2.0 )« besteht aus einem Rahmen »VBA.Math.Sqr( … )« und einem an Stelle der Lücke »…« eingesetztem Argumentausdruck »2.0«.

Für diese Lücke »…« darf jedoch im allgemeinen nicht irgendein beliebiger  Wertausdruck eingesetzt werden. Das folgende Programm zeigt, daß ein Ausdruck vom Typ »String« beispielsweise zu einer Fehlermeldung führt.

Direktbereich

? VBA.Math.Sqr( "abc" )
⚠ Laufzeitfehler '13': Typen unverträglich
⚠ Run-time error '13': Type mismatch

Die Fehlermeldung drückt aus, daß ein Ausdruck von einem anderen Typ als »String« erwartet wurde.

Beispiel einer Dokumentation

Entfernt man aus einem Aufrufausdruck den Argumentausdruck, so enthält man einen Rahmen mit einer Lücke, wie beispielsweise den Rahmen »java.lang.Math.floor( … )« mit einer Lücke »…« in den runden Klammern. Solch eine Lücke an der Stelle eines entfernten Argumentausdrucks nennt man eine Parameter (Substantiv mit Genus Maskulinum und Betonung auf der zweiten Silbe). Ein Parameter drückt die Erwartung eines Argumentes aus. Der Parameter kennzeichnet die Stelle an welcher ein Argumentausdruck von einem bestimmten Typ erwartet wird. Ein Parameter ist wie eine Lücke, die dann vom Argument gefüllt werden kann.

In der Dokumentation einer Funktion findet man eine nähere Beschreibung des Parameters.

Die folgende Kurzbeschreibung der Funktion »VBA.Math.Sqr« findet man im Objektkatalog. Wir nennen eine solche Kurzbeschreibungen auch eine Proklamation.

Die Proklamation wird von Microsoft auch „Syntax“ genannt, was aber nicht mit der allgemeinen Bedeutung des Wortes „Syntax“ übereinstimmt.

Die folgende Proklamation zeigt nun eine ausführlichere Beschreibung eines Parameters, in welcher sich neben dem Namen noch eine Angabe zum Parametertyp befindet. Dadurch wird dann erklärt, wie der Argumentwert interpretiert wird (hier als Double-Wert). Bei der Verwendung solcher Funktionen ist es dann der Normalfall, daß der Argumentausdruck den Typ des Parameters hat. Beim Aufruf dieser Funktion sollte der Argumentausdruck also normalerweise den Typ »Double« haben. Der Wert des Aufrufausdrucks ist dann im allgemeinen die Quadratwurzel des Argumentwerts.

Der Proklamation folgt oft noch eine Prosa : ein deutsch- oder englischsprachiger Text mit allen Informationen, die nicht schon der Proklamation entnommen werden können.

»VBA.Math.Sqr« [Proklamation]

Function Sqr(Number As Double) As Double
    Element von VBA.Math

»VBA.Math.Sqr« [Prosa (vereinfacht)]

Ergibt die Quadratwurzel von Number.

In der obenstehenden Dokumentation wird durch »Number As Double« ein Parameter mit dem Typ »Double« und dem Namen »Number« dokumentiert. Die Funktion kann und muß also mit einem Argument vom Typ »Double« aufgerufen werden. In dem Text der Beschreibung der Funktion kann dann mit »Number« auf den Argumentwert Bezug genommen werden.

Parameternamen Damit man sich besser auf einen Parameter beziehen kann, hat ein Parameter einen Namen, den Parameternamen. Der Parametername ist eine Bezeichnung für einen Wert (wie beispielsweise eine Zahl), welcher dann erst durch die Angabe eines Argumentausdrucks konkret bestimmt wird. Ein Parametername hat jedoch für einen Aufruf einer Funktion sonst keine Bedeutung. Er erleichtert es nur, sich in der Dokumentation einer Funktion auf den Parameter zu beziehen.

Parametertyp Um zu beschreiben, daß bestimmte Lücken nur Ausdrücke bestimmter Typen zulassen, ordnet man Parametern einen Typ  zu, den man auch als Parametertyp  bezeichnen kann. Zunächst akzeptiert ein Parameter dann nur Argumente des Parametertyps (Ausnahmen von dieser Regel werden später behandelt). Ein Parameter vom Typ »String« akzeptiert also ein Argument vom Typ »String«, nicht jedoch vom Typ »Integer« oder »Double«. Umgekehrt akzeptiert ein Parameter vom Typ »Integer« oder »Double« kein Argument vom Typ »String«. Ein Double-Parameter einer Funktion besagt unter anderem, daß jene Funktion noch eines Double-Wertes bedarf, um ihre Aufgabe zu erfüllen.

Eine parametrisierte Funktion  ist eine Funktion mit mindestens einem Parameter.

Das folgende Beispielprogramm zeigt einen der Dokumentation entsprechenden Aufruf mit einem Argumentausdruck vom Typ »double«.

Direktbereich

? VBA.Math.Sqr( 4.0 )
 2 

In der Dokumentation einer Funktion, die einen Parameter hat, findet man also eine Beschreibung  (wie beispielsweise »double a«) dieses Parameters, die aus einem Typ und meist einem Namen besteht.

⚠ Die Dokumentation einer Funktion erklärt dem Leser die Eigenschaften und die Bedeutung dieser Funktion. Sie ist nicht  dafür gedacht als Teil einer VBA -Eingabe kopiert zu werden. In der Dokumentation steht beispielsweise »Function Sqr(Number As Double) As Double«, ein korrekter Aufruf dieser Funktion ist beispielsweise »VBA.Math.Sqr( 4.0 )«. Die Parameterbeschreibung »Number As Double« aus der Dokumentation gehört also nicht in den Quelltext.

Zeile aus einer Proklamation

Function Sqr(Number As Double) As Double

Ausschnitt aus einer VBA -Eingabe

VBA.Math.Sqr( 4.0 )

Der Objektkatalog und die Hilfe-Datei

Manchmal findet man die genaue Angabe des Typs eines Parameters nicht in der Hilfe-Datei zu VBA  (F1), sondern nur im Objekt-Katalog (F2).

In diesem Kurs wird mit „Dokumentation“ die Gesamtheit der von Microsoft  zu einer Funktion veröffentlichten Informationen gemeint, also die Zusammenfassung der Informationen aus dem Objekt-Katalog und der Hilfe-Datei, sowie weiterer Quellen wie etwa die offizielle „VBA -Sprachnorm“ »MS-VBAL«, welche beispielsweise zur Funktion »Sqr« den Abschnitt 6.1.2.10.1.10 enthält, oder die „MSDN “-Webseiten. Im Rahmen dieses Kurses reicht der Objekt-Katalog und die Hilfe-Datei aber meistens aus.

Parameter ohne  Typ

Bei manchen Parameterbeschreibungen fehlt die Angabe eines Typs. Beispielsweise findet sich in der Parameterbeschreibung »Number« aus der Dokumentation der Funktion »VBA.Math.Abs« oder der Funktion »VBA.Strings.Len« im Objektkatalog keine Typangabe.

»VBA.Math.Abs« (Proklamation des Objektkatalogs)

Function Abs( Number )

»VBA.Strings.Len« (Proklamation)

Function Len(Expression)
    Element von VBA.Strings

Die Proklamation von »VBA.Strings.Len« zeigt, mit dem Wort »Expression« in den runden Klammern, daß beim Aufruf dieser Funktion die Angabe eines Argumentausdrucks nötig ist. Ein Wort in den runden Klammern in der Proklamation einer Funktion beschreibt den Parameter  der Funktion, das ist die Stelle an welcher in einem Ausdruck für den Aufruf dieser Funktion der Argumentausdruck eingesetzt werden muß. Der Parameter von »VBA.Strings.Len« hat den Namen »Expression«.

Wenn die Typangabe in der Proklamation („Syntax“) fehlt, dann ist dies so zu verstehen, daß zunächst alle Datentypen akzeptabel sind. – Eventuelle Einschränkungen finden sich dann in der Prosa  (also im Rest) der Dokumentation. (Bei manchen Parametern, für die in der Proklamation kein Typ angegeben ist, sind alle Typen zulässig, bei manchen nur bestimmte Typen.)

Leere Parameterlisten

Wenn die Klammern hinter dem Funktionsnamen in der Dokumentation leer  sind, dann hat die dokumentierte Funktion keine Parameter, und muß entsprechend ohne Argument  aufgerufen werden.

»VBA.Information.Err« [Proklamation]

Function Err() As ErrObject
    Element von VBA.Information

»VBA.Information.Err« [Beschreibung]

Ergibt die Kennzahl des letzten Fehlers.

Direktbereich

? VBA.Information.Err()
 0 

Parameter und Argumente

Parameterbeschreibungen  und Argumentausdrücke  werden manchmal miteinander verwechselt :

Parameterbeschreibungen  wie »Number As Double« finden sich in der Dokumentation  als Beschreibung einer Lücke, sie drücken das Fehlen  eines bestimmten Wertes aus, die Erwartung  eines Ausdrucks beim Aufruf im Quelltext.

Wir schreiben Parameterbeschreibungen wie »Number As Double« nicht in den Quelltext!

Argumentausdrücke  finden sich im Quelltext innerhalb mancher Ausdrücke und geben den zur Ermittlung des Parameterwerts zu nutzenden Ausdruck an, beispielsweise als ein Numerale oder als eine Summe.

Da Parameterbeschreibungen das Fehlen  eines Wertes ausdrücken und Argumentausdrücken einen Wert  ausdrücken, sind Argumentausdrücke  gewissermaßen das Gegenstück zu Parameterbeschreibungen.

Weitere Beispiele für Funktionsdokumentationen

Hier zeigen wir noch die Dokumentation einer schon in einer früheren Lektion verwendeten Funktion.

»VBA.Conversion.Int« [Proklamation]

Function Int(Number)
    Element von VBA.Conversion

»VBA.Conversion.Int« [Beschreibung (vereinfacht)]

Schneidet eventuell vorhandene Nachkommastellen ab.

Im Falle der Dokumentation dieser Funktion ist gar kein Parametertyp  angegeben, das Wort »As« fehlt. In diesem Falle kann man nur aus dem Namen  des Parameters erraten, daß hier ein numerischer Ausdruck (eine Zahl) erwartet wird. Manchmal finden sich Angaben dazu auch noch im Rest der Dokumentation.

Ausblick

Welche  Argumenttypen für welche  Parametertypen akzeptabel sind und wie sie dann interpretiert werden, wird in einer der folgenden Lektionen („Aufrufwandlung in VBA “) behandelt werden.

Übungsfragen

?   Verständnis von Fachbegriffen ʳ²⁸

In den folgenden Zitaten findet sich: »Number« und »4.0« – welcher dieser beiden Texte ist ein Parametername  und welcher ist ein Argumentausdruck ?

»VBA.Math.Sqr« [Proklamation]

Function Sqr(Number As Double) As Double
    Element von VBA.Math

Direktbereich

? VBA.Math.Sqr( 4.0 )
 2 

?   Verständnis von Fachbegriffen ʳ²⁸

Zu einer (hypothetischen) Funktion »m« wird erklärt: „Die Funktion »m« ergibt den Wert 4.“. Welchen Wert hat dann »m( 3 )«?

Zu einer (hypothetischen) Funktion »f« wird erklärt: „Die Funktion »f« ergibt den Wert ihres Arguments.“. Welchen Wert hat dann »f( 3 )«?

?   Dokumentation lesen ʳ²⁸

Dokumentation einer Funktion mit einem Parameter

Function Val(String As String) As Double
    Element von VBA.Conversion

(»String As String« steht so im Objektkatalog!)

Fragen zum Verständnis der obigen Dokumentation

• Welchen Namen  hat die dokumentierte Funktion?
• Welchen Namen hat der Parameter  der Funktion?
• Welchen Datentyp  hat der Parameter der Funktion?
• Welchen Datentyp hat ein Aufruf  der Funktion?
• Zu welcher Klasse  (= zu welchem Modul) gehört diese Funktion?
• Zu welcher Bibliothek  (= zu welchem Projekt) gehört diese Klasse?

?   Ausdrücke lesen ʳ²⁸

Können Sie – ohne eine VBA -Implementation zu verwenden – den ungefähren Wert des folgenden Ausdrucks vorhersagen?

• »VBA.Math.Sqr( VBA.Math.Sqr( 16 ))«

Welchen Datentyp hat der voranstehende Ausdruck?

?   Reihenfolge von Rechenschritten ʳ²⁸

In welcher Reihenfolge werden die beiden Funktionen bei der Auswertung des folgenden Ausdrucks aktiviert?

Ausdruck

VBA.Math.cos( VBA.Math.sin( 2 ))

?   Quelltext beurteilen ʳ²⁸

Ist die folgende Eingabe in den Direktbereich korrekt? Begründen Sie Ihre Antwort!

Direktbereich

? Function Sqr(Number As Double) As Double

Bedeutung von Ausdrücken ʳ³⁶

Ist «VBA.Math.Sqr( 2.7 )» eine Funktion?

Nicht aus der Dokumentation kopieren!

Ein Programmierer muß Dokumentationen von Funktionen verstehen, um dann die daraus gewonnenen Informationen zum Schreiben von Quelltexten verwenden zu können. Ein gelegentlicher Fehler von Anfängern, welche die Dokumentation noch nicht richtig verstehen, ist es, die Dokumentation einer Funktion als Quelltext einzugeben. Das ist in der Regel verkehrt.

Nicht aus der Dokumentation als Quelltext kopieren!

Der folgende Text zeigt, wie es aussehen kann, wenn ein Anfänger einen Teil der Dokumentation als Quelltext eingibt, wie dies öfter beobachtet wurde. Anfänger, die so vorgehen sind danach meist nicht in der Lage, die Eingabe noch selbständig zu korrigieren. Daher sollte es grundsätzlich vermieden werden, einen Teil der Dokumentation als Quelltext zu kopieren.

Teil der Dokumentation

Function Round( Double ) As Double
    Element von VBA.Math

Eingabe

? Function Round( Double ) As Double

Dialog (deutsche Version)

⚠ Fehler beim Kompilieren:
Erwartet: Ausdruck

Dialog (englische Version)

⚠ Compile Error: 
Expected: Expression

Schon zuvor wurde ja ein Programmbeispiel vorgestellt, das zeigt, wie die Funktion »VBA.Math.Rnd« richtig aufgerufen wird. Wenn man sich das Programmieren durch Kopieren aus einer Vorlage erleichtern will, dann sollte man ein solches Beispielprogramm  kopieren, aber nichts aus der Dokumentation!

Wer bei der Bearbeitung der folgenden Aufgaben eine Zeile der Proklamation in das Programm kopiert, macht wahrscheinlich einen Fehler. Die Zeilen der Proklamationen sollen nicht kopiert werden. Sie geben dem Programmierer Informationen über eine Operation, aufgrund derer ein Aufruf dieser Operation dann richtig in einen Quelltext eingebaut werden kann. Dieser Einbau geschieht aber meistens nicht dadurch, daß eine Zeile der Proklamation einfach in den Quellcode kopiert wird.

Übungsaufgaben

Diese Übungsaufgaben sollen das selbständige Schreiben von Aufrufen von Funktionen mit einem Parameter an Hand der Dokumentation üben.

Denken Sie daran, nichts aus der Dokumentation in das Programm zu kopieren!

/   Anwendung der Funktion »LCase(Zeichenfolge)«

Dokumentation (vereinfacht)

Function LCase$(String) As String
    Element von VBA.Strings

Die Funktion "LCase$" akzeptiert als Argument ein Ausdruck vom Typ „Zeichenfolge“. Dadurch kann ihr also ein bestimmtes Zeichen als Zeichenfolgenliteral (in Anführungszeichen) mitgeteilt werden. Das Funktionsergebnis ist dann für eine Majuskel (für einen „großen“ Buchstaben, eine Versalie) die entsprechende Minuskel (der entsprechende „kleine“ Buchstabe, der Gemeine).

Ermitteln Sie durch Verwendung der Funktion "LCase$" die Minuskel zur Majuskel "A".

Hinweis für den Dozenten  ► Weiter unten befinden sich noch Reserveaufgaben zu dieser Übungsaufgabe

/   Anwendung der Funktion »Round« ʳ²⁴

Dokumentation (vereinfacht)

Function Round( Double ) As Double
    Element von VBA.Math
    Round to a given number of decimal places

Ermitteln Sie durch Verwendung der Funktion "Round" den gerundeten Wert der Zahl 64,8 (gemäß der hier angegebenen vereinfachten Syntax).

/   Mathematische Aufrufe schreiben ʳ²⁸

Schreiben Sie möglichst kurze Ausdrücke, die den folgenden sprachlichen Bezeichnungen entsprechen, ohne dabei den Wert des Ausdrucks schon selber im Kopf auszurechnen! Die Werte der Ausdrücke sollten den mathematischen Werten der vorgegebenen Texte möglichst nahe kommen. (Passende Funktionen können in der Klasse »VBA.Math« gefunden werden.)

• Der Kosinus von Null
• Die Wurzel aus zwölf Prozent von Vierundsiebzig

?   Runden ʳ⁴⁰

Schreiben Sie eine Eingabe, welche die auf zwei Nachkommastellen gerundete Quadratwurzel von 10 ausgibt. Dabei soll die VBA -Implementation die Quadratwurzel berechnen und dann das Ergebnis runden.

Reserveaufgaben

/   Aufrufe schreiben (1)

(Diese Reserveaufgabe wird erst nach der Nachbesprechung der ersten obenstehenden Aufgabe bearbeitet, falls diese Aufgabe noch nicht gelöst werden konnte.)

Schreiben Sie ein Programm, welches das Ergebnis eines Aufrufs der Funktion »Sgn« ausgibt (welche Werte dabei genau verwendet werden, ist egal.)

Dokumentation (übersetzt)

VBA
  Class Math
    Function Sgn( Number )
      Ergibt die Signumfunktion des Arguments;
      0, wenn das Argument Number 0.0 ist,
      1, wenn das Argument Number groesser als 0 ist,
      -1, wenn das Argument Number kleiner als Null ist.

/   Aufrufe schreiben (2)

(Diese Reserveaufgabe wird erst nach der Nachbesprechung der vorherigen Aufgabe bearbeitet, falls die vorherige Aufgabe noch nicht gelöst werden konnte.)

Schreiben Sie ein Programm, welches das Ergebnis eines Aufrufs der Funktion »Sqr« ausgibt (welche Werte dabei genau verwendet werden, ist egal.)

Dokumentation (übersetzt und vereinfacht)

VBA
  Class Math
    Function Sqr(Number As Double) As Double
      Ergibt die Quadratwurzel von Number.

Zusatzsfragen *

?   Ausdrücke lesen ʳ⁴⁰ *

Die folgenden Fragen sollen durch Lesen der Dokumentation beantwortet werden, nicht durch Ausprobieren (Starten von Programmen).

Welche Werte kann der Ausdruck »VBA.Conversion.CInt( VBA.Math.Rnd() * 3 )« haben?

Welche Werte kann der Ausdruck »VBA.Conversion.Int( VBA.Math.Rnd() * 3 )« haben?