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

Mit dieser API können Sie aus Natural-Programmen auf UNIX- und Windows-Dateien zugreifen.

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:

- Parameter-Beschreibung

- Ablauf-Umgebung

- Programmiererfordernisse

- Öffnen und Schließen einer Datei

- Lesen einer Datei

- Suchen nach bestimmten Datasets innerhalb einer Datei

- Schreiben einer Datei

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

- Löschen einer Datei

- Kopieren einer Datei

- Verschieben oder Umbenennen einer Datei

- Existenzprüfung einer Datei

- Erstellen einer Dateiliste für ein Verzeichnis

## Parameter-Beschreibung

Folgende Themen werden behandelt:

- Data Area NOPUNX1A

- data buffer

- caller module (nur Eingabe, optional)

### Data Area NOPUNX1A

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.
`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 kann alternativ zu `NODE` übergeben werden; wird nur verwendet, wenn `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` 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.
`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 | Buffer-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 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 | 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.

### data buffer

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.

### caller module (nur Eingabe, 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)
                ...

## Ablauf-Umgebung

- Die API kann auf Großrechnern, UNIX oder Windows ausgeführt werden.

- Mit der 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.

## Programmiererfordernisse

#### API-Aufruf

Generell wird die API `NOPUNX1N` mit dem angeforderten Objekt und der angeforderten Funktion aufgerufen.

#### 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

#### Prüfung des Rückgabecodes

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.

#### Session

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.

#### Session-Ablauf

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

## Öffnen und Schließen einer Datei

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

## Lesen einer Datei

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

In `NOPUNX1A.F-LINE` können Sie eine Zeilennummer für die Startzeile angeben.

Wenn `NOPUNX1A.F-LINE` den Wert `0` (Null) oder `1` enthält, beginnt die Lesesequenz am Anfang der Datei.

#### 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 nach bestimmten Datasets 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.

## Löschen einer Datei

Mit der Funktion `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.

## Kopieren einer Datei

Mit der Funktion `FILE / COPY` wird die Zieldatei in `F-RECORD-250` übergeben.

## Verschieben oder Umbenennen einer Datei

Mit der Funktion `FILE / MOVE` wird die Zieldatei in `F-RECORD-250` übergeben.

## Existenzprüfung einer Datei

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.

## Erstellen einer Dateiliste für ein Verzeichnis

Mit der Funktion `FILE / DIR` können Sie eine Liste mit Dateien eines Verzeichnisses 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-Beschreibung
- Ablauf-Umgebung
- Programmiererfordernisse
- Öffnen und Schließen einer Datei
- Lesen einer Datei
- Suchen nach bestimmten Datasets innerhalb einer Datei
- Schreiben einer Datei
- Lesen und Schreiben einer Datei unter Verwendung eines großen Puffers
- Löschen einer Datei
- Kopieren einer Datei
- Verschieben oder Umbenennen einer Datei
- Existenzprüfung einer Datei
- Erstellen einer Dateiliste für ein Verzeichnis