Builtins

Builtins sind Konstanten, Variablen, Funktionen und Anweisungen, die zusätzliche Informationen bereitstellen und Datenbearbeitungen ermöglichen.

Builtin-Konstanten

Mithilfe von Builtin-Konstanten können Informationen zu Objektparametern angegeben werden, z. B. die maximal empfohlene Namenslänge, Flags usw. Viele der Objekttypen verfügen über einen eigenen Abschnitt für Konstanten, in dem die Builtin-Konstanten für dieses Objekt aufgelistet sind (siehe z. B. UL_PIN).

Die folgenden Builtin-Konstanten werden zusätzlich zu den für die verschiedenen Objekttypen aufgeführten Konstanten definiert:


EAGLE_VERSION	EAGLE-Programmversionsnummer (Ganzzahl)
EAGLE_RELEASE	EAGLE-Programm-Release-Nummer (Ganzzahl)
EAGLE_SIGNATURE	Zeichenfolge bestehend aus EAGLE-Programmname, Versions- und Copyright-Informationen
EAGLE_PATH	Zeichenfolge bestehend aus dem vollständigen Pfad der ausführbaren EAGLE-Datei
EAGLE_DIR	Zeichenfolge bestehend aus dem Verzeichnis der EAGLE-Installation ($EAGLEDIR)
EAGLE_HOME	Zeichenfolge, die beim Starten von EAGLE das Stammverzeichnis des Benutzers enthält ($HOME)
eagle_epf	Zeichenfolge bestehend aus dem vollständigen Pfad der aktuell verwendeten Datei eagle.epf
OS_SIGNATURE	Zeichenfolge bestehend aus einer Signatur des Betriebssystems (z. B. Mac..., Windows... oder Linux)
REAL_EPSILON	Minimale, positive reelle Zahl, sodass Folgendes gilt: 1.0 + REAL_EPSILON != 1.0
REAL_MAX	Größtmöglicher reeller Wert
REAL_MIN	Kleinstmöglicher reeller Wert (positiv!). Die kleinstmögliche Zahl ist -REAL_MAX
INT_MAX	Größtmöglicher ganzzahliger Wert
INT_MIN	Kleinstmöglicher ganzzahliger Wert
TS-Punkt	Wert von PI (3.14..., reelle Zahl)
Verwendung	Zeichenfolge bestehend aus dem Text aus der #usage-Anweisung

Diese Builtin-Konstanten enthalten die Verzeichnispfade, die im Dialogfeld Verzeichnisse definiert sind, wobei die speziellen Variablen ($HOME und $EAGLEDIR) durch ihre tatsächlichen Werte ersetzt werden. Da jeder Pfad aus mehreren Verzeichnissen bestehen kann, sind diese Konstanten Zeichenfolgenanordnungen mit einem einzelnen Verzeichnis in jedem Element. Das erste leere Element markiert das Ende des Pfads:

path_lbr[]    Libraries
path_dru[]    Design Rules
path_ulp[]    User Language Programs
path_scr[]    Scripts
path_cam[]    CAM Jobs
path_epf[]    Projects

Wenn Sie diese Konstanten zum Erstellen eines vollständigen Dateinamens verwenden, müssen Sie ein Verzeichnistrennzeichen verwenden. Beispiel:

string s = path_lbr[0] + '/' + "mylib.lbr";

Die Bibliotheken, die derzeit durch den Befehl BENUTZEN verwendet werden:

used_libraries[]

Builtin-Variablen

Mithilfe von Builtin-Variablen werden Informationen zur Laufzeit bereitgestellt.

int argc    number of arguments given to the RUN command
string argv[] arguments given to the RUN command (argv[0] is the full ULP file name)

Integrierte Funktionen

Mithilfe von Builtin-Funktionen können Sie bestimmte Aufgaben ausführen, z. B. formatierte Zeichenfolgen drucken, Datenanordnungen sortieren usw.

Sie können auch eigene Funktionen schreiben und diese zum Strukturieren Ihres User-Language-Programms verwenden.

Die Builtin-Funktionen werden in folgende Kategorien unterteilt:

Zeichenfunktionen
Funktionen zur Dateiverarbeitung
Mathematische Funktionen
Sonstige Funktionen
Netzfunktionen
Druckfunktionen
Zeichenfolgenfunktionen
Zeitfunktionen
Objektfunktionen
XML-Funktionen

Alphabetische Referenz aller Builtin-Funktionen:

abs()
acos()
asin()
atan()
ceil()
cfgget()
cfgset()
clrgroup()
country()
cos()
exit()
exp()
fdlsignature()
filedir()
fileerror()
fileext()
fileglob()
filename()
fileread()
filesetext()
filesize()
filetime()
floor()
frac()
inch2u()
ingroup()
isalnum()
isalpha()
iscntrl()
isdigit()
isgraph()
islower()
isprint()
ispunct()
isspace()
isupper()
isxdigit()
language()
log()
log10()
lookup()
max()
mic2u()
mil2u()
min()
mm2u()
neterror()
netget()
netpost()
palette()
pow()
printf()
round()
setgroup()
setvariant()
sin()
sleep()
sort()
sprintf()
sqrt()
status()
strchr()
strjoin()
strlen()
strlwr()
strrchr()
strrstr()
strsplit()
strstr()
strsub()
strtod()
strtol()
strupr()
strxstr()
system()
t2day()
t2dayofweek()
t2hour()
t2minute()
t2month()
t2second()
t2string()
t2year()
tan()
time()
tolower()
toupper()
trunc()
u2inch()
u2mic()
u2mil()
u2mm()
variant()
xmlattribute()
xmlattributes()
xmlelement()
xmlelements()
xmltags()
xmltext()

Zeichenfunktionen

Zeichenfunktionen werden zum Bearbeiten einzelner Zeichen verwendet.

Die folgenden Zeichenfunktionen sind verfügbar:

isalnum()
isalpha()
iscntrl()
isdigit()
isgraph()
islower()
isprint()
ispunct()
isspace()
isupper()
isxdigit()
tolower()
toupper()

is...()

Funktion

Überprüfen, ob ein Zeichen in eine bestimmte Kategorie fällt

Syntax

int isalnum(char c);
int isalpha(char c);
int iscntrl(char c);
int isdigit(char c);
int isgraph(char c);
int islower(char c);
int isprint(char c);
int ispunct(char c);
int isspace(char c);
int isupper(char c);
int isxdigit(char c);

Gibt Folgendes zurück

Die Funktionen für is... geben einen Wert ungleich null zurück, wenn das angegebene Zeichen in die Kategorie fällt; ansonsten null.

Zeichenkategorien

isalnum   letters (A to Z or a to z) or digits (0 to 9)
isalpha   letters (A to Z or a to z)
iscntrl   delete characters or ordinary control characters (0x7F or 0x00 to 0x1F)
isdigit   digits (0 to 9)
isgraph   printing characters (except space)
islower   lowercase letters (a to z)
isprint   printing characters (0x20 to 0x7E)
ispunct   punctuation characters (iscntrl or isspace)
isspace   space, tab, carriage return, new line, vertical tab, or formfeed  (0x09 to 0x0D, 0x20)
isupper   uppercase letters (A to Z)
isxdigit  hex digits (0 to 9, A to F, a to f)

Beispiel

char c = 'A';
if (isxdigit(c))
   printf("%c is hex\n", c);
else
   printf("%c is not hex\n", c);

to...()

Funktion

Konvertieren eines Zeichens in Groß- oder Kleinbuchstaben

Syntax

char tolower(char c);
char toupper(char c);

Gibt Folgendes zurück

Die tolower-Funktion gibt das konvertierte Zeichen zurück, wenn c in Großbuchstaben geschrieben ist. Alle anderen Zeichen werden unverändert zurückgegeben. Die toupper-Funktion gibt das konvertierte Zeichen zurück, wenn c in Kleinbuchstaben geschrieben ist. Alle anderen Zeichen werden unverändert zurückgegeben.

Siehe auch strupr, strlwr.

Funktionen zur Dateiverarbeitung

Die Funktionen zur Dateinamenverarbeitung werden verwendet, um mit Dateinamen, Größen und Zeitstempeln zu arbeiten.

Weitere Informationen zum Schreiben in eine Datei finden Sie unter output().

fileerror()

Funktion

Gibt den Status der E/A-Operationen zurück.

Syntax

int fileerror();

Gibt Folgendes zurück

Die fileerror-Funktion gibt 0 zurück, wenn alles in Ordnung ist.

Siehe auch output, printf, fileread.

fileerror prüft den Status aller E/A-Operationen, die seit dem letzten Aufruf dieser Funktion ausgeführt wurden, und gibt 0 zurück, wenn alles in Ordnung ist. Wenn eine der E/A-Operationen einen Fehler verursacht hat, wird ein anderer Wert als 0 zurückgegeben.

Rufen Sie vor einer E/A-Operation fileerror auf, um einen möglichen vorherigen Fehlerstatus zurückzusetzen, und rufen Sie die Funktion nach der E/A-Operation erneut auf, um zu sehen, ob sie erfolgreich war.

Wenn fileerror einen anderen Wert als 0 zurückgibt (wodurch ein Fehler angezeigt wird), wurde dem Benutzer bereits eine entsprechende Fehlermeldung angezeigt.

Beispiel

fileerror();
output("file.txt", "wt") {
  printf("Test\n");
  }
if (fileerror())
   exit(1);

fileglob()

Funktion

Durchführen einer Verzeichnissuche

Syntax

int fileglob(string &array[], string pattern);

Gibt Folgendes zurück

Die fileglob-Funktion gibt die Anzahl der in die Anordnung kopierten Einträge zurück.

Siehe auch dlgFileOpen(), dlgFileSave().

fileglob führt eine Verzeichnissuche mit pattern durch.

pattern darf die Zeichen '' und '?' als Platzhalter enthalten. Wenn *pattern mit einem '/' endet, wird der Inhalt des angegebenen Verzeichnisses zurückgegeben.

Namen in der resultierenden Anordnung, die mit einem '/' enden, sind Verzeichnisnamen.

Die Anordnung wird alphabetisch sortiert, wobei die Verzeichnisse zuerst angezeigt werden.

Die speziellen Einträge '.' und '..' (für die aktuellen und übergeordneten Verzeichnisse) werden nie in der Anordnung zurückgegeben.

Wenn pattern nicht übereinstimmt oder wenn Sie nicht über die Berechtigung verfügen, das angegebene Verzeichnis zu durchsuchen, ist die resultierende Anordnung leer.

Anmerkung für Windows-Benutzer: Das Verzeichnis-Trennzeichen in der Anordnung ist immer ein Schrägstrich. Dadurch wird sichergestellt, dass User-Language-Programme plattformunabhängig funktionieren. In der Anordnung wird der umgekehrte Schrägstrich ('\') auch als Verzeichnis-Trennzeichen behandelt.

Beim Sortieren von Dateinamen unter Windows wird die Groß-/Kleinschreibung nicht berücksichtigt.

Beispiel

string a[];
int n = fileglob(a, "*.brd");

Dateinamenfunktionen

Funktion

Teilen eines Dateinamens in einzelnen Teile

Syntax

string filedir(string file);
string fileext(string file);
string filename(string file);
string filesetext(string file, string newext);

Gibt Folgendes zurück

filedir gibt das Verzeichnis der Datei zurück (einschließlich des Laufwerkbuchstabens unter Windows).

fileext gibt die Dateierweiterung zurück.

filename gibt den Namen der Datei (einschließlich der Erweiterung) zurück.

filesetext gibt die Datei mit auf newext festgelegter Erweiterung zurück.

Siehe auch Dateidatenfunktionen.

Beispiel

if (board) board(B) {
  output(filesetext(B.name, ".out")) {
    ...
    }
  }

Dateidatenfunktionen

Funktion

Ruft den Zeitstempel und die Größe einer Datei ab.

Syntax

int filesize(string filename);
int filetime(string filename);

Gibt Folgendes zurück

filesize gibt die Größe (in Byte) der angegebenen Datei zurück.

filetime gibt den Zeitstempel der angegebenen Datei in Sekunden zurück. Das Format ist kompatibel für die Verwendung mit den Zeitfunktionen.

Siehe auch Zeit- und Dateinamenfunktionen.

Beispiel

board(B)
  printf("Board: %s\nSize: %d\nTime: %s\n",
         B.name, filesize(B.name),
         t2string(filetime(B.name)));

Dateieingabefunktionen

Dateieingabefunktionen werden verwendet, um Daten aus Dateien zu lesen. Die folgende Dateieingabe ist verfügbar:

fileread()

Weitere Informationen zum Schreiben in eine Datei finden Sie unter output().

fileread()

Funktion

Liest Daten aus einer Datei.

Syntax

int fileread(dest, string file);

Gibt Folgendes zurück

fileread gibt die Anzahl der Objekte zurück, die aus der Datei gelesen werden.

Die tatsächliche Bedeutung des Rückgabewerts hängt vom Typ von dest ab.

Siehe auch lookup, strsplit, fileerror.

Wenn es sich bei dest um eine Zeichenanordnung handelt, wird die Datei als binäre Rohdaten gelesen, und der Rückgabewert entspricht der Anzahl der Byte, die in die Zeichenanordnung eingelesen werden (was der Dateigröße entspricht).

Wenn es sich bei dest um eine Zeichenfolgenanordnung handelt, wird die Datei als Textdatei gelesen (eine Zeile pro Anordnungselement), und der Rückgabewert entspricht der Anzahl der Zeilen, die in die Zeichenfolgenanordnung eingelesen werden. Zeilenumbruchzeichen werden entfernt.

Wenn dest eine Zeichenfolge ist, wird die gesamte Datei in diese Zeichenfolge gelesen, und der Rückgabewert entspricht der Länge dieser Zeichenfolge (die nicht notwendigerweise der Dateigröße entspricht, wenn das Betriebssystem Textdateien mit dem Zeichen cr/lf anstelle eines newline-Zeichens speichert).

Beispiel

char b[];
int nBytes = fileread(b, "data.bin");
string lines[];
int nLines = fileread(lines, "data.txt");
string text;
int nChars = fileread(text, "data.txt");

Mathematische Funktionen

Mathematische Funktionen werden zum Ausführen mathematischer Operationen verwendet. Die folgenden mathematischen Funktionen sind verfügbar:

abs()
acos()
asin()
atan()
ceil()
cos()
exp()
floor()
frac()
log()
log10()
max()
min()
pow()
round()
sin()
sqrt()
trunc()
tan()

Fehlermeldungen

Wenn die Argumente eines mathematischen Funktionsaufrufs zu einem Fehler führen, zeigt die Fehlermeldung die tatsächlichen Werte der Argumente an. Damit führen die Anweisungen

real x = -1.0;
real r = sqrt(2 * x);

zur Fehlermeldung

Invalid argument in call to 'sqrt(-2)'

Absolute, maximale und minimale Funktionen

Funktion

Absolute, maximale und minimale Funktionen

Syntax

type abs(type x);
type max(type x, type y);
type min(type x, type y);

Gibt Folgendes zurück

abs gibt den absoluten Wert von x zurück.

max gibt das Maximum von x und y zurück.

min gibt das Minimum von x und y zurück.

Der Rückgabetyp dieser Funktionen entspricht dem (größeren) Typ der Argumente. type muss char, int oder real sein.

Beispiel

real x = 2.567, y = 3.14;
printf("The maximum is %f\n", max(x, y));

Rundungsfunktionen

Funktion

Rundungsfunktionen

Syntax

real ceil(real x);
real floor(real x);
real frac(real x);
real round(real x);
real trunc(real x);

Gibt Folgendes zurück

ceil gibt die kleinste Ganzzahl zurück, die nicht kleiner als x ist.

floor gibt die größte Ganzzahl zurück, die nicht größer als x ist.

frac gibt den Bruchteil von x zurück.

round gibt x gerundet auf die nächste Ganzzahl zurück.

trunc gibt den ganzzahligen Teil von x zurück.

Beispiel

real x = 2.567;
printf("The rounded value of %f is %f\n", x, round(x));

Trigonometrische Funktionen

Funktion

Trigonometrische Funktionen

Syntax

real acos(real x);
real asin(real x);
real atan(real x);
real cos(real x);
real sin(real x);
real tan(real x);

Gibt Folgendes zurück

acos gibt den Arkuskosinus von x zurück.

asin gibt den Arkussinus von x zurück.

atan gibt den Arkustangens von x zurück.

cos gibt den Kosinus von x zurück.

sin gibt den Sinus von x zurück.

tan gibt die Tangente von x zurück.

Konstanten

PI ist der Wert von "pi" (3.14...)

Anmerkung:

Winkel werden in Bogenmaß angegeben.

Beispiel

real x = PI / 2;
printf("The sine of %f is %f\n", x, sin(x));

Exponentialfunktionen

Funktion

Exponentialfunktionen

Syntax

real exp(real x);
real log(real x);
real log10(real x);
real pow(real x, real y);
real sqrt(real x);

Gibt Folgendes zurück

exp gibt den Exponentialwert e für die Potenz von x zurück. log gibt den natürlichen Logarithmus von x zurück. log10 gibt den dekadischen Logarithmus von x zurück. pow gibt den Wert von x für die Potenz von y zurück. sqrt gibt die Quadratwurzel von x zurück.

Beispiel

real x = 2.1;
printf("The square root of %f is %f\n", x, sqrt(x));
printf("The 3rd root of %f is %f\n", x, pow(x, 1.0/3));

Sonstige Funktionen

Sonstige Funktionen werden verwendet, um unterschiedliche Aufgaben auszuführen.

Die folgenden sonstigen Funktionen sind verfügbar:

Konfigurationsparameter
country()
exit()
fdlsignature()
language()
lookup()
palette()
sort()
status()
system()
Einheitenkonvertierung

Konfigurationsparameter

Funktion

Speichern und Abrufen von Konfigurationsparametern

Syntax

string cfgget(string name[, string default]);
void cfgset(string name, string value);

Gibt Folgendes zurück

cfgget gibt den Wert des unter dem angegebenen Namen gespeicherten Parameters zurück. Wenn noch kein solcher Parameter gespeichert wurde, wird der Wert des optionalen Vorgabewerts (oder eine leere Zeichenfolge, sofern kein Vorgabewert angegeben ist) zurückgegeben. Mit der cfgget-Funktion werden Werte abgerufen, die zuvor mit einem Aufruf von cfgset() gespeichert wurden.

Mit der cfgset-Funktion wird der Parameter mit dem angegebenen Namen auf den angegebenen Wert gesetzt.

Die gültigen Zeichen für den Namen lauten 'A'-'Z', 'a'-'z', '0'-'9', '.' und '_'.

Bei Parameternamen muss die Groß- und Kleinschreibung beachtet werden.

Die Parameter werden in der eaglerc-Datei des Benutzers gespeichert. Um sicherzustellen, dass unterschiedliche User-Language-Programme die jeweiligen Parameter der anderen User-Language-Programme nicht überschreiben, wenn sie dieselben Parameternamen verwenden, wird empfohlen, den Namen des ULP an den Anfang des Parameternamens zu setzen. So könnte z. B. bei einem ULP namens mytool.ulp, das einen Parameter namens MyParam verwendet, dieser Parameter unter folgendem Namen gespeichert werden:

mytool.MyParam

Da die Konfigurationsparameter in der eaglerc-Datei gespeichert sind, die auch alle anderen benutzerspezifischen EAGLE-Parameter enthält, ist es auch möglich, mit cfgget() und cfgset() auf die EAGLE-Parameter zuzugreifen. Um sicherzustellen, dass keine ULP-Parameter mit EAGLE-Parametern kollidieren, müssen die EAGLE-Parameter das Präfix EAGLE enthalten. Beispiel:

EAGLE:Option.XrefLabelFormat

Beachten Sie, dass keine Dokumentation zu allen internen EAGLE-Parametern und zu deren Speicherung in der eaglerc-Datei existiert. Seien Sie außerdem beim Ändern dieser Parameter sehr vorsichtig. Wie bei der eaglerc-Datei selbst sollten Sie diese Parameter nur bearbeiten, wenn Sie sich gut auskennen. Einige EAGLE-Parameter erfordern möglicherweise einen Neustart von EAGLE, damit die Änderungen wirksam werden. In der eaglerc-Datei werden die User-Language-Parameter mit dem Präfix ULP: gespeichert. Daher kann dieses Präfix optional vor den User-Language-Parameternamen stehen. Beispiel:

ULP:mytool.MyParam

Beispiel

string MyParam = cfgget("mytool.MyParam", "SomeDefault");
MyParam = "OtherValue";
cfgset("mytool.MyParam", MyParam);

country()

Funktion

Gibt den Ländercode des verwendeten Systems zurück.

Syntax

string country();

Gibt Folgendes zurück

country gibt eine Zeichenfolge bestehend aus zwei Großbuchstaben zurück, die das im aktuellen System verwendete Land angeben. Wenn keine derartige Ländereinstellung ermittelt werden kann, wird die Vorgabe US zurückgegeben.

Siehe auch Sprache.

Beispiel

dlgMessageBox("Your country code is: " + country());

exit()

Funktion

Das User-Language-Programm wird beendet.

Syntax

void exit(int result);
void exit(string command);

Siehe auch AUSFÜHREN.

Die exit-Funktion beendet die Ausführung eines User-Language-Programms.

Wenn ein ganzzahliges Ergebnis ausgegeben wird, wird es als Rückgabewert des Programms verwendet. Wenn ein Zeichenfolgenbefehl angegeben ist, wird dieser Befehl ausgeführt, als ob er direkt nach dem Befehl AUSFÜHREN in die Befehlszeile eingegeben worden wäre. In diesem Fall wird der Rückgabewert des ULP auf EXIT_SUCCESS festgelegt.

Konstanten

EXIT_SUCCESS    return value for successful program execution (value 0)
EXIT_FAILURE    return value for failed program execution (value -1)

fdlsignature()

Funktion

Berechnet eine digitale Signatur für DesignLink von Premier Farnell.

Syntax

string fdlsignature(string s, string key);

Die fdlsignature-Funktion wird zum Berechnen einer digitalen Signatur beim Zugriff auf die DesignLink-Benutzeroberfläche von Premier Farnell verwendet.

language()

Funktion

Gibt den Sprachencode des verwendeten Systems zurück.

Syntax

string language();

Gibt Folgendes zurück

language gibt eine Zeichenfolge bestehend aus zwei Kleinbuchstaben zurück, die die im aktuellen System verwendete Sprache angeben. Wenn keine derartige Spracheinstellung ermittelt werden kann, wird die Vorgabe en zurückgegeben.

Siehe auch Land.

Die Sprachfunktion kann verwendet werden, um anzugeben, dass ein ULP je nach der vom aktuellen System verwendeten Sprache eine andere Meldungszeichenfolge verwenden soll.

Im folgenden Beispiel werden alle im ULP verwendeten Zeichenfolgen in der Zeichenfolgenanordnung I18N[] aufgeführt. Dabei ist eine Zeichenfolge vorangestellt, die die verschiedenen von diesem ULP unterstützten Sprachcodes enthält. Beachten Sie die vtab-Zeichen, die zum Trennen der einzelnen Teile jeder Zeichenfolge verwendet werden (sie sind wichtig für die Suchfunktion), und die Verwendung der Kommas zum Trennen der Zeichenfolgen. Die eigentliche Arbeit wird in der tr()-Funktion ausgeführt, die die übersetzte Version der angegebenen Zeichenfolge zurückgibt. Wenn die ursprüngliche Zeichenfolge in der I18N-Anordnung nicht gefunden werden kann oder keine Übersetzung für die aktuelle Sprache vorhanden ist, wird die ursprüngliche Zeichenfolge in unübersetzter Form verwendet.

Die erste in der I18N-Anordnung definierte Sprache muss diejenige sein, in der die im gesamten ULP verwendeten Zeichenfolgen geschrieben werden. Dies sollte im Allgemeinen Englisch sein, damit das Programm für die größte Benutzeranzahl zugänglich ist.

Beispiel

string I18N[] = {
  "en\v"
  "de\v"
  "it\v"
  ,
  "I18N Demo\v"
  "Beispiel f?r Internationalisierung\v"
  "Esempio per internazionalizzazione\v"
  ,
  "Hello world!\v"
  "Hallo Welt!\v"
  "Ciao mondo!\v"
  ,
  "+Ok\v"
  "+Ok\v"
  "+Approvazione\v"
  ,
  "-Cancel\v"
  "-Abbrechen\v"
  "-Annullamento\v"
  };
int Language = strstr(I18N[0], language()) / 3;
string tr(string s)
{
  string t = lookup(I18N, s, Language, '\v');
  return t ? t : s;
}
dlgDialog(tr("I18N Demo")) {
  dlgHBoxLayout dlgSpacing(350);
  dlgLabel(tr("Hello world!"));
  dlgHBoxLayout {
    dlgPushButton(tr("+Ok")) dlgAccept();
    dlgPushButton(tr("-Cancel")) dlgReject();
    }
  };

lookup()

Funktion

Sucht Daten in einer Zeichenfolgenanordnung.

Syntax

string lookup(string array[], string key, int field_index[, char separator]);
string lookup(string array[], string key, string field_name[, char separator]);

Gibt Folgendes zurück

lookup gibt den Wert des Felds zurück, das durch field_index oder field_name identifiziert wird. Wenn das Feld nicht vorhanden ist oder kein mit der Zeichenfolge übereinstimmender Schlüssel gefunden wurde, wird eine leere Zeichenfolge zurückgegeben.

Siehe auch fileread, strsplit.

Eine Anordnung, die mit lookup() verwendet werden kann, besteht aus Textzeichenfolgen, die jeweils für einen Datensatz stehen.

Jeder Datensatz enthält eine willkürliche Anzahl von Feldern, die durch ein Trennzeichen getrennt sind (Vorgabe ist '\t', Tabulator). Das erste Feld in einem Datensatz wird als Schlüssel verwendet und erhält die Nummer 0.

Alle Datensätze müssen eindeutige Schlüsselfelder aufweisen, und keines der Schlüsselfelder darf leer sein. Andernfalls ist nicht definiert, welcher Datensatz gefunden wird.

Wenn die erste Zeichenfolge in der Anordnung einen Header-Datensatz enthält (d. h. ein Datensatz, bei dem jedes Feld den entsprechenden Inhalt beschreibt), wird durch die Verwendung von lookup mit einer field_name-Zeichenfolge automatisch der Index dieses Felds bestimmt. Dadurch können Sie die lookup-Funktion verwenden, ohne genau zu wissen, welcher Feldindex die gewünschten Daten enthält. Der Benutzer muss sicherstellen, dass der erste Datensatz tatsächlich Header-Informationen enthält.

Wenn der Schlüsselparameter im Aufruf von lookup() eine leere Zeichenfolge ist, wird die erste Zeichenfolge der Anordnung verwendet. Dadurch kann ein Programm ermitteln, ob ein Header-Datensatz mit den erforderlichen Feldnamen vorhanden ist.

Wenn ein Feld das Trennzeichen enthält, muss dieses Feld in doppelten Anführungszeichen eingeschlossen werden (z. B. "abc;def", wobei das Semikolon (';') als Trennzeichen verwendet wird). Das Gleiche gilt, wenn das Feld doppelte Anführungszeichen (") enthält. In diesem Fall müssen die doppelten Anführungszeichen innerhalb des Felds verdoppelt werden (z. B. "abc;""def";ghi", was abc;"def";ghi entspricht).

Es empfiehlt sich, das vorgegebene Tabulatortrennzeichen zu verwenden, bei dem dieses Problem nicht besteht (kein Feld kann ein Tabulatorzeichen enthalten).

Hier sehen Sie eine Beispieldatendatei (zur besseren Lesbarkeit wurde ';' als Trennzeichen verwendet):

Name;Manufacturer;Code;Price
7400;Intel;I-01-234-97;$0.10
68HC12;Motorola;M68HC1201234;$3.50

Beispiel

string OrderCodes[];
if (fileread(OrderCodes, "ordercodes") > 0) {
   if (lookup(OrderCodes, "", "Code", ';')) {
      schematic(SCH) {
        SCH.parts(P) {
          string OrderCode;
          // both following statements do exactly the same:
          OrderCode = lookup(OrderCodes, P.device.name, "Code", ';');
          OrderCode = lookup(OrderCodes, P.device.name, 2, ';');
          }
        }
      }
   else
      dlgMessageBox("Missing 'Code' field in file 'ordercodes');
   }

palette()

Funktion

Gibt Informationen zur Farbpalette zurück.

Syntax

int palette(int index[, int type]);

Gibt Folgendes zurück

Die palette-Funktion gibt einen ganzzahligen ARGB-Wert in der Form 0xaarrggbb oder den Typ der aktuell verwendeten Palette (abhängig vom Wert des Index) zurück.

Die palette-Funktion gibt den ARGB-Wert der Farbe mit dem angegebenen Index zurück (der sich im Bereich 0 bis PALETTE_ENTRIES-1 befinden kann). Wenn type nicht angegeben (oder -1) ist, wird die dem aktuellen Editor-Fenster zugewiesene Palette verwendet. Andernfalls gibt type an, welche Farbpalette verwendet werden soll (PALETTE_BLACK, PALETTE_WHITE oder PALETTE_COLORED). Der spezielle Wert -1 für index führt dazu, dass die Funktion den Wert type der Palette zurückgibt, der derzeit im Editor-Fenster verwendet wird.

Wenn index oder type außerhalb des Bereichs liegt, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Konstanten


PALETTE_TYPES	Anzahl der Palettentypen (3)
PALETTE_BLACK	Palette mit schwarzem Hintergrund (0)
PALETTE_WHITE	Palette mit weißem Hintergrund (1)
PALETTE_COLORED	Palette mit farbigem Hintergrund (2)
PALETTE_ENTRIES	Anzahl der Farben pro Palette (64)

sleep()

Funktion

Verzögerung um die Anzahl der angegebenen Sekunden

Syntax

void sleep(int seconds);

Siehe auch time().

Die Ruhezustandsfunktion verzögert die Ausführung eines ULP-Programms für eine bestimmte Anzahl an Sekunden.

sort()

Funktion

Sortiert eine Anordnung oder eine Reihe von Anordnungen.

Syntax

void sort(int number, array1[, array2,...]);

Die Sortierfunktion sortiert eine gegebene Anordnung array1 direkt oder sortiert eine Reihe von Anordnungen (beginnend mit array2). In diesem Fall ist array1 eine Anordnung von Ganzzahlen, die als Zeigeranordnung verwendet wird.

In jedem Fall definiert das Zahlenargument die Anzahl der Elemente in der/den Anordnung(en).

Sortieren einer einzelnen Anordnung

Wenn die Sortierfunktion mit einer einzelnen Anordnung aufgerufen wird, wird diese Anordnung direkt sortiert, wie im folgenden Beispiel:

string A[];
int n = 0;
A[n++] = "World";
A[n++] = "Hello";
A[n++] = "The truth is out there...";
sort(n, A);
for (int i = 0; i < n; ++i)
    printf(A[i]);

Sortieren einer Reihe von Anordnungen

Wenn die Sortierfunktion mit mehr als einer Anordnung aufgerufen wird, muss die erste Anordnung eine ganzzahlige Anordnung sein, während alle anderen Anordnungen einen beliebigen Anordnungstyp aufweisen können und die zu sortierenden Daten beinhalten. Das folgende Beispiel zeigt, wie die erste Anordnung als Zeiger verwendet wird:

numeric string Nets[], Parts[], Instances[], Pins[];
int n = 0;
int index[];
schematic(S) {
  S.nets(N) N.pinrefs(P) {
    Nets[n] = N.name;
    Parts[n] = P.part.name;
    Instances[n] = P.instance.name;
    Pins[n] = P.pin.name;
    ++n;
    }
  sort(n, index, Nets, Parts, Instances, Pins);
  for (int i = 0; i < n; ++i)
      printf("%-8s %-8s %-8s %-8s\n",
             Nets[index[i]], Parts[index[i]],
             Instances[index[i]], Pins[index[i]]);
  }

Dahinter steht der Gedanke, dass ein Netz mit mehreren Pins verbunden sein kann. In einer Netzliste sollen die Netznamen möglicherweise sortiert werden, und in einem Netz sollen außerdem die Bauteilnamen sortiert werden usw. Beachten Sie die Verwendung des numerischen Schlüsselworts in den Zeichenfolgenanordnungen. Dadurch werden die Zeichenfolgen so sortiert, dass ein numerischer Teil am Ende der Zeichenfolgen berücksichtigt wird, wodurch IC1, IC2,... IC9, IC10 anstelle der alphabetischen Reihenfolge IC1, IC10, IC2,...IC9 zurückgegeben wird.

Beim Sortieren einer Reihe von Anordnungen muss die erste (index-)Anordnung den Typ int aufweisen und muss nicht initialisiert werden. Alle Inhalte, die die index-Anordnung möglicherweise vor dem Aufrufen der Sortierfunktion enthält, werden durch die resultierenden Indexwerte überschrieben.

status()

Funktion

Zeigt eine Statusmeldung in der Statusleiste an.

Syntax

void status(string message);

Siehe auch dlgMessageBox().

Die Statusfunktion zeigt die angegebene Meldung in der Statusleiste des Editor-Fensters an, in dem das ULP ausgeführt wird.

system()

Funktion

Führt ein externes Programm aus.

Syntax

int system(string command);

Gibt Folgendes zurück

Die Systemfunktion gibt den Beendigungsstatus des Befehls zurück. Dies ist in der Regel 0, wenn alles in Ordnung ist, und im Fall eines Fehlers ein Wert ungleich null.

Die Systemfunktion führt das externe Programm aus, das durch die Befehlszeichenfolge vorgegeben ist, und wartet, bis das Programm beendet wird.

Eingabe-/Ausgabeumleitung

Wenn das externe Programm die Standardeingabe aus einer bestimmten Datei lesen (oder die Standardausgabe in eine bestimmte Datei schreiben) soll, muss die Eingabe/Ausgabe umgeleitet werden.

Unter Linux und Mac OS X wird hierzu in der Befehlszeile einfach ein '<' oder '>', gefolgt vom gewünschten Dateinamen hinzugefügt. Beispiel:

system("program < infile > outfile");

Hierbei wird das Programm ausführt, und es wird aus infile gelesen und in outfile geschrieben.

Unter Windows müssen Sie dazu explizit einen Befehlsprozessor ausführen. Beispiel:

    system("cmd.exe /c program < infile > outfile");

(Auf DOS-basierten Windows-Systemen verwenden Sie command.com anstelle von cmd.exe.)

Hintergrundausführung

Die Systemfunktion wartet, bis das angegebene Programm beendet ist. Dies ist nützlich für Programme, die nur wenige Sekunden lang ausgeführt werden oder die volle Aufmerksamkeit des Benutzers erfordern.

Wenn ein externes Programm länger ausgeführt wird und der Systemaufruf sofort zurückgegeben werden soll, ohne dass gewartet wird, bis das Programm beendet ist, können Sie der Befehlszeichenfolge unter Linux und Mac OS X ganz einfach ein '&' hinzufügen. Beispiel:

system("program &");

Unter Windows müssen Sie dazu explizit einen Befehlsprozessor ausführen. Beispiel:

system("cmd.exe /c start program");

(Auf DOS-basierten Windows-Systemen verwenden Sie command.com anstelle von cmd.exe.)

Beispiel

int result = system("simulate -f filename");

Dadurch wird ein Simulationsprogramm aufgerufen, das mit einer Datei arbeitet, die gerade mit dem ULP erstellt wurde. Beachten Sie, dass die Simulation hier nur ein Beispiel und nicht Teil des EAGLE-Pakets ist.

Wenn Sie steuern möchten, welche Systembefehle tatsächlich ausgeführt werden, können Sie eine Wrapper-Funktion schreiben, die den Benutzer zur Bestätigung auffordert, bevor der Befehl ausgeführt wird. Beispiel:

int MySystem(string command)
{
  if (dlgMessageBox("!Ok to execute the following command?<p><tt>" + command + "</tt>", "&Yes", "&No") == 0)
     return system(command);
  return -1;
}
int result = MySystem("simulate -f filename");

Einheitenkonvertierung

Funktion

Konvertiert interne Einheiten.

Syntax

real u2inch(int n);
real u2mic(int n);
real u2mil(int n);
real u2mm(int n);
int inch2u(real n);
int mic2u(real n);
int mil2u(real n);
int mm2u(real n);

Gibt Folgendes zurück

u2inch gibt den Wert von n in Zoll zurück.

u2mic gibt den Wert von n in Mikrometer (1/1000 mm) zurück.

u2mil gibt den Wert von n in mil (1/1000 Zoll) zurück.

u2mm gibt den Wert von n in Millimetern zurück.

inch2u gibt den Wert von n (in Zoll) in internen Einheiten zurück.

mic2u gibt den Wert von n (in Mikrometer) in internen Einheiten zurück.

mil2u gibt den Wert von n (in mil) in internen Einheiten zurück.

mm2u gibt den Wert von n (in Millimetern) in internen Einheiten zurück.

Siehe auch UL_GRID.

EAGLE speichert alle Koordinaten- und Größenwerte als ganzzahlige Werte mit einer Auflösung von 1/320000 mm (0.003125 µ). Die oben genannten Funktionen zur Einheitenkonvertierung können verwendet werden, um diese internen Einheiten in die gewünschten Maßeinheiten zu konvertieren und umgekehrt.

Beispiel

board(B) {
  B.elements(E) {
    printf("%s at (%f, %f)\n", E.name,
           u2mm(E.x), u2mm(E.y));
    }
  }

Netzfunktionen

Netzfunktionen werden verwendet, um auf Remote-Standorte im Internet zuzugreifen.

neterror()

Funktion

Gibt die Fehlermeldung des letzten Aufrufs der Netzfunktion zurück.

Syntax

string neterror(void);

Gibt Folgendes zurück

neterror gibt eine Textmeldung zurück, in der der Fehler beschrieben wird, der beim letzten Aufruf einer Netzwerkfunktion aufgetreten ist.

Wenn kein Fehler aufgetreten ist, ist der Rückgabewert eine leere Zeichenfolge.

Siehe auch netget, netpost.

Die neterror-Funktion sollte aufgerufen werden, nachdem eine der anderen Netzfunktionen einen negativen Wert zurückgegeben hat. Dies weist darauf hin, dass ein Fehler aufgetreten ist. Der Rückgabewert von neterror ist eine Textzeichenfolge, die dem Benutzer angezeigt werden kann.

Bei Fehlern im Zusammenhang mit SSL-Verbindungen (HTTPS) beachten Sie außerdem die Anmerkung in netget.

Beispiel

string Result;
if (netget(Result, "http://web.cadsoft.de/cgi-bin/http-test?see=me&hear=them") >= 0) {
   // process Result
   }
else
   dlgMessageBox(neterror());

netget()

Funktion

Führt eine GET-Anforderung im Netz durch.

Syntax

int netget(dest, string url[, int timeout]);

Gibt Folgendes zurück

netget gibt die Anzahl der vom Netz gelesenen Objekte zurück. Die tatsächliche Bedeutung des Rückgabewerts hängt vom Typ von dest ab.

Im Fall eines Fehlers wird ein negativer Wert zurückgegeben, und neterror() wird möglicherweise aufgerufen, um dem Benutzer eine Fehlermeldung anzuzeigen.

Siehe auch netpost, neterror, fileread.

Die Funktion netget sendet die angegebene URL an das Netzwerk und speichert das Ergebnis in der dest-Variable. Wenn über die als Wartezeit angegebene Zeitspanne keine Netzaktivität aufgetreten ist, wird die Verbindung beendet. Die vorgabemäßige Wartezeit beträgt 20 Sekunden.

Die URL muss das zu verwendende Protokoll (HTTP, HTTPS oder FTP) enthalten und kann name=value-Paare von Parametern umfassen. Beispiel:

http://web.cadsoft.de/cgi-bin/http-test?see=me&hear=them
ftp://ftp.cadsoft.de/eagle/userfiles/README

Wenn eine Benutzer-ID und ein Kennwort für den Zugriff auf einen Remote-Standort erforderlich sind, können Sie diese wie folgt angegeben werden:

https://userid:password@www.site.com/...

Wenn es sich bei dest um eine Zeichenanordnung handelt, wird das Ergebnis als binäre Rohdaten behandelt, und der Rückgabewert entspricht der Anzahl der Byte, die in der Zeichenanordnung gespeichert sind.

Wenn es sich bei dest um eine Zeichenfolgenanordnung handelt, wird das Ergebnis als Textdaten behandelt (eine Zeile pro Anordnungselement), und der Rückgabewert entspricht der Anzahl der Zeilen, die in der Zeichenfolgenanordnung gespeichert sind. Zeilenumbruchzeichen werden entfernt.

Wenn es sich bei dest um eine Zeichenfolge handelt, wird das Ergebnis in dieser Zeichenfolge gespeichert, und der Rückgabewert entspricht der Länge der Zeichenfolge. Beachten Sie, dass bei binären Daten das Ergebnis beim ersten Vorkommen eines Byte mit dem Wert 0x00 abgeschnitten wird.

Wenn Sie einen Proxy verwenden müssen, um über HTTP oder HTTPS auf das Internet zuzugreifen, können Sie diesen im Dialogfeld Konfigurieren unter Hilfe/Nach Update suchen in der Systemsteuerung einrichten.

SSL-Verbindungen

Für SSL-Verbindungen (Anforderung über HTTPS) sind Zertifikate erforderlich, die auf einigen Systemen möglicherweise fehlen oder abgelaufen sind. Die Verbindung schlägt dann mit der entsprechenden Fehlermeldung fehl, die Sie mit neterror() abfragen können. Mit dieser Fehlermeldung sollte es möglich sein, fehlende Zertifikate zu installieren oder abgelaufene Zertifikate zu aktualisieren und die Verbindung so herzustellen. Die Vorgehensweise hängt von Ihrem System ab (z. B. unter Windows über die Systemsteuerung/Internetoptionen usw.).

Beispiel

string Result;
if (netget(Result, "http://web.cadsoft.de/cgi-bin/http-test?see=me&hear=them") >= 0) {
   // process Result
   }
else
   dlgMessageBox(neterror());

netpost()

Funktion

Führt eine POST-Anforderung im Netz durch.

Syntax

int netpost(dest, string url, string data[, int timeout[, string content_type] ]);

Gibt Folgendes zurück

netpost gibt die Anzahl der Objekte zurück, die aus dem Netz gelesen werden. Die tatsächliche Bedeutung des Rückgabewerts hängt vom Typ von dest ab. Im Fall eines Fehlers wird ein negativer Wert zurückgegeben, und neterror() wird möglicherweise aufgerufen, um dem Benutzer eine Fehlermeldung anzuzeigen.

Siehe auch netget, neterror, fileread.

Die Funktion netpost sendet die angegebenen Daten an die angegebene URL im Netz und speichert das Ergebnis in der dest-Variablen.

Wenn über die als Wartezeit angegebene Zeitspanne keine Netzaktivität aufgetreten ist, wird die Verbindung beendet. Die vorgabemäßige Wartezeit beträgt 20 Sekunden.

Wenn content_type angegeben ist, wird der vorgegebene Inhaltstyp text/html; charset=utf-8 überschrieben. Die URL muss das zu verwendende Protokoll (HTTP oder HTTPS) enthalten.

Wenn eine Benutzer-ID und ein Kennwort für den Zugriff auf einen Remote-Standort erforderlich sind, können Sie diese wie folgt angegeben werden:

https://userid:password@www.secret-site.com/...

Wenn Sie Probleme im Zusammenhang mit SSL-Verbindungen (HTTPS) haben, beachten Sie die Anmerkung in netget.

Beispiel

string Data = "see=me\nhear=them";
string Result;
if (netpost(Result, "http://web.cadsoft.de/cgi-bin/http-test", Data) >= 0) {
   // process Result
   }
else
   dlgMessageBox(neterror());

Druckfunktionen

Druckfunktionen werden zum Drucken formatierter Zeichenfolgen verwendet.

printf()

Funktion

Schreibt die formatierte Ausgabe in eine Datei.

Syntax

int printf(string format[, argument, ...]);

Gibt Folgendes zurück

Die printf-Funktion gibt die Anzahl der Zeichen zurück, die in die Datei geschrieben wurden, die mit der letzten Ausgabeanweisung geöffnet wurde. Im Fall eines Fehlers gibt printf -1 zurück.

Siehe auch sprintf, output, fileerror.

Format-Zeichenfolge

Die Formatzeichenfolge steuert, wie die Argumente konvertiert, formatiert und gedruckt werden. Es müssen genauso viele Argumente vorhanden sein, wie für das Format erforderlich sind. Die Anzahl und der Typ der Argumente werden mit dem Format verglichen, und eine Abweichung führt zu einer Fehlermeldung. Die Formatzeichenfolge enthält zwei Arten von Objekten: einfache Zeichen und Format-Platzhalter.

Einfache Zeichen werden einfach unverändert in die Ausgabe kopiert.
Format-Platzhalter rufen Argumente aus der Argumentliste ab und wenden eine Formatierung auf sie an.

Format-Platzhalter

Ein Format-Platzhalter hat das folgende Format:

% [flags] [width] [.prec] type

Jeder Format-Platzhalter beginnt mit dem Prozentzeichen (%). Nach dem % steht Folgendes, in der nachfolgend angegebenen Reihenfolge:

an optional sequence of flag characters, [flags]
an optional width specifier, [width]
an optional precision specifier, [.prec]
the conversion type character, type

Konvertierungstyp-Zeichen


d	Dezimal-Ganzzahl mit Vorzeichen
o	Oktal-Ganzzahl ohne Vorzeichen
u	Dezimal-Ganzzahl ohne Vorzeichen
x	Hexadezimal-Ganzzahl ohne Vorzeichen (mit a, b,...)
X	Hexadezimal-Ganzzahl ohne Vorzeichen (mit A, B,...)
f	Reeller Wert mit Vorzeichen im Format [-]dddd.dddd
e	Reeller Wert mit Vorzeichen im Format [-]d.dddde±ddd
E	Wie e, aber mit E für Exponent
g	Reeller Wert mit Vorzeichen im e- oder f-Format, basierend auf dem angegebenen Wert und der angegebenen Genauigkeit
G	Wie g, aber mit E für Exponent, wenn das e-Format verwendet wurde
c	Einzelnes Zeichen
s	Zeichenfolge
%	Das %-Zeichen wird gedruckt.

Flag-Zeichen

Die folgenden Flag-Zeichen können in beliebiger Reihenfolge und Kombination angezeigt werden:


"-"	Das formatierte Element wird im Feld linksbündig ausgerichtet; normalerweise werden die Elemente rechtsbündig ausgerichtet.
"+"	Ein positives Element mit Vorzeichen beginnt immer mit einem Pluszeichen (+); normalerweise beginnen nur negative Elemente mit einem Vorzeichen.
" "	Ein positives Element mit Vorzeichen beginnt immer mit einem Leerzeichen; wenn sowohl "+" als auch " " angegeben sind, überschreibt "+" das Leerzeichen " ".

Breite-Platzhalter

Mit dem Breite-Platzhalter wird die minimale Feldbreite für einen Ausgabewert festgelegt.

Die Breite wird entweder direkt durch eine Dezimalzeichenfolge oder indirekt durch ein Sternchen (*) angegeben. Wenn Sie für den Breite-Platzhalter ein Sternchen verwenden, bestimmt das Argument (das ein int-Argument sein muss) vor dem (mit diesem Format-Platzhalter) zu formatierenden Argument die minimale Ausgabefeldbreite.

In keinem Fall führt eine nicht vorhandene oder kleine Feldbreite dazu, dass ein Feld abgeschnitten wird. Wenn das Ergebnis einer Konvertierung breiter als die Feldbreite ist, wird das Feld einfach erweitert, um das Konvertierungsergebnis aufzunehmen.


n	Es werden mindestens n Zeichen gedruckt. Wenn der Ausgabewert weniger als n Zeichen enthält, wird die Ausgabe mit Leerzeichen aufgefüllt (rechts aufgefüllt, wenn das Flag "-" angegeben ist, ansonsten links aufgefüllt).
0n	Es werden mindestens n Zeichen gedruckt. Wenn der Ausgabewert weniger als n Zeichen enthält, wird er auf der linken Seite mit Nullen aufgefüllt.
*	Die Argumentliste enthält den Breite-Platzhalter, der dem zu formatierenden tatsächlichen Argument vorangestellt sein muss.

Genauigkeitsplatzhalter

Ein Genauigkeitsplatzhalter beginnt immer mit einem Punkt (.), um ihn von einem möglichen vorherigen Breite-Platzhalter zu trennen. Die Genauigkeit wird dann wie bei der Breite entweder direkt durch eine Dezimalzeichenfolge oder indirekt durch ein Sternchen (*) angegeben. Wenn Sie für den Genauigkeitsplatzhalter ein Sternchen verwenden, bestimmt das Argument (das ein int-Argument sein muss) vor dem (mit diesem Format-Platzhalter) zu formatierenden Argument die Genauigkeit.


Keine	Genauigkeit auf Vorgabe festgelegt.
.0	Bei int-Typen ist die Genauigkeit auf die Vorgabe gesetzt. Bei real-Typen wird kein Dezimalpunkt gedruckt.
.n	Es werden n Zeichen oder n Dezimalstellen gedruckt. Wenn der Ausgabewert mehr als n Zeichen enthält, kann die Ausgabe abgeschnitten oder gerundet werden (je nach type-Zeichen).
*	Die Argumentliste enthält den Genauigkeitsplatzhalter, der dem zu formatierenden tatsächlichen Argument vorangestellt sein muss.

Vorgegebene Genauigkeitswerte


douxX	1
eEf	6
gG	Alle signifikanten Ziffern
c	Keine Auswirkungen
s	Gesamte Zeichenfolge drucken

Auswirkung der Genauigkeitsangabe (.n) auf die Konvertierung


douxX	.n gibt an, dass mindestens n Zeichen gedruckt werden. Wenn das Eingabeargument weniger als n Ziffern aufweist, wird der Ausgabewert links mit Nullen aufgefüllt. Wenn das Eingabeargument mehr als n Ziffern aufweist, wird der Ausgabewert nicht abgeschnitten.
eEf	.n gibt an, dass nach dem Dezimalpunkt n Zeichen gedruckt werden und die zuletzt gedruckte Ziffer gerundet wird.
gG	.n gibt an, dass höchstens n signifikante Ziffern gedruckt werden.
c	.n hat keine Auswirkungen auf die Ausgabe.
s	.n gibt an, dass nicht mehr als n Zeichen gedruckt werden.

Binäre Nullzeichen

Im Gegensatz zu sprintf kann die printf-Funktion binäre Nullzeichen (0x00) drucken.

char c = 0x00;
printf("%c", c);

Beispiel

int i = 42;
real r = 3.14;
char c = 'A';
string s = "Hello";
printf("Integer: %8d\n", i);
printf("Hex:     %8X\n", i);
printf("Real:    %8f\n", r);
printf("Char:    %-8c\n", c);
printf("String:  %-8s\n", s);

sprintf()

Funktion

Schreibt die formatierte Ausgabe in eine Zeichenfolge.

Syntax

int sprintf(string result, string format[, argument, ...]);

Gibt Folgendes zurück

Die sprintf-Funktion gibt die Anzahl der Zeichen zurück, die in die Ergebniszeichenfolge geschrieben werden. Im Fall eines Fehlers gibt sprintf -1 zurück.

Siehe auch printf.

Format-Zeichenfolge

Siehe printf.

Binäre Nullzeichen

Beachten Sie, dass sprintf keine Zeichenfolgen mit eingebetteten binären Nullzeichen (0x00) zurückgeben kann. Wenn die resultierende Zeichenfolge ein binäres Nullzeichen enthält, werden alle Zeichen, die diesem Nullzeichen folgen, gelöscht. Verwenden Sie printf, wenn Sie binäre Daten ausgeben möchten.

Beispiel

string result;
int number = 42;
sprintf(result, "The number is %d", number);

Zeichenfolgenfunktionen

Zeichenfolgenfunktionen werden zum Bearbeiten von Zeichenfolgen verwendet.

Die folgenden Zeichenfolgenfunktionen sind verfügbar:

strchr()
strjoin()
strlen()
strlwr()
strrchr()
strrstr()
strsplit()
strstr()
strsub()
strtod()
strtol()
strupr()
strxstr()

strchr()

Funktion

Überprüft eine Zeichenfolge auf das erste Vorkommen eines bestimmten Zeichens.

Syntax

int strchr(string s, char c[, int index]);

Gibt Folgendes zurück

Die strchr-Funktion gibt den ganzzahligen Versatz des Zeichens in der Zeichenfolge zurück, oder -1, wenn das Zeichen in der Zeichenfolge nicht auftritt.

Siehe auch strrchr, strstr.

Wenn index angegeben wird, beginnt die Suche an dieser Position. Negative Werte werden vom Ende der Zeichenfolge gezählt.

Beispiel

string s = "This is a string";
char c = 'a';
int pos = strchr(s, c);
if (pos >= 0)
   printf("The character %c is at position %d\n", c, pos);
else
   printf("The character was not found\n");

strjoin()

Funktion

Verbindet eine Zeichenfolgenanordnung, um eine einzelne Zeichenfolge zu bilden.

Syntax

string strjoin(string array[], char separator);

Gibt Folgendes zurück

Die strjoin-Funktion gibt die kombinierten Einträge der Anordnung zurück.

Siehe auch strsplit, lookup, fileread.

strjoin verbindet alle Einträge in der Anordnung, getrennt durch das angegebene Trennzeichen, und gibt die resultierende Zeichenfolge zurück.

Wenn das Trennzeichen das Zeilenumbruchzeichen ('\n') ist, wird die resultierende Zeichenfolge mit einem Zeilenumbruchzeichen beendet. Dies geschieht, um eine Textdatei aus N Zeilen (die jeweils mit einem Zeilenumbruchzeichen enden) zu erhalten und wird mit der fileread()-Funktion eingelesen und in eine Anordnung von N Zeichenfolgen aufgeteilt, die mit der ursprünglichen Zeichenfolge verknüpft werden soll, wenn diese aus der Datei gelesen wird.

Beispiel

string a[] = { "Field 1", "Field 2", "Field 3" };
string s = strjoin(a, ':');

strlen()

Funktion

Berechnet die Länge einer Zeichenfolge.

Syntax

int strlen(string s);

Gibt Folgendes zurück

Die strlen-Funktion gibt die Anzahl der Zeichen in der Zeichenfolge zurück.

Beispiel

string s = "This is a string";
int l = strlen(s);
printf("The string is %d characters long\n", l);

strlwr()

Funktion

Wandelt Großbuchstaben in einer Zeichenfolge in Kleinbuchstaben um.

Syntax

string strlwr(string s);

Gibt Folgendes zurück

Die strlwr-Funktion gibt die geänderte Zeichenfolge zurück. Die ursprüngliche Zeichenfolge (als Parameter angegeben) wird nicht geändert.

Siehe auch strupr, tolower.

Beispiel

string s = "This Is A String";
string r = strlwr(s);
printf("Prior to strlwr: %s - after strlwr: %s\n", s, r);

strrchr()

Funktion

Überprüft eine Zeichenfolge auf das letzte Vorkommen eines bestimmten Zeichens.

Syntax

int strrchr(string s, char c[, int index]);

Gibt Folgendes zurück

Die strrchr-Funktion gibt den ganzzahligen Versatz des Zeichens in der Zeichenfolge zurück, oder -1, wenn das Zeichen in der Zeichenfolge nicht auftritt.

Siehe auch strchr, strrstr.

Wenn index angegeben wird, beginnt die Suche an dieser Position. Negative Werte werden vom Ende der Zeichenfolge gezählt.

Beispiel

string s = "This is a string";
char c = 'a';
int pos = strrchr(s, c);
if (pos >= 0)
   printf("The character %c is at position %d\n", c, pos);
else
   printf("The character was not found\n");

strrstr()

Funktion

Überprüft eine Zeichenfolge auf das letzte Vorkommen einer bestimmten Unterzeichenfolge.

Syntax

int strrstr(string s1, string s2[, int index]);

Gibt Folgendes zurück

Die Funktion strrstr gibt den ganzzahligen Versatz des ersten Zeichens von s2 in s1 oder -1 zurück, wenn die Unterzeichenfolge in der Zeichenfolge nicht vorhanden ist.

Siehe auch strstr, strrchr.

Wenn index angegeben wird, beginnt die Suche an dieser Position. Negative Werte werden vom Ende der Zeichenfolge gezählt.

Beispiel

string s1 = "This is a string", s2 = "is a";
int pos = strrstr(s1, s2);
if (pos >= 0)
   printf("The substring starts at %d\n", pos);
else
   printf("The substring was not found\n");

strsplit()

Funktion

Teilt eine Zeichenfolge in separate Felder auf.

Syntax

int strsplit(string &array[], string s, char separator);

Gibt Folgendes zurück

Die strsplit-Funktion gibt die Anzahl der in die Anordnung kopierten Einträge zurück.

Siehe auch strjoin, lookup, fileread.

strsplit teilt die Zeichenfolge s am angegebenen Trennzeichen und speichert die resultierenden Felder in der Anordnung.

Wenn das Trennzeichen das Zeilenumbruchzeichen ('\n') ist, wird das letzte Feld automatisch gelöscht, wenn es leer ist. Dies geschieht, um eine Textdatei aus N Zeilen (die jeweils mit einem Zeilenumbruchzeichen enden) zu erhalten und wird mit der fileread()-Funktion eingelesen, sodass sie in eine Anordnung von N Zeichenfolgen aufgeteilt wird. Bei anderen Trennzeichen wird ein leeres Feld am Ende der Zeichenfolge gezählt, sodass "a:b:c:" vier Felder ergibt, wobei das letzte leer ist.

Beispiel

string a[];
int n = strsplit(a, "Field 1:Field 2:Field 3", ':');

strstr()

Funktion

Überprüft eine Zeichenfolge auf das erste Vorkommen einer bestimmten Unterzeichenfolge.

Syntax

int strstr(string s1, string s2[, int index]);

Gibt Folgendes zurück

Die strstr-Funktion gibt den ganzzahligen Versatz des ersten Zeichens von s2 in s1 oder -1 zurück, wenn die Unterzeichenfolge in der Zeichenfolge nicht vorhanden ist.

Siehe auch strrstr, strchr, strxstr.

Wenn index angegeben wird, beginnt die Suche an dieser Position. Negative Werte werden vom Ende der Zeichenfolge gezählt.

Beispiel

string s1 = "This is a string", s2 = "is a";
int pos = strstr(s1, s2);
if (pos >= 0)
   printf("The substring starts at %d\n", pos);
else
   printf("The substring was not found\n");

strsub()

Funktion

Extrahiert eine untergeordnete Zeichenfolge aus einer Zeichenfolge.

Syntax

string strsub(string s, int start[, int length]);

Gibt Folgendes zurück

Die strsub-Funktion gibt die durch den Wert start und length angegebene Unterzeichenfolge zurück. Der Wert für length muss positiv sein, andernfalls wird eine leere Zeichenfolge zurückgegeben. Wenn length ausgelassen wird, wird der Rest der Zeichenfolge (beginnend bei start) zurückgegeben.

Wenn start auf eine Position außerhalb der Zeichenfolge verweist, wird eine leere Zeichenfolge zurückgegeben.

Beispiel

string s = "This is a string";
string t = strsub(s, 4, 7);
printf("The extracted substring is: %s\n", t);

strtod()

Funktion

Konvertiert eine Zeichenfolge in einen reellen Wert.

Syntax

real strtod(string s);

Gibt Folgendes zurück

Die Funktion strtod gibt die numerische Darstellung der angegebenen Zeichenfolge als reellen Wert zurück. Die Konvertierung endet am ersten Zeichen, das nicht in das Format einer reellen Konstante passt. Wenn während der Konvertierung der Zeichenfolge ein Fehler auftritt, wird 0.0 zurückgegeben.

Siehe auch strtol.

Beispiel

string s = "3.1415";
real r = strtod(s);
printf("The value is %f\n", r);

strtol()

Funktion

Konvertiert eine Zeichenfolge in einen ganzzahligen Wert.

Syntax

int strtol(string s);

Gibt Folgendes zurück

Die strtol-Funktion gibt die numerische Darstellung der angegebenen Zeichenfolge als int-Wert zurück. Die Konvertierung endet am ersten Zeichen, das nicht in das Format einer ganzzahligen Konstante passt. Wenn während der Konvertierung der Zeichenfolge ein Fehler auftritt, wird 0 zurückgegeben.

Siehe auch strtod.

Beispiel

string s = "1234";
int i = strtol(s);
printf("The value is %d\n", i);

strupr()

Funktion

Konvertiert Kleinbuchstaben in einer Zeichenfolge in Großbuchstaben.

Syntax

string strupr(string s);

Gibt Folgendes zurück

Die strupr-Funktion gibt die geänderte Zeichenfolge zurück. Die ursprüngliche Zeichenfolge (als Parameter angegeben) wird nicht geändert.

Siehe auch strlwr, toupper.

Beispiel

string s = "This Is A String";
string r = strupr(s);
printf("Prior to strupr: %s - after strupr: %s\n", s, r);

strxstr()

Funktion

Überprüft eine Zeichenfolge auf das erste Vorkommen eines bestimmten regulären Ausdrucks.

Syntax

int strxstr(string s1, string s2[, int index[, int &length]]);

Gibt Folgendes zurück

Die strxstr-Funktion gibt den ganzzahligen Versatz der Unterzeichenfolge in s1 zurück, der dem regulären Ausdruck in s2 entspricht, oder -1, wenn der reguläre Ausdruck in der Zeichenfolge nicht übereinstimmt.

Siehe auch strstr, strchr, strrstr.

Wenn index angegeben wird, beginnt die Suche an dieser Position. Negative Werte werden vom Ende der Zeichenfolge gezählt.

Wenn length angegeben ist, wird die tatsächliche Länge der entsprechenden Unterzeichenfolge in dieser Variablen zurückgegeben.

Reguläre Ausdrücke ermöglichen die Suche nach einer Anordnung innerhalb einer Textzeichenfolge. Der reguläre Ausdruck "i.*a" enthält beispielsweise eine Folge von Zeichen, die mit einem 'i' beginnt, gefolgt von einem beliebigen Zeichen ('.') in beliebiger Häufigkeit ('*'), und das mit 'a' endet. Es würde beispielsweise "is a" sowie "is this a" oder "ia" gefunden. Einzelheiten zu regulären Ausdrücken finden Sie beispielsweise im Buch Mastering Regular Expressions von Jeffrey E. F. Friedl.

Beispiel

string s1 = "This is a string", s2 = "i.*a";
int len = 0;
int pos = strxstr(s1, s2, 0, len);
if (pos >= 0)
   printf("The substring starts at %d and is %d charcaters long\n", pos, len);
else
   printf("The substring was not found\n");

URN-Funktionen

URN-Funktionen werden zur URN-Verarbeitung verwendet.

urnbase()

Funktion

Extrahiert den Basis-URN aus einer URN-Zeichenfolge.

Syntax

string urnbase(string urn);

Gibt Folgendes zurück

Die urnbase-Funktion gibt den Basis-URN des angegebenen URN zurück, d. h. den URN ohne nachfolgende Version oder /. Der Basis-URN von urn:adsk.eagle:footprint:123/4 lautet beispielsweise urn:adsk.eagle:footprint:123. Wenn keine Version vorhanden ist, wird die Eingabezeichenfolge zurückgegeben.

Beispiel

string urn = "urn:adsk.eagle:footprint:123/4";
string base = urnbase(urn);
printf("The base URN is: %s\n", base);

urnversion()

Funktion

Extrahiert die Version aus einer URN-Zeichenfolge.

Syntax

int urnversion(string urn);

Gibt Folgendes zurück

Die Funktion urnversion gibt die Version des angegebenen URN zurück, d. h. die Zahl nach dem /. Wenn keine Version vorhanden ist, wird -1 zurückgegeben.

Beispiel

string urn = "urn:adsk.eagle:footprint:123/4";
int version = urnversion(urn);
printf("The URN version is: %d\n", version);

Zeitfunktionen

Zeitfunktionen werden verwendet, um Uhrzeit- und Datumsinformationen abzurufen und zu verarbeiten.

Die folgenden Zeitfunktionen sind verfügbar:

sleep()
t2day()
t2dayofweek()
t2hour()
t2minute()
t2month()
t2second()
t2string()
t2year()
time()
timems()

time()

Funktion

Ruft die aktuelle Systemzeit ab.

Syntax

int time(void);

Gibt Folgendes zurück

Die Zeitfunktion gibt die aktuelle Systemzeit als die Anzahl der Sekunden zurück, die seit einem systemabhängigen Referenzdatum verstrichen sind.

Siehe auch Zeitkonvertierungen, filetime, timems().

Beispiel

int CurrentTime = time();

timems()

Funktion

Ruft die Anzahl der Millisekunden seit dem Start des ULP ab.

Syntax

int timems(void);

Gibt Folgendes zurück

Die timems-Funktion gibt die Anzahl der Millisekunden seit dem Start des ULP zurück. Nach 86400000 Millisekunden (d. h. alle 24 Stunden) beginnt der Wert wieder bei 0.

Siehe auch time.

Beispiel

int elapsed = timems();

Zeitkonvertierungen

Funktion

Sie können einen Zeitwert in Tag, Monat, Jahr usw. konvertieren.

Syntax

int t2day(int t);
int t2dayofweek(int t);
int t2hour(int t);
int t2minute(int t);
int t2month(int t);
int t2second(int t);
int t2year(int t);

string t2string(int t[, string format]);

Gibt Folgendes zurück

*t2day* returns the day of the month (1..31)
*t2dayofweek* returns the day of the week (0=sunday..6)
*t2hour* returns the hour (0..23)
*t2minute* returns the minute (0..59)
*t2month* returns the month (0..11)
*t2second* returns the second (0..59)
*t2year* returns the year (including century!)
*t2string* returns a formatted string containing date and time

Siehe auch time.

Die t2string-Funktion ohne den optionalen Formatparameter konvertiert die angegebene Zeit t in eine länderspezifische Zeichenfolge in der lokalen Zeit.

Wenn t2string mit einer Formatzeichenfolge aufgerufen wird, wird dieses Format verwendet, um zu bestimmen, wie das Ergebnis aussehen soll.

Die folgenden Ausdrücke können in einer Formatzeichenfolge verwendet werden:


d	Tag als Zahl ohne führende Null (1 bis 31)
dd	Tag als Zahl mit einer führenden Null (01 bis 31)
ddd	Abgekürzter lokalisierter Name des Tags (z. B. Mo bis So)
dddd	Langer lokalisierter Name des Tags (z. B. Montag bis Sonntag)
M	Monat als Zahl ohne führende Null (1-12)
MM	Monat als Zahl mit einer führenden Null (01-12)
MMM	Abgekürzter lokalisierter Name des Monats (z. B. Jan bis Dez)
MMMM	Langer lokalisierter Name des Monats (z. B. Januar bis Dezember)
yy	Jahr als zweistellige Zahl (00-99)
yyyy	Jahr als vierstellige Zahl
h	Stunde ohne führende Null (0 bis 23 oder 1 bis 12 bei AM/PM-Anzeige)
hh	Stunde mit einer führenden Null (00 bis 23 oder 01 bis 12 bei AM/PM-Anzeige)
m	Minute ohne führende Null (0 bis 59)
mm	Minute mit einer führenden Null (00 bis 59)
s	Sekunde ohne führende Null (0 bis 59)
ss	Sekunde mit einer führenden Null (00 bis 59)
Z	Millisekunden ohne führende Nullen (immer 0, da die angegebene Zeit nur eine Genauigkeit von einer Sekunde aufweist)
zzz	Millisekunden mit führenden Nullen (immer 000, da die angegebene Zeit nur eine Genauigkeit von einer Sekunde aufweist)
AP	Verwendung der AM/PM-Anzeige (AP wird durch AM oder PM ersetzt)
ap	Verwendung der am/pm-Anzeige (ap wird durch am oder pm ersetzt)
U	Anzeigen der angegebenen Zeit in UTC (muss das erste Zeichen sein; Vorgabe ist die lokale Zeit)

Alle anderen Zeichen werden unverändert kopiert. Jede Zeichenfolge, die in einfachen Anführungszeichen eingeschlossen ist, wird als Text behandelt und nicht als Ausdruck verwendet. Zwei aufeinander folgende einzelne Anführungszeichen ('') werden in der Ausgabe durch ein einzelnes Anführungszeichen ersetzt.

Beispiel

int t = time();
printf("It is now %02d:%02d:%02d\n",
       t2hour(t), t2minute(t), t2second(t));
printf("ISO time is %s\n", t2string(t, "Uyyyy-MM-dd hh:mm:ss"));

Objektfunktionen

Objektfunktionen werden verwendet, um auf allgemeine Informationen zu Objekten zuzugreifen.

Die folgenden Objektfunktionen sind verfügbar:

clrgroup()
ingroup()
setgroup()
setvariant()
variant()

clrgroup()

Funktion

Löscht die Gruppen-Flags eines Objekts.

Syntax

void clrgroup(object);

Siehe auch ingroup(), setgroup(), Befehl GRUPPE.

Die clrgroup()-Funktion löscht die Gruppen-Flags des angegebenen Objekts, sodass es nicht mehr Teil der zuvor definierten Gruppe ist.

Bei der Anwendung auf ein Objekt, das andere Objekte enthält (z. B. UL_BOARD oder UL_NET), werden die Gruppen-Flags aller enthaltenen Objekte rekursiv gelöscht, jedoch mit entsprechenden Einschränkungen wie für setgroup().

Beispiel

board(B) {
  B.elements(E)
    clrgroup(E);
  }

ingroup()

Funktion

Überprüft, ob sich ein Objekt in der Gruppe befindet.

Syntax

int ingroup(object);

Gibt Folgendes zurück

Die ingroup-Funktion gibt einen Wert ungleich null zurück, wenn sich das angegebene Objekt in der Gruppe befindet.

Siehe auch clrgroup(), setgroup(), Befehl GRUPPE.

Wenn eine Gruppe im Editor definiert wurde, kann die ingroup()-Funktion verwendet werden, um zu überprüfen, ob ein bestimmtes Objekt Teil der Gruppe ist.

Objekte mit einer einzigen Koordinate, die einzeln in der aktuellen Zeichnung ausgewählt werden können (z. B. UL_TEXT, UL_VIA, UL_CIRCLE usw.), geben einen Wert ungleich null in einem Aufruf für ingroup() zurück, wenn sich diese Koordinate innerhalb der definierten Gruppe befindet.

UL_WIRE gibt 0, 1, 2 oder 3 zurück, je nachdem, ob sich keiner, der erste, der zweite oder beide Endpunkte in der Gruppe befinden.

UL_RECTANGLE und UL_FRAME geben einen Wert ungleich null zurück, wenn sich eine oder mehrere der Ecken in der Gruppe befinden. Für die obere rechte Ecke wurde der Wert Bit 0 eingestellt, für die obere linke Ecke Bit 1, für die untere linke Ecke Bit 2 und für die untere rechte Ecke Bit 3.

Objekte mit höherer Rangordnung, die keine Koordinaten besitzen (UL_NET, UL_SEGMENT, UL_SIGNAL, UL_POLYGON) oder die nicht als Zeichnungsobjekte verfügbar sind (UL_SHEET, UL_DEVICESET, UL_SYMBOL, UL_FOOTPRINT), geben einen Wert ungleich null zurück, wenn sich eines oder mehrere der enthaltenen Objekte in der Gruppe befinden. Weitere Informationen zu den Objekthierarchien finden Sie unter Objekttypen.

UL_CONTACTREF und UL_PINREF haben zwar keine eigenen Koordinaten, geben jedoch einen Wert ungleich null zurück, wenn sich das referenzierte UL_CONTACT- bzw. UL_PIN-Objekt innerhalb der Gruppe befindet. Für andere nicht auswählbare Objekte wie UL_GRID, UL_VARIANT oder Linien eines UL_TEXT- oder UL_FRAME-Objekts ist das Verhalten von ingroup() nicht definiert und sollte daher nicht verwendet werden.

Identifizieren des Kontextmenüobjekts

Wenn das ULP über ein Kontextmenü gestartet wird, kann über den Gruppenmechanismus auf das ausgewählte Objekt zugegriffen werden. Aus dem ausgewählten Objekt wird eine Ein-Element-Gruppe erstellt. Sie kann daher mit ingroup() identifiziert werden. (Siehe auch SETZEN und AUSFÜHREN).

Beispiel

output("group.txt") {
  board(B) {
    B.elements(E) {
      if (ingroup(E))
         printf("Element %s is in the group\n", E.name);
      }
    }
  }

setgroup()

Funktion

Legt die Gruppen-Flags eines Objekts fest.

Syntax

void setgroup(object[, int flags]);

Siehe auch clrgroup(), ingroup(), Befehl GRUPPE.

Die setgroup()-Funktion legt die Gruppen-Flags des angegebenen Objekts fest, sodass es Teil der Gruppe wird.

Wenn keine Flags angegeben sind, wird das Objekt der Gruppe als Ganzes hinzugefügt (d. h. alle seine Auswahlpunkte, falls es über mehrere verfügt).

Wenn Flags einen Wert ungleich null aufweisen, werden nur die Gruppen-Flags der angegebenen Punkte des Objekts festgelegt. Bei UL_WIRE bedeutet dies, dass '1' das Gruppen-Flag des ersten Punkts, '2' das des zweiten Punkts und '3' beide Flags festlegt. Alle zuvor festgelegten Gruppen-Flags bleiben unverändert, wenn ein Aufruf von setgroup() erfolgt.

Bei der Anwendung auf ein Objekt, das andere Objekte enthält (z. B. UL_BOARD oder UL_NET), werden die Gruppen-Flags aller enthaltenen Objekte rekursiv festgelegt, jedoch mit den folgenden Einschränkungen:

Dies gilt nicht für UL_LIBRARY und UL_SCHEMATIC. Untergeordnete Objekte, die nicht auswählbar oder nicht einzeln auswählbar sind, werden nicht markiert (z. B. UL_GRID- oder UL_VARIANT-Objekte oder Linien von UL_TEXT- oder UL_FRAME-Objekten).

Weitere Informationen zu den Objekthierarchien finden Sie unter Objekttypen.

Beispiel

board(B) {
  B.elements(E)
    setgroup(E);
  }

setvariant()

Funktion

Legt die aktuelle Bestückungsvariante fest.

Syntax

int setvariant(string name);

Siehe auch variant(), UL_VARIANTDEF, Befehl VARIANTE.

Die setvariant()-Funktion legt die aktuelle Bestückungsvariante auf die Variante fest, die nach Name angegeben wird. Dies kann verwendet werden, um durch alle Bauteile zu navigieren und die Daten genauso zu sehen, wie sie in der angegebenen Variante definiert sind.

Der Name muss auf eine gültige Bestückungsvariante verweisen, die in der aktuellen Zeichnung enthalten ist.

Diese Funktion gibt einen Wert ungleich null zurück, wenn die angegebene Bestückungsvariante vorhanden ist, ansonsten null.

Die Bestückungsvariante, die durch einen Aufruf von setvariant() festgelegt wurde, ist nur aktiv, bis das User-Language-Programm zurückkehrt. Danach entspricht die Variante in der Zeichnung der Variante vor dem Start des ULP.

Das Festlegen der Bestückungsvariante in einer Leiterplatte ist nur dann möglich, wenn der konsistente Stromlaufplan geladen ist.

Beispiel

if (setvariant("My variant")) {
   // do something ...
else
   // error: unknown variant

variant()

Funktion

Abfrage der aktuellen Bestückungsvariante

Syntax

string variant(void);

Siehe auch setvariant(), UL_VARIANTDEF, Befehl VARIANTE.

Die variant()-Funktion gibt den Namen der aktuellen Bestückungsvariante zurück. Wenn derzeit keine Variante ausgewählt ist, wird die leere Zeichenfolge ('') zurückgegeben.

Beispiel

string CurrentVariant = variant();

XML-Funktionen

XML-Funktionen werden zum Verarbeiten von XML-Daten (Extensible Markup Language) verwendet. Die folgenden XML-Funktionen sind verfügbar:

xmlattribute()
xmlattributes()
xmlelement()
xmlelements()
xmltags()
xmltext()

xmlattribute(), xmlattributes()

Funktion

Extrahieren der Attribute eines XML-Tags

Syntax

string xmlattribute(string xml, string tag, string attribute);
int xmlattributes(string &array[], string xml, string tag);

Siehe auch xmlelement(), xmltags(), xmltext().

Die xmlattribute-Funktion gibt den Wert des angegebenen Attributs aus dem angegebenen Tag innerhalb des angegebenen XML-Codes zurück. Wenn ein Attribut im selben Tag mehr als einmal vorhanden ist, wird der Wert des letzten Vorkommens verwendet.

Die xmlattributes-Funktion speichert die Namen aller Attribute des angegebenen Tags innerhalb des angegebenen XML-Codes in der Anordnung und gibt die Anzahl der gefundenen Attribute zurück. Die Reihenfolge entspricht nicht notwendigerweise der Reihenfolge im angegebenen XML-Code. Wenn ein Attribut im selben Tag mehr als einmal vorhanden ist, wird der Name nur einmal in der Anordnung angegeben.

Das Tag wird in Form eines Pfads angegeben.

Wenn der angegebene XML-Code einen Fehler enthält, ist das Ergebnis einer XML-Funktion leer, und dem Benutzer wird eine Warnmeldung angezeigt, die Informationen darüber enthält, wo der Fehler im ULP und im XML-Code aufgetreten ist. Beachten Sie, dass die Zeilen- und Spaltennummer im XML-Code auf die eigentliche Zeichenfolge verweist, die dieser Funktion als XML-Parameter zugewiesen ist.

Beispiel

// String XML contains the following data:
//<root>
//  <body abc="def" xyz="123">
//    ...
//  </body>
//</root>

string s[];
int n = xmlattributes(s, XML, "root/body");

// Result: { "abc", "xyz" }

string s = xmlattribute(XML, "root/body", "xyz");

// Result: "123"

xmlelement(), xmlelements()

Funktion

Extrahieren von Elementen aus XML-Code

Syntax

string xmlelement(string xml, string tag);
int xmlelements(string &array[], string xml, string tag);

Siehe auch xmltags(), xmlattribute(), xmltext().

Die xmlelement-Funktion gibt das komplette XML-Element des angegebenen Tags innerhalb des angegebenen XML-Codes zurück. Das Ergebnis enthält weiterhin den äußeren XML-Tag des Elements und kann daher zur weiteren Verarbeitung mit den anderen XML-Funktionen verwendet werden. Leerzeichen in Klartextteilen des Elements bleiben erhalten. Die allgemeine Formatierung der XML-Tags innerhalb des Elements und die Reihenfolge der Elementattribute können sich jedoch vom ursprünglichen XML-Code unterscheiden. Wenn in der XML-Datei mehrere Vorkommen des Tags existieren, wird das erste Vorkommen zurückgegeben. Verwenden Sie xmlelements, wenn Sie alle Vorkommen abrufen möchten.

Die xmlelements-Funktion funktioniert genauso wie xmlelement, gibt jedoch alle Vorkommen von Elementen mit dem angegebenen Tag zurück. Der Rückgabewert ist die Anzahl der in der Anordnung gespeicherten Elemente.

Das Tag wird in Form eines Pfads angegeben.

Beispiel

// String XML contains the following data:
//<root>
//  <body>
//    <contents>
//      <string>Some text 1</string>
//      <any>anything 1</any>
//    </contents>
//    <contents>
//      <string>Some text 2</string>
//      <any>anything 2</any>
//    </contents>
//    <appendix>
//      <string>Some text 3</string>
//    </appendix>
//  </body>
//</root>
//

string s = xmlelement(XML, "root/body/appendix");

// Result: " <appendix>\n  <string>Some text 3</string>\n </appendix>\n"

string s[];
int n = xmlelements(s, XML, "root/body/contents");

// Result: { " <contents>\n  <string>Some text 1</string>\n  <any>anything 1</any>\n </contents>\n",
//           " <contents>\n  <string>Some text 2</string>\n  <any>anything 2</any>\n </contents>\n"
//         }

xmltags()

Funktion

Extrahieren der Liste der Tag-Namen in einen XML-Code

Syntax

int xmltags(string &array[], string xml, string tag);

Siehe auch xmlelement(), xmlattribute(), xmltext().

Die xmltags-Funktion gibt die Namen aller Tags auf der obersten Ebene des angegebenen Tags innerhalb des angegebenen XML-Codes zurück. Der Rückgabewert ist die Anzahl der in der Anordnung gespeicherten Tag-Namen.

Jeder Tag-Name wird nur einmal zurückgegeben, auch wenn er mehrere Male im XML-Code existiert.

Das Tag wird in Form eines Pfads angegeben.

Beispiel

//String XML contains the following data:
//<root>
//  <body>
//    <contents>
//      <string>Some text 1</string>
//      <any>anything 1</any>
//    </contents>
//    <contents>
//      <string>Some text 2</string>
//      <any>anything 2</any>
//    </contents>
//    <appendix>
//      <string>Some text 3</string>
//    </appendix>
//  </body>
//</root>
//

string s[];
int n = xmltags(s, XML, "root/body");

// Result: { "contents", "appendix" } 

int n = xmltags(s, XML, "");        

// Result: "root"

xmltext()

Funktion

Extrahieren der Textdaten eines XML-Elements

Syntax

string xmltext(string xml, string tag);

Siehe auch xmlelement(), xmlattribute(), xmltags().

Die Funktion xmltext gibt die Textdaten des angegebenen Tags innerhalb des angegebenen XML-Codes zurück.

Alle Tags innerhalb des Texts werden entfernt, Leerzeichen (einschließlich Zeilenumbruchzeichen) werden beibehalten.

Das Tag wird in Form eines Pfads angegeben.

Beispiel

// String XML contains the following data:
//<root>
//  <body>
//    Some <b>text</b>.
//  </body>
//</root>
//

string s = xmltext(XML, "root/body");

// Result: "\n    Some text.\n  "

Builtin-Anweisungen

Builtin-Anweisungen werden in der Regel verwendet, um einen bestimmten Kontext zu öffnen, in dem auf Datenstrukturen oder Dateien zugegriffen werden kann. Die allgemeine Syntax einer Builtin-Anweisungen lautet wie folgt:

name(parameters) statement

Dabei ist name der Name der Builtin-Anweisung, parameters steht für einen oder mehrere Parameter, und statement ist der Code, der im Kontext ausgeführt wird, der von der Builtin-Anweisung geöffnet wird.

Beachten Sie, dass statement eine zusammengesetzte Anweisung sein kann. Beispiel:

board(B) {
  B.elements(E) printf("Element: %s\n", E.name);
  B.Signals(S)  printf("Signal: %s\n", S.name);
  }

Die folgenden Builtin-Anweisungen sind verfügbar:

board()
deviceset()
library()
module()
output()
footprint() (neu ab EAGLE 9.1)
schematic()
sheet()
symbol()

board()

Funktion

Öffnet einen Leiterplattenkontext.

Syntax

board(identifier) statement

Siehe auch schematic, library.

Die board-Anweisung öffnet einen Leiterplattenkontext, wenn das aktuelle Editor-Fenster eine Leiterplattenzeichnung enthält. Eine Variable des Typs UL_BOARD wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Leiterplattenkontext erfolgreich geöffnet und eine board-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die board-Variable zugegriffen werden, um weitere Daten aus der Leiterplatte abzurufen.

Wenn das aktuelle Editor-Fenster keine Leiterplattenzeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob eine Leiterplatte vorhanden ist

Wenn Sie die board-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Leiterplattenzeichnung enthält. In diesem Fall verhält sich board wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Leiterplattenzeichnung gibt, ansonsten wird 0 zurückgegeben.

Zugriff auf die Leiterplatte über einen Stromlaufplan

Wenn das aktuelle Editor-Fenster eine Stromlaufplanzeichnung enthält, können Sie dennoch auf die Leiterplatte dieses Stromlaufplans zugreifen, indem Sie das project-Präfix vor die board-Anweisung stellen. Beispiel:

project.board(B) { ... }

Dadurch wird ein Leiterplattenkontext geöffnet, unabhängig davon, ob das aktuelle Editor-Fenster eine Leiterplatten- oder eine Stromlaufplanzeichnung enthält. Es muss jedoch auf dem Desktop ein Editor-Fenster vorhanden sein, das diese Leiterplatte enthält.

Beispiel

if (board)
   board(B) {
     B.elements(E)
       printf("Element: %s\n", E.name);
     }

deviceset()

Funktion

Öffnet einen Deviceset-Kontext.

Syntax

deviceset(identifier) statement

Siehe auch footprint, symbol, library.

Die deviceset-Anweisung öffnet einen Deviceset-Kontext, wenn das aktuelle Editor-Fenster eine Device-Zeichnung enthält. Eine Variable des Typs UL_DEVICESET wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Deviceset-Kontext erfolgreich geöffnet und eine deviceset-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die deviceset-Variable zugegriffen werden, um weitere Daten aus dem Deviceset abzurufen.

Wenn das aktuelle Editor-Fenster keine Device-Zeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob ein Deviceset vorhanden ist

Wenn Sie die deviceset-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Device-Zeichnung enthält. In diesem Fall verhält sich deviceset wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Device-Zeichnung gibt, ansonsten wird 0 zurückgegeben.

Beispiel

if (deviceset)
   deviceset(D) {
     D.gates(G)
       printf("Gate: %s\n", G.name);
     }

library()

Funktion

Öffnet einen Bibliothekskontext.

Syntax

library(identifier) statement

Siehe auch board, schematic, deviceset, footprint, symbol.

Die library-Anweisung öffnet einen Bibliothekskontext, wenn das aktuelle Editor-Fenster eine Bibliothekszeichnung enthält. Eine Variable des Typs UL_LIBRARY wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Bibliothekskontext erfolgreich geöffnet und eine library-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die library-Variable zugegriffen werden, um weitere Daten aus der Bibliothek abzurufen.

Wenn das aktuelle Editor-Fenster keine Bibliothekszeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob eine Bibliothek vorhanden ist

Wenn Sie die library-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Bibliothekszeichnung enthält. In diesem Fall verhält sich library wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Bibliothekszeichnung gibt, ansonsten wird 0 zurückgegeben.

Beispiel

if (library)
   library(L) {
     L.devices(D)
       printf("Device: %s\n", D.name);
     }

module()

Funktion

Öffnet einen Modulkontext.

Syntax

module(identifier) statement

Siehe auch board, library, schematic, sheet.

Die module-Anweisung öffnet einen Modulkontext, wenn das aktuelle Editor-Fenster eine Modulzeichnung enthält. Die module-Anweisung öffnet einen Modulkontext, wenn im Editor-Fenster derzeit eine Modulzeichnung bearbeitet wird. Eine Variable des Typs UL_MODULE wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Modulkontext erfolgreich geöffnet und eine module-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die module-Variable zugegriffen werden, um weitere Daten aus dem Modul abzurufen.

Wenn das aktuelle Editor-Fenster keine Modulzeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.# Wenn im Editor-Fenster derzeit keine Modulzeichnung bearbeitet wird, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob ein Modul vorhanden ist

Wenn Sie die module-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Modulzeichnung enthält. In diesem Fall verhält sich module wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Modulzeichnung gibt, ansonsten wird 0 zurückgegeben.

Beispiel

if (module)
   module(M) {
     printf("Module: %s\n", M.name);
     }

output()

Funktion

Öffnet eine Ausgabedatei für nachfolgende printf()-Aufrufe.

Syntax

output(string filename[, string mode]) statement

Siehe auch printf, fileerror.

Die output-Anweisung öffnet eine Datei mit dem angegebenen Dateinamen und Modus für die Ausgabe durch nachfolgende printf()-Aufrufe. Wenn die Datei erfolgreich geöffnet wurde, wird die Anweisung ausgeführt. Anschließend wird die Datei geschlossen.

Wenn die Datei nicht geöffnet werden kann, wird eine Fehlermeldung angezeigt, und die Ausführung des ULP wird abgebrochen.

Die Ausgabedatei wird vorgabemäßig in das Projektverzeichnis geschrieben.

Dateimodi

Der Modusparameter definiert, wie die Ausgabedatei geöffnet werden soll. Wenn kein Modusparameter angegeben ist, lautet der Vorgabewert wt.

a append to an existing file, or create a new file if it does not exist
w create a new file (overwriting an existing file)
t open file in text mode
b open file in binary mode
D delete this file when ending the EAGLE session (only works together with w)
F force using this file name (normally *.brd, *.sch and *.lbr are rejected)

Moduszeichen können in beliebiger Reihenfolge und Kombination angezeigt werden. Es ist jedoch nur der letzte von a bzw. w oder t bzw. b bedeutend. So wird beim Modus abtw z. B. eine Datei für Textschreibvorgänge geöffnet, die identisch ist mit wt.

Verschachtelte Ausgabeanweisungen

Ausgabeanweisungen können verschachtelt sein, solange genügend Datei-Handles verfügbar sind und vorausgesetzt, dass keine zwei aktiven Ausgabeanweisungen auf dieselbe Datei zugreifen.

Beispiel

void PrintText(string s)
{
  printf("This also goes into the file: %s\n", s);
}
output("file.txt", "wt") {
  printf("Directly printed\n");
  PrintText("via function call");
  }

footprint(), neu ab EAGLE 9.1

Funktion

Öffnet einen Footprint-Kontext.

Syntax

footprint(identifier) statement (new as of EAGLE 9.1)

Siehe auch library, deviceset, symbol.

Die footprint-Anweisung öffnet einen Package-Kontext, wenn das aktuelle Editor-Fenster eine Package-Zeichnung enthält. Eine Variable des Typs UL_FOOTPRINT wird erstellt und erhält den durch die Kennung angegebenen Namen.

Anmerkung: Die footprint-Anweisung wurde in EAGLE 9.1 neu eingeführt. Für die Abwärtskompatibilität mit früheren EAGLE-Versionen steht package als Alias zur Verfügung.

Nachdem der Footprint-Kontext erfolgreich geöffnet und eine footprint-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die footprint-Variable zugegriffen werden, um weitere Daten aus dem Grundriss abzurufen.

Wenn das aktuelle Editor-Fenster keine Footprint-Zeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob ein Footprint vorhanden ist

Wenn Sie die footprint-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Footprint-Zeichnung enthält. In diesem Fall verhält sich footprint wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Footprint-Zeichnung gibt, ansonsten wird 0 zurückgegeben.

Beispiel

if (footprint)
   footprint(F) {
     F.contacts(C)
       printf("Contact: %s\n", C.name);
     }

schematic()

Funktion

Öffnet einen Stromlaufplan-Kontext.

Syntax

schematic(identifier) statement

Siehe auch board, library, module, sheet.

Die schematic-Anweisung öffnet einen Stromlaufplan-Kontext, wenn das aktuelle Editor-Fenster eine Stromlaufplan-Zeichnung enthält. Eine Variable des Typs UL_SCHEMATIC wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Stromlaufplan-Kontext erfolgreich geöffnet und eine Stromlaufplan-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die Stromlaufplan-Variable zugegriffen werden, um weitere Daten aus dem Stromlaufplan abzurufen.

Wenn das aktuelle Editor-Fenster keine Stromlaufplan-Zeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob ein Stromlaufplan vorhanden ist

Wenn Sie die schematic-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Stromlaufplan-Zeichnung enthält. In diesem Fall verhält sich schematic wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Stromlaufplan-Zeichnung gibt, ansonsten wird 0 zurückgegeben.

Zugriff auf den Stromlaufplan über eine Leiterplatte

Wenn das aktuelle Editor-Fenster eine Leiterplattenzeichnung enthält, können Sie dennoch auf den Stromlaufplan der Leiterplatte zugreifen, indem Sie das project-Präfix vor die schematic-Anweisung stellen. Beispiel:

project.schematic(S) { ... }

Dadurch wird ein Stromlaufplan-Kontext geöffnet, unabhängig davon, ob das aktuelle Editor-Fenster eine Leiterplatten- oder eine Stromlaufplanzeichnung enthält. Es muss jedoch auf dem Desktop ein Editor-Fenster vorhanden sein, das diesen Stromlaufplan enthält.

Zugriff auf den aktuellen Plan

Verwenden Sie die sheet-Anweisung, um direkt auf den aktuell geladenen Plan zuzugreifen.

Zugriff auf das aktuelle Modul

Verwenden Sie die module-Anweisung, um direkt auf das derzeit bearbeitete Modul zuzugreifen.

Beispiel

if (schematic)
   schematic(S) {
     S.parts(P)
       printf("Part: %s\n", P.name);
     }

sheet()

Funktion

Öffnet einen Plankontext.

Syntax

sheet(identifier) statement

Siehe auch schematic.

Die sheet-Anweisung öffnet einen Plankontext, wenn das aktuelle Editor-Fenster eine Planzeichnung enthält. Eine Variable des Typs UL_SHEET wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Plankontext erfolgreich geöffnet und eine Planvariable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die Planvariable zugegriffen werden, um weitere Daten aus dem Plan abzurufen.

Wenn das aktuelle Editor-Fenster keine Planzeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob ein Plan vorhanden ist

Wenn Sie die sheet-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Planzeichnung enthält. In diesem Fall verhält sich sheet wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Planzeichnung gibt, ansonsten wird 0 zurückgegeben.

Beispiel

if (sheet)
   sheet(S) {
     S.instances(I)
       printf("Instance: %s\n", I.name);
     }

symbol()

Funktion

Öffnet einen Symbolkontext.

Syntax

symbol(identifier) statement

Siehe auch library, deviceset, footprint.

Die symbol-Anweisung öffnet einen Symbolkontext, wenn das aktuelle Editor-Fenster eine Symbolzeichnung enthält. Eine Variable des Typs UL_SYMBOL wird erstellt und erhält den durch die Kennung angegebenen Namen.

Nachdem der Symbolkontext erfolgreich geöffnet und eine symbol-Variable erstellt wurde, wird die Anweisung ausgeführt. Im Rahmen der Anweisung kann auf die symbol-Variable zugegriffen werden, um weitere Daten aus dem Symbol abzurufen.

Wenn das aktuelle Editor-Fenster keine Symbolzeichnung enthält, wird eine Fehlermeldung angezeigt, und das ULP wird beendet.

Überprüfen, ob ein Symbol vorhanden ist

Wenn Sie die symbol-Anweisung ohne ein Argument verwenden, können Sie überprüfen, ob das aktuelle Editor-Fenster eine Symbolzeichnung enthält. In diesem Fall verhält sich symbol wie eine ganzzahlige Konstante und gibt 1 zurück, wenn es im aktuellen Editor-Fenster eine Symbolzeichnung gibt, ansonsten wird 0 zurückgegeben.

Beispiel

if (symbol)
   symbol(S) {
     S.pins(P)
       printf("Pin: %s\n", P.name);
     }