Walkthrough with MFBSI

Introduction

MFBSI wraps cassub cassub and cassout casout with additional features so schedulers can have more control over JES jobs.

The main MFBSI documentation is in the Enterprise Developer product help (see Micro Focus Batch Scheduler Integration) and applies to the native Enterprise Server product. The architecture of Enterprise Server for .NET implementation is slightly different although the main functionality is the same.

The main things schedulers need that aren't provided by cassub/ cassout are a way to determine when a job has finished, and what the results of the job (status, exit code, output) were. MFBSI does this by creating files in an MFBSI work directory as jobs are processed.

The default MFBSI user exit called mfbsiemx.dll has been compiled into managed code and is included in the \binAnyCPU\SEE folder and will be on the path provided by the Enterprise Server command prompt.

The mfbsijcl utility is common to Enterprise Server andEnterprise Server for .NET and should be on the path set by the Enterprise Developer command prompt.

MFBSI environment variables

mfbsiemx and mfbsijcl both need two environment variables set in order to function correctly. Setting environment variables for mfbsiemx means setting them in the seepubsub environment (as discussed below). For mfbsijcl, you can set them in the command session where you are running mfbsijcl, if you have started it manually. If you want to run it under control of a scheduler, you might want to put it in a script.

The variables are:

• MFBSI_DIR - per the MFBSI documentation, set this to the full path of the MFBSI work directory. You have to create this directory so you can put your configuration file (see next section) there. The directory structure should end in the region name. For example, c:/tmp/JCLDEMO.
• ES_SERVER - set this to the region name. For example, "JCLDEMO". In the native-code Enterprise Server, this is automatically set for mfbsiemx, but in ES.NET, you have to set it explicitly.

These variables can be included in the seepubsub.exe.config file as described in the section seepubsub Configuration File.

MFBSI configuration file

As described in the MFBSI documentation, you need to create an MFBSI configuration file, which you'll put in the MFBSI work directory. This is a text file named mfbsi.cfg with a simple format covered in the MFBSI documentation.

The following is an example mfbsi.cfg file:

* Configuration file for MFBSI
* How to contact the server
ES-Server=-stcp:localhost:9122
* How to submit JCL, and path to folder containing it
JCL-Submit=-jD:\dev\jcldemo
* Extension for JCL files
JCL-Ext=jcl
* Let MFBSIJCL wait for region startup if a job is pending
ES-SHUTDOWN-JWAIT=continue
* Request JESYSMSG log from ES and write it to file <sjobid>.log
JESYSMSG
* Form sjobid from the ES job number
SJobID=JobNo

The critical parameter for Enterprise Server for .NET is ES-Server, which specifies how to connect to the region for the cassub and the casout commands. It must use the "-s" form (for example - "-s:tcp:localhost:9022"), because Enterprise Server for .NET does not support the other options.

Running seepubsub+MFBSI standalone

This is the development configuration, similar to running self-hosted dispatcher and SEPs. The main advantages are:

• Interactive seepubsub makes it easy to start or stop, or see what is happening.
• You can easily set environment variables for MFBSI.

Interactive mode is not ideal for production use, but might be useful when developing an MFBSI configuration.

1. Create your configuration file as described above.
2. Set environment variables as described above.
3. Start ES.NET components (dispatcher, listener, etc) if running self-hosted. You can also run seepubsub before ES.NET is available: it will periodically try to connect.
4. Start the JES region if necessary.
5. Start seepubsub, telling it to subscribe to your region and pass events to mfbsiemx:
   • seepubsub -verbose mfbinp://localhost:port mfbsiemx
     • where port is the MFBINP port (9022 if listener is self-hosted, 9122 if listener is running as a service and using the default configuration file).
6. seepubsub should indicate that it is subscribed to the region, and show a short information message. Clicking Enter will show the current state of the subscription (number of events delivered, etc).
7. You should see a file named "region.Started" (where region is the value of the ES_SERVER environment variable) in your MFBSI work directory.
8. Test MFBSI as described below.

Running seepubsub+MFBSI as a Windows service

This is the recommended production configuration.

1. Create your configuration file as described above.
2. Edit seepubsub.exe.config. Add a <subscription> element to the <subscriptions> section:
   • <subscription url="mfbinp://localhost:port" program="mfbsiemx"/>
     • where port is your MFBINP port (9022 for self-hosted listener, 9122 for service-hosted listener with default config). You can add other attributes if you want; they're all optional.
   • Set the environment variables described above in your system environment and reboot, or configure them in the subscription - environment section in the configuration file as described in seepubsub Configuration File.
   • Make sure that the exit binary is reachable by the service. Define the exits path in the System path environment variable, or define the exit using a fully qualified path in the configuration file.
     Note: Failure to do this results in the exit not working.
3. Install seepubsub as a service by running "seepubsub -i".
4. Start the seepubsub service ("net start seepubsub").
5. Start the Enterprise Server for .NET components if self-hosted.
6. Start the region if necessary.
7. Check that the region Started file has been created in your MFBSI work directory.
8. Test MFBSI as described in the next section.

Testing MFBSI

To see MFBSI in action, you can run mfbsijcl manually to have it submit a job, and then check the results. You can also execute it using a third-party scheduler.

In either case, the JCL source you wish to submit must be in the directory specified by the JCL-Submit directive in your MFBSI configuration file. You can use the JCLDEMO.JCL sample that comes with Enterprise Server (located in \etc\SEE\files\sysunder your product installation directory).

Running mfbsijcl manually

1. Run "mfbsijcl jcl-name". For example, if you're using the same settings as the sample MFBSI configuration file shown above, and you're submitting JCLDEMO.JCL, this would just be "mfbsijcl JCLDEMO".
2. mfbsijcl should not exit until the job has ended and MFBSI has retrieved the job log.
3. When it does exit, check the exit code with "echo %ERRORLEVEL%". It is 0 if the job ran successfully.
4. Look in the MFBSI work directory for a file named JOBnumber.log. Check that it contains the JES log for the job.