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 KSH script environment variables
Within the Batch Runtime, a phase corresponds to an activity or a step on the source system.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).
Table 3‑3 Script structure JUMP_LABEL=STEP2 (PENULTIMATESTEP) 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. To use a symbol, use the following syntax: $[symbol]Listing 3‑2 Symbol use examplesListing 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 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.Listing 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.Listing 3‑6 Call to the m_ProcInclude function exampleListing 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.The following example 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. 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.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 usage of the m_CondExec, m_CondIf, m_CondElse and m_CondEnd functions: see Conditioning the execution of a step.If the 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.Files are created using the m_FileBuild function.When using the Batch Runtime, a file can be used either by a Batch Runtime function (for example: m_FileSort, m_FileRename etc.) or a 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 the 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 programA generation file is defined through the m_GenDefine function. The only parameter to be specified is the maximum number of versions to keep on the disk:The m_FileAssign function has a special parameter (-g) that serves to specify that the file being assigned is a generation file and to set the desired version of the file.Listing 3‑15 Example of using a generation file:To define and use a file whose data is written directly inside the Korn shell script, use the standard UNIX cat command as follows:Listing 3‑16 In-stream data exampleListing 3‑17 Using a concatenated set of files exampleFiles (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 the 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.The connection and disconnection, as well as the commit and rollback operations are handled implicitly by the Batch Runtime. However, the programmer must ensure that the environment variable MT_DB_LOGIN is correctly defined. The MT_DB_LOGIN value must have 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.Listing 3‑18 RDBMS connection exampleListing 3‑19 Log file exampleWhen not using JES2, the log file is created under the ${MT_LOG} directory with the following name: <Job name>_<TimeStamp>_<Job id>.logEntry 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.