Some variables (such as ORACLE_SID,
COBDIR,
LIBPATH,
COBPATH …) are shared variables between different components and are not described in this current document.
Table 3‑1 lists the environment variables that are used in the KSH scripts and must be defined before using the software.
Note:
|
For DATA and TMP, the full path can only contain [a-zA-Z0-9_/.].
|
Table 3‑2 lists the environment variables that are used by Batch Runtime and must be defined before using the software.
|
|
|
|
|
|
|
|
|
(See the BatchRT.conf configuration file)
|
|
|
|
Indicates the working mode of m_DBTableLoad and m_DBTableUnload.
When it is set to "yes", m_DBTableLoad and m_DBTableUnload call the COBOL programs; in this mode, the related data file for load/unload are in the same format as in z/OS for utility DSNUTILB (Load/Unload) and for utility DSNTIAUL (Unload). The COBOL program name could be: schema-table-L ( DSNUTILB Load), schema-table-U ( DSNUTILB Unload), or schema-table-u ( DSNTIAUL Unload).
When it is set to other values than "yes", " MT_CTL_FILES" are necessary for m_DBTableLoad and m_DBTableUnload.
|
|
Indicates the default schema for DB, When MT_DSNUTILB_LOADUNLOAD is set to " yes". The default value is " DEFSCHEMA". This variable is used for specify the schema for COBOL programs "schema-table-L" and "schema-table-U".
|
|
(See the BatchRT.conf configuration file)
|
|
|
|
|
|
|
|
The default is directory GENERATION_FILE. To manage GDG files in database, you need to set the value to GENERATION_FILE_DB and configure MT_GDG_DB_ACCESS appropriately. If the value is specified as NULL or with an incorrect directory name, error occurs when using this environment variable.
|
|
Path of the used "ksh" ( pdksh or ksh88 only).
•
|
Do not copy pdksh from other machines. You should either download the source code from official website and then build pdksh executable from it, or install pdksh through the official installer which is included in the corresponding OS release image.
|
•
|
If you build pdksh from source code, recommend that you define the CPU frequency ( CLK_TCK, in ksh_time.h) from 60HZ to 100HZ, as most modern Linux/UNIX platforms use 100 as their default CPU frequency.
|
|
|
|
|
(See the BatchRT.conf configuration file)
|
|
|
|
|
|
(See the BatchRT.conf configuration file)
|
|
|
|
(See the BatchRT.conf configuration file).
|
|
(See the BatchRT.conf configuration file)
|
|
MT_JESDECRYPT must be set to jesdecrypt object file.
(See the BatchRT.conf configuration file)
|
|
(See the BatchRT.conf configuration file)
|
|
TUXEDO SRVGRP value of the ARTDPL server.
(See the BatchRT.confconfiguration file)
|
Table 3‑3 lists optional environment variables used by Batch Runtime.
|
|
|
|
|
|
|
Note:
|
It precedes MT_DB_LOGIN in accessing file catalog. If file catalog DB is the same as data DB, configuring MT_DB_LOGIN only is required; otherwise, both must be configured.
|
|
|
Controls whether empty SYSOUT files are cleaned up at the end of job execution.
|
|
|
|
A variable used to enable CPU time usage monitor of step for all job. Set MT_CPU_MON_STEP=yes to enable CPU time usage monitor of step for all job. If MT_CPU_MON_STEP is not configured or its value is not equal "yes", this feature is disabled.
|
|
If MT_DB_LOGIN2 has a non-null value, BatchRT uses runb2 (which supports parallel Oracle and DB2 access).
|
|
|
|
•
|
When <DB TYPE> is " ORA", the <connection string> format is <user>/<pwd>@<instance id>. For example, ORA01:ORA:tigger/scot@orains01.
|
•
|
When <DB TYPE> is " DB2", the <connection string> format is <instance id> user <user> using <pwd>. For example, DB202:DB2:db2ins02 user tom using cat.
|
This file is accessed when "DB SYSTEM" is specified in the following EJR API: m_ProgramExec, m_DBTableLoad, m_DBTableUnload, m_ExecSQL, m_DSNUTILB, and m_UtilityExec.
Note:
|
When "DB SYSTEM" is specified in a nested way, only the outer setting takes effect. For example, in the following case, only " ORA01" takes effect (and " ORA02" is ignored).
|
|
|
If it is configured to "Y", Batch runtime provides you DSNTIAUL utility to unload data from Oracle Database tables. This utility has the same functionality as DSNTIAUL utlity on mainframe with DB2. If it is configured to " N" or if it is not configured, Batch runtime executes SQL statement and writes the output to a specific file in plain text. The default value is " Y".
|
|
If it is configured to "Y", BatchRT generates an EJR log file and writes every phase's log to it. If it is configured to " N", BatchRT does not generate the EJR log file. The default value is " Y".
|
|
A list of executable programs. The programs are invoked by runbexci instead of runb. For each program in this list, whether or not -n is specified by m_ProgramExec, the program is invoked only by runbexci.
|
|
|
|
|
|
If configured to "Y", the GDG changes are committed using a single database access.
If configured to "N", the GDG changes are committed using one or more database accesses The default value is "N".
|
|
•
|
MT_GDG_USEDCB=Y: Create . dcb file for GDG (default behavior). In this mode, LSEQ or SEQ can be specified as file type of GDG members in m_FileAssign statement.
|
•
|
MT_GDG_USEDCB=N: Don't create .dcb file for GDG. In this mode, file type of GDG members can only be LSEQ; whatever file type that you specify in m_FileAssign statement is ignored.
|
|
|
If MT_META_DB has a non-null value, BatchRT uses the database type defined in MT_META_DB for meta data. Otherwise, MT_DB is used.
|
|
The full install path of Workbench refine, which will be invoked to convert a JCL job to a KSH job. For example:
|
|
The value of environment variable REFINEDISTRIB, which is used when Workbench converts a JCL job. For example:
|
|
|
|
In BatchRT.conf this item is used to make runb redirect SYSIN and SYSOUT for COBOL program run by m_ProgramExec.
If "SYSIN" is set, the stdin for utilitiy will be redirect to file ${DD_SYSIN}, if DD_SYSIN doesn't exist, don't redirect. example: MT_SYS_IO_REDIRECT=SYSIN
If "SYSOUT" is set, the stdout and stderr for utilitiy will be redirect to file ${DD_SYSOUT}, if DD_SYSOUT doesn't exist, don't redirect.
Example: MT_SYS_IO_REDIRECT=SYSOUT
"SYSIN" and " SYSOUT" can be set at the same time, separated by comma, such as " SYSIN,SYSOUT"
Example: MT_SYS_IO_REDIRECT=SYSIN,SYSOUT
By default, MT_SYS_IO_REDIRECT=SYSIN,SYSOUT
|
|
In EJR mode, if it is configured to "Y", BatchRT generates a SYSLOG file. If it is configured to " N", BatchRT does not generate the SYSLOG file. The default value is " Y".
|
|
If it is configured to "Y", use hour, minute, second, or millisecond for Step Start Time and Step End Time in SYSLOG file. If it is configured to " N", use hour, minute, or second (millisecond cannot be used). The default value is " N".
|
|
|
|
A list of executable programs, programs that don't exist but users don't want to fail any jobs because of them. When m_ProgramExec invokes nonexistent programs, JOB will continue if those programs are specified in this list. For example:
MT_UTILITY_LIST_UNSUPPORT=IEHINITT,IEHLIST,IEHMOVE,IEHSTATR,IEHPROGM,IEBCOMPR,IEBEDIT,IEBIMAGE,IEBUPDTE,IEBDG,IEBPTPCH
|
|
|
|
If configured to "Y", record-sequential ASCII files are sorted in EBCDIC order.
If configured to "N", record-sequential ASCII files are sorted in ASCII order.
|
|
If configured to "Y", for numeric DISPLAY items with included signs, the signs are to be interpreted according to the EBCDIC convention.
If configured to "N", for numeric DISPLAY items with included signs, the signs are to be interpreted according to the ASCII convention.
|
|
Any return code greater than or equal to MT_PROG_RC_ABORT is considered as abort; any code less than MT_PROG_RC_ABORT is considered as commit.
|
2.
|
MT_ACC_FILEPATH should be located on shared storage (NFS), which should have same mount point on all machines in the domain, since the control files for file locking are put in this directory; in addition, users need to make sure AccLock and AccWait files under this directory can be read / written by the effective user of the process running the jobs.
|
ABEND routines,
ILBOABN0,
CEE3ABD and
ART3ABD can be called from a running program to force it to abort and return the
abend code to KSH script. For example,
ILBOABN0 is supplied as both source and binary
gnt file. It can be directly called by any user-defined COBOL program.
DISPLAY "USER: HELLO USER".
CALL "ILBOABN0" USING RT-PARAM.
DISPLAY "USER: CAN'T REACH HERE WHEN ILBOABN0 IS CALLED".
As described in Script Execution Phases, during the Conversion Phase, a Korn shell script is expanded by including the procedure's code each time a call to the
m_ProcInclude function is encountered. It is necessary that after this operation, the resulting expanded Korn shell script still respects the rules of the general structure of a script as defined in the
General Structure of a Script.
As specified in Best Practices, this way of coding procedures is provided mainly for supporting Korn shell scripts resulting from z/OS JCL translation and it is not recommended for Korn shell scripts newly written for the target platform.
Listing 3‑11 shows how to replace the assignment of the logical file
SYSUT1 using the
m_FileOverride function.
The m_CondIf,
m_CondElse and
m_CondEndif functions can be used to condition the execution of one or several steps in a script. The behavior is similar to the z/OS JCL statement constructs
IF,
THEN,
ELSE and
ENDIF.
The m_CondIf function must always have a relational expression as a parameter as shown in
Listing 3‑13. These functions can be nested up to 15 times.
The m_CondExec function is used to condition the execution of a step. The
m_CondExec must have at least one condition as a parameter and can have several conditions at the same time. In case of multiple conditions, the step is executed only if all the conditions are satisfied.
The m_CondExec function must be the first function to be called inside the concerned step as shown in
Listing 3‑14.
•
|
The start label specified by the m_JobBegin function: this label is usually the first label in the script, but can be changed to any label present in the script if the user wants to start the script execution from a specific step.
|
•
|
The value assigned to the JUMP_LABEL variable in each step: this assignment is mandatory in each step, but its value is not necessarily the label of the following step.
|
The environment variable defined via the m_FileAssign function is named:
DD_IFN. This naming convention is due to the fact that it is the one used by Micro Focus COBOL to map internal file names to external file names.
1.
|
Use environment variable MT_ACC_FILEPATH to specify a directory for the lock files required by concurrent access control mechanism.
|
As shown in Listing 3‑17, the first line defines a GDG and sets its maximum generations to 15, the second line redefines the same GDG maximum generations to 30, the third line defines a GDG without specifying "-s" option (its maximum generations is set to 9999), the fourth line defines a GDG implicitly and sets its maximum generations to 9999, the fifth line defines a GDG use model file
$DATA/FILE, which can be either a GDG file or a normal file.
After the above job runs, $DATA/GDG1 has five GDS numbered as 1, 2, 4, 5, and 9, respectively. The corresponding GDS files are listed as below.
To refer to an existing generation file (GDS) in a GDG, call m_FileAssign with "
-d OLD/SHR/MOD,…" and "
-g 0", "
-g all", or "
-g -n" parameters. "
-g 0" refers to the current generation, "
-g all" refers to all generation files, "
-g -n" refers to the generation file which is the nth generation counting backward from the current generation (as 0 generation).
For example, if GDG1 contains six GDS numbered as 1, 4, 6, 7, 9, and 10, respectively, the mapping of GN and RGN is listed as below.
If "DELETE" is specified in the DISPOSITION filed of
m_FileAssign, the corresponding GDS will be deleted after the current step finishes, resulting in a change of mapping between GN and RGN. The changed mapping will be visible in the next step.
For example, if GDG1 contains six GDS numbered as 1, 4, 6, 7, 9, and 10, respectively, the mapping of GN and RGN is listed as below.
In the above example, GDG1 has six GDS numbered as 1, 4, 6, 7, 9, and 10, respectively. The GDS pointed by SYSUT1 (the GDS whose GN is 9), by SYSUT2 (the GDS whose GN is 6), by SYSUT3 (the GDS file whose GN is 7), and by SYSUT4 (the GDS file whose GN is 1) are deleted.
For example, GDG1 has six GDS numbered as 1, 4, 6, 7, 9, and 10, respectively.
MT_GENERATION variable specifies the way of managing GDG files. To manage GDG in
*.gens files, you need to set the value to
GENERATION_FILE.
Note:
|
To enable this function, MT_GENERATION must be set to GENERATION_FILE_DB, MT_DB must be set to DB_ORACLE or DB_DB2LUW (or set MT_META_DB to DB_ORACLE or DB_DB2LUW), and MT_GDG_DB_ACCESS must be set to valid database connection string to access Oracle Database or DB2 database.
|
Table 3‑5 shows the general management for each GDG managed by Batch Runtime. In this table, each row represents a GDG. All GDG files share a single
GDG_DETAIL table.
Table 3‑6 shows the detailed information of all the GDG generation files. In this table, each row represents a generation file of a GDG.
GDG_FILE_NAME (the physical generation file name) is not stored in table
GDG_DETAIL since it can be constructed from
GDG_BASE_NAME in
GDG_DEFINE and
GDG_ABS_NUM in
GDG_DETAIL.
Table 3‑7 shows the rule of generation file name:
This variable is used along with MT_GENERATION when it is set to
GENERATION_FILE_DB, and must be set with the valid database login account. For accessing Oracle DB, it should be specified in the format of
userid/password@sid, for example,
scott/tiger@orcl.
Used along with MT_GENERATION when set to
GENERATION_FILE_DB. It indicates how to commit GDG changes to database during the commit phase. If configured to "
Y", the GDG changes are committed using a single database access. If configured to "N", the GDG changes are committed using one or more database accesses.
.dcb file can have two values: "
-t <file type>" and "
-r <record length>".
-t <file type> must be
LSEQ or
SEQ in
m_FileAssign to create the first generation file. If you don't specify any file type in
job ksh file,
LSEQ will be used by default.
For SEQ file, the value is mandatory and must be a number or "
number1-number2".
For LSEQ file, the value is optional. Once set, this value must be a number or "
number1-number2".
Create .dcb file for GDG data set when the first generation file is created by
m_FileAssign -g +1.
Notes:
|
If a GDG is created by m_GenDefine rather than m_FileAssign, .dcb file will not exist until the first generation file is created by m_FileAssign -g +1.
|
Once .dcb file is created, its contents will not be changed by any other
m_FileAssign statement afterwards, unless such
m_FileAssign creates the first generation file again.
m_FileAssign -d OLD SYSIN $
{SYSIN}/SYSIN/MUEX07
The MT_DB_LOGIN value must use the following form:
dbuser/dbpasswd[@ssid]or “
/”.
Note:
|
"/" should be used when the RDBMS is configured to allow the use of UNIX authentication and not RDBMS authentication, for the database connexion user.
|
The -b option must also be used if the main program executed does not directly use the RDBMS but one of its subsequent sub-programs does as shown in
Listing 3‑30.
The m_ProgramExec function may submit three types of files.
Make sure that the .gnt files can be found in
$COBPATH (for Micro Focus COBOL) or
$COB_LIBRARY_PATH (for COBOL-IT).
•
|
ProgA(): if you do not need parameters
|
m_ProgramExec will determine the deliverable type of the program in the following sequence: COBOL program (
.gnt), C program in callable shared library (
.so), and other executable programs. Once a COBOL program is executed,
m_ProgramExec will not execute other programs with the same name. For example, once
ProgA.gnt is executed,
ProgA.so or other programs named
ProgA will not be executed.
For .gnt file and
.so files,
m_ProgramExec launches the
runb program to run it. ART provides
runb for the followings.
The runb program, runtime compiled with database librairies, runs the
runbatch program.
The runbatch program, is in charge to :
In this example, the contents of the file ${DATA}/MTWART.JCL.INFO (ddname
SYSUT1) are copied into the file (ddname
SYSUT2) which is using the option
-w INTRDR, and then this file (ddname
SYSUT2) is submitted.
INTRDR job which is generated by COBOL program can be submitted automatically in real time. Once a COBOL program closes
INTRDR, the job
INTRDR is submitted immediately without waiting for the current step to finish. To enable this feature, file handler
ARTEXTFH.gnt needs to be linked to COBOL program.
ARTEXTFH.gnt is placed at "
${MT_ROOT}/COBOL_IT/ARTEXTFH.gnt".
Whether an m_* API calls its user-defined entry/exit function depends on the existence of
m_*_Begin and
m_*_End under
ejr/USER_EXIT.
A pair of general user entry/exit APIs, mi_UserEntry and
mi_UserExit, are called at the entry and exit point of each external API. The argument to these APIs consists of the function name in which they are called, and the original argument list of that function. You don’t need to modify these two APIs, but just need to provide your custom entry/exit for m_* external APIs.
mi_UserEntry and
mi_UserExit are placed under
ejr/COMMON.
Table 3‑9 lists the Log message levels provided by Batch Runtime:
Table 3‑10 shows the variables you can use for specifying the general log header:
MT_LOG_HEADER is a new configuration variable added in
CONF/BatchRT.conf, for example:
If the value of MT_LOG_HEADER is not a null string, its contents are evaluated as a shell statement to get its real value to be printed as the log header, otherwise this feature is disabled.
Note:
|
The string that configured to MT_LOG_HEADER is treated as a shell statement in the source code, and is interpreted by " eval" command to generate the corresponding string used as log header:
|
•
|
MT_LOG_HEADER must be a valid shell statement for " eval", and must be quoted by single quotation marks.
|
The string "%s" at the end of each identifier represents it will be written to log file. You can configure its value using the following variables defined in
CONF/Batch.conf. For more information, see
Table 3‑12.
To configure strings to these MT_LOG_FILE_* variables, replace the placeholders with corresponding values (just string replacement). The result is treated as a shell statement, and is interpreted by "
eval" command to generate the corresponding string writing to log:
•
|
All the command line used in MT_LOG_HEADER must be quoted by " $()". For example: $(ls -l --time-style=+'%Y/%m/%d %H:%M:%S' --no-group <%FULLPATH%> )
|
If the level of FileInfo message is equal to or less than the message level specified for Batch Runtime and
MT_LOG_FILE_* is set to a null string,
FileInfo message will not be displayed in job log. If
MT_LOG_FILE_* is set to an incorrect command to make file information invisible, FileInfo message will not be displayed in job log as well, but the job execution will not be impacted.
The SYSIN file must contain the SQL requests and the user has to verify the contents regarding the database target.
•
|
Set DB_HOME correctly because it is required by BDB; DB_HOME points to a place where temporary files are put by BDB.
|
•
|
Unset COB_ENABLE_XA environment variable before booting the TuxJES system.
|
•
|
A trusted SSH connection must be configured between host1 and host2, that is, the user ( user2) who boots up ARTJESCONV is allowed to log into host1 without passwords. By doing this, ARTJESCONV can invoke ART Workbench installed on host1 directly without interaction.
|
Note:
|
If multiple ARTJESCONV servers on more than one machine are configured in JES domain, the trusted SSH connection should be configured on each machine equipped with ARTJESCONV.
|
1.
|
Login host2 with user name user2.
|
2.
|
Run "cd $HOME/.ssh" on host2.
|
3.
|
Run "ssh-keygen -t rsa" to generate id_rsa and id_rsa.pub.
|
4.
|
Login host1 with user name user1.
|
5.
|
Run "cd $HOME/.ssh" on host1.
|
The template working folder for JCL conversion is $JESROOT/jcl_conv_dir, which will be created automatically if it does not exist at startup.
$JESDIR/Batch_RT/jcl_conv_dir contents are automatically copied to such working folder when Batch Runtime starts. When a JCL job is submitted, JES copies this template folder to folder
$JESROOT/<JOBID>/JCL, and puts the JCL job file to folder
$JESROOT/<JOBID>/JCL/source/JCL/, where Workbench works.
Users need to copy all the INCL,
PROC, and
SYSIN to the template working folder for each JCL job. When converting and executing a JCL job,
$JESROOT/<JOBID>/JCL/target/PROC:$JESROOT/<JOBID>/JCL/target /INCL is added to the head of the environment variable
PROCLIB, and
$JESROOT/<JOBID>/JCL/target/Master-SYSIN is set to the environment variable
SYSIN.
MT_REFINEDIR and
MT_REFINEDISTRIB are required to be configured. For more information, please refer to
Table 3‑3.
Option -l is used to submit a JCL job with the following usage.
The column, job type, is added to the results with one of the following values.
By m_SetJobExecLocation API of Batch Runtime, users can develop KSH jobs with NJE support. For example,
•
|
At least one ARTJESINITIATOR server must be deployed in that server group.
|
If NJE support is disabled in jesconfig, the statement
m_SetJobExecLocation <SvrGrpName> is ignored by TuxJES and then the job may executed by any
ARTJESINITIATOR in any server group.
In MP mode, MT_TMP needs to be configured on NFS, and all the nodes in tuxedo domain should have the same value of
MT_TMP and share it.
MT_TMP can be configured in file
$MT_ROOT/CONF/BatchRT.conf, or to
export it as environment value before tlisten is started in each node.
If NJESUPPORT is enabled in
jesconfig, a new queue named
EXECGRP must be created in the existing queue space
JES2QSPACE. If
EXECGRP is not created, no jobs can be processed by JES.
In the above sample, job TEST1 will be submitted by the current job and executed by the
ARTJESINITIATOR which belongs to JES's Tuxedo server group
ATLANTA.
If it is set to yes (MT_USE_FILE_CATALOG=yes), the file catalog functionality is enabled; otherwise, the functionality is disabled.
For Db2, its value is "your-database USER your-username USING your-password" (for example, "
db2linux USER db2svr USING db2svr").
MT_CATALOG_DB_LOGIN precedes
MT_DB_LOGIN in accessing file catalog. If file catalog DB is the same as data DB, configuring
MT_DB_LOGIN only is required; otherwise, both must be configured.
You can use CreateTableCatalog[Oracle|Db2].sh or
DropTableCatalog[Oracle|Db2].sh to create or drop the new database table.
MT_REXX_PATH has no default value. It should be set with the main path where all REXX execs located in. Place REXX programs in proper subdirectories under
${MT_REXX_PATH}. These subdirectories correspond to PDS on mainframe where REXX programs live.
If SYSEXEC is defined, BatchRT accepts programs run by
m_ProgramExec as
REXX EXEC.
DD SYSEXEC specifies where to find object REXX programs.
Batch_RT/tools/rexx/tso is where TSO commands are located. REXX APIs should be put in the
Batch_RT/tools/rexx/lib directory.