bs2do - calling BS2000 procedures from the POSIX shell (BS2000)

The BS2000 procedure to be executed is started in an ENTER-JOB with the CALL-PROCEDURE command. bs2do waits synchronously for the ENTER-JOB to terminate.

Syntax

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

-D

Debug mode - temporary files are not deleted and remain available for diagnosis.

-V

Verbose - single steps are logged to stdout.

-o

the BS2000 system file SYSOUT opened when the ENTER-JOB is started is copied to the POSIX file outfile.

outfile

name of the POSIX file into which the BS2000 system file SYSOUT is copied when the ENTER-JOB is started. outfile can be any POSIX path name.

procedure

name of the file containing the BS2000 procedure to be executed.

procedure can be any POSIX path name or a string bs2:BS2Name, where BS2Name is a
BS2000 procedure name according to the SDF syntax of the operand FROM-FILE of the BS2000 /CALL-PROC command.

parameter

parameters of the BS2000 procedure to be executed. Entries are made according to the SDF syntax of the PROCEDURE-PARAMETERS operand of the BS2000 /CALL-PROC command, the enclosing parentheses being optional.

The following applies to procedure and parameter: special characters (e.g. (, ), $) are to be masked for the shell. bs2do does not interpret the operands, e.g. among other things keywords in keyword parameters are not converted to uppercase.

File

Input files:

• stdin: not used

• procedure file procedure

• options file optionfile, where optionfile can be any POSIX path name. By default, /opt/BS2DO/options/bs2doopt.std is installed.

Output files:

• stdout: output of messages if the option -V (verbose) is specified

• stderr: bs2do error messages, contents of the job variable defined in the options file optionfile

• BS2000 system file SYSOUT copied to POSIX file outfile, if the -o option is specified

Variable

BS2DOOPT

POSIX path name of an options file. If the environment variable BS2DOOPT is not defined, the implicitly installed options file optionfile is used.

Hint

Extended description

bs2do sets up the batch job #T.pid.ENTER in BS2000, where pid is the POSIX process number of the process executing bs2do. The batch job is initiated with

/.DOpid LOGON

If the procedure procedure is located in the POSIX file system, it is copied to the BS2000 file T.pid.PRO. The batch job is then started as follows:

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

The operands PROCESSING-ADMISSION, HOST, JOB-CLASS and JOB-PRIORITY can be set via the options file optionfile.

In the batch job, the system file SYSOUT is assigned to the file #T.pid.OUT, the job variable #BS2DOJV is set up and then the procedure is called, the name of the #BS2DOJV job variable can be set via the options file optionfile:

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

The LOGGING operand can be set via the options file optionfile. The FROM-FILE operand is only specified if procedure is in the POSIX file system. Otherwise, the string procedure is adopted unchanged. Special characters (e.g. (,),$) are to be masked for the shell.

After the procedure procedure terminates, the system file SYSOUT is closed and the POSIX shell is started.

/START-PROG SHELL

The SHELL operand can be set via the options file optionfile.

If no error display was set in procedure (/EXIT-PROCEDURE ERROR=NO), the signal SIGUSR1 is sent to the parent process of the batch job as a terminating message.

If the error display was set in the procedure procedure (/EXIT-PROCEDURE ERROR=YES), the value of the job variable #BS2DOJV and the signal SIGUSR2 are sent to the parent process of the batch job as a terminating message.

In both cases, if the -o outfile option is specified, the file #T.pid.OUT is first copied to the POSIX file outfile. When the shell terminates, all T.pid files are deleted and the batch job is terminated.

All temporary #T.pid files are also deleted. In debug mode (-D option), no temporary files are created, but only T.pid files that are not deleted when the batch job terminates.

The options file

The structure of the options file is as follows:

keyword keyword = value

Lines that do not begin with a valid keyword are ignored. Continuation lines are exceptions to this rule. value can be extended beyond the end of a line with the - character.

List of supported keywords and corresponding values:

BS2DOJV

Job variable name (optional). If job variables are not offered by the product, no value may be specified for this keyword

SHELL

Operand of START-PROG for loading the POSIX shell

PROCESSING-ADMISSION
HOST
JOB-CLASS JOB-PRIORITY

Correspond to the operand of ENTER-JOB with the same name

LOGGING

Corresponds to the operand of CALL-PROC with the same name

The standard options file /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)
# 

Restrictions

Since bs2do cannot bypass the BS2000 security mechanisms, restrictions must be observed if PROCESSING-ADMISSION <> SAME is set in the options file:

• The user ID in which the ENTER-JOB is to be executed must have POSIX user permissions.

• If the -o option is specified, the user ID in which the ENTER-JOB is to be executed must have search and write permissions in the current directory in which bs2do was called. Otherwise, the ENTER-JOB SYSOUT file is not copied to the UFS, even if the -o option is set.

• The procedure to be executed is not copied from the UFS into another user ID, i.e. executing a procedure under a different user ID is only supported with procedure being equal to bs2:BS2Name.

Example

In the following examples, a prefixed DO: represents the shell prompt which is followed by entries to the shell. Lines between the shell prompts are the outputs from the commands concerned. The procedure proc is included as an example:

/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

Example 1

Procedure proc in POSIX, simple evaluation of the termination status

DO: bs2do proc
%   JMS0066 JOB ODO492CACCEPTED ON 04-04-23 AT 11:28, TSN=57EE
DO: echo $?
0

Example 2

Procedure proc in BS2000 file, SYSOUT is output in POSIX

DO: bs2do -o example2.out bs2:proc
%   JMS0066 JOB ODO494CACCEPTED ON 04-04-23 AT 11:29, TSN=57EG
DO: cat example2.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

Example 3

Procedure proc in BS2000 PLAM library, erroneous procedure parameter

DO: bs2cp proc 'bs2:BS2LIB(PROC,J)'  # copy proc in PLAM library
DO: bs2do -o example3.out bs2:\(BS2LIB,PROC\) "CMDPAR='x x'"
%  JMS0066 JOB 'DO501' ACCEPTED ON 04-04-23 AT 12:51, TSN = 57EN
BS2DOJV: Command 'STA x x' failed
DO:echo $?
1
DO: cat example3.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

Example 4

Procedure proc in POSIX, erroneous procedure parameter, redirection of stderr

DO: bs2do proc "CMD='STA P',CMDPAR=',TYPE=x " 2>example4.err
DO: echo $?
1
DO: cat example4.err
%  JMS0066 JOB 'DO620' ACCEPTED ON 04-04-23 AT 15:43, TSN = 57H1
BS2DOJV: Command 'STA P ,TYPE=x' failed