Some variables (such as ORACLE_SID, COBDIR, LIBPATH, COBPATH …) are shared variables between different components and are not described in this current document. See the Rehosting Workbench Installation Guide.Table 3‑1 lists the environment variables are used in the KSH scripts and must be defined before using the software.
Table 3‑1 KSH Script Environment Variables Table 3‑2 lists the environment variables are used by Batch Runtime and must be defined before using the software.
(See the BatchRT.conf configuration file) (See the BatchRT.conf configuration file) A mandatory environment variable which indicates the directory to GDG technical functions. The default is directory GENERATION_FILE. If the value is specified as NULL or with an incorrect directory name, error occurs when using this environment variable. Timing of implicit GDG commitment. If it is set to JOB, implicit GDG commitment is performed at the end of job; if it is set to STEP, implicit GDG commitment is performed at the end of step (See Committing a GDG for details). (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.conf configuration file)Within Batch Runtime, a phase corresponds to an activity or a step on the source system.At the end of each phase, the JUMP_LABEL variable is updated to give the label of the next phase to be executed.In the following example, the last functional phase sets JUMP_LABEL to JOBEND: this label allows a normal termination of the job (exits from the phase loop).The mandatory parts of the script (the beginning and end parts) are shown in bold and the functional part of the script (the middle part) in normal style as shown in Table 3‑3. The optional part of the script must contain the labels, branching and end of steps as described below. The items of the script to be modified are shown in italics.
Table 3‑3 Script Structure JUMP_LABEL=STEP2 (PENULTIMATESTEP) For the label, which must point to END_JOB. The _ is necessary, because the character is forbidden on z/OS. Listing 3‑1 shows a Korn shell script example.Listing 3‑1 Korn shell Script ExampleSymbols are internal script variables that allow script statements to be easily modifiable. A value is assigned to a symbol through the m_SymbolSet function as shown in Listing 3‑2. To use a symbol, use the following syntax: $[symbol]Listing 3‑2 Symbol Use ExamplesThe most frequent steps are those that execute an application or utility program. These kind of steps are generally composed of one or several file assignment operations followed by the execution of the desired program. All the file assignments operations must precede the program execution operation shown in Listing 3‑3Listing 3‑3 Application Program Execution Step ExampleAn in-stream procedure in a Korn shell script always starts with a call to the m_ProcBegin function, followed by all the tasks composing the procedure and terminating with a call to the m_ProcEnd function. Listing 3‑4 is an example.Listing 3‑4 In-stream Procedure ExampleExternal procedures do not require the use of the m_ProcBegin and m_ProcEnd functions; simply code the tasks that are part of the procedure shown in Listing 3‑5Listing 3‑5 External Procedure ExampleThe use of a procedure inside a Korn shell script is made through a call to the m_ProcInclude function.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.A procedure, either in-stream or external, can be used in any place inside a calling job provided that the above principals are respected shown in Listing 3‑6Listing 3‑6 Call to the m_ProcInclude Function ExampleListing 3‑7 and Listing 3‑8 are examples.Listing 3‑7 Defining Procedure ExampleListing 3‑8 Calling Procedure ExampleAs 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.The overriding of a file assignment is made using the m_FileOverride function that specifies a replacement for the assignment present in the procedure. The call to the m_FileOverride function must follow the call to the procedure in the calling script.Listing 3‑9 shows how to replace the assignment of the logical file SYSUT1 using the m_FileOverride function.Listing 3‑9 m_FileOverride Function ExampleListing 3‑10 m_FileOverride Procedure Call: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‑11. These functions can be nested up to 15 times.Listing 3‑11 m_CondIf, m_CondElse, and m_CondEndif ExampleThe 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‑12.Listing 3‑12 m_CondExec Example with Multiple Conditions
• 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 usage of the m_CondExec, m_CondIf, m_CondElse and m_CondEndif functions: see Conditioning the Execution of a Step.If Batch Runtime administrator wishes to change the default messages (to change the language for example), this can be done through a configuration file whose path is specified by the environment variable: MT_DISPLAY_MESSAGE_FILE.When using Batch Runtime, a file can be used either by a Batch Runtime function (for example: m_FileSort, m_FileRename etc.) or by a program, such as a COBOL program.In both cases, before being used, a file must first be assigned. Files are assigned using the m_FileAssign function that: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.Once a file is assigned, it can be passed as an argument to any of Batch Runtime functions handling files by using the ${DD_IFN} variable.Listing 3‑13 Example of File AssignmentListing 3‑14 Example of Using a File by a COBOL Program
1. Use environment variable MT_ACC_FILEPATH to specify a directory for the lock files required by concurrent access control mechanism.
2.
•
• Following two lines in ejr/CONF/BatchRT.conf should be commented out:Oracle Tuxedo Application Runtime for Batch allows you to manage GDG files either based on file or based on database (DB). In file-based management way, Batch Runtime manages GDG files in separate "*.gens" files, and one "*.gens" corresponds to one GDG file. In DB-based management way, Batch Runtime manages GDG information centrally in Oracle database.A GDG (Generation Data Group) file is defined through the m_GenDefine function. A GDG can be defined explicitly or implicitly, and can be "redefined".As shown in Listing 3‑15, the first line defines a GDG explicitly 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), and the fourth line defines a GDG implicitly and sets its maximum generations to 9999.Listing 3‑15 Example of Defining a Generation FileTo add a new generation file into a GDG, call m_FileAssign with "-d NEW,…" and "-g +n" parameters. The generations files can only be added into a GDG generation by generation. That is, generation n+1 can only be added after generation n is already added. Following are two examples for adding generation files into a GDG, Listing 3‑16 demonstrates a correct usage, while Listing 3‑17 demonstrates an incorrect usage.
Note: To refer to an existing generation in a GDG, call m_FileAssign with "-d OLD,…" and "-g -n" or "-g 0" parameters. "-g 0" refers to the current generation, "-g -n" refers to the generation file which is the nth generation counting backward from the current generation (as 0 generation). See Listing 3‑18 for an example of referring to existing generation files in a GDG:Listing 3‑18 Referring to Existing Generation Files in a GDG
Note: You can only delete a GDG as whole by calling m_FileDelete with the GDG base name, as shown in Listing 3‑19. Deleting a specific generation file is not supported.Listing 3‑19 Deleting a GDGTo commit all the changes of GDG to be persistent, m_GenCommit is called explicitly with the GDG base name, as shown in Listing 3‑20. After the committing, all the new generation files become to old generations and all the changes to old generation files are committed too. If no GDG base name is provided with m_GenCommit, all the GDG files that have been accessed in a job are committed. This kind of committing is called explicit committing.Listing 3‑20 Committing All the Changes on a GDGGDG changes can be committed implicitly at the end of a job or a step according to a configuration variable MT_GDG_COMMIT. If MT_GDG_COMMIT is configured to JOB, all GDG changes in a job are committed implicitly at the end of job if the job succeeds. If MT_GDG_COMMIT is configured to STEP or COMP, all GDG changes in a step are committed implicitly at the end of step if the step succeeds. The difference between STEP and COMP is that current generation is not changed with MT_GDG_COMMIT=COMP but changed with MT_GDG_COMMIT=STEP at the end of each step. The difference between JOB and COMP is that all the changes to GDG prior to a failed step are kept with MT_GDG_COMMIT=COMP, but lost with MT_GDG_COMMIT=JOB.
Note: Listing 3‑21 and Listing 3‑22 add two generation files in two steps separately.Listing 3‑23 and Listing 3‑24 add one generation file in one step and then refer to that new file in another step.m_FileAssign -d NEW,CATLG -g +2 SYSUT1 ${DATA}/PJ01DDD.BT.GDG
Note: In Listing 3‑21, if STEP2 fails, the new file corresponding to -g +1 is kept with MT_GDG_COMMIT=COMP, but lost with MT_GDG_COMMIT=JOB.m_FileAssign -d NEW,CATLG -g +1 SYSUT1 ${DATA}/PJ01DDD.BT.GDGListing 3‑23 Adding one generation file in one step and referring to new file, with MT_GDG_COMMIT=JOB or COMPm_FileAssign -d OLD,CATLG -g +1 SYSUT1 ${DATA}/PJ01DDD.BT.GDGListing 3‑24 Adding one generation file in one step and referring to new file, with MT_GDG_COMMIT=STEPm_FileAssign -d OLD,CATLG -g 0 SYSUT1 ${DATA}/PJ01DDD.BT.GDGTo roll back all the changes on a GDG, call m_GenRollback with the GDG base name, as shown in Listing 3‑25. After rolling back, the GDG is kept as before.Listing 3‑25 Rolling Back All the Changes on a GDGGDG changes can be rolled back implicitly at the end of a job or a step according to a configuration variable MT_GDG_COMMIT. If MT_GDG_COMMIT is configured to JOB, all GDG changes in a job are rolled back implicitly at the end of job if the job fails. If MT_GDG_COMMIT is configured to STEP, all GDG changes in a step are rolled back implicitly at the end of step if the step fails.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.In file-based GDG management mechanism, one GDG file can only be accessed by one job at any time, that is, a single GDG cannot be accessed by multiple jobs simultaneously. To access a GDG file, the file lock must be acquired by the existing internal function mi_FileConcurrentAccessReservation. File-based GDG management mechanism uses a file *.gens (* represents the GDG base name) to control concurrency and authorization. User access checking depends on whether the *.gens file can be accessed or not.Table 3‑4 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‑4 GDG_DEFINE It cannot contain only a relative path relative to a single repository. The length of GDG_BASE_NAME is limited to 1024, i.e. the minimum of PATH_MAX on different UNIX platforms. It contains the upper limit of generations specified by -s option. -s option can be set in the range of 1-9999. Primary Key: GDG_BASE_NAMETable 3‑5 shows the detailed information of all the GDG generation files. In this table, each row represents a generation file of a GDG.
Table 3‑5 GDG_DETAIL Primary Key: GDG_BASE_NAME+ GDG_ABS_NUMGDG_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.
Note: Table 3‑6 shows the rule of generation file name:
Table 3‑6 Generation File Naming Rule Specifies how to manage GDG files. To manage GDG files in database set the value to GENERATION_FILE_DB and configure MT_GDG_DB_ACCESS appropriately.Used along with MT_GENERATION when set to GENERATION_FILE_DB, and must be set with the valid database login account. To access Oracle DB, it should be specified in the following format: 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.DB-based GDG management mechanism maintains the same concurrency control behavior as File-based GDG management mechanism, but has a different *.ACS (* represents the GDG base name) file format. In DB-based GDG management mechanism, you don’t need to lock the tables mentioned in Database Tables as any job that accesses the rows corresponding to a GDG must firstly acquire the file lock of the GDG. That is to say, there is no need to perform concurrency control in the database access level. You cannot access database if you don’t have access permission (read or write) to the corresponding *.ACS file. If you need to modify a GDG file, you must have write permissions to the generation files and the directory holding the generation files, and MT_GDG_DB_ACCESS must be configured correctly to have appropriate permissions to the tables mentioned in Database Tables.
• *.ACS fileThese information should be kept consistently for a GDG file. Batch Runtime checks the consistency from GDG_DEFINE to Physical files when a GDG file is accessed the first time in a job. If exceptions happen and result in inconsistency among these information, Batch Runtime terminates the current job and reports error.To define and use a file whose data is written directly inside the Korn shell script, use the m_FileAssign function with the -i parameter. By default the string _end is the “end” delimiter of the in-stream flow as shown in Listing 3‑26.Listing 3‑26 In-stream Data ExampleTo use a set of files as a concatenated input (which in z/Os JCL was coded as a DD card, where only the first one contains a label), use the m_FileAssign function with the -C parameter as shown in Listing 3‑27.Listing 3‑27 Using a Concatenated Set of Files ExampleTo use an “external sysin” file which contains commands to be executed, use the m_UtilityExec function.Files (including generation files) can be deleted using the m_FileDelete function:In other words, if in the z/OS JCL there was a file copy operation involving the converted file, this is translated to a standard copy operation for files in Batch Runtime, in other words an m_FileLoad operation).When executing an application program that needs to connect to the RDBMS, the -b option must be used when calling the m_ProgramExec function.
• Set the environment variable MT_DB_LOGIN before booting the TuxJES system.
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‑28.Listing 3‑28 RDBMS Connection ExampleThe m_ProgramExec function may submit three types of executable files (Cobol executable, command language script, or C executable). It launchs the runb program. We have provided the runb for $ARTDIR/Batch_RT/ejr_mf_ora (on Linux) and ejr_ora (other platforms). If you use neither Microfocus COBOL compiler nor Oracle Database, go to $ARTDIR/Batch_RT/ejr and run "make.sh" to generate your required runb.The runbatch program, is in charge to :Batch Runtime allows you to add custom pre- or post- actions for public APIs. For each m_* (* represents any function name) function, you can provide m_*_Begin and m_*_End function and put them in ejr/USER_EXIT directory. They are invoked automatically when a job execution entering or leaving an m_* API.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.You are suggested not to call exit in user entry/exit function. Because In the framework, exit is aliased an internal function, mif_ExitTrap, which is invoked ultimately if exit in user entry/exit function is called. If exit 0 is called, the framework does nothing and job is continue, if exit not_0 is called, a global variable is set and may terminate the current job.You should include only one function, e.g. m_*_Begin or m_*_End, in a single file with the same name as the function, and then put all such files under ejr/USER_EXIT.You are not allowed to provide custom entry/exit functions for any mi_ prefix function provided by Batch Runtime.
Table 3‑7 Log Message Format
• b: Specific for exceptions messages Fatal/Error/Warning Table 3‑8 lists the Log message levels provided by Batch Runtime:
Table 3‑8 Log Message Level Same as level 3 and high level functions which correspond to the -d regexp option Same as 7 and technical level functions which correspond to the -d regexp option
• Use -V option of EJR
• Use the environment variable MT_DISPLAY_LEVELThe display level set by EJR can override the level set by MT_DISPLAY_LEVEL.For each launched job, Batch Runtime produces a log file containing information for each step that was executed. This log file has the following structure as shown in Listing 3‑29.Listing 3‑29 Log File ExampleWhen not using TuxJes, the log file is created under the ${MT_LOG} directory with the following name: <Job name>_<TimeStamp>_<Job id>.logTable 3‑9 shows the variables you can use for specifying the general log header:
Name of the job assigned by m_JobBegin in the job script. Name of the proc when the code included from a PROC by m_ProcInclude is executing; empty otherwise.MT_LOG_HEADER is a new configuration variable added in CONF/BatchRT.conf, for example:MT_LOG_HEADER='$(date'+%Y%m%d:%H%M%S'):${MTI_SITE_ID}:${MTI_JOB_NAME}:${MTI_JOB_ID}:${MTI_JOB_STEP}: '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:Syntax inside: eval mt_MessageHeader=\"${MT_LOG_HEADER}\"
• MT_LOG_HEADER must be a valid shell statement for "eval", and must be quoted by single quotation marks.
•
• All the command line used in MT_LOG_HEADER must be quoted by "$()". For example: $(date '+%Y%m%d:%H%M%S')You can modify the above examples according to your format needs using only the variables listed in Table 3‑9.The following message identifiers are defined in CONF/Messages.conf to support using of mi_DisplayFormat to write file assignment and file information log.CONF/Messages.conf is not configurable. Do not edit this file.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‑11.
• MT_LOG_FILE_ASSIGN (for FileAssign)
• MT_LOG_FILE_RELEASE (for FileRelease)
• MT_LOG_FILE_INFO (for FileInfo)Three configuration variables should be defined in CONF/BatchRT.conf to determine the detailed file information format. With the placeholders listed in Table 3‑10, you can configure file log information more flexibly.
Table 3‑10 Placeholders SHR or NEW
Table 3‑11 Configuration Variables in CONF/BatchRT.conf
Note: "operation" is hard-coded into source code, such as FileCopy source, FileCopy Destination, and FileDelete etc. 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:Syntax inside: eval mt_FileInfo=\"${MT_LOG_FILE_INFO}\"
• After placeholders are replaced, MT_LOG_FILE_* must be a valid shell statement for "eval", and must be quoted by single quotation marks.
•
• 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.Entry points are provided in some functions (m_JobBegin, m_JobEnd, m_PhaseBegin, m_PhaseEnd) in order to insert specific actions to be made in relation with the selected Job Scheduler.Note that the environment variable MT_DB_LOGIN must be set (database connection user login).The SYSIN file must contain the SQL requests and the user has to verify the contents regarding the database target.