NOPUNX1N - Entire System Server-Aufrufe für Zugriff auf UNIX- und Windows-Dateien

#### Search Results

Search

# NOPUNX1N - Entire System Server-Aufrufe für Zugriff auf UNIX- und Windows-Dateien

Dieser Abschnitt behandelt folgende Themen:

- Parameter

- Ablauf-Umgebung

- Programmier-Hinweise

- Öffnen und Schließen von Dateien

- Fehlerprüfung

- Lesen einer Datei

- Suchen bestimmter Datensätze innerhalb einer Datei

- Schreiben einer Datei

- Lesen und Schreiben einer Datei unter Verwendung eines großen Puffers

- Datei löschen

- Datei kopieren

- Datei verschieben oder umbenennen

- Existenz einer Datei prüfen

- Dateiliste eines Verzeichnisses erstellen

Diese API ermöglicht Ihnen den Zugriff auf UNIX- und Windows-Dateien aus Natural-Programmen.

Bei `FILE / READ` oder `FILE / WRITE` und wenn der Puffer-Typ B, C oder D benutzt wird:

    CALLNAT 'NOPUNX1N' NOPUNX1A data-buffer

Bei allen anderen Aufrufen:

    CALLNAT 'NOPUNX1N' NOPUNX1A

Zum Aufrufen von `NOPUNX1N` müssen Sie die Parameter Data Area `NOPUNX1A` benutzen, die im folgenden Abschnitt beschrieben wird.

## Parameter

Die Parameter in der Parameter Data Area `NOPUNX1A` haben folgende Bedeutung:

Parameter | Format/Länge | Verwendung
--- | --- | ---
`OBJECT` | A16 | ein | Mögliche Werte: `USER` `FILE` `JOB` `SERVER`
`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.
anderer Wert | Siehe Inhalt von `RETURN-TEXT`.
`RETURN-TEXT` | A80 | aus | Erklärung zu `RETURN-CODE`.
`NODE` | N5 | ein | Knoten, wie in Entire Operations definiert.
`NODE-NAME` | A16 | ein | Knoten-Name kann alternativ zu `NODE` übergeben werden; wird nur ausgewertet, falls `NODE=0`.
`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 `UL-PASSWORD-A256` verwenden. Anmerkung Es empfiehlt sich, dieses Feld nach erfolgreichem `USER` / `LOGON` zu löschen.
`SID` | N10 |  | Obsolet. Bitte nicht mehr verwenden.
`UID` | N10 |  | Obsolet. Bitte nicht mehr verwenden.
`REDEF-1` | A10 | - | Redefinitionsbereich.
`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 | ein/aus | Betriebssystemklasse des Knotens (`NODE`). Mögliche Werte
`B` | BS2000
`M` | z/OS
`V` | z/VSE
`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.
`Y` | Fragezeichen (?) als Trigraph-Escape verwenden
anderes Zeichen | Dieses Zeichen als Trigraph-Escape verwenden.
`TRACE-LEVEL` | N1 | ein | `0` | Kein Trace.
`> 0` | Trace eingeschaltet.
`TRACE-TARGET` | A1 | ein | Gibt an, wohin der Trace geschrieben werden soll.
`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 `FILE`-Funktionen `READ`, `WRITE` und `APPEND`. 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.
Für die Puffer-Typen `B`, `C` und `D`: Der Puffer muss als separater Parameter im Statement `CALLNAT 'NOPUNX1N'` übergeben werden (siehe oben).
`OBJECT-AREA` | A1200 | - | Objekt-spezifische Felder.
|  |  | Objekt: `FILE` (Redefinition von `OBJECT-AREA`)
`F-FILE` | A250 | ein | Dateiname. Der Dateiname ist vollqualifiziert anzugeben, d.h. als kompletter Pfad ab Basis des Dateisystems. Der Dateiname darf Umgebungsvariablen enthalten.
`F-HANDLE` | N10 | nur von der API zu ändern | Datei-Handle. Wird vom Entire System Server beim ersten Zugriff auf die Datei vergeben; gilt bis `FILE` / `CLOSE`.
`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 `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 `BUFFER-TYPE='A'` verwendet.
`F-RECORD-250` | A250 | ein/aus | `FILE / READ`, `FILE / WRITE`: Effektiver Datensatz. Wird nur bei `BUFFER-TYPE='A'` verwendet.
`F-RECORD-SEPARATOR` | A5 | ein | Für zukünftige Verwendung.
`F-LINE-LIMIT` | N10 | ein | `FILE/COPY, FILE/MOVE:` Für 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: | Group für das Kommando.
Windows: | Domäne für das Kommando.
`JCM-WAIT-FOR-TERMINATION` | A1 | ein | `N` | Auf das Kommando-Ende soll nicht gewartet werden.
`Y` | Auf das Kommando-Ende 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 Exitcode-Meldung an die Ausgabedatei anhängen.
`Y` | Die Exitcode-Meldung NPR3355 an die Ausgabedatei anhängen. (Standardwert)
`JCM-EXIT-CODE` | N10 | aus | Der Exitcode des Kommandos.
`JCM-PID` | N10 | aus | Die Process-ID 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` | Exitcode aus einer Ausgabedatei lesen.
`CANCEL` | Prozess abbrechen.
`JSU-EXIT-CODE-SIGN` |  |  | Vorzeichen `+` oder `-` des Exitcode. Hat der Exitcode selbst 10 Zeichen, dann enthält `exitCode` den absoluten Teil, und das Vorzeichen muss aus `exitCodeSign` gelesen werden. `exitCodeSign` wird immer gesetzt, unabhängig von einem Vorzeichen in `exitCode`.
`JSU-USER` | A20 | ein | Benutzerkennung für die zu startende Datei.
`JSU-GROUP` | A20 | ein | Optional:
UNIX: | Group für die zu startende Datei.
Windows: | Domäne für die zu startende Datei.
`JCA-KILL-MODE` | A1 | ein | Nur für Unix, nur für Funktion `CANCEL`:
`K` | `SIGKILL` verwenden. (Standardwert)
`T` | `SIGTERM` verwenden.
`JSU-PID` | N10 | aus | Die Process-ID 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 `UL-PASSWORD-MODE` bestimmt. Wenn dieses Feld leer ist, wird das Passwort aus `PASSWORD` übernommen. Anmerkung Es empfiehlt sich, dieses Feld nach erfolgreichem `USER / LOGON` zu löschen.

## Ablauf-Umgebung

- Die API ist unter Entire Operations auf Großrechnern und Entire Operations auf Open Systems (UNIX + Windows) einsetzbar.

- Mit der API kann nur auf UNIX- und Windows-Knoten zugegriffen werden.

- In der verwendeten Natural-Umgebung müssen als Steplibs SYSEOR und die von SYSEOR verwendeten Steplibs definiert sein.

- Die von Entire Operations verwendeten Systemdateien (System File 1, SAT Log File) müssen über `LFILE`-Zuweisung definiert sein.

## Programmier-Hinweise

#### Allgemeines

Im folgenden bedeutet der Aufruf `OBJECT / FUNCTION` (z.B. `USER / LOGON`) den Aufruf von `NOPUNX1N` mit dem angebenen Objekt und der angegebenen Funktion.

#### Windows-Dateinamen

Windows-Dateinamen können auch mit normalen Schrägstrich-Zeichen (/) anstelle des umgekehrten Schrägstrichs (\) angegeben werden.

#### Beispiel:

    c:/work/file1.txt

ist gleichbedeutend mit

    c:\work\datei1.txt

#### Session

Alle Datei-Operationen funktionieren nur innerhalb einer gültigen Session.

Die Session wird mit `USER / LOGON` aufgebaut und mit `USER / LOGOFF` beendet.

Während der Session dürfen `SESSION-ID`, `UID`, `GID` nicht geändert werden.

#### Session-Ablauf

    USER / LOGON
    FILE / ...
    FILE / ...
    ...
    USER / LOGOFF

## Öffnen und Schließen von Dateien

- Dateien brauchen nicht explizit geöffnet zu werden. Das wird beim ersten Zugriff mit `FILE / READ` oder `FILE / WRITE` automatisch ausgeführt.

- Nach dem Lesen oder Schreiben einer Datei muss die Datei mit `FILE / CLOSE` geschlossen werden.

## Fehlerprüfung

Nach jedem Aufruf von `NOPUNX1N` ist der Fehlercode in `NOPUNX1A.RETURN-CODE` zu überprüfen. In `NOPUNX1A.RETURN-TEXT` wird ein Fehlertext zurückgegeben.

## Lesen einer Datei

Mit der Funktion `FILE/READ` wird eine Datei sequenziell gelesen.

In `NOPUNX1A.F-LINE` kann eine Startzeile übergeben werden.

Wenn `NOPUNX1A.F-LINE` den Wert `0` (Null) oder 1 enthält, wird ab Dateibeginn gelesen.

#### Schema

    USER / LOGON

    R1. repeat
       FILE / READ
       if (NOPUNX1A.RETURN-CODE ne 0)
           escape bottom (R1.)
       end-if
       ... Record behandeln
    end-repeat       /* R1.

    FILE / CLOSE

    USER / LOGOFF

## Suchen bestimmter Datensätze innerhalb einer Datei

Mit der Funktion `FILE / SCAN` ist es möglich, eine Datei gezielt nach einer bestimmten Zeichenkette zu durchsuchen. Die Suchzeichenkette muss in `NOPUNX1A.F-SEARCH-TEXT` übergeben werden.

#### Schema

    USER / LOGON

    R1. repeat
       FILE / SCAN
       if (NOPUNX1A.RETURN-CODE ne 0)
           escape bottom (R1.)
       end-if
       ... Record behandeln

       add 1 to NOPUNX1A.F-LINE
    *           -- Startzeile für Folge-Scan
    end-repeat       /* R1.

    FILE / CLOSE

    USER / LOGOFF

## Schreiben einer Datei

Mit der Funktion `FILE / WRITE` wird eine Datei sequenziell geschrieben.

#### Schema

    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

## Lesen und Schreiben einer Datei unter Verwendung eines großen Puffers

Beispiel für die Verwendung eines großen Puffers für das Lesen und Schreiben von Dateien.

1. 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

2. Rufen Sie die API auf:

       CALLNAT 'NOPUNX1N' NOPUNX1A #BUFFER-99000

   Die Parameterdefinition 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, aber nicht die angegebene Puffergröße überschreiten.

## Datei löschen

Mit `FILE / DELETE` kann man eine oder mehrere Dateien löschen.

Wenn `F-FILE` ein Platzhalterzeichen (*) enthält, werden alle Dateien gelöscht, für die das Platzhalterzeichen zutrifft.

## Datei kopieren

Für `FILE / COPY` wird die Zieldatei in `F-RECORD-250` übergeben.

## Datei verschieben oder umbenennen

Für `FILE / MOVE` wird die Zieldatei in `F-RECORD-250` übergeben.

## Existenz einer Datei prüfen

Zur Existenzprüfung einer Datei kann die Funktion `FILE / DIR` mit einem eindeutigen Dateinamen verwendet werden. Wenn in `NOPUNX1A.RETURN-CODE` eine Null zurückgegeben wird, so existiert die Datei.

## Dateiliste eines Verzeichnisses erstellen

Mit `FILE / DIR` können Sie Dateilisten für ein Verzeichnis erstellen.

Mit dem in `NOPUNX1A.F-FILE` bereitgestellten Platzhalterzeichen-Ausdruck können Sie die Liste eingrenzen.

#### Beispiele:

`/tmp/*` | Alle Dateien im Verzeichnis `/tmp`.
`/tmp/*.txt` | Dateien im Verzeichnis `/tmp`, die mit `.txt` enden.

Die Dateinamen werden in `F-RECORD-BUFFER` zurückgegeben. Die Namen sind durch Semikolon (;) getrennt.

Als Beispiel für die Separierung siehe `SHOW-DIR-BUFFER` (weiter unten).

Wenn der Puffer für die Dateinamen nicht ausgereicht hat, wird in `NOPUNX1A.RETURN-CODE` der Wert `19` (`more objects`) zurückgegeben.

#### Schema

Dateiename mit Platzhalterzeichen (Wildcard-Notation).

    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

### On this page

- Parameter
- Ablauf-Umgebung
- Programmier-Hinweise
- Öffnen und Schließen von Dateien
- Fehlerprüfung
- Lesen einer Datei
- Suchen bestimmter Datensätze innerhalb einer Datei
- Schreiben einer Datei
- Lesen und Schreiben einer Datei unter Verwendung eines großen Puffers
- Datei löschen
- Datei kopieren
- Datei verschieben oder umbenennen
- Existenz einer Datei prüfen
- Dateiliste eines Verzeichnisses erstellen