The MFBSI Configuration File

To simplify scheduler configuration, you can store most MFBSIJCL command line parameters for a given Enterprise Server with Mainframe Subsystem Support (MSS) in a configuration file. Storing parameters in a configuration file means that potentially the only parameter needed in order to execute MFBSIJCL on a command line is the JCL member name.

By default, the name of the configuration file is mfbsi.cfg and it resides in the location specified by the MFBSI_DIR environment variable. You can change the default location and the file name as needed with the CFG=... command line parameter, or by setting a value for the MFBSI_CFG environment variable in the shell where MFBSIJCL is running.

A template of the configuration file, named mfbsi.cfg_model, is located in the <install-directory>\etc folder (Windows), or the $COBDIR/demo/mfbsi folder (UNIX).

That directory also contains the JCL file, rc08.jcl, which invokes IDCAMS. You can use this JCL with MFBSI for your initial tests.

Format of the mfbsi.cfg file

  • An asterisk (*) or a semi-colon (;) in position 1 of a line indicate a comment. To enable a parameter defined in the file, delete the comment symbol and specify a suitable value for the parameter.
  • Any blank lines in the file are ignored.
  • Parameter names are not case sensitive.
  • Keyword parameter values are case insensitive. Other parameter values may be case sensitive, especially with directory extensions on UNIX and Linux platforms.
  • If a parameter is defined both in the configuration file and on the command line, the command line definition takes precedence.
  • Some special parameters are only available from the configuration file and cannot be directly used from the command line.
  • If you use the access codes -j or -x on the MFBSIJCL command line, the values of the configuration parameters JCL-Submit and JCL-Ext in mfbsi.cfg are ignored.
When you use a configuration file, the minimum execution command line parameter you need to specify for mfbsijcl is the name of the JCL file to submit with or without the extension. In this case, specify the following parameters in mfbsi.cfg:
ES-Server=-r|-l|-sTCP
Specifies how to access the enterprise server region.
JCL-Submit=-j|-xJCLpathLocation
Specifies the location of the enterprise server region or instance where the JCL will be submitted.

where:

-j
Specifies jobfile name by content. The submitted file must be on the client's platform, which could be the same platform as the target enterprise server. The submitted JCL is physically passed over the communications link. See cassub for more information.
-x
Specifies the jobfile name by reference. The submitted file must be on the same platform as the enterprise server. This technique is more efficient, since only the name of the file is passed by the communications link. See cassub for more information.
JCL-Ext=jcl_extension_name
Specifies the extension to be used, if not specified in the command line parameter. Refers to the JCL file.
SJobID=JobNo|StdOut|JCL
Specifies how to output the MFBSIJCL execution log:
JobNo
Specifies a file in MFBSI_DIR named JOBnnnnnnn where nnnnnnn is the job number.
StdOut
Directs the MFBSIJCL log to StdOut.
JCL
Specifies a file in MFBSI_DIR named with the JCL member name.
JESYSMSG
Specify this if you need to retrieve the JCL JESYSMSG execution log.
REGION=RegionName
Specifies the target region/instance name when using a custom MFBSI_DIR. Where MFBSI_DIR path does not use the region/instance name as the last directory:
RegionName
Is the target enterprise server region name.
SHOW-SUBMIT-JCL=Y[es]
After substitution and including //SYSIN DD * data, gets the full JCL submitted to Enterprise Server, which is shown in the mfbsijcl output log.
ES_PAC=pacname
When running inside a Performance and Availability Cluster (PAC), this is the PAC name and is mandatory in mfbsi.cfg. This requires Enterprise Server 5.0 PU1 or later.
Note: This is mandatory when running in a PAC.
ES_PAC_ENDPOINT=
psor_name=sor,host_ipaddress:port_number 1
psor_name=sor,[userid@][configfile][,property=[value]]… 2 [6]
1 This is the connection string for a Redis-based PAC Scale-Out Repository (PSOR).This is the name of the PSOR being used followed by SOR type, the host and or IP address, and then the port number. For example: MyPSOR=redis,127.0.0.1:6379.

2 This is the connection string for an Oracle Coherence-based PAC Scale-Out Repository (PSOR). This is the optional user to use when Oracle Coherence security is enabled. The configfile is the name, location, URL of the cache configuration file. If this is omitted it defaults to mfes-cache-config.xml. The Java property and corresponding value pair. For example, MySOR=coherence,mfes-cache-config.xm,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1:7574. See PAC and SOR Environment Variables for more information.

This entry is mandatory in mfbsi.cfg file.

Note:
  • When Redis sentinels are used, all of them must be identified .
  • This is mandatory when running in a PAC.
  • When using Micro Focus Batch Scheduler Integration (MFBSI) with a Coherence-based Scale-out Repository (SOR) for a Performance and Availability Cluster (PAC) the connection string should be specified in a similar manner to when using Redis. See Prerequisites in the Scale-Out Performance and Availability Clusters chapter for more information. Micro Focus strongly recommends you specify the connection from MFBSI as thin, remote even if the PAC is using thin, direct as the connections are typically very short-lived and are better served by thin, remote connections. [6]

The template configuration file includes a list of the parameters you can use:

  • To access an enterprise server with Mainframe Subsystem Support and specify its name and location:
    ES-Server=-rES-JCL
    ES-Server=-sTCP:10.1.1.101:32793
    ES-Server=-sTCP:HostName:32793
    ES-Server=-lES-SERV
    Note: When running inside a Performance and Availability Cluster (PAC), Micro Focus recommends that you use ES-Server=-sTCP that points to the address of a load balancer which will redirect requests to an available enterprise server instance.
  • To submit a JCL file (-x or –j) and specify the path to the JCL member directory:
    JCL-Submit=-jPathToJCLfile
    JCL-Submit=-xPathToJCLfile
    Note: Do not use double quotes for directory names that include spaces.

    PathToJCLfile can use one or more references to environment variables. In this case, you need to prefix the environment variable with a $. For example, JCL-Submit=-x$SEE_JCL_BASE/$JCL_PDS.

    The environment variables SEE_JCL_BASE and JCL_PDS are substituted with their respective values.

  • When using a custom MFBSI_DIR setting, the last part of the MFBSI_DIR path does not specify the region name:
    REGION=RegionName

    where:

    RegionName
    Is the target enterprise server region name.
  • To specify the JCL file extension to add to the JCL member name specified on the command line:
    JCL-Ext=jcl_extension_name

    where:

    jcl_extension_name
    Is the extension to be used. The default is no extension. For example, JCL-Ext=jcl.
    Note: You must not specify the period (".") before the extension.
  • To specify the startup timeout in seconds before issuing an alert:
    StartupTimeout=n
  • To specify the run timeout in seconds before issuing an alert:
    RunTimeout=n
  • To specify the alert back elapsed time in seconds:
    AlertBackTimeout=n
  • To avoid stopping the MFBSIJCL execution when the enterprise server is stopped and the job is still waiting for execution:
    ES-SHUTDOWN-JWAIT=CONTINUE
    This is optional but recommended.
  • To request the JESYSMSG log from the enterprise server written in the SjobID.log file:
    JESYSMSG
  • To request the JESYSMSG log from the enterprise server and write it to StdOut:
    JESYSMSG=StdOut
  • To assign a name for the MFBSI jobLog file:
    • When using the job number assigned by the enterprise server:
      SJobID=JobNo
    • When using the JCL member name:
      SJobID=JCL
    • To write the MFBSI job execution log to the standard output (StdOut):
      SJobID=StdOut
  • To request the execution of a pre-submit user-exit module:
    JCLExit=pgmName

    Use the associated string passed to the pre-submit user-exit module to determine what action to perform (a maximum of 32 characters):

    JCLExitID=IdentString
  • To invoke a termination user exit just before terminating the execution of MFBSIJCL:
    TerminateExit=pgmName
  • By default, performing a soft-kill on an MFBSIJCL process that is waiting for JOB termination also cancels the JOB in Enterprise Server before terminating.

    Use the following parameter to avoid killing the JOB when the process is soft-killed:

    ES_JOB_KILL=NO
    By default, ES_JOB_KILL=YES.
  • Optional, set to ON by default. This parameter is mainly useful if your JCL member contains a mix of STD NUM ON and OFF records.

    With STDNUM=OFF, JCL records columns 73-80 content are ignored even if they contain any JCL statements or any in-stream data.

    The previous MFBSI logic based on whether the contents of the first record include or not any JCL-containing data in columns 73-80 is maintained.

    STDNUM=ON
  • To specify the type of JCL files other than the default one, JES2:
    JCLType={VSE|JES2|JES3}
  • Optional, when MSS security is enabled:
    • To specify a user ID:
      UserID=myUser
    • To specify a password:
      Password=myPwd
    • To specify a security group:
      SGroup=securityGroup
  • Symbolic parameters substitution and using the Control-M AutoEdit Facility.

    To substitute parameters without accessing the Control-M AutoEdit facility, use:

    SkelProcessType=MFBSI
    Note: Using these parameters is mandatory when you use JCL parameters.

    Substitution is requested with SkelProcessType.

    To enable the specific Control-M AutoEdit Facility processing, use:

    SkelProcessType=CONTROL-M

    Or:

    SkelProcessType=MFBSICTM

    Optional, to substitute parameters even if no parameters are specified on the MFBSIJCL command line. This enables substitution of system parameters like DATE, and DAY:

    AutoEdit

    Optional, to specify the parameter substitution prefix as either one or two characters:

    SUBST-Prefix=parameterValue

    The default parameterValue is %%.

    Optional, to specify the day the week starts:

    StartOfWeek=Sunday|Monday

    The default value is Sunday .

    Optional, to force submitting the substituted JCL by reference or by content, CASSUB –x:

    CASSUB-CTM={BYREF|CONTENT}
    By default, CASSUB... –j ... is used.
  • Optional, to specify the use of API calls for CASSUB/CASOUT in place of their native commands, and avoid having to create a new process for them specify:
    CASAPI
  • To specify the OS codes returned by MFBSIJCL if a job abends:
    • With a SYSTEM abend:
      SYS-ABEND-RC=nnn
    • With a USER abend:
      USR-ABEND-RC=nnn
    • With a Run-Time system abend:
      RTS-ABEND-RC=nnn
  • The default delays used by MFBSIJCL to check for a job state in Enterprise Server are as follows:
    • Two seconds before each check for "Job Started".
    • Ten seconds before each check for "Job Concluded".

    You can use the following two parameters to configure these delays:

    JOBSTART-LOOKUP-FREQ={nn|AUTO}
    JOBEND-LOOKUP-FREQ={nn|AUTO}

    where:

    nn
    Indicates a delay in seconds with a minimum of 1 and a maximum of 60 seconds.
    AUTO
    MFBSIJCL automatically optimizes the lookup delay.

    When AUTO is used, MFBSIJCL uses an initial delay of one second for three minutes after which the default values are restored.

    Using these parameters significantly reduces the overhead elapsed time in MFBSIJCL when compared to the Enterprise Server JCL reported execution time of a job. This has an effect mainly in scenarios when you have short-running jobs that are frequently executed.

  • When JOBSTART-LOOKUP-FREQ or JOBSTART-LOOKUP-FREQ are set to AUTO, you can use the parameter Job-AUTO-Delay to customize the delay used by MFBSIJCL. For example, you can switch from high lookup frequency back to the default values.

    Use Job-AUTO-Delay to set the value from 1 to 60 (in minutes). The default is 3 minutes.

  • Optional, to specify the maximum possible delay (in minutes) for an ended job to conclude in MSS/JCL:
    EMX-Timeout=nn
    The default value is six minutes.
  • To produce a detailed trace log of mfbsijcl execution. That can be used if requested by Micro Focus Support. This is not recommended in a production environment:
    MFDEBUG