Sie können diese API benutzen, um aus Natural-Programmen auf UNIX- und Windows-Dateien zuzugreifen.
Bei FILE / READ oder FILE / WRITE und wenn
der BUFFER-TYPE
B, C oder D benutzt wird:
CALLNAT 'NOPUNX1N' NOPUNX1A data-buffer[caller-module]
Bei allen anderen Aufrufen:
CALLNAT 'NOPUNX1N' NOPUNX1A [1X caller module]
Weitere Informationen siehe unter data buffer und caller module.
Für Aufrufe an NOPUNX1N müssen Sie die Parameter Data
Area NOPUNX1A benutzen, die im folgenden Abschnitt beschrieben
wird.
Dieser Abschnitt behandelt folgende Themen:
Folgende Themen werden behandelt:
Die Parameter in der Parameter Data Area NOPUNX1A
haben folgende Bedeutung:
| Parameter | Format/Länge | Verwendung | ||
|---|---|---|---|---|
OBJECT |
A16 | ein | Mögliche Werte:
|
|
FUNCTION
|
A8 | ein | Mögliche Werte für USER:
|
|
LOGON |
Bei einem Knoten anmelden | |||
LOGOFF
|
Bei einem Knoten abmelden. | |||
Mögliche Werte für FILE:
|
||||
APPEND |
An eine existierende Datei anhängen. | |||
COPY |
Datei kopieren. | |||
CLOSE |
Datei schließen. | |||
DELETE |
Datei löschen. | |||
DELDIR |
Verzeichnis löschen. | |||
DIR |
Datei-Liste. | |||
DTA |
Dateien sortiert nach Änderungszeit in aufsteigender Reihenfolge auflisten. | |||
DTD |
Dateien sortiert nach Änderungszeit in absteigender Reihenfolge auflisten. | |||
GETATTR |
Datei-Attribute abrufen. | |||
LINECNT |
Zeilen einer Datei zählen. | |||
MOVE |
Datei verschieben (oder umbenennen). | |||
READ |
Datei lesen. | |||
SCAN |
In ein Datei nach Strings suchen. | |||
WRITE |
Datei schreiben. | |||
Mögliche
Werte für JOB:
|
||||
CANCEL |
Einen Job stornieren. | |||
COMMAND |
Ein Kommando ausführen. | |||
GETEXIT |
Den Exit Code eines bereits beendeten Jobs abrufen. | |||
Mögliche
Werte für SERVER:
|
||||
CL-TL-G |
Command Log Level und Trace Level abrufen. | |||
RETURN-CODE |
N8 | aus | 0
|
Funktion war ok. |
4 |
Keine weiteren Daten | |||
101 |
Objekt ist nicht implementiert | |||
102 |
Kein UNIX- oder Windows-Knoten | |||
404 |
Benutzer nicht definiert | |||
5509 |
Anmeldung fehlgeschlagen. Überprüfen
Sie USERID und/oder PASSWORD.
|
|||
5510 |
Anmeldung erforderlich | |||
5995 |
Datei nicht gefunden | |||
| anderer Wert | Siehe Inhalt von
RETURN-TEXT.
|
|||
RETURN-TEXT |
A80 | aus | Erläuternder Text zu
RETURN-CODE.
|
|
NODE |
N5 | ein | Knoten, wie in Entire Operations definiert. | |
NODE-NAME |
A16 | ein | Knoten-Name
|
|
NODE-ACCESS-MODE |
A1 | nur von der API zu ändern | leer | Noch nicht geprüft. |
N |
Knoten ist nicht lokal. | |||
Y |
Knoten ist lokal. | |||
Dieses Feld wird von der
API bei USER / LOGON gesetzt. Es soll von der
Anwendung nicht geändert werden.
|
||||
USERID |
A20 | ein | Benutzerkennung für Logon. | |
GROUP |
A20 | ein | Optional: | |
| UNIX | Group für Logon. | |||
| Windows | Domäne für Logon. | |||
PASSWORD |
A16 | ein | Passwort für Logon.
Obsolet. Bitte Anmerkung |
|
SID oder SESSION-ID |
N10 | Kann nur von der API geändert werden. | Wird von der API nach einem erfolgreichen USER /
LOGON-Aufruf bereitgestellt. Bei anderen Aufrufen ist es ein
Eingabeparameter.
|
|
SERVER-COMMAND-LOG-LEVEL |
N5 | aus | Ausgabe von SERVER / CL-TL-G.
|
|
SERVER-TRACE-LEVEL |
N5 | aus | Ausgabe von SERVER / CL-TL-G.
|
|
HTML-CODE-HANDLING |
A1 | ein/aus | Für FILE-Funktionen.
|
|
CODEPAGE-ID |
N5 | ein | Für die FILE-Funktionen WRITE und
APPEND.
|
|
OPSYS-CLASS |
A1 | Kann nur von der API geändert werden. | Betriebssystemklasse des Knotens (NODE).
Mögliche Werte |
|
B |
BS2000 | |||
M |
z/OS | |||
X |
UNIX | |||
W |
Windows | |||
USE-PAM |
A1 | ein | Für USER / LOGON.
Mögliche Werte |
|
N |
Kein PAM für
LOGON verwenden.
|
|||
Y |
PAM für
LOGON verwenden.
|
|||
INHERIT-ACCESS-TIME |
A1 | ein | Für FILE-Funktionen.
|
|
BUFFER-FORMAT |
A1 | ein | Für die FILE-Funktionen READ,
WRITE und APPEND.
Mögliche Werte |
|
T |
Text, einzelner Datensatz. | |||
3 |
Text, mehrere Datensätze, 3-Byte-Felder. | |||
L |
Text, mehrere Datensätze, Felder mit variabler Länge. | |||
A |
Base64-kodiertes Format. | |||
UNUSED-1 |
A10 | - | Unbenutzt. | |
ESC-TRIGRAPH |
A1 | ein | Trigraph-Verwendung: | |
leer oder
N |
Keine Trigraph-Konvertierung erfolgt. | |||
Y
|
Fragezeichen (?) als Trigraph-Fluchtzeichen verwenden | |||
| anderes Zeichen | Dieses Zeichen als Trigraph-Fluchtzeichen verwenden. | |||
| Informationen zu Trigraphen-Kodierung siehe entsprechenden Abschnitt in Trigraphen-Kodierung für JCL-Start auf UNIX- und Windows-Knoten. | ||||
TRACE-LEVEL |
N1 | ein | 0 |
Kein Trace. |
>
0 |
Trace eingeschaltet. | |||
TRACE-TARGET |
A1 | ein | Gibt an, wohin der Trace geschrieben wird. | |
S |
SYSOUT | |||
L |
Entire Operations-Protokoll (NOP Log) | |||
B |
Beide:
SYSOUT und Entire Operations-Protokoll (NOP Log). Nur relevant, wenn
TRACE-LEVEL > 0.
|
|||
BUFFER-TYPE |
A1 | ein | Puffer-Typ.
Hauptsächliche Verwendung bei den
Mögliche Werte |
|
A (oder leer)
|
XS-FIRWA-BUFFER-TYPE,
Größe 600.
|
|||
B |
XS-FIRWB-BUFFER-TYPE,
Größe 9700.
|
|||
C |
XS-FIRWC-BUFFER-TYPE,
Größe 99000.
|
|||
D |
XS-FIRWD-BUFFER-TYPE,
Größe 59000.
|
|||
Bei den Puffer-Typen
B, C und D:
Der Puffer muss als separater Parameter im Statement
|
||||
OBJECT-AREA |
A1200 | - | Objekt-spezifische Felder. | |
Objekt: FILE
(Redefinition von OBJECT-AREA)
|
||||
F-FILE |
A250 | ein | Dateiname.
Der Dateiname muss vollständig qualifiziert sein. Das bedeutet, er muss einen vollständigen Pfad enthalten, der mit dem Root des Dateisystems beginnt. Der Dateiname kann Umgebungsvariablen enthalten. |
|
F-HANDLE |
N10 | Kann nur von der API zu geändert werden. | Datei-Handle.
Wird vom Entire System Server beim ersten Zugriff auf
die Datei vergeben. Aktiv bis |
|
F-LINE |
N10 | ein/aus | ein | Zeilennummer, ab der gelesen werden soll (0 oder 1: ab Dateibeginn lesen) |
| aus | (Letzte) gelesene Zeilennummer. | |||
F-NUMBER-RECORDS |
N10 | aus | Anzahl der gelesenen Datensätze. | |
F-SEARCH-TEXT |
A100 | ein | Nur bei FILE
/ SCAN: Text, nach dem in der Datei gesucht werden soll.
|
|
F-RECORD-BUFFER |
A600 | ein/aus | Gesamter Record-Buffer
(Redefinition von F-RECORD-BUFFER)
Wird nur bei |
|
F-RECORD-250 |
A250 | ein/aus | FILE / READ,
FILE / WRITE: Effektiver Datensatz.
Wird nur bei |
|
F-RECORD-SEPARATOR |
A5 | ein | Für zukünftige Verwendung. | |
F-LINE-LIMIT |
N10 | ein | FILE/COPY,
FILE/MOVE:
Bei Textdateien: Die maximale Anzahl der zu kopierenden oder verschiebenden Datensätze. |
|
Objekt: JOB
Funktion: COMMAND (Redefinition von
OBJECT-AREA).
|
||||
JCM-COMMAND |
A500 | ein | Das auszuführende Kommando. | |
JCM-OUTPUT-FILE |
A250 | ein | Die Ausgabedatei für das Kommando. | |
JCM-REMOVE-OUTPUT-FILE |
A1 | ein | N |
Die Ausgabedatei behalten. |
Y |
Die Ausgabedatei nach erfolgreicher Kommando-Ausführung löschen. | |||
JCM-USER |
A20 | ein | Benutzerkennung für das Kommando. | |
JCM-GROUP |
A20 | ein | Optional: | |
| Unix: | Gruppe für das Kommando. | |||
| Windows: | Domäne für das Kommando. | |||
JCM-WAIT-FOR-TERMINATION |
A1 | ein | N |
Auf die Beendigung des das Kommandos soll nicht gewartet werden. |
Y |
Auf die Beendigung des das Kommandos soll gewartet werden. | |||
JCM-OUTPUT-MODE |
A1 | ein | C |
Bestehende Ausgabedatei überschreiben. (Standardwert) |
A |
Falls die Ausgabedatei bereits existiert, Ausgabe an diese anfügen. | |||
JCM-EXIT-CODE-MSG-APPEND |
A1 | ein | N |
Keine Exit-Code-Meldung an die Ausgabedatei anhängen. |
Y |
Die Exit-Code-Meldung NPR3355 an die Ausgabedatei anhängen. (Standardwert) | |||
JCM-EXIT-CODE |
N10 | aus | Der Exit-Code des Kommandos. | |
JCM-PID |
N10 | aus | Die Prozesskennung des Kommandos. | |
Objekt: JOB
Funktion: SUBMIT (Redefinition von
OBJECT-AREA)
|
||||
JSU-SUBMIT-FILE |
A250 | ein | Die zu startende Datei (z.B. Shell-Script, Windows BAT-Datei). | |
JSU-SYSOUT-FILE |
A250 | ein | Ausgabedatei für die zu startende Datei. | |
JSU-EXIT-CODE |
N10 | aus | Nur für die Funktionen | |
GETEXIT |
Exit-Code aus einer Ausgabedatei lesen. | |||
CANCEL |
Prozess abbrechen. | |||
JSU-EXIT-CODE-SIGN |
Vorzeichen +
oder - des Exit-Code.
Hat der Exit-Code selbst 10 Zeichen, dann enthält
|
|||
JSU-USER |
A20 | ein | Benutzerkennung für die zu startende Datei. | |
JSU-GROUP |
A20 | ein | Optional: | |
| UNIX: | Gruppe für die zu startende Datei. | |||
| Windows: | Domäne für die zu startende Datei. | |||
JCA-KILL-MODE |
A1 | ein | Nur bei UNIX, nur für
Funktion CANCEL:
|
|
K |
SIGKILL verwenden.
(Standardwert)
|
|||
T |
SIGTERM verwenden.
|
|||
JSU-PID |
N10 | aus | Die Prozesskennung der gestarteten Datei. | |
Objekt: USER
Funktion: LOGON (Redefinition von
OBJECT-AREA)
|
||||
UL-PASSWORD-MODE |
A1 | ein | C |
UL-PASSWORD-A256 enthält
ein Passwort im Klartext. (Standardwert)
|
E |
UL-PASSWORD-A256 enthält
ein verschlüsseltes Passwort
|
|||
UL-PASSWORD-A256 |
A256 | ein | Das Passwort.
Die Verschlüsselung wird durch
PASSWORD
übernommen.
Anmerkung |
|
Die Angabe ist obligatorisch bei FILE /
READ oder FILE / WRITE und wenn
BUFFER-TYPE
B, C oder D verwendet wird. In allen
anderen Fällen ist die Angabe optional.
Hier können Sie den Namen eines aufrufenden Moduls angeben. Er
wird zur leichteren Identifizierung des Aufrufers an NPR / UNIX
weitergegeben. Wenn Sie hier Ihren eigenen Modulnamen übergeben wollen, können
Sie den folgenden Code verwenden:
...
1 #PROGRAM (A8)
...
#PROGRAM := *PROGRAM
...
CALLNAT ‘NOPUNX1N’ NOPUNX1A 1X #PROGRAM (AD=O)
...
Die API kann auf Großrechnern, UNIX oder Windows ausgeführt werden.
Mit dieser API kann nur auf UNIX- und Windows-Knoten zugegriffen werden.
In der gewählten Natural-Umgebung müssen Sie die Steplib SYSEOR und die von SYSEOR verwendeten Steplibs definieren.
Die von Entire Operations verwendeten Systemdateien (System File
1, System Automation Tools Log File) müssen über
LFILE-Zuordnungen definiert sein.
Generell wird die API NOPUNX1N mit dem angeforderten
Objekt und der angeforderten Funktion aufgerufen.
Windows-Dateinamen können auch mit normalen Schrägstrich-Zeichen (/) anstelle des umgekehrten Schrägstrichs (\) angegeben werden.
c:/work/file1.txt
ist gleichbedeutend mit
c:\work\datei1.txt
Die Überprüfung von NOPUNX1A.RETURN-CODE nach jedem
API-Aufruf ist obligatorisch.
NOPUNX1A.RETURN-CODE = 0 (Null) bedeutet, dass der
API-Aufruf in Ordnung war.
NOPUNX1A.RETURN-TEXT kann weitere Informationen zu dem
Rückgabecode enthalten.
Wenn ein Fehler auftritt, ist eine entsprechende Reaktion erforderlich
Wenn eine Verarbeitung als Reaktion auf einen Fehler abgebrochen werden soll:
Wenn eine Datei zurzeit geöffnet ist, muss sie mit
FILE / CLOSE geschlossen werden.
Wenn eine Sitzung zurzeit geöffnet ist, muss sie mit
USER / LOGOFF geschlossen werden.
Alle Datei-Operationen funktionieren nur innerhalb einer gültigen Session.
Eine Session muss mit USER / LOGON gestartet werden und
muss mit USER / LOGOFF beendet werden.
Während einer Session (einschließlich USER /
LOGOFF) darf die NOPUNX1A.SESSION-ID nicht
geändert werden.
Ein USER / LOGOFF am Ende einer Sitzung
ist obligatorisch.
Nach dem USER / LOGOFF ist die
NOPUNX1A.SESSION-ID ungültig und darf nicht mehr für
einen Aufruf verwendet werden.
USER / LOGON FILE / ... FILE / ... ... USER / LOGOFF
Dateien dürfen nicht explizit geöffnet werden. Dies geschieht
automatisch mit dem ersten Aufruf von FILE / READ
oder FILE / WRITE.
Beim ersten erfolgreichen FILE / READ
oder FILE / WRITE gibt die API ein File Handle in
NOPUNX1A.F-HANDLE zurück. Dieses muss bei allen
nachfolgenden Aufrufen an dieselbe Datei (Lese- oder Schreibsitzung) übergeben
werden, einschließlich des letzten FILE /
CLOSE-Aufrufs.
Nach einer Lese- oder Schreibsitzung muss die Datei mit der
Funktion FILE / CLOSE geschlossen werden.
NOPUNX1A.F-HANDLE wird dann ungültig.
Mit der Funktion FILE / READ wird eine
Datei im sequenziellen Modus gelesen.
In NOPUNX1A.F-LINE können Sie eine
Zeilennummer für die Startzeile bereitstellen.
Wenn NOPUNX1A.F-LINE den Wert
0 (Null) oder 1 enthält, beginnt die Lesesequenz am
Anfang der Datei.
USER / LOGON
R1. repeat
FILE / READ
if (NOPUNX1A.RETURN-CODE ne 0)
escape bottom (R1.)
end-if
... handle record
end-repeat /* R1.
FILE / CLOSE
USER / LOGOFF
Mit der Funktion FILE / SCAN ist es möglich, eine Datei
gezielt nach einer bestimmten Zeichenfolge zu durchsuchen. Die Suchzeichenfolge
muss in NOPUNX1A.F-SEARCH-TEXT übergeben werden.
USER / LOGON
R1. repeat
FILE / SCAN
if (NOPUNX1A.RETURN-CODE ne 0)
escape bottom (R1.)
end-if
... handle record
add 1 to NOPUNX1A.F-LINE
* -- line start for follow-up scan
end-repeat /* R1.
FILE / CLOSE
USER / LOGOFF
Mit der Funktion FILE / WRITE wird eine Datei in
sequenziellem Modus geschrieben.
USER / LOGON
R1. repeat
... allocate record in NOPUNX1A.F-RECORD-250
FILE / WRITE
if (...)
escape bottom (R1.)
end-if
end-repeat /* R1.
FILE / CLOSE
USER / LOGOFF
Im Folgenden finden Sie ein Beispiel für die Verwendung eines großen Datenpuffers zum Lesen oder Schreiben von Dateien.
Definieren Sie einen großen Puffer:
1 #BUFFER-99000 (A99000)
Wählen Sie einen der folgenden Puffer-Typen:
NOPUNX1A.BUFFER-TYPE := 'B' /* 9900 bytes NOPUNX1A.BUFFER-TYPE := 'C' /* 99000 bytes NOPUNX1A.BUFFER-TYPE := 'D' /* 59000 bytes
Rufen Sie die API auf:
CALLNAT 'NOPUNX1N' NOPUNX1A #BUFFER-99000
Die Parameterdatendefinition für NOPUNX1N ist:
DEFINE DATA PARAMETER USING NOPUNX1A PARAMETER 1 P-BUFFER-99000 (A99000) BY VALUE RESULT OPTIONAL ... END-DEFINE
Anmerkung#BUFFER-99000 kann je nach der Größe, die mit
NOPUNX1A.BUFFER-TYPE angegeben wird, maximal 9900, 99000 oder
59000 Bytes enthalten. Die in den Puffer geschrieben Daten dürfen weniger Bytes
haben. Sie dürfen die angegebene Puffergröße nicht überschreiten.
Mit der Funktion FILE / DELETE können Sie eine oder
mehrere Dateien löschen.
Wenn F-FILE ein Platzhalterzeichen (*) enthält, werden
alle Dateien gelöscht, bei denen das Platzhalterzeichen zutrifft.
Mit der Funktion FILE / COPY wird die Zieldatei in
F-RECORD-250 übergeben.
Mit der Funktion FILE / MOVE wird die Zieldatei in
F-RECORD-250 übergeben.
Zur Existenzprüfung einer Datei kann die Funktion FILE /
DIR mit einem definierten Dateinamen verwendet werden. Wenn in
NOPUNX1A.RETURN-CODE eine 0 (Null) zurückgegeben wird, existiert
die Datei.
Mit der Funktion FILE / DIR können Sie eine Liste mit
Dateien eines Verzeichnisses erstellen.
Mit dem in NOPUNX1A.F-FILE enthaltenen
Platzhalterzeichen-Ausdruck können Sie die Liste eingrenzen.
/tmp/* |
Alle Dateien im Verzeichnis
/tmp.
|
/tmp/*.txt |
Dateien im Verzeichnis /tmp,
die die Endung .txt haben.
|
Die Dateinamen werden in F-RECORD-BUFFER gespeichert.
Die Namen sind durch Semikolon (;) getrennt.
Als Beispiel für die Trennung siehe SHOW-DIR-BUFFER
(weiter unten).
Wenn der Puffer für die Dateinamen nicht ausreicht, wird in
NOPUNX1A.RETURN-CODE der Wert 19 (more
objects) zurückgegeben.
Dateiename mit Platzhalterzeichen (Wildcard-Notation) in
NOPUNX1A.F-FILE zuordnen.
USER / LOGON
... allocate file name (with wildcard) in NOPUNX1A.F-FILE
R1. repeat
FILE / DIR
decide on first value of NOPUNX1A.RETURN-CODE
value 0, 19 /* 0: ok, 19: more objects
perform SHOW-DIR-BUFFER
none value
ignore
end-decide
if NOPUNX1A.RETURN-CODE ne 19
escape bottom (R1.)
end-if
add 1 to NOPUNX1A.F-LINE
end-repeat /* R1.
FILE / CLOSE
USER / LOGOFF
* ---------------------------------------------------------------------
DEFINE SUBROUTINE SHOW-DIR-BUFFER
* ---------------
* -- Function FILE / DIR:
* -- The record buffer contains a file list, with delimiter ';'
* -- This routine separates the single file names out of the buffer.
* -- #DIR-FILE and #DIR-REST should be declared as (A600)
*
SDB1. REPEAT
EXAMINE NOPUNX1A.F-RECORD-BUFFER FOR ';' REPLACE FIRST WITH ':'
SEPARATE NOPUNX1A.F-RECORD-BUFFER INTO #DIR-FILE #DIR-REST
WITH DELIMITER ':'
* -- now #DIR-FILE contains a single file name, without qualifiers
IF #DIR-REST = ' '
ESCAPE BOTTOM (SDB1.)
END-IF
NOPUNX1A.F-RECORD-BUFFER := #DIR-REST
END-REPEAT /* SDB1.
END-SUBROUTINE