bs2do - Aufruf von BS2000-Prozeduren aus der POSIX-Shell (BS2000)

(call BS2000 procedures from the POSIX shell)

Die auszuführende BS2000-Prozedur wird in einem ENTER-JOB mit dem Kommando CALL-PROCEDURE gestartet. bs2do wartet synchron auf die Beendigung des ENTER-JOB.

Syntax

bs2do[ -DV][ -o outfile] procedure [[(]parameter[)]]

-D

Debugmode - temporäre Dateien werden nicht gelöscht und stehen für Diagnose zur Verfügung.

-V

Verbose - Einzelschritte werden auf stdout protokolliert.

-o

Die beim Start des ENTER-JOB geöffnete BS2000-Systemdatei SYSOUT wird in die POSIX-Datei outfile kopiert.

outfile

Der Name der POSIX-Datei, die eine Kopie der beim Start des ENTER-JOB geöffneten BS2000-Systemdatei SYSOUT aufnimmt. outfile ist ein beliebiger POSIX-Pfadname.

procedure

Der Name der Datei, die die auszuführende BS2000-Prozedur enthält.

procedure ist ein beliebiger POSIX-Pfadname oder ein String bs2:BS2Name.
BS2Name ist ein BS2000-Prozedurname entsprechend der SDF-Syntax des Operanden FROM-FILE des BS2000-Kommandos /CALL-PROC.

parameter

Die Parameter der auszuführenden BS2000-Prozedur. Die Angabe erfolgt entsprechendder SDF-Syntax des Operanden PROCEDUR-PARAMETERS des BS2000-Kommandos CALL-PROC, wobei die einschließenden runden Klammern optional sind.

Für procedure und parameter gilt: Sonderzeichen (z. B. (, ), $) sind für die Shell zu entwerten. bs2do interpretiert den Operanden nicht, u. a. werden z. B. Schlüsselwörter in Schlüsselwortparametern nicht in Großbuchstaben umgesetzt.

Datei

Eingabe-Dateien:

• stdin: nicht benutzt

• Prozedurdatei procedure

• Optionsdatei optionfile, wobei optionfile ein beliebiger POSIX-Pfadname sein kann. Standardmäßig ist /opt/BS2DO/options/bs2doopt.std installiert.

Ausgabe-Dateien:

• stdout: Ausgabe von Meldungen bei Angabe von Option -V (verbose).

• stderr: Fehlermeldungen von bs2do, Inhalt der in der Optionsdatei optionfile vereinbarten Jobvariablen.

• BS2000-Systemdatei SYSOUT nach POSIX-Datei outfile bei Angabe von Option -o.

Variable

BS2DOOPT

POSIX-Pfadname einer Optionsdatei.

Ist die Umgebungsvariable BS2DOOPT nicht definiert, so wird die standardmäßig installierte Optionsdatei optionfile verwendet.

Hinweis

Ausführliche Beschreibung

bs2do baut im BS2000 den Stapelauftrag #T.pid.ENTER auf, wobei pid die POSIX-Prozessnummer des Prozesses ist, der bs2do ausführt). Eingeleitet wird der Stapelauftrag durch

/.DOpid LOGON

Liegt die Prozedur procedure im POSIX-Dateisystem, wird diese in die BS2000-Datei T.pid.PRO kopiert. Dann wird der Stapelauftrag gestartet:

/ENTER-JOB   FROM-FILE=#T.pid.ENTER,-
/            PROCESSING-ADMISSION=SAME,-
/            HOST=*STD,-
/            JOB-CLASS=*STD,-
/            JOB-PRIORITY=*STD

Die Operanden PROCESSING-ADMISSION, HOST, JOB-CLASS und JOB-PRIORITY sind über die Optionsdatei optionfile einstellbar.

In dem Stapelauftrag wird die Systemdatei SYSOUT der Datei #T.<pid>.OUT zugeordnet, die Jobvariable #BS2DOJV eingerichtet und anschließend die Prozedur procedure aufgerufen, der Name der Jobvariablen #BS2DOJV ist über die Optionsdatei optionfile einstellbar:

/CALL-PROC  FROM-FILE=T.pid.PRO,-
/           PROC-PAR=parameter,-
/           LOGGING=NO

Der Operand LOGGING ist über die Optionsdatei optionfile einstellbar. Der Operand FROM-FILE wird nur angegeben, wenn procedure im POSIX-Dateisystem liegt, ansonsten wird der String procedure unverändert übernommen. Sonderzeichen (z.B. (,),$) sind für die Shell zu entwerten.

Nach Abschluss der Prozedur procedure wird die Systemdatei SYSOUT geschlossen und die POSIX-Shell gestartet.

/START-PROG SHELL

Der Operand SHELL ist über die Optionsdatei optionfile einstellbar.

Wurde in der Prozedur procedure keine Fehleranzeige gesetzt (/EXIT-PROCEDURE ERROR=NO), so wird an den Vaterprozess des Stapelauftrages das Signal SIGUSR1 als Endenachricht gesendet.

Wurde in der Prozedur procedure die Fehleranzeige gesetzt (/EXIT-PROCEDURE ERROR=YES), wird der Inhalt der Jobvariablen #BS2DOJV und anschließend das Signal SIGUSR2 als Endenachricht an den Vaterprozess des Stapelauftrages gesendet.

In beiden Fällen wird vorher bei angegebener Option -o outfile die Datei #T.pid.OUT in die POSIX-Datei outfile kopiert. Nach Beendigung der Shell werden alle Dateien T.pid gelöscht und der Stapelauftrag beendet.

Alle temporären Dateien #T.pid werden ebenfalls gelöscht. Im Debugmode (Option -D) werden keine temporären Dateien, sondern ausschließlich Dateien T.pid angelegt, die bei Ende des Stapelauftrages nicht gelöscht werden.

Die Optionsdatei

Die Optionsdatei ist aufgebaut nach dem Schema

Schlüsselwort keyword = value

Zeilen, die nicht mit einem gültigen Schlüsselwort keyword beginnen, werden ignoriert. Ausgenommen sind Fortsetzungszeilen. value kann über Zeilengrenzen mit dem Zeichen - fortgesetzt werden.

Die folgende Liste zeigt die unterstützten Schlüsselwörter und die zugehörigen value-Angaben:

BS2DOJV

Jobvariablenname (optional). Wenn das Produkt Jobvariablen nicht zur Verfügung stellt, darf für dieses keyword kein value angegeben werden.

SHELL

Operanden von START-PROG zum Laden der POSIX-Shell

PROCESSING-ADMISSION
HOST
JOB-CLASS JOB-PRIORITY

entsprechen den gleichnamigen Operanden von ENTER-JOB

LOGGING

entspricht dem gleichnamigen Operanden von CALL-PROC

Die Standard-Optionsdatei /opt/BS2DO/options/bs2doopt.std:

#
#    bs2do controlling job variable
#    (temporary JV in order to allow parallel calls within one userid)
#
BS2DOJV = #BS2DOJV
#
#    BS2000 enter-job operands
#
PROCESSING-ADMISSION = SAME
HOST = *STD
JOB-CLASS = *STD
JOB-PRIORITY = *STD
#
#    BS2000 call-proc operands
#
LOGGING = NO
#
#    optional shell configuration
#
#SHELL = *M($TSOS.SINLIB.POSIX-BC.vvv.SHELL,SH,RUN-MODE=ADVANCED,PROG-MODE=ANY)
#

Einschränkungen

Da bs2do nicht die BS2000-Sicherheitsmechanismen umgehen kann, sind Einschränkungen zu beachten, wenn PROCESSING-ADMISSION <> SAME in der Optionsdatei eingestellt ist:

• Die Benutzerkennung, in welcher der ENTER-JOB ausgeführt werden soll, muss POSIX-Benutzer-Rechte haben.

• Bei Angabe der Option -o muss die Benutzerkennung, in der der ENTER-JOB ausgeführt werden soll, in dem aktuellen Verzeichnis, in dem bs2do aufgerufen wurde, such- und schreibberechtigt sein. Ansonsten wird trotz der Option -o die SYSOUT-Datei des ENTER-JOBS nicht ins UFS kopiert.

• Die auszuführende Prozedur wird nicht aus dem UFS in eine andere Benutzerkennung kopiert, d.h. das Ausführen einer Prozedur in einer anderen Benutzerkennung wird nur unterstützt, wenn procedure gleich bs2:BS2Name ist.

Beispiel

In den folgenden Beispielen repräsentiert ein vorangestelltes DO: das Shellprompt, hinter dem Eingaben an die Shell folgen. Zeilen zwischen den Shellprompts sind Ausgaben des jeweiligen Kommandos. Beispielprozedur ist die Prozedur proc:

/BEGIN-PROCEDURE PAR=YES(PROC-PAR=(&CMD='STA',&CMDPAR='L'))
/
/      WRITE-TEXT T='-----> ''&CMD &CMDPAR'''
/      &CMD &CMDPAR
/      SKIP-COMMAND TO-LABEL=OK
/
/      SET-JOB-STEP
/      MOD-JV JV-CONTENTS=#BS2DOJV,-
/             SET-VALUE=C'Command ''&CMD &CMDPAR'' failed'
/      SKIP-COMMAND TO-LABEL=ERR
/
/.ERR  REMARK
/      WRITE-TEXT T='-----> DOING EXIT-PROCEDURE ERROR=YES'
/      EXIT-PROCEDURE ERROR=YES
/
/.OK   REMARK
/      WRITE-TEXT T='-----> DOING EXIT-PROCEDURE ERROR=NO'
/      EXIT-PROCEDURE ERROR=NO
/
END-PROCEDURE

Beispiel 1

Prozedur proc in POSIX, einfache Auswertung des Endestatus.

DO: bs2do proc

%JMS0066 JOB ODO492CACCEPTED ON 98-04-23 AT 11:28, TSN=57EE

DO: echo $?

0

Beispiel 2

Prozedur proc in BS2000-Datei, Ausgabe von SYSOUT in POSIX

DO: bs2do -o beispiel2.out bs2:proc

%   JMS0066 JOB ODO494CACCEPTED ON 98-04-23 AT 11:29, TSN=57EG

DO: cat beispiel2.out

/CREATE-JV JV=#BS2DOJV

/SET-JOB-STEP

/MODIFY-JV JV=#BS2DOJV,SET-VALUE=C' '

/SET-JOB-STEP

/CALL-PROC FROM-FILE=proc,LOGGING=NO

-----> 'STA L'

NAME        TSN TYPE       PRI     CPU-USED CPU-MAX ACCOUNT#

DO494      57EG 2 BATCH    9 220     0.6044   32000 1

RLOGIN     57C7 2 DIALOG   0 210    14.3916   9999  1

%  SPS0171 NO LOCAL SPOOLOUT JOB PRESENT

%  SPS0420 RSO WARNING : SOME RSO PRINT-JOBS CANNOT BE DISPLAYED

%  SCP1095 DPRINTSV WARNING : SOME DPRINT PRINT-JOBS CANNOT BE ..

-----> DOING EXIT-PROCEDURE ERROR=NO

/SKIP-COMMANDS TO-LABEL=NOERR

/.NOERR  REMARK

/SYSFILE SYSOUT=*DUMMY

Beispiel 3

Prozedur proc in BS2000-PLAM-Bibliothek, fehlerhafter Prozedurparameter

DO: bs2cp proc 'bs2:BS2LIB(PROC,J)'  # proc in PLAM Bibliothek

# kopieren

DO: bs2do -o beispiel3.out bs2:\(BS2LIB,PROC\) "CMDPAR='x x'"

%  JMS0066 JOB 'DO501' ACCEPTED ON 98-04-23 AT 12:51, TSN = 57EN

BS2DOJV: Command 'STA x x' failed

DO:echo $?

1

DO: cat beispiel3.out

/CREATE-JV JV=#BS2DOJV

/SET-JOB-STEP

/MODIFY-JV JV=#BS2DOJV,SET-VALUE=C'  '

/SET-JOB-STEP

/CALL-PROC FROM-FILE=(BS2LIB,PROC),PROC-PAR=(CMDPAR='x x'),LOGGING= ..

-----> 'STA x x'

%  EXC0898 INVALID OPERAND IN COMMAND. COMMAND REJECTED

%  CMD0205 ERROR IN PRECEDING COMMAND OR PROGRAM AND PROCEDURE ..

-----> DOING EXIT-PROCEDURE ERROR=YES

%  CMD0205 ERROR IN PRECEDING COMMAND OR PROGRAM AND PROCEDURE ..

/SET-JOB-STEP

/SKIP-COMMANDS TO-LABEL=ERROR

/.ERROR  REMARK

/SYSFILE SYSOUT=*DUMMY

Beispiel 4

Prozedur proc in POSIX, fehlerhafte Prozedurparameter, Umlenkung von stderr

DO: bs2do proc "CMD='STA P',CMDPAR=',TYPE=x " 2>beispiel4.err

DO: echo $?

1

DO: cat beispiel4.err

%  JMS0066 JOB 'DO620' ACCEPTED ON 98-04-23 AT 15:43, TSN = 57H1

BS2DOJV: Command 'STA P ,TYPE=x' failed