Micro Focus Enterprise Server for .NET

Welcome to Enterprise Developer

  • Introduction to Enterprise Server for .NET
  • System Architecture
  • Quick Start

Featured Sections

  • Administrator Role
  • Deployment
  • Development Role
  • Windows Azure Support
  • Enterprise Server for .NET Glossary

Online Resources

  • Micro Focus Infocenter
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Community Forums
  • Micro Focus Training Store

Provide Feedback

  • Email us feedback regarding this Help
  • Role-based Contents - Introduction
  • Windows Azure Support
  • Enterprise Server for .NET Glossary
Related concepts
Introduction to Enterprise Server for .NET
System Architecture
Quick Start


Role-based Contents - Introduction

This role-based table of contents is intended to enable you to find content specific to your role. For example, as a systems administrator you might be interested only in topics that relate to systems setup and management, but have no interest in what a developer needs to know.

The following role-based content is available to you.

  • General Information for all Roles
  • Administrator Role
  • Deployment
  • Development Role
Parent topic: Micro Focus Enterprise Server for .NET


General Information for all Roles

All users should read the following sections. They contain topics that are important for all roles.

Note: This documentation set is generic to the Enterprise Server for .NET product that is shipped with both Enterprise Developer for Visual Studio 2010 and Visual Studio 2012, and Enterprise Server. For the sake of simplicity and readability, when referring to paths, product names, start menu structures etc, the Enterprise Developer ones are used. If you are reading this documentation with other variants of the product, please substitute the appropriate paths and start menu structures. The paths etc are almost identical, differing only in the product name.
  • Introduction to Enterprise Server for .NET
  • System Architecture
  • Quick Start
  • Error Messages
Parent topic: Role-based Contents - Introduction


Introduction to Enterprise Server for .NET

Enterprise Server for .NET lets you run emulated mainframe CICS and JCL applications as .NET managed code. You can use it on a single system, in a scale-out configuration where work is spread out amongst multiple machines, or in the Microsoft Azure cloud infrastructure.

With Enterprise Server for .NET, emulated CICS and JES regions are not tied to a single machine instance. Region and task state, and optionally, program modules and VSAM data are stored in Microsoft SQL Server databases, while transaction processing is handled by worker processes running under the Windows Process Activation Service and the Windows Service Manager, or as Azure worker roles.

Enterprise Server for .NET is a flexible, highly scalable, and highly available solution for migrating mainframe applications to the Microsoft .NET platform.

Parent topic: General Information for all Roles


System Architecture

The diagram below details the main components in an Enterprise Server for .NET implementation.

Figure 1. Enterprise Server for .NET product architecture

The components in an implementation can operate on separate machines. You can expand an implementation's processing and storage capacity by scaling out, or simply adding more machines.

When scaling out, the listener, dispatcher and SEP can operate on different machines. Each machine that has a dispatcher and/or SEP requires an event monitor service. A machine that just runs a listener does not require an event monitor service.

  • Operating Components
  • Processing Event Sequence - CICS
  • Processing Event Sequence - JES
  • System Architecture Options
  • Detailed Architecture
Parent topic: General Information for all Roles


Operating Components

An Enterprise Server for .NET deployment has the following operating components:

  • The WCF/WAS Operating Environment
  • Region Databases
  • Cross-region Database
  • Listener
  • Dispatcher
  • Service Execution Process (SEP)
  • Event Monitor
Parent topic: System Architecture


The WCF/WAS Operating Environment

Apart from the database components, the Enterprise Server for .NET components operate as a collection of Windows Communication Foundation (WCF) services. Some are self-hosted Windows service programs, and others run under Windows Activation Service (WAS).

WCF is a part of the Microsoft .NET Framework. WAS is a mechanism for hosting .NET WCF services under IIS. It provides a ServiceHost and manages AppDomains for the service code.

The components that run as self-hosted services are:

  • Event Monitor
  • Communications Listener

The components that run under WAS are:

  • Dispatcher
  • Service Execution Processes (SEPs)
Note: Enterprise Server for .NET includes the wassetup command to configure IIS and WAS. You can run this script from a command line after you install the software, or whenever you want to ensure that IIS and WAS are in the correct configuration states.

From the Windows Services display, you can view the status of the Event Monitor and the Listener components, available from the Administrative Services window.

Figure 1. Server EE Listener Service Running Under WCF
Note: You can run all of the Enterprise Server for .NET components in self-hosted mode. To do this, use the command line functionality rather than the user interface to start the component.
Parent topic: Operating Components


Region Databases

A region database maintains the operating details for the region.

Each region in your installation has a corresponding Microsoft SQL Server or Server Express database. That is, a separate database is created for each region that you configure. Within your installation, these databases can run either in the same SQL Server instance, or on a scaled-out installation, in different SQL Server instances running on different machines.

A region database maintains details of:

  • the sessions running in the region
  • the request queue
  • resource definitions
  • transaction classes
  • any resource locks that are applied
  • console messages
  • scheduled tasks, that is tasks that are scheduled using the START API

You can also locate the applications that the region uses in the region database. For example, map files and assemblies.

Parent topic: Operating Components


Cross-region Database

A cross-region database is used by regions in the same database server instance to coordinate operations between these regions. Only one cross-region database is associated with each database server instance.

A cross-region database manages:

  • system-wide resource locks
  • system-wide DB-hosted file locks
  • event monitor registration
  • firing events to event monitors for scheduled task timer expiry

You can locate region and resource definitions in the cross-region database, as well as the map files and assemblies that regions in your installation use.

Parent topic: Operating Components


Listener

A listener provides a communication channel for clients (such as 3270 emulators, or batch submission) to a CICS or JES region.

It is configured to provide one or more channels to a region or regions. Each channel is associated with a TCP port, a protocol (such as TN3270 or MFBINP), and a CICS or JES region name.

A client, such as a 3270 emulator, connects to the port for an appropriate channel. The listener does any work needed to set up the conversation. It then connects to the dispatcher to establish contact with the region. A listener can also connect directly to SEPs.

The listener listens for input from both the clients and the SEPs to which it is connected. It forwards input from the clients to the region for processing, and it sends responses from the SEPs back to the clients.

A listener can be started as either a Windows service or a Windows console application. When the dispatcher and SEP are hosted under IIS, the listener is normally run as a Windows service. When the dispatcher and SEP are self-hosted, it is normally run as a Windows console application. The -was command line option determines whether the listener communicates with an IIS-hosted or self-hosted dispatcher.

A listener forwards new client sessions and client input to a dispatcher, and receives responses from a SEP to send back to the client. A dispatcher can also send a response back to a client via the listener. For example, in the case of a CICS session, it can free up the keyboard if the Clear key is pressed and no next transaction is associated with the session, or send an error response when the region isn't started.

Parent topic: Operating Components


Dispatcher

The dispatcher is the service responsible for queuing client requests received from a listener, and dispatching requests to available SEPs.

At the start of a session, the dispatcher registers the client session with the Regions database.

A dispatcher indirectly queues requests received from the listener by invoking a stored procedure in the region database. The stored procedure determines whether there is a SEP available to dispatch the next queued request with the highest priority (which might be a different request from the one just queued). If a SEP is available, the stored procedure returns the ID of the request to be dispatched to the dispatcher. The dispatcher then invokes the SEP service with this request ID. If no SEP is available, the stored procedure indicates this to the dispatcher and no SEP service is invoked.

When no SEP is available for dispatch, it means that the maximum number of SEPs configured for the region are currently running tasks.

A dispatcher service can be either self-hosted within a seedispatch.exe process, or WAS-hosted within a w3wp.exe process.

  • Advanced Dispatcher Information
Parent topic: Operating Components


Advanced Dispatcher Information

When a task completes, the SEP that was running it invokes a stored procedure to remove the request that has just completed from the request queue, and get the next available request to execute (i.e. it is not the dispatcher that waits until a SEP becomes available to dispatch the next request, it is a running SEP that pops the next available request off the request queue).

The output from this request is sent directly from the SEP to the listener. If the response from the SEP is at the end of a task, the next client input for the same session will be routed to the dispatcher by the listener (that is, treated as a new request). If the response from the SEP is during task execution, the next client input for the same session will be routed directly to the SEP running the task by the listener.

A dispatcher can also be invoked by an event monitor to dispatch a scheduled task. A scheduled task gets created as a result of the START API. A timer is associated with a scheduled task. That is, the START API allows you to start a new task either at some time in the future, or immediately. When this timer expires, an event is posted by the cross-region database which gets picked up by an event monitor process. The event monitor invokes a dispatcher service passing it information about the scheduled task. The dispatcher builds and queues a request for the scheduled task in much the same way as it queues a request from a listener process.

Parent topic: Dispatcher


Service Execution Process (SEP)

A SEP is a container inside which a CICS transaction or a JES program runs.

In Enterprise Server for .NET, SEPs operate as discrete application domains rather than as processes, to keep SEPs isolated.

SEPs are hosted within a SEP pool.

A SEP pool is a collection of AppDomains.

Each SEP is responsible for the execution of a single request. When a request completes, the SEP is returned to the pool and made available for a subsequent request execution.

SEPs are removed from the pool if the SEP needs to be abended due to a timeout, or if the associated terminal disconnects.

SEPs can be self-hosted in seesep.exe processes, or WAS-hosted in w3wp.exe processes. WAS-hosted SEP processes are started on demand and periodically recycled by WAS.

Parent topic: Operating Components


Event Monitor

The event monitor is the seemonitor.exe Windows service process installed on machines that run dispatcher and/or SEP services.

An event monitor is responsible for:

  • providing administration and management functionality for the SEP and dispatcher services that run on the same machine as the monitor.
  • starting and stopping regions on the machine on which it is running.

Event monitors on different machines communicate with each other to perform specific tasks, such as:

  • internal transaction request (ITR) invocations that require coordination with SEPs that are running, or have run, tasks for a given CICS or JES region.
  • region shutdown.

A dispatcher, SEP or the user interface starts the event monitor (seemonitor service) on the local machine if it is not currently running. They automatically restart the event monitor if it is terminated for any reason.

Each SEP pool registers itself with its local event monitor when the pool is created.

Each region operating on a machine registers with the local event monitor the first time a request for the region is processed by a SEP.

The event monitor is notified when a registered SEP pool process terminates or IIS recycles a SEP pool.

Registered SEP pools are used by the event monitor to route ITRs, administration user interface monitoring, task-kill and region-shutdown requests.

Parent topic: Operating Components


Processing Event Sequence - CICS

The sequence of events depends on the event type.

  • The Establishing Communications sequence of events occurs when you first connect to an Enterprise Server for .NET CICS region, for example to display the opening screen.
  • The Input Transactions sequence of events occurs when you input a transaction from your 3270 session.
  • The Scheduled Transactions sequence of events occurs when a process is triggered by a timer.
  • Processing Event: Establishing Communications
  • Processing Event: Input Transactions
  • Processing Event: Scheduled Transactions
Parent topic: System Architecture


Processing Event: Establishing Communications

This is the sequence of events that occurs when you configure an Enterprise Server for .NET session. For example, when you connect a TN3270 client to the listener, the following sequence occurs:

  1. The listener conducts Telnet and TN3270 negotiations with the client to establish communications.
  2. The listener contacts the dispatcher and requests a session.
  3. The dispatcher notifies the region database to set up a session.
  4. The session starts, and details are returned to the dispatcher.

    The Enterprise Server for .NET auto-install system transaction is invoked to install the terminal in the region and generate the initial screen.

  5. The dispatcher forwards the initial screen to the 3270 terminal.
Parent topic: Processing Event Sequence - CICS


Processing Event: Input Transactions

When you input a transaction, the following sequence of events occurs:

  1. You enter a transaction into your 3270 emulator. The listener submits the request to the dispatcher.
  2. The dispatcher sends the request to the transaction queue on the region database.

    The region database determines the SEP that is available to process the request.

  3. The region database forwards the processing SEP details back to the dispatcher.
  4. The dispatcher tells the SEP to get the request from the region database.
  5. The SEP retrieves processing details from the region database and begins processing.
  6. While this is happening, the dispatcher sends any subsequent transactions to the region database where they are queued on the request queue.
  7. When the SEP finishes processing the initial transaction, it sends the output to the listener, which then sends the response to the 3270 emulator.

    The SEP checks the request queue on the region database for details of any more transactions to process.

    The SEP processes any subsequent transactions that the dispatcher has placed on the region database request queue, and sends the output to the listener.

    When there are no more transactions to be processed, the SEP returns to the SEP pool and becomes available for further processing.

Parent topic: Processing Event Sequence - CICS


Processing Event: Scheduled Transactions

When the region database triggers a scheduled transaction, the following sequence of events occurs:

  1. The scheduled transaction is triggered in the region database, which then notifies the cross-region database of the transaction request.
  2. The cross-region database sends the transaction details to the event monitor.
  3. The event monitor retrieves the transaction details from the region database.
  4. The event monitor forwards the transaction details to the dispatcher.
  5. The Dispatcher sends the request to the transaction queue on the region database, which handles SEP processing of the transaction.

    From this point onwards, the scheduled transaction behaves in the same way as an input transaction.

Parent topic: Processing Event Sequence - CICS


Processing Event Sequence - JES

Submitting a batch job for execution is broken into two sequences for the sake of clarity:

  • Job Submission Sequence
  • Job Execution Sequence
Parent topic: System Architecture


Job Submission Sequence

This is the basic sequence of events that is followed when a job is submitted into a JES batch region.

  1. The JCL job is submitted to the listener on the MFBINP port associated with the target region from one of the following tools:
    1. Cassub.exe
    2. The administration GUI
    3. A scheduler using the public API interfaces
  2. The listener receives the job and sends it to the dispatcher.
  3. The dispatcher queues the submission request.
  4. Either the dispatcher tells a SEP to retrieve the job or a SEP picks up the request automatically if it is busy.

    The SEP parses the job doing all the prerequisite checks.

  5. If the job is successfully parsed, the job is queued for execution.
  6. The listener is sent the appropriate good or bad response which is returned to the client.
  7. The event monitor is notified that a job is ready for execution.

At this point the submission process is complete.

Parent topic: Processing Event Sequence - JES


Job Execution Sequence

This is the basic sequence of events that occurs for job execution.

This assumes that a job has been submitted and gone through the job submission process described in the previous topic.

  1. The Event Monitor is made aware that a job is available for execution. It notifies the dispatcher.
  2. The dispatcher checks for an available initiator.
  3. If an available initiator is found, a SEP is told to retrieve the job. If no initiator is found, the job remains queued.
  4. The SEP retrieves the job and executes it.
Parent topic: Processing Event Sequence - JES


System Architecture Options

Enterprise Server for .NET installations have three primary architecture configuration options:

  • A single machine running Microsoft SQL Server or Server Express, and the Enterprise Server for .NET software.
  • Multiple non-clustered machines using a single Microsoft SQL Server. Each machine uses the same Microsoft SQL Server installation.
  • Multiple clustered machines using a single Microsoft SQL Server.

    This configuration increases capacity by scaling out an installation. See the section on scaling out an Enterprise Server for .NET configuration.

You can also configure multiple non-clustered machines with different Enterprise Server for .NET components. For example, you can have a number of listener machines and a number of processing machines. The listener machines do not perform any processing other than running the listener.

  • Single Machine Architecture
  • Multiple Machine Architecture
  • Scale Out Architecture
Parent topic: System Architecture


Single Machine Architecture

In this architecture, both the Enterprise Server for .NET and Microsoft SQL Server database software components are installed on a single machine. SEPs created during processing are created on the machine.

This architecture is used primarily for developing applications. It is also useful for testing the installation process, and becoming familiar with the environment.

Parent topic: System Architecture Options


Multiple Machine Architecture

In this architecture, the Enterprise Server for .NET components are installed on separate machines. Each machine uses the same Microsoft SQL Server database server. With this setup:

  • Each machine can create new regions, and access the existing regions defined in the region database.
  • When a machine initiates a process, the SEP is created on that machine.

Parent topic: System Architecture Options


Scale Out Architecture

A scale out architecture involves running an Enterprise Server for .NET installation across multiple machines.

An installation is scaled out using clustering. All machines in the cluster use a single Microsoft SQL Server to store the installation's operating records.

Different options are available for clustering. See the section on scaling out an installation for more information.

Parent topic: System Architecture Options


Detailed Architecture

Enterprise Server for .NET regions can run in self-hosted or WAS-hosted modes. User applications run within Application Domain threads in a process named SEESEP.EXE for self-hosted mode, or the W3WP.EXE worker process in WAS-hosted mode.

When you debug an application executing within a specified region, a special debug SEESEP.EXE process is created when you start debugging from the Visual Studio IDE.

This SEP registers itself to a specific region, and does not run in a region-agnostic mode as normal SEPs do. The SEP processes only those requests that match the criteria specified in the debug properties of the project.

In whichever mode the region is started, with or without debug support, the applications are monitored in a similar way providing support for CICS timeouts, for example.

  • SEP Pool Layout Architecture
Parent topic: System Architecture


SEP Pool Layout Architecture

Parent topic: Detailed Architecture


Quick Start

In this section you will verify an installation by running both CICS and JCL transactions within a sample region.

  • Installing and Verifying the Software
Parent topic: General Information for all Roles


Installing and Verifying the Software

These topics describe how to configure your system, install the software, and verify that it is operating as it should.

Note:
  • When you re-install the software or install a new version of the software, changes that you have made to the default configuration files are not overwritten. The installation process does, however, install copies of the default configuration files which you can use if you need to recover the default setup. These are installed in the following location:

    • 32-bit systems:

      %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE

    • 64-bit systems:

    • %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE

  • When you install a new version of the software, you can use the upgrade utility so that your region and resource definition files can use any new functionality that the upgrade provides.
  • Setting Up the Operating Environment
  • Installing Enterprise Server for .NET
  • Upgrading from an Earlier Version
  • Verifying the Installation
  • Supplied Samples and Configuration Files
Parent topic: Quick Start


Setting Up the Operating Environment

An Enterprise Server for .NET installation can operate in the following environments:
  • Operating systems:
    • Windows 7 or later
    • Windows Server 2008 R2 or later

    You need to install the additional Windows features on these platforms.

  • IIS with selected additional Windows features
  • Microsoft .NET Framework 4.0
The following application software and Windows features need to be in place:
  • Microsoft SQL Server 2008 R2 or later. For beta or development installations, SQL Server Express 2008 R2 or later is sufficient.

    This can be downloaded from The Microsoft SQL Server download site http://www.microsoft.com/en-us/sqlserver/get-sql-server/try-it.aspx

  • If you are developing applications:
    1. Microsoft Visual Studio 2010® or Microsoft Visual Studio 2012.
    2. Micro Focus Enterprise Developer.

  • 3270 terminal emulator, for example Rumba.
  • Additional Windows features:

    From Control Panel > Programs and Features > Turn Windows features on or off, select the following:

    • Internet Information Services
      • Web Management Tools:
        • IIS 6 Management Compatibility (select all available features)
        • IIS Management Console
        • IIS Management Scripts and Tools
        • IIS Management Service
      • World Wide Web Services:
        • Application Development Features:
          • .NET Extensibility
          • ASP.NET
      • Common Http Features: Add all available features
      • Health and Diagnostics: Add all available features
      • Security:
        • Basic Authentication
        • Windows Authentication
    • Microsoft .NET framework 3.5.1
      • Windows Communication Foundation HTTP Activation
      • Windows Communication Foundation Non-HTTP Activation
  • TCP port sharing

    Start the TCP port sharing service. The wassetup command used to configure the environment after installation now implicitly enables and starts the TCP port sharing service.

    See help topics on how to enable and configure the NET.TCP port sharing service, for further information.

  • To Activate Windows and IIS Components
  • To Install Additional Features on a Windows 2008 Server
  • To Install Additional Features on a Windows 2012 Server
Parent topic: Installing and Verifying the Software


To Activate Windows and IIS Components

To activate the Windows and IIS components that Enterprise Server for .NET requires:
  1. From the Control Panel, open Programs and Features.
  2. In the left panel, select Turn Windows features on or off.
  3. Ensure that the necessary features are activated. See Setting Up the Operating Environment for more details.
After you install Enterprise Server for .NET, you need to run the wassetup command.
Parent topic: Setting Up the Operating Environment


To Install Additional Features on a Windows 2008 Server

  1. From the Control Panel, open Programs and Features.
  2. In the left panel, select Turn Windows features on or off.
  3. In the Tree pane, expand the Roles item.
  4. If the Web Server (IIS) role is not listed:
    1. In the Results pane, click Add Roles to display the Add Roles Wizard.
    2. In the Tree pane, click Server Roles.
    3. In the dialog that is displayed, select Web Server (IIS) and click Next to display the Web Server (IIS) dialog.
    4. Click Next to display the Select Role Services dialog.
  5. If the Web Server (IIS) role is listed, in the Results pane, click Add Role Services.
  6. In the Select Role Services dialog:
    • Under Management tools, select:
      • IIS Management Console
      • IIS Management Script and Tools
      • IIS Management Service
      • IIS 6 Management Compatibility (select all available features)
    • Under Application Development select:
      • .NET Extensibility
      • ASP .NET
    • Under Common Http Features, select all available features.
    • Under Health and Diagnostics, select all available features.
    • Under Security, select:
      • Basic Authentication
      • Windows Authentication
  7. Add the Windows Process Activation and its children.
  8. Click Install.
  9. When the installation completes, click Close.
  10. In the Tree pane, click Features, and in the Results pane, click Add Features.
  11. In the Add Features Wizard:
    1. Under .NET Framework 3.5.1 Features, select all available features.
    2. Click Next to display the Confirm Installation Selections dialog.
    3. Click Install. Wait for the installation to complete, and then click Close.
Parent topic: Setting Up the Operating Environment


To Install Additional Features on a Windows 2012 Server

To operate Enterprise Server for .NET on a Windows 2012 server, you need to install additional Windows features that are supplied with the installation software.
  1. Open the Server Manager and select local server - Add roles and Features.
  2. Add the Web Server ( IIS) role with the following, making sure that the Application development role is installed:
    • Under Common Http Features, select all available features.
    • Under Health and Diagnostics, select all available features.
    • Under Security, select:
      • Basic Authentication
      • Windows Authentication
    • Under Application Development select:
      • .NET extensibility 3.5
      • .NET extensibility 4.5
      • Application initialization
    • Under Management tools, select:
      • IIS management Console
      • IIS 6 Management (select all available options )
  3. Add the Windows Process Activation Service feature, and all its children.
  4. Add the .NET Framework 4.5 features to include
    • Named Pipe Activation
    • TCP Activation
    • TCP Port Sharing
Parent topic: Setting Up the Operating Environment


Installing Enterprise Server for .NET

Enterprise Server for .NET is installed by and requires Micro Focus Enterprise Developer.

Note: After installing Enterprise Server for .NET, you must configure WAS and IIS support. To do this, run the configuration command from an Enterprise Developer command prompt.
  • To Run the Installation Software
  • To Configure IIS and WAS Support
  • Default Installation Paths
Parent topic: Installing and Verifying the Software


To Run the Installation Software

Your system must have the required prerequisite software installed and configured, and the operating environment configured.
  1. Locate and start the Micro Focus Enterprise Developer installation program.
  2. Follow the prompts to install the software on your computer.

You must run the command to configure IIS and WAS support before using Enterprise Server for .NET.

Parent topic: Installing Enterprise Server for .NET


To Configure IIS and WAS Support

Enterprise Server for .NET includes the command wassetup.cmd. This command configures IIS and WAS. Run this command after installing Enterprise Server for .NET.

Note: You can run all of the Enterprise Server for .NET components in self-hosted mode. To do this, use the command line functionality rather than the user interface.

To run the command:

  1. From the Windows Program menu, select Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt.
  2. Enter the following command in the command prompt.
    wassetup
  3. Press Enter.

    Messages indicate its progress as it configures IIS and WAS.

The IIS and WAS environments are now configured correctly for Enterprise Server for .NET.
Parent topic: Installing Enterprise Server for .NET


Default Installation Paths

The default paths where the Enterprise Server for .NET program files are installed are as follows:

Item | Path
Product installation root. | 32 bit: %ProgramFiles%\Micro Focus\Enterprise Developer 64 bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer
System configuration files. The read-only master resource definition and ESDEMO region startup files reside here. | 32 bit: %ProgramFiles%\Micro Focus\Enterprise Developer\etc\SEE\files\sys 64 bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\files\sys
Product help. | %ProgramFiles%\Micro Focus\Enterprise Developer\help\SEE
System executables. Each of the .exe files has a corresponding .exe.config file. The listener configuration file, seelistener.exe.config, resides here. | 32 bit: %ProgramFiles%\Micro Focus\Enterprise Developer \binAnyCPU\SEE 64 bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE
System WAS/IIS installation files. | 32 bit: %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE\WAS 64 bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE\WAS
Default resource definition and ESDEMO region startup files. These files can be modified. Modifications are retained if product is uninstalled/reinstalled. | %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config
CICS samples (ACCT, MFAIEXIT, SQLEXIT, …) | %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet
Location of data files created by CICS if a Data location is not specified in a region’s startup file. | %APPDATA%\Micro Focus\SEE\2.2\Data
Parent topic: Installing Enterprise Server for .NET


Upgrading from an Earlier Version

When upgrading Enterprise Server for .NET from a previous version, you can run the upgrade utility to re-configure existing configuration files. After re-configuring, configuration files can use any new functionality that the upgrade delivers. Use an Enterprise Developer command prompt to run the upgrade utility.

  • To Upgrade Definition Files after an Upgrade
  • To Upgrade a Resource Definition File in the Cross-region Database
Parent topic: Installing and Verifying the Software


To Upgrade Definition Files after an Upgrade

The software upgrade must be installed before using this procedure.

Use this procedure to upgrade region and resource definition files after a software upgrade.
  1. Open an Enterprise Developer command prompt.
  2. Type seeupgrade to upgrade the definition files. Press Enter.
As with all configuration file changes, you must re-start the region before any changes take effect.
Parent topic: Upgrading from an Earlier Version


To Upgrade a Resource Definition File in the Cross-region Database

For region definition files deployed to the cross-region database:

  1. Use the seedeploy utility to extract the resource definition file from the cross-region database.
  2. Use the seeupgrade utility to upgrade the extracted file.
  3. Use the seedeploy utility to re-load the upgraded resource definition file back to the cross-region database.
Parent topic: Upgrading from an Earlier Version


Verifying the Installation

Enterprise Server for .NET includes sample region configurations that you can load and use to test the installation. CICS support can be verified using the sample ESDEMO region, and JES support using the sample JCLDEMO region.

The verification process described in this help assumes that this is the first time the Enterprise Server for .NET Administration UI is configured and Enterprise Server for .NET started.

  • To Set Up and Start the User Interface for the First Time
  • Verifying A CICS Region
  • Verifying a JES Region
Parent topic: Installing and Verifying the Software


To Set Up and Start the User Interface for the First Time

The Enterprise Server for .NET user interface is provided as a Microsoft Management Console (MMC) snap-in. When you start the user interface, the MMC opens and loads the snap-in.
Note: When starting the user interface the first time after either installing the product, a re-boot, or applying operating system updates, run the wassetup command. This command configures IIS and WAS if required, and ensures that all required services are running. This procedure includes the details.
  1. From the Windows Start menu, click Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt.
    Note: 64 bit systems have a 32-bit and a 64-bit command prompt available. It does not matter which one you use to run the wassetup command.
  2. At the command prompt, type wassetup and click Enter to run the command with the default -i parameter.

    Messages show the command's progress. When the command completes, the command window displays the message Operation successfully completed.

  3. From the Windows Start menu, click Micro Focus Enterprise Developer > Enterprise Server for .NET > SEE Administration.

    The MMC starts with the Enterprise Server for .NET snap-in loaded.

Parent topic: Verifying the Installation
Parent topic: Setting Up the User Interface


Verifying A CICS Region

The topics in this section describe how to create and start the sample ESDEMO CICS region and how to connect a 3270 terminal to it to run transactions.

  • To Create the Demonstration CICS Region
    This topic describes how to define the sample CICS region named ESDEMO to the Enterprise Server for .NET Administration UI.
  • To Start the Demonstration CICS Region
    This topic explains how to start the sample CICS region named ESDEMO from the Enterprise Server for .NET Administration UI.
  • To Configure and Start the Listener for the ESDEMO Region
    This topic explains how to configure the listener ports for the ESDEMO region and how to start the seelistener service using this configuration from the Enterprise Server for .NET Administration UI.
  • To Connect a 3270 Client to the ESDEMO Region and Run a Sample Transaction
    This topic explains how to connect a 3270 client to the ESDEMO region and run the sample ACCT transaction.
  • To Run the CICS Installation Verification Procedure
    This topic walks you through the sample account transaction.
Parent topic: Verifying the Installation


To Create the Demonstration CICS Region

Follow the instructions in To Define a New Region specifying ESDEMO as the region name and %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config\Region_ESDEMO.config when prompted to enter the location of the region's startup file.
Parent topic: Verifying A CICS Region
Related tasks
To Define a New Region With an Existing Region Startup File


To Start the Demonstration CICS Region

  1. In the Tree pane under CICS->Regions, select the ESDEMO region.
  2. In the Actions pane, click Start/Stop Region.

    The Start button appears at the bottom of the Results pane, along with the Cold Start and Warm Start options.

  3. At the bottom of the Results pane, ensure that the Cold Start option is selected. Click Start.

    Output from the start process appears in the Results pane. Details for any errors that occur are displayed here.

    The start process generates messages to show the progress, and confirm that the region starts. Once the region starts, it is available to handle 3270 terminal connections.

The region is now running and is available for use.
Parent topic: Verifying A CICS Region


To Configure and Start the Listener for the ESDEMO Region

The default listener configuration file installed with the product includes a TN3270 port configuration for the ESDEMO region specifying port 9023. This is the port that a 3270 client such as Rumba would use to connect to the region. You only need to configure the database server details to use this listener with the ESDEMO region.

Note: Stopping and re-starting the seelistener service starts the listener with the latest configurations.

Use the following procedure to configure and start the listener for the ESDEMO region:

  1. In the Tree pane, choose Configuration Editors > Listener . See 1 in the diagram below. The Listener Configuration Editor view is displayed in the Results pane.
  2. Select the File Open icon. See 2 in the diagram below.

    The standard Open File dialog opens.

  3. From the Open File dialog, navigate to the product installation folder where the file seelistener.exe.config resides, select it and click Open. See 3 in the diagram below.
    • For 32-bit systems, this file is in %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE
    • For 64-bit systems, this file is in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE

    The configuration file opens in the Listener Configuration Editor in the Results pane.
  4. In the Listener Configuration Editor, expand the Regions item and select the ESDEMO region. See 4 in the diagram below.
  5. Enter your database server instance name in the value field associated with the Database server instance property. See 5 in the diagram below.

  6. Expand the ESDEMO region node and verify that there are two child nodes: MFBINP and TN3270. Select the TN3270 node and verify that the Port property value is 9023. See 6 in the diagram below. This is the port that you will need to configure for your TN3270 emulator to allow it to connect to the region.
  7. Choose File > Save, or click the Save icon in the toolbar to save the file. See 7 in the diagram below.
  8. Choose Options > Start Listener, or click the Start Listener icon in the toolbar to start the listener. See 8 in the diagram below.
    Note: If the listener is already started, you must stop it and then re-start it for your configuration changes to take effect.

The listener is started and is available to receive TN3270 client connections for the ESDEMO region.
Parent topic: Verifying A CICS Region


To Connect a 3270 Client to the ESDEMO Region and Run a Sample Transaction

This procedure describes how to use Rumba terminal emulation software to connect to the demonstration region. However, you can use any suitable TN3270 emulator to connect to the ESDEMO region.
  1. Start the Rumba mainframe display.
  2. From the Connection menu, choose Configure.

    The Connection Configuration dialog box appears.

  3. On the Connection Configuration dialog box, click the TN3270 tab, and in the Telnet Port area, select User Defined and type the port number configured for the listener, for example 9023. Click OK.
  4. From the Connection menu, choose Connect.

    The emulator connects to the region.

  5. Clear the screen, and type acct. Press Enter to run the sample account transaction.

    The account transaction's initial screen appears.

This verifies that the Enterprise Server for .NET installation is successful.
Parent topic: Verifying A CICS Region


To Run the CICS Installation Verification Procedure

This procedure runs the installation verification. This is done after configuring and starting the enterprise server and connecting to it with a 3270 emulator. When you first connect, a Welcome screen displays.

Perform the following steps to verify the installation.

  1. Press Clear (3270 key).

    The display clears.

  2. Type the following command, then press Enter.
    CFCR ACCTFIL

    The following messages display.

    Base - ACCTFIL KSDS Key 1 for 5 VARIABLE 63 to 383
ACCTIX     ALTR   Key    6 for   12

CFCR - File successfully created
  3. Press Clear (3270 key).

    The display clears.

  4. Type the following command, then press Enter.
    acct

    The following screen appears.

    Figure 1. Running the Installation Verification Procedure
    Running the Installation Verification Procedure

    You can now add a record to the demonstration account file.

  5. Press Tab until the cursor is positioned in the field immediately following the label REQUEST TYPE.
  6. Type A. The cursor automatically moves ahead to the ACCOUNT field.
  7. Type 22222 then press Enter.
  8. Fill in the fields as follows:
    Field | Value
    SURNAME | SMITH
    FIRST | JOHN
    MI | S
    TITLE | MR
    TELEPHONE | 501234
    ADDRESS (1) | 59 THE COURT
    ADDRESS (2) | WOODED AVENUE
    NO. CARDS ISSUED | 1
    DATE ISSUED | 03 04 98
    REASON | N
    CARD CODE | X
    APPROVED BY | GGC

    Other fields are optional and can be left blank.

  9. Press Enter.
  10. Display the record you have just entered by typing SMITH into the SURNAME field and pressing Enter.
  11. Press Clear (3270 key).

    The display clears.

  12. Type exit and press Enter to disconnect the 3270 emulator.
Parent topic: Verifying A CICS Region


Verifying a JES Region

The topics in this section describe how to create and start the sample JCLDEMO JES region, and how to submit jobs to it and view their outputs.

  • To Create the Demonstration JES Region
    This topic describes how to define the sample JES region named JCLDEMO to the Enterprise Server for .NET Administration UI.
  • To Start the Demonstration JES Region
    This topic explains how to start the sample JES region named JCLDEMO from the Enterprise Server for .NET Administration UI.
  • To Configure and Start the Listener for the JCLDEMO Region
    This topic explains how to configure the listener ports for the JCLDEMO region and how to start the seelistener service using this configuration from the Enterprise Server for .NET Administration UI .
  • To Run the JES Installation Verification Procedure
    This topic demonstrates how to use the Enterprise Server for .NET Administration UI to submit jobs to the JCLDEMO region, view the job outputs in the spool view and view datasets created by the jobs in the catalog view.
Parent topic: Verifying the Installation


To Create the Demonstration JES Region

Follow the instructions in To Define a New Region specifying JCLDEMO as the region name and %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config\Region_JCLDEMO.config when prompted to enter the location of the region's startup file.
Parent topic: Verifying a JES Region
Related tasks
To Define a New Region With an Existing Region Startup File


To Start the Demonstration JES Region

  1. In the Tree pane under JES->Regions, select the JCLDEMO region. See 1 in the diagram below.
  2. In the Actions pane, click Start/Stop Region. See 2 in the diagram below.

    The Start/Stop Region view appears in the Results pane.

  3. At the bottom of the Results pane, ensure that Cold Start is selected and then click on Start. See 3 in the diagram below.

    Messages are now displayed to show the progress of the region startup process. A final confirmation message is displayed to indicate that the region has successfully started. See 4 in the diagram below.

The region is now available for job submission.
Parent topic: Verifying a JES Region


To Configure and Start the Listener for the JCLDEMO Region

The default listener configuration file installed with the product includes an MFBINP port configuration for the JCLDEMO region specifying port 9122. This is the port used for job submission to the region from the Enterprise Server for .NET Administration UI or cassub command-line utility. You only need to configure the database server details to use this listener with the JCLDEMO region.

Note: Stopping and re-starting the seelistener service starts the listener with the latest configurations.

Use the following procedure to configure and start the listener for the JCLDEMO region:

  1. In the Tree pane, choose Configuration Editors > Listener . See 1 in the diagram below. The Listener Configuration Editor view is displayed in the Results pane.
  2. Select the File Open icon. See 2 in the diagram below.

    The standard open file dialog opens.

  3. From the open file dialog, navigate to the product installation folder where the file seelistener.exe.config resides, select it and click Open. See 3 in the diagram below.
    • For 32-bit systems, this file is in %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE
    • For 64-bit systems, this file is in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE

    The configuration file opens in the Listener Configuration Editor in the Results pane.
  4. In the Listener Configuration Editor, expand the Regions item and select the JCLDEMO region. See 4 in the diagram below.
  5. Enter your database server instance name in the value field associated with the Database server instance property. See 5 in the diagram below.

  6. Expand the JCLDEMO region node and verify that there is an MFBINP child node. Select the MFBINP node and verify that the Port property value is 9122. See 6 in the diagram below. This is the port that will be used by the Enterprise Server for .NET Administration UI and cassub command-line utility for job submission to the region.
  7. Choose File > Save, or click the Save icon in the toolbar to save the file. See 7 in the diagram below.
  8. Choose Options > Start Listener, or click the Start Listener icon in the toolbar to start the listener. See 8 in the diagram below.
    Note: If the listener is already started, you must stop it and then re-start it for your configuration changes to take effect.

The listener is started and is available to receive job submission requests for the JCLDEMO region.
Parent topic: Verifying a JES Region


To Run the JES Installation Verification Procedure

The JCLDEMO region must be started, and the listener configured and running to accept job submission requests for the region. See the following topics to do this:
  • To Create the Demonstration JES Region
  • To Start the Demonstration JES Region
  • To Configure and Start the JCLDEMO Region's Listener Ports
  1. In the Tree pane under JES->Regions, select the JCLDEMO region. See 1 in the diagram below.
  2. In the Actions pane, click Submit JCL. See 2 in the diagram below.

    The Submit JCL view appears in the Results pane.

  3. In the Submit JCL to JES entry field, enter the fully-qualified name of the sample JCLDEMO.JCL file that will have been installed with the product. You may want to use the Browse button to navigate to this file in the file system.
    • For 32-bit systems, this file is in %ProgramFiles%\Micro Focus\Enterprise Developer\etc\SEE\files\sys
    • For 64-bit systems, this file is in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\files\sys
  4. Ensure that JES2 is selected as the JCL submission type and then click on Submit. See 3 in the diagram below.

    The selected JCL file is submitted to the JCLDEMO region. Messages are now displayed to show the progress of the job submission. A final confirmation message is displayed to indicate that the job has been successfully submitted and is ready for execution. See 4 in the diagram below.

  5. In the Actions pane, click View console. See 5 in the diagram below.

    The Console view is displayed. The last two messages displayed in the view indicate that the job was successfully submitted. There are no messages indicating that the job has gone into execution.

    The reason there are no messages indicating that the job has gone into execution is that the job that was submitted in the previous step was for class B and there are no class B initiators available to run it. There are 3 initiators configured in the JCLDEMO region startup file: 2 class A and 1 class ABC. However, the class ABC initiator is not enabled. The next step explains how to enable the class ABC initiator.

  6. In the Actions pane, click Initiators. See 6 in the diagram below.

    The Initiators view is displayed. Click on the check box next to the initiator named Init-ABC to enable it. See 7 in the diagram below.

  7. In the Actions pane, click View console to display the region's console again. Messages will now be displayed indicating that the job submitted earlier is now running. See 8 in the diagram below.

  8. In the Actions pane, click Spool to display the job log and sysout datasets. See 9 in the diagram below.

    The Spool view is displayed in the Results pane. The left-hand window in this pane lists the jobs that have been submitted to the region and indicates their state. When a job is selected in the left-hand window, its associated job log and sysout datasets are listed in the right-hand window. Double-click any of these to display their contents.

  9. In the Actions pane, click Catalog to display the datasets cataloged for the region. See 10 in the diagram below.

    The Catalog view is displayed in the Results pane. The view lists the datasets that have been cataloged for the region. When a dataset is selected, its attributes are displayed in the Properties window. Double-click a dataset to display its contents.

Parent topic: Verifying a JES Region


Supplied Samples and Configuration Files

The Enterprise Server for .NET installation routine installs default configuration files, sample code, and applications when isntalled as part of the development environment.

  • The sample files are installed in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet
  • The default configuration files are stored in %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config

The current software release contains the following:

  • Supplied Configuration Files - CICS
  • Sample: CICS ACCT Transaction
  • Sample - CICS BankDemo
  • Samples: SQL Server Connection String Exit Programs
  • Sample: Terminal Configuration Exit Program
Parent topic: Installing and Verifying the Software


Supplied Configuration Files - CICS

The following default configuration files are supplied with the installation software:

  • Region_ESDEMO.config

    This is the region configuration that the demonstration region uses.

  • ResourceDefinitions.config

    This is the resource configuration that the demonstration region uses.

By default, these are installed in %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config

Copies of these files, and the listener configuration file seelistener.exe.config, are installed in the following locations. You can use these files to recover the default installation settings if needed:

  • For 32-bit installations: %ProgramFiles%\Micro Focus\Enterprise Developer\etc\SEE\files\sys

  • For 64-bit installations: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer \etc\SEE\files\sys

Unlike the files in %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config, these copies are overwritten whenever the product is re-installed.
Note: The listener configuration file, seelistener.exe.config is overwritten by re-installs. You need to re-configure the listener after re-installing the software.

Parent topic: Supplied Samples and Configuration Files


Sample: CICS ACCT Transaction

This sample is the source for the CICS ACCT transaction. You can modify and re-compile this transaction, or compile it and use it as it is. The installation software includes a compiled version of this transaction for installation testing.

You can use the samples browser to locate this sample, or use the information below:

The ACCT sample is in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\ACCT.

How to Run the Demonstration

  • To run this demonstration in Visual Studio:
    1. Open ACCT.sln.
    2. Build the application.
    3. Follow the instructions in the Debugging Tutorial section of the Enterprise Server for .NET documentation for details of how to configure a CICS region to allow the ACCT application to be debugged.

The ACCT.sln solution contains one project ACCT.cblproj:

  • ACCT00.cbl

    The program associated with the ACCT transaction. It displays a menu screen for the on-line account file application, which prompts the user for input. Transaction AC01 is invoked when that input is received.

  • acct01.cbl

    The program associated with the AC01 transaction. Analyzes all requests, and completes those for name inquiries and record displays. For update transactions, it sends the appropriate data entry screen and sets the next transaction identifier to AC02, which completes the update operation. For print requests, it starts transaction AC03 to do the actual printing.

  • acct02.cbl

    The program associated with the AC02 transaction. It completes requests for account file updates (adds, modifies, and deletes), after the user entered the update information.

  • acct03.cbl

    The program associated with the AC03 transaction. It completes a request for printing of a customer record, which was processed initially by transaction AC01.

  • acct04.cbl

    The program associated with the AC04 transaction. It is a general purpose error routine that is invoked by other programs in the online account file application when an unrecoverable error has occurred. It sends a message to the input terminal describing the type of error and prompts the operator to report it. It then abends, resulting in any updates made in the uncompleted transaction being backed out.

  • ACCTMENU.CBL

    The program XCTLed by the AC01 transaction to display a menu.

  • acctset.bms

    The ACCT application's BMS mapset.

  • acctrec.cpy

    The record definition for the ACCTFIL file used by the application.

  • acctset.cpy

    COBOL data mapping for each of the application's BMS maps.

Parent topic: Supplied Samples and Configuration Files


Sample - CICS BankDemo

The BankDemo application is a more advanced application than the ACCT example. It has more programs and maps, and more interestingly, can be configured to use HCOSS to access the samples database.

Note: This sample assumes that you have followed and completed the installation verification process described here Installing and Verifying the Software and you have successfully started and run the ACCT example.

This walkthrough will take you through the steps required to build and deploy the BankDemo application into a database hosted deployment using a local machine architecture. It will use HCOSS to access the applications database.

If you do not want to use HCOSS to access the database, ignore the HCOSS configuration steps.

The BankDemo sample is in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo.
  1. Create the BANKDEMO database.
    1. Open the SQL Server Management Studio.
    2. Connect to the database where you would like to host the region and BANKDEMO database.

      They do not have to be on the same machine, but this tutorial assumes that all databases reside on the local machine.

    3. Open the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo\SQL\BankDemoCreateAll.SQL file.
    4. Execute the SQL. This will create the required tables and pre-load them with the BankDemo data.

  2. Build the application in Enterprise Developer for Visual Studio.
    1. Open Enterprise Developer for Visual Studio.
    2. Open the bankdemo.sln.
    3. Select the relevant project to build:
      1. If using HCOSS, make BankDemo the startup project.
        1. Open the project properties

        2. Select the COBOL properties (1)
        3. Click build events button (2)
        4. Enter the DSN name configured in the HCOSS tool below, e.g. BANKDEMO (3).
      2. If not using HCOSS, make BankDemo2 the startup project.
    4. For HCOSS, configure the database connection.
      1. Open the HCO for SQL Server Tools.

      2. Select the Manage Connections activity from the list on the left and select New SQL Server Connection in the connection list dialog.

      3. Configure the connection data.
        1. Enter BANKDEMO into the Data Source Name.
        2. Either use Integrated Windows Authentication, or Use the SQL Server Login, depending on how you wish to authenticate in the database.
        3. Enter the name of the relevant SQL server instance ( e.g. (local) or machinename\databasename ....).
        4. Check Use a database other than the default database.
        5. Select BANKDEMO from the database dropdown list.

        6. Click the CICS region radio button and configure the displayed dialog.
          1. Either use Integrated Windows Authentication, or Use the SQL Server Login, depending on how you wish to authenticate in the database.
          2. Enter the name of the relevant SQL server instance ( e.g. (local) or machinename\databasename ....).
          3. Enter BANKDEMO as the CICS region.

        7. Click Save.
    5. Build the project.

      The project should build with no errors or warnings. For the HCOSS version the post build event will perform the bind to the configured database

    6. This step is optional and is presented to show how to manually perform the bind step. The bind is normally done by the post build event during the project build for the HCOSS project.

      Select the Manage Packages and Plans activity from the Activities list in the left pane.
      1. Make sure that the bind scripts tab is selected.
      2. In the Bind Script File Actions, click Open and open %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo\BankDemo.hcodsn.
      3. Select BANKDEMO from the SQL Server Connection dropdown.
      4. Click Execute All.

        This will bind the binaries generated when you built the project to the BANKDEMO database.

  3. Deploy the BANKDEMO application into the cross region database.
    1. Open an Enterprise developer command prompt as Administrator.
    2. Navigate to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo directory.
    3. Deploy the bankdemo application into the cross region database.
      • At the command prompt execute bankdemodbdeploy with the parameter to the database to deploy to, e.g. bankdemodbdeploy localhost/sqlexpress or machinename/databasename. or (local) or (local)/sqlexpress . Please note the use of the forward / when specifying the database name if required.
    4. It is well worth looking at this batch file to understand how files are uploaded to the database. This knowledge is invaluable to deployment when developing your own deployment scripts.
  4. Configure an XA resource definition for the bankdemo database as described in Configuring XA resources
    1. An XA resource definition is used to tell the region how to connect to the database.
    2. Ensure that the application plan field in the XA resource definition is set correctly ( BANKDEMO in this case).
    3. It is not required to set the application plan in the region definition , as the XA resource definition takes precedence.
  5. Create the BANKDEMO region.

    These steps are not detailed, as most of the process has been previously described in other tutorials.

    1. Open the Enterprise Server for .NET Administration UI.
      1. Create a new CICS Region called BANKDEMO, hosted in the (local) database.
      2. Select the region definition file from the cross region database. It was deployed in the previous step.
        • It is called region_bankdemo_db.config
        • If using HCOSS, edit the region definition or PCT entry and set the XA resource name to the name of the XA resource you created above.

    2. Create a listener endpoint for the BANKDEMO region on a suitable port.
    3. Start the region.
    4. Check to see that the system picks up the XA resource definition .

    5. Start the listener.
  6. Run Bankdemo.
    1. Connect a TN3270 terminal to the listener port you configured to be associated with BANKDEMO.

      You should be presented with a blank screen, with a flashing cursor.

    2. Type 'bank' and click Enter.

      You will be presented with the initial login screen.

    3. Enter an account, in the format B000xx, e.g. B0001 and anything in the password field.

      You will be presented with the first screen (BANK20) in the demonstration application.

    4. Tab to a field, enter a character and click Enter.

      Look at the console view in the administration tool, and notice that the transactions are being loaded from the database as opposed to disk.

Parent topic: Supplied Samples and Configuration Files


Samples: SQL Server Connection String Exit Programs

The sample SQL server connection string user exit can be found in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\SQLEXIT

This exit can be called by Enterprise Server for .NET to obtain the connection string to use for user SQL connections.

  • sqlexit.cbl and the project sqlexit.cblproj

    This sample exit program uses the MicroFocus.SEE.UserExit.IConnectionStringExit.GetConnectionString() method with no parameters to retrieve the connection string for the user SQL database. Use this exit when a single CICS region uses the exit program.

    The connection string this sample program returns is
    Data Source=(local);Initial Catalog=master;Integrated Security=SSPI
  • sqlexit2.cbl and the project file sqlexit2.cblproj:

    This exit uses the MicroFocus.SEE.UserExit.IConnectionStringExit2.GetConnectionString() method that takes parameters to retrieve the connection string for the user SQL database by specifying the database server instance and region names. This exit is typically used when multiple regions use the exit program.

Parent topic: Supplied Samples and Configuration Files


Sample: Terminal Configuration Exit Program

The sample files are located in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\MFAIEXIT

The TN3270 listener and the DFHZAI terminal auto-install program have basic support for assigning a unique terminal netname and terminal ID, and for handling the basic IBM 3270 models — model 2, 3, 4, or 5, which have different screen sizes.

Normally, the client will send a terminal type name, which will be recorded in the TCTTE and used to assign the terminal model. (The resulting screen size can be seen in the output of the CINQ transaction.) DFHZAI will assign a terminal netname of the form NETaxxx, where a is a capital letter and xxx are three digits or capital letters. The terminal ID is taken from the last four characters of the netname.

Clients can also request a netname. DFHZAI will honor this request if the name, and the corresponding terminal ID, are not in use; otherwise, the request will be rejected and the conversation terminated.

Customers can override the normal handling of terminal types, netnames, and IDs in auto-install using the auto-install exit. Before finishing the terminal installation process, DFHZAI will try to link to a program named MFAIEXIT. If this program exists, it receives a commarea with the netname, ID, and device type currently assigned to the terminal. It can change any of those fields and set flags telling DFHZAI to set the changes in the TCTTE.

This facility provides a simple way to override the terminal model based on the netname requested by the client, for example.

The sample program recognizes the netname NEWNAME and changes it to FROMEXIT. It also recognizes the netnames MODELx, where x is 2-4, and sets the appropriate device type. You can modify this example program to suit your requirements.

To run this demonstration in Visual Studio :

  • Open the MFAIEXIT.SLN
  • Build the user exit.

The project contains:

  • mfaiexit.cbl

    The exit program receives the ai-exit control block (defined in mfaiexit.cpy) in its COMMAREA when it is invoked by the auto-install transaction program DFHZAI. It can modify the netname, terminal ID, and/or device type before returning. If it modifies netname or terminal ID, it must set ai-name-source-exit to true. Note that a modified netname or terminal ID must be unique among terminals attached to the region, or autoinstall will fail. If it modifies device type, it must set ai-type-source-exit to true. Note that a modified device type string is not validated, and if it is not of the form "IBM-327[89]-[2345]-E" (or "IBM-3287-1" for a printer), some aspects of terminal support might not work correctly.

  • mfaiexit.cpy

    This control block is passed to the exit program in the COMMAREA. If the exit modifies the netname or terminal ID fields (and wants autoinstall to use its values), it should set ai-name-source-exit to true. Similarly, if the exit modifies the device type, it should set ai-type-source-exit.

Parent topic: Supplied Samples and Configuration Files


Error Messages

Error messages in ES for .NET are grouped by module.

Click on a message group below for a list of error messages in that group

  • AD - series
    Messages that are issued by the Administration tool.
  • AM - series
    Messages issued by CFMT and CPMT
  • BP - series
    Messages from the BINP module
  • CF - series
    Messages from the configuration module
  • CM - series
    Messages that are from command line executables
  • CNV - series
    Messages from the region conversion utility
  • DP - series
    Messages from the dispatcher module
  • DT - series
    Messages from the deployment module
  • EL - series
    Messages from the event logger module
  • EM - series
    Messages from the Event Monitor .
  • EP - series
    Messages from the SEP module
  • EX - series
    General Exception messages
  • JA - series
    Messages from the seeout command line tool.
  • KC - series
    Messages from the SEP.
  • LO - series
    Messages from the logon provider
  • LS - series
    Messages from the Listener module.
  • MS - series
    Messages from the BMS map handler module
  • OP - series
    Message from the write to operator module.
  • PC - series
    Messages from the SEP module.
  • PS - series
    Messages from the publish / subscribe module.
  • RD - series
    Messages from the region definition module.
  • TX - series
    Messages from dfhzrun module.
  • UPG - series
    Messages from the seeupgrade command line module
  • WU - series
    Messages from the WCF module
Parent topic: General Information for all Roles


AD - series

AD0001E Region name of region performing the submit operation must be started before being able to submit JCL Please make sure that the region specified is started
An attempt was made to submit JCL to a region that is not started.
  • System action: Operation terminates
  • User response: Start the specified region and retry
  • Module: Admin tool
AD0002E Native ES region is not configured for JCL submission The native enterprise server is not configured to run JCL jobs. Configure it appropriately, restart if required and re-submit. Refer to the native enterprise server documentation.
A job submission to a native enterprise server failed as it was not configured to run JCL jobs.
  • System action: Operation terminates
  • User response: Configure the native region appropriately and retry
  • Module: Admin tool
AD0003E Error reading JCL file name of JCL file being opened /read for job submission The JCL file specified could not be opened. Check that the file exists, and that sufficient permissions are in place to allow access to it.
The specified JCL file could not be read.
  • System action: Operation terminates
  • User response: Check that the file exists, and that sufficient permissions are in place to allow access to it
  • Module: Admin tool
AD0004I: JCL submission to host name:port number initiated, type JES type
JCL was submitted.
  • System action: none
  • User response: none
  • Module: Admin tool
Parent topic: Error Messages


AM - series

AM1001W CFMT file (or dataset) name not supplied
Description: A valid file name or dataset was not supplied to the CFMT transaction.
  • System action: None
  • User response: Ensure that the file name / dataset is valid and retry the transaction
  • Module: dfhzcfmt
AM1002I CFMT Usage fn file name where fn= OPen,CLose,ENable,DIsable,INquire,Name
Description: No input was supplied with the transaction. This message documents the required parameters. The user should enter the transaction ID, function, and file name. The function may be "open", "close", "enable", "disable", "inquire" or "name". The transaction considers only the first two letters of the function parameter to determine its action.
  • System action: None
  • User response: None
  • Module: dfhzcfmt
AM1003I Zero length input for CFMT at terminal-id, user user-id
Description: The transaction CFMT started on the terminal but there was no input data. The request executed on terminal terminal-id where user user-id was signed on.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Module: dfhzcfmt
AM1004W Invalid CFMT initiation at terminal-id, user user-id
Description: The transaction CFMT started on the terminal but the start was not a valid start. The request executed on terminal terminal-id where user user-id was signed on.
  • System action: None
  • User response: Correct the transaction initiation and resubmit the request
  • Module: dfhzcfmt
AM1005I CFMT - File file name opened successfully terminal-id, user user-id
Description: The request to open the file was successful.
  • System action: The file was opened
  • User response: None
  • Module: dfhzcfmt
AM1006I CFMT - File file name closed successfully terminal-id, user user-id
Description: The request to close the file was successful.
  • System action: The file was closed
  • User response: None
  • Module: dfhzcfmt
AM1007I CFMT - File file name enabled successfully terminal-id, user user-id
Description: The request to enable the file was successful.
  • System action: The file was enabled
  • User response: None
  • Module: dfhzcfmt
AM1008I CFMT - File file name disabled successfully terminal-id, user user-id
Description: The request to disable the file was successful.
  • System action: The file was disabled
  • User response: None
  • Module: dfhzcfmt
AM1009I CFMT - File file name is open-status and enable-status, terminal-id , user user-id
Description: The inquire request was successful with a status of file open-status and enable-status. If an unexpected CVDA value is returned for either of these statuses, the actual numeric status will be reported.
  • System action: None
  • User response: None
  • Module: dfhzcfmt
AM1010W CFMT invalid request (request) for file file name at terminal-id, user user-id
Description: The request for the file was not recognized. It may be OPen, CLose, ENable, DIsable, INquire or NAme. Only the first two characters of the request are examined by the program. The request is not case sensitive.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcfmt
AM1011W CFMT file file name not found terminal-id, user user-id
Description: The file was not found. The file name is case sensitive.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcfmt
AM1012E CFMT request not authorized for file file name at terminal-id, user user-id
Description: The request for the file is not authorized.
  • System action: The request is ignored
  • User response: Correct the input or consult the security administrator.
  • Module: dfhzcfmt
AM1013E CFMT file file name unexpected response (EIBRESP) terminal-id, user user-id
Description: The requested action for the file resulted in an unexpected API response.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcfmt
AM1014W CFMT illogical response for request to file file name terminal-id, user user-id
Description: The requested action for the file resulted in an illogical API response. The requested transition is illogical, for example, an open request for a file that is already open.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcfmt
AM1015I CFMT file file name DSNAME (DSNAME)
Description: The DSNAME associated with the file is displayed.
  • System action: None
  • User response: None
  • Module: dfhzcfmt
AM1016I CFMT function function completed. error count error(s) encountered. See CEBR.
Description: The requested action has completed. The number of errors is shown.
  • System action: None
  • User response: Use the CEBR transaction to view the log
  • Module: dfhzcfmt
AM1017E CFMT file file name IOERR (EIBRESP/EIBRESP2) terminal-id, user user-id
Description: The requested action for the file resulted in an IOERR.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcfmt
AM2001W CPMT program or table name not supplied
Description: The program name to action was not supplied. Usage is CPMT fn program-name.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Module: dfhzcpmt
AM2003I Zero length input for CPMT at terminal-id, user user-id
Description: The transaction CPMT started on the terminal but there was no input data.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Module: dfhzcpmt
AM2004W Invalid CPMT initiation at terminal-id, user user-id
Description: The transaction CPMT started on the terminal but the start was not a valid start.
  • System action: None
  • User response: Correct the transaction initiation and resubmit the request
  • Module: dfhzcpmt
AM2005I CPMT - Program program name newcopy terminal-id, user user-id
Description: The request to load a new copy of the program was successful.
  • System action: A new copy of the program is loaded.
  • User response: None
  • Module: dfhzcpmt
AM2006I CPMT - Program program name phasein terminal-id, user user-id
Description: The request to load a new copy of the named program by user user-id at terminal terminal-id was successful. The new copy will be used for all new requests.
  • System action: A new copy of the program is being phased in
  • User response: None
  • Module: dfhzcpmt
AM2007I CPMT - Program program name private terminal-id, user user-id
Description: The request to mark the program as private was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2008I CPMT - Program program name shared terminal-id, user user-id
Description: The request to mark the program as shared was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2009I CPMT - Program program name dplsubset terminal-id, user user-id
Description: The request to mark the program as dplsubset was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2010I CPMT - Program program name fullapi terminal-id, user user-id
Description: The request to mark the program as fullapi was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2011I CPMT - Program program name cedf terminal-id, user user-id
Description: The request to mark the program as cedf was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2012I CPMT - Program program name nocedf terminal-id, user user-id
Description: The request to mark the program as nocedf was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2013I CPMT - Program program name is disabled terminal-id, user user-id
Description: The request to mark the program as disabled was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2014I CPMT - Program program name is enabled terminal-id, user user-id
Description: The request to mark the program as enabled was successful.
  • System action:
  • User response: None
  • Module: dfhzcpmt
AM2016I Program program name is not currently loaded
Description: Program has not been loaded. The full name cannot be displayed until it has been accessed.
  • System action:
  • User response: Do a NEWCOPY or PHASEIN command and repeat this inquiry
  • Module: dfhzcpmt
AM2018W CPMT invalid request (request) for program program name at terminal-id, user user-id
Description: The request for the program was not recognized. It may be OPen, CLose, ENable, DIsable, or INquire. Only the first two characters of the request are examined by the program. The request is not case sensitive.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcpmt
AM2019W CPMT program program name not found terminal-id, user user-id
Description: The program was not found. The program name is case sensitive on some platforms.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcpmt
AM2020E CPMT request not authorized for program program name at terminal-id, user user-id
Description: The request for the program is not authorized.
  • System action: The request is ignored
  • User response: Correct the input or consult the security administrator.
  • Module: dfhzcpmt
AM2021E CPMT program program name unexpected response (EIBRESP) terminal-id, user user-id
Description: The requested action for the program resulted in an unexpected API response.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Module: dfhzcpmt
Parent topic: Error Messages


BP - series

BP0001E Error processing MFBINP Cobcall header Additional text from BP0001_x will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support or the network administrator. This message may indicate that a client program is sending invalid data to an MFBINP channel configured for the ES.NET listener.
  • Module: mfbinp
BP0002E Error processing MFBINP message Additional text will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support or the network administrator. This message may indicate that a client program is sending invalid data to an MFBINP channel configured for the ES.NET listener.
  • Module: mfbinp
BP0003E Error processing MFBINP Standard header Additional text will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support or the network administrator. This message may indicate that a client program is sending invalid data to an MFBINP channel configured for the ES.NET listener.
  • Module: mfbinp
BP0004E one of the BP Error messages
Description: The MFBINP request cannot be processed. It may specify an invalid function or service name, for example. The message text contains additional information.
  • System action: The MFBINP request is rejected.
  • User response: Contact support.
  • Module: dfhzbinp
BP0005E CASA_File_Set: Missing or invalid request from client
Description: The CASA_File_Set service, used by the casfile utility and other components, received an invalid request.
  • System action: The request is discarded.
  • User response: This is usually an internal error. Contact support.
  • Module: dfhzfile
BP0006E CASA_File_Set: Unable to allocate number of bytes bytes
Description: The CASA_File_Set service, used by the casfile utility and other components, was unable to process the request.
  • System action: The request is discarded.
  • User response: Contact support.
  • Module: dfhzfile
BP0007E CASA_File_Set: Option "-z" (pass ACEE) is not supported
Description: The –z option of the casfile utility is not supported in this implementation.
  • System action: The request is discarded.
  • User response: Retry without the –z option.
  • Module: dfhzfile
BP0008E Error processing MFBINP Reply header Additional text will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support.
  • Module: mfbinp
BP0009E Error processing MFBINP Ok message Additional text from BP0001_x will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support.
  • Module: mfbinp
BP0010E Error processing MFBINP Ok message Additional text from BP0001_x will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support.
  • Module: mfbinp
BP0011E Error processing MFBINP Data message Additional text from BP0001_x will be appended
Description: The MFBINP message is invalid.
  • System action: The MFBINP message is discarded.
  • User response: Contact support.
  • Module: mfbinp
BP0012E Error receiving for subscription MFBINP session ID ("subscriber description"): exception message in stack trace
Description: The ES Event Manager client support module encountered an error while trying to receive event messages for the given subscription.
  • System action: The event subscriber will no longer receive messages for this subscription.
  • User response: Restart the event subscriber.
  • Module: mfbinp
Parent topic: Error Messages


CF - series

CF0001E Region startup file "name of region startup file" not found
Description: The region start up file associated with the region could not be located
  • System action: Start up process stops
  • User response: Ensure that the region file exists and is on the path specified
  • Module: Configuration
CF0002E Failed to configure region
Description: Region start up could not configure the region, normally due to a configuration error.
  • System action: Start up process stops
  • User response: Rectify the error and restart
  • Module: Configuration
CF0003E No "microfocus.cics" section found in the resource definition file
Description: The resource definition file is malformed. The region startup process cannot find the microfocus.cics section it needs to perform start processing.
  • System action: Start up processing stops
  • User response: Ensure that the resource definition is correct. Check for XML errors
  • Module: Configuration
CF0004E An exception occurred accessing the master database: exception message
Description: The master database hosted in the SQL server instance cannot be accessed.
  • System action: System halts
  • User response: Check the event logs and the console log for exceptions and rectify the problem (e.g. a logon failure might suggest a permission issue)
  • Module: Configuration
CF0005I Created database "database name"
Description: A database was successfully created.
  • System action: none
  • User response: none
  • Module: Configuration
CF0006E Failed to create database "database name"
Description: A process could not create a required database.
  • System action: Operation terminates
  • User response: Check the event logs and the console log for exceptions and rectify the problem (e.g., a logon failure might suggest a permission issue)
  • Module: Configuration
CF0007E An exception occurred creating database "database name": exception message
Description: A process could not create a database.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a logon failure might suggest a permission issue)
  • Module: Configuration
CF0008E An exception occurred accessing the cross-region database: exception message
Description: A process could not access the cross-region database.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a logon failure might suggest a permission issue)
  • Module: Configuration
CF0009E An exception occurred creating region "region name": exception message
Description: The specified region could not be created.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a logon failure might suggest a permission issue)
  • Module: Configuration
CF0010E SIT "SIT name" not found
Description: The SIT specified in the region configuration could not be found.
  • System action: Operation terminates
  • User response: Check the region configuration and resource definition information and correct the error
  • Module: Configuration
CF0011E An exception occurred creating the CSA: exception message
Description: The CSA database could not be created.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a logon failure might suggest a permission issue)
  • Module: Configuration
CF0012E An exception occurred creating a certificate: exception message
Description: A process could not create a certificate.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a permission denied failure might suggest a permission issue)
  • Module: Configuration
CF0013E An exception occurred creating a certificated login: exception message
Description: A process could not create a certificated login.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a permission denied failure might suggest a permission issue)
  • Module: Configuration
CF0014E An exception occurred preparing the certificate directory: exception message
Description: A process could not create the certificate directory.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a permission denied failure might suggest a permission issue)
  • Module: Configuration
CF0015E An exception occurred creating the transient tables: exception message
Description: A process could not create a required table.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a permission denied failure might suggest a permission issue)
  • Module: Configuration
CF0016E No "groups" found in the "microfocus.cics" section of the resource definition file
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0017E An exception occurred creating file locations: exception message
Description: file locations could not be created.
  • System action: Operation terminates
  • User response: Study the exception message and rectify the problem (e.g. a permission denied failure might suggest a permission issue)
  • Module: Configuration
CF0018E No "sits" found in the "microfocus.cics" section of the resource definition file
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0019E No "startuplists" found in the "microfocus.cics" section of the resource definition file
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0020I SQL Server instance created using description of SQL Server product retrieved from SQL Server
Description: A SQL server instance was created.
  • System action: none
  • User response: none
  • Module: Configuration
CF0021I Using datasource "name of SQLServer instance retrieved from the database connection"
Description: The named datasource is being used.
  • System action: none
  • User response: none
  • Module: Configuration
CF0022I Successfully cold started region 'region name'
Description: The specified region has been started.
  • System action: none
  • User response: none
  • Module: Configuration
CF0023I Using database "database name"
Description: The specified database is being used.
  • System action: none
  • User response: none
  • Module: Configuration
CF0024E An exception occurred accessing the database "database name": exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: Configuration
CF0025I Successfully warm started region 'region name'
Description: Region was warm started
  • System action: none
  • User response: none
  • Module: Configuration
CF0026E Startup list "startup list name" not found
Description: The named start up list was not found.
  • System action: Operation terminates
  • User response: none
  • Module: Configuration
CF0027I Using SIT "SIT name"
Description: The specified SIT is being used
  • System action: none
  • User response: none
  • Module: Configuration
CF0028E An exception occurred warm starting region "region name" : exception message
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: Configuration
CF0029W Resource name "resource definition name" attribute "attribute name" has an invalid value "attribute type". Element ignored.
Description: An attribute in the resource definition has an invalid value.
  • System action: Element is ignored
  • User response: Correct the attribute
  • Module: Configuration
CF0030W Resource name "resource definition name" contains invalid character "character in error". Element ignored.
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0031W Unknown element "name of unknown element" ignored in "section name" section of resource definition file
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0032E An exception occurred processing the resource definition file: exception message
Description: An exception occurred processing the configuration file.
  • System action: none
  • User response: Study the exception message for clues and ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0033W Missing "name" attribute on a "element name" element. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0034W Group "group name" defined more than once. First occurrence is used
Description: A configuration error in a configuration file has occurred.
  • System action: The first occurrence of the group is used
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0035W Group "group name" "resource types" defined more than once. First occurrence used
Description: A configuration error in a configuration file has occurred.
  • System action: The first occurrence is used
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0036W Unknown element "unknown element name" ignored in group "group name" section of resource definition file
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0037W Missing "attribute name" attribute on a "resource type name" element in group "group name". Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0038W Unknown element "unknown element name" ignored in the "resource type name" definitions for group "group name"
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored.
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0039W Unknown element "unknown element name" ignored in the "section name" section of resource definition file
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0040W Startup list "startup list name" defined more than once. First occurrence is used
Description: A configuration error in a configuration file has occurred.
  • System action: The first occurrence is used
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0041W Missing "name" attribute on group element for startuplist "startup list name". Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0042W Group "group name" does not exist for startuplist "startup list name". Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0043W Unknown element "unknown element name" ignored in the "startup list name" startuplist definition
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0044W Missing "path" or "url" attribute on "location" element in the "section name" section of the resource definition file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0045W Unknown element "unknown element name" ignored in the "PLT name" PLT definition
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0046E Cannot cold start CICS region 'region name'. Region currently in 'region state' state (started, starting, stopping)
Description: A cold start was requested but the region is already in a started, starting or stopping state.
  • System action: Start request is ignored
  • User response: Ensure that the region is in a stopped state before trying a cold start. If the region is already started, stop it before trying a start. If it is in a starting state, wait for the start to complete. If it is in a stopping state, then wait for it to stop. If it is in a starting or stopping state, and it doesn’t complete that action, you can try a force stop
  • Module: Configuration
CF0047E Cannot warm start region type region 'region name'. Region currently in 'region state' state (started, starting, stopping)
Description: A warm start was requested but the region is already in a started, starting or stopping state.
  • System action: Start request is ignored
  • User response: Ensure that the region is in a stopped state before trying a warm start. If the region is already started, stop it before trying a start. If it is in a starting state, wait for the start to complete. If it is in a stopping state, then wait for it to stop. If it is in a starting or stopping state, and it doesn’t complete that action, you can try a force stop
  • Module: Configuration
CF0048E Cannot shutdown region 'region name'. Region currently in 'region state ' state (started, starting, stopping)
Description: A region stop/shutdown was requested but the region is already in a started, starting or stopping state.
  • System action: Shutdown request is ignored
  • User response: Ensure that the region is in a started state before trying a shutdown. If the region is in a starting state, wait for the start to complete. If it is in a stopping state, then wait for it to stop. If it is in a starting or stopping state, and it doesn’t complete that action, you can try a force stop
  • Module: Configuration
CF0049E An exception occurred shutting down region "region name" : exception message
Description: The region could not be shut down, and generated an exception.
  • System action: Shut down is halted
  • User response: Study the exception for clues, and rectify the issue
  • Module: Configuration
CF0050I Successfully shutdown region 'region name'
Description: The region was shut down correctly.
  • System action: none
  • User response: none
  • Module: Configuration
CF0051I Shutdown of region type region 'region name' starting
Description: A shutdown request was received and the shutdown sequence has started.
  • System action: none
  • User response: none
  • Module: Configuration
CF0052I Cold start of region 'region name' starting
Description: A Cold start request was received and the region is starting.
  • System action: none
  • User response: none
  • Module: Configuration
CF0053I Warm start of region 'region name' starting
Description: A Warm start request was received and the warm start sequence has started.
  • System action: none
  • User response: none
  • Module: Configuration
CF0054E No region startup file specified
Description: An attempt to control a region was made, but no region startup file was defined.
  • System action: Operation terminates
  • User response: Specify a region start up file and try the operation again
  • Module: Configuration
CF0055E Invalid region startup file name specified
Description: An attempt to control a region was received but an incorrect region startup file was given.
  • System action: Operation terminates
  • User response: Use a valid region startup file name and attempt the operation again
  • Module: Configuration
CF0056E No "microfocus.region" section found in the region startup file
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0057E No "region" found in the "microfocus.region" section of the region startup file
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0058E Invalid resource definition file name specified
Description: An invalid resource definition file name has been specified. Probably in the region start up file.
  • System action: Operation terminates
  • User response: Use a valid resource definition file name and attempt the operation again
  • Module: Configuration
CF0059E Resource definition file "name of resource definition file" not found
Description: An invalid resource definition file name has been specified. Probably in the region start up file.
  • System action: Operation terminates
  • User response: Use a valid resource definition file name and attempt the operation again
  • Module: Configuration
CF0060E No messages were received for region startup or shutdown processing. Region state unknown.
Description: The monitor has not been able to determine the state of the region.
  • System action: Operation terminates
  • User response: Check that the infrastructure is correct (network, endpoint configuration etc) and retry
  • Module: Configuration
CF0061W Unknown element "name of unknown element" ignored in "section name" section of region startup file
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0062E An exception occurred processing the region startup file exception message
Description: An exception occurred whilst processing the region startup file.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed. An error in XML can create this sort of exception
  • Module: Configuration
CF0063W Element "element name" defined more than once. First occurrence is used
Description: A configuration error in a configuration file has occurred.
  • System action: The first occurrence of the element is used
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0064E Failed to connect to the region 'database name' database
Description: The region database could not be contacted.
  • System action: Operation terminates
  • User response: Ensure that the database is accessible, permissions are correct (the user ID that the process is running under has access). Ensure that the database is running, that the database address is correct, ports are correct, protocols are correct etc
  • Module: Configuration
CF0065W Skipping invalid channel (no "name" element) in listener configuration
Description: A configuration error in a configuration file has occurred.
  • System action: Element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0066W Skipping invalid channel definition "channel name" in listener configuration file: reason
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0067W Unknown element "element name" ignored in listener configuration file
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0068E An exception occurred processing the listener configuration file exception message
Description: The listener configuration information contains an error that caused the listener to generate an exception.
  • System action: Listener halts
  • User response: Examine the exception for clues. Ensure that the listener configuration file XML is well formed
  • Module: Configuration
CF0069W Element 'element name' defined more than once for region 'region' in listener configuration file
Description: A configuration error in a configuration file has occurred.
  • System action: none
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0070W Missing "name" attribute on a "element name" element in the listener configuration file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: none
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0071W Region "region" defined more than once in the listener configuration file. First occurrence is used
Description: A configuration error in a configuration file has occurred.
  • System action: none
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0072E Failed to start the event monitor service
Description: The event monitor service could not be started.
  • System action: none
  • User response: Check the event log for exceptions and rectify any issues found
  • Module: Configuration
CF0073W WARNING - Forcing region termination - data may be lost
Description: The user has requested to force stop a region.
  • System action: none
  • User response: none
  • Module: Configuration
CF0074E Cannot warmstart region 'region name'. Region previously stopped using 'immediate' or 'force'
Description: A warmstart was requested on a region that had been shutdown with force or immediate.
  • System action: Operation terminates
  • User response: Perform a cold start on the region
  • Module: Configuration
CF0075W only one of "path" and "url" attributes allowed on "location" element in the "section name" section of the resource definition file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0076W The "deploy" element must have a "target" attribute. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0077W Child elements of the "deploy" element must have a "file" attribute. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0078W Unsupported "target" value ""target" attribute" for deploy element. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0079E An exception occurred deploying files:exception message
Description: An attempt was made to deploy a file to a database which resulted in an exception.
  • System action: Operation terminates
  • User response: Study the exception for clues as to why the operation failed. Look in the event log for further clues
  • Module: Configuration
CF0080W Missing "key" or "value" attribute on "add" element in the "section name" section of the resource definition file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0081E An exception occurred processing CICS override values: exception message
Description: An exception occurred processing CICS override values.
  • System action: Operation terminates
  • User response: Study the exception for clues, ensure that the CICS override configuration is correct
  • Module: Configuration
CF0082I Using region startup file "region startup file name"
Description: Region start up is using the region startup file name specified.
  • System action: none
  • User response: none
  • Module: Configuration
CF0083I Using resource definition file "resource definition file name"
Description: Region startup is using the resource definition file specified.
  • System action: none
  • User response: none
  • Module: Configuration
CF0084I Application binary "binary name" deployed to table name from file path.
Description: A binary file was successfully deployed to the database table specified.
  • System action: none
  • User response: none
  • Module: Configuration
CF0084W An application binary named "binary name" already exists in table name. Skipping deployment of file path.
Description: A deployment of a binary file to the database failed because it already existed.
  • System action: Action skipped.
  • User response: Make sure that the file does not exist in the table before you deploy. (Use the delete operation first to make sure it does not exist.)
  • Module: Configuration
CF0085I Application binary "binary name" deployed to table name from file path.
Description: A binary file was successfully deployed to the database table specified.
  • System action: none
  • User response: none
  • Module: Configuration
CF0086I Using configuration file name
Description: The configuration file specified is being used.
  • System action: none
  • User response: none
  • Module: Configuration
CF0087W Run wasreset to resolve this problem. If this error still occurs after running wasreset then run wassetup.
Description: A problem was detected that could be resolved by running wasreset from an enterprise server/developer command prompt.
  • System action: none
  • User response: Run wasreset to reset the IIs and WCF infrastructure. If this does not resolve the problem, run wassetup to re-initialize the Micro Focus application pool and WCF infrastructure
  • Module: Configuration
CF0088I Loaded user SQL exit user SQLexit assembly name
Description: The specified SQL user exit has been loaded into process.
  • System action: none
  • User response: none
  • Module: Configuration
CF0089I Initialized user SQL connection string
Description: The HCOS SQL connection string has been successfully initialized.
  • System action: none
  • User response: none
  • Module: Configuration
CF0090W Failed to initialize user SQL connection string
Description: The SQL connection string failed to initialize.
  • System action: none
  • User response: Ensure that the SQL connection information is correctly using the HCO configuration tooling
  • Module: Configuration
CF0091W Failed to load user SQL exit user SQLexit assembly name
Description: The SQL user exit assembly could not be loaded into process.
  • System action: none
  • User response: Check that the assembly is available, has been built correctly, and that the code within it is correct
  • Module: Configuration
CF0119I Cold starting type of region region 'region name'
Description: The specified CICS or JES region is being started.
  • System action: none
  • User response: none
  • Module: Configuration
CF0092W Unable to remove old certificate file "path to certificate file" on database server database server name: error message from script
Description: The system is unable to remove the certificate file from the database server.
  • System action: Removal failed
  • User response: The error message from script should contain enough information to allow the problem to be fixed. Since the problem occurs on the database server system, you might need to consult the database administrator
  • Module: Configuration
CF0093E Unable to determine/create certificate directory on database server database server name: error message
Description: The directory that contains the certificates could not be determined or created.
  • System action: Operation terminates
  • User response: Examine the error message for information to help resolve the issue. Consult the database administrator
  • Module: Configuration
CF0094E Error creating table table name in cross-region database on server DB server name: message from SQL script
Description: The specified table could not be created within the cross region database on the specified database server.
  • System action: Operation terminates
  • User response: Examine the message from the SQL script to help understand the issue
  • Module: Configuration
CF0095E Current user does not have permissions to start region "region name" on "server instance "server instance"
Description: The current user does not have the authority to start the region.
  • System action: Operation terminates
  • User response: Make sure that the user has the required authority/permissions to start the region
  • Module: Configuration
CF0096E Error dropping stored procedure proc name from database DB name on server DB instance: exception message SQL error code
Description: The specified stored procedure could not be dropped from the database.
  • System action: Operation terminates
  • User response: Examine the exception message and SQL error code to help identify the underlying issue
  • Module: Configuration
CF0097E Exception occurred attempting to output console message Message : console message Region : region name Database server : database server name Exception : exception type exception message exception stack trace
Description: The system could not send a message to the console
  • System action: Operation terminates
  • User response: Examine the exception trace to help identify the problem
  • Module: Configuration
CF0098E An exception occurred attempting to determine IIS application pool configuration. The IIS application pool used to run Micro Focus Enterprise Server for .NET must be configured with the "disallowOverlappingRotation" attribute set to "false". Exception : pseudo 1 2
Description: The system could not determine the IIS application pool configuration.
  • System action: Operation terminates
  • User response: Ensure that the application pool is configured with disallowOverlappingRotation set to false
  • Module: Configuration
CF0099W Unable to determine the name of the current IIS application pool being used. Ensure that the IIS application pool used to run Micro Focus Enterprise Server for .NET is configured with the "disallowOverlappingRotation" attribute set to "false".
Description: The system could not determine the IIS application pool configuration.
  • System action: Operation terminates
  • User response: Ensure that the application pool is configured with disallowOverlappingRotation set to false.
  • Module: Configuration
CF0100W Unable to determine how the IIS application pool being used to run Micro Focus Enterprise Server for .NET is configured. Ensure that the "disallowOverlappingRotation" attribute is set to "false" for this application pool.
Description: The system could not determine the IIS application pool configuration.
  • System action: Operation terminates
  • User response: Ensure that the application pool is configured with disallowOverlappingRotation set to false.
  • Module: Configuration
Application pool name: Name of IIS application pool CF0101W The IIS application pool being used to run Micro Focus Enterprise Server for .NET is configured with the "disallowOverlappingRotation" attribute set to "true". Ensure that the "disallowOverlappingRotation" attribute is set to "false" for this application pool.
Description: The IIS application pool is configured incorrectly.
  • System action: none
  • User response: Ensure that the application pool is configured with disallowOverlappingRotation set to false.
  • Module: Configuration
CF0102E Error initiating region startup on Name of machine
Description: The system could not initiate region start up for the region.
  • System action: Operation terminates
  • User response: Ensure that the region configuration is correct, check that the endpoints are configured correctly
  • Module: Configuration
CF0103E Error querying region startup progress on Name of machine
Description: The system could not query region start up progress for the region.
  • System action: Operation terminates
  • User response: Ensure that the region configuration is correct, check that the endpoints are configured correctly
  • Module: Configuration
CF0104E Error during region startup completion on Name of machine
Description: The system could not complete the region startup process.
  • System action: Operation terminates
  • User response: Indicates a communication failure with the event monitor performing the termination of region start-up processing. Generally benign, but look at previous messages for indication of failure or success of the operation
  • Module: Configuration
CF0105E Error initiating region shutdown on Name of machine
Description: The system could not initiate region shut down
  • System action: System halts
  • User response: Indicates an internal logic error. Contact Technical Support
  • Module: Configuration
CF0106E Error querying region shutdown progress on Name of machine
Description: The system could query shutdown progress.
  • System action: System halts
  • User response: Indicates an internal logic error. Contact Technical Support
  • Module: Configuration
CF0107E Error during region shutdown completion on Name of machine
Description: The system detected an error during shutdown completion processing.
  • System action: System halts
  • User response: Indicates a communication failure with the event monitor performing the termination of region shutdown processing. Generally benign, but look at previous messages for indication of failure or success of the operation
  • Module: Configuration
CF0108E The properties file 'Name of properties file' does not exist
Description: The configured properties file could not be found.
  • System action: Operation terminates
  • User response: Check the path to the file, and that the file exists
  • Module: Configuration
CF0109E An exception occurred reading the properties file 'Name of properties file': exception message
Description: The configured properties file could not be read.
  • System action: Operation terminates
  • User response: Examine the exception for the cause of the problem (e.g. permissions, file locked etc), and rectify
  • Module: Configuration
CF0110W Pseudo-variable 'pseudo-variable name' value not found for path 'path '
Description: The configured properties file could not be read.
  • System action: Operation terminates
  • User response: Examine the exception for the cause of the problem (e.g. permissions, file locked etc), and rectify
  • Module: Configuration
CF0111W The "IIS Metabase and IIS 6 configuration compatibility" feature must be enabled to allow the system to determine whether the IIS application pool used to run Micro Focus Enterprise Server for .NET is configured with the "disallowOverlappingRotation" attribute set to "false".
Description: A query to determine some IIS configuration failed.
  • System action: none
  • User response: Ensure that the required IIS features are installed and enabled
  • Module: Configuration
CF0112E Database server instance must be specified for a cross-region region startup file
Description: A region is configured to use a startup file from a cross region database, but the database instance has not been defined.
  • System action: Operation terminates
  • User response: Provide the database instance name that must be used for the region and retry the operation
  • Module: Configuration
CF0113E An exception occurred connecting to the database database name Database server instance: database server instance
Description: A connection to the database on the database server could not be made.
  • System action: Operation terminates
  • User response: Ensure that the database server is accessible, ports are correct, permissions are correct, DNS entries are correct etc and try again. This is normally caused by a permissions or TCP problem
  • Module: Configuration
CF0114E Invalid region startup file type 'type' specified
Description: The region start up type is invalid.
  • System action: Operation terminates
  • User response: Ensure that the start up type is correct and retry the operation
  • Module: Configuration
CF0115W Initiator 'name' must be specified. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: The element is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0116W Initiator 'count' must be in the range 1 - maximum initiator count allowed. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: none
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0117W Initiator 'class' characters must be 'A-Z', 'a-z' or '0-9'. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: none
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0118W At least one initiator class must be specified by the 'class' attribute. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: none
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0119I Cold starting type of region region 'region name'
Description: The regions specified is being cold started.
  • System action: none
  • User response: none
  • Module: Configuration
CF0120I Warm starting type of region region 'region name'
Description: The regions specified is being warm started.
  • System action: none
  • User response: none
  • Module: Configuration
CF0121E Cannot start region type region 'region name'. Region currently in 'region state ' state (started, starting, stopping)
Description: The region could not be started as the region is in an invalid state to be started.
  • System action: Operation terminates
  • User response: Make sure the region is in a stopped state and retry the start
  • Module: Configuration
CF0122W Element "element name" defined more than once in the global configuration file. First occurrence is used
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0123W Unknown element "name of unknown element" ignored in "section name" section of the global configuration file
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0124W Ignored XA resource with empty or missing name in the "xaresources" section of the global configuration file
Description: A configuration error in a configuration file has occurred.
  • System action: XA resource is ignored
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0125W Unknown type for resource "name of resource" in the "xaresources" section of the global configuration file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0126W Empty or missing open string for resource "name of resource" in the "xaresources" section of the global configuration file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0127W Resource "name of resource" already defined in the "xaresources" section of the global configuration file. Element ignored
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0128W A machine at the endpoint 'remote endpoint' is running an earlier version of Enterprise Server for .NET and does not support the level of functionality required to perform an attempted remote operation. Please upgrade the target machine(s) to ensure the system can provide consistent run-time behavior.
Description: The machine at the specified endpoint is running a back level version of the product that does not support the functionality required.
  • System action: none
  • User response: Make sure that all the machines being used for this Enterprise Server for .NET installation are at the latest level
  • Module: Configuration
CF0129W Invalid value for attribute attribute name (must be "true" or "false"). Assuming "false".
Description: A configuration error in a configuration file has occurred.
  • System action: A value of false is assumed
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0130E Circular environment setting detected while expanding "environment variable name". Configuration rejected.
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0131E Incorrect environment setting syntax detected while expanding "environment variable name". Configuration rejected.
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0132W Unrecognized child element "element name" in subscription for "subscription URL"
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0133W The <set> element must have "name" and "value" attributes
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0134W Unknown element "unknown element name" ignored in "section name" section of the seepubsub configuration file
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0135E An exception occurred processing the seepubsub configuration file exception message
Description: A configuration error in a configuration file caused an exception.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0136W object type "object name" is defined more than once in the configuration file. The first definition is used. (eg "Applid")
Description: A configuration error in a configuration file has occurred.
  • System action: The first definition is used
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0137W Unknown element "unknown element name" ignored in "section name" section of the configuration file
Description: A configuration error in a configuration file has occurred.
  • System action: EMI
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0138E An exception occurred processing the configuration file: exception message
Description: A configuration error in a configuration file caused an exception.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF0139W No "client" element found in the "MicroFocus.SEE.EXCI" section of the region startup file. EXCI client not configured.
Description: A configuration error in a configuration file has occurred.
  • System action: The EXCI client is not configured
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF9998E An exception occurred shutting down region "region name":newline characterexception message
Description: A configuration error in a configuration file has occurred.
  • System action: Operation terminates
  • User response: Ensure that the configuration file contains the correct configuration, and that the configuration file is well formed
  • Module: Configuration
CF9999E An exception occurred starting region "region name": exception message
Description: An exception was detected whilst trying to start a region.
  • System action: Operation terminates
  • User response: Study the exception for information that could help rectify the problem
  • Module: Configuration
Parent topic: Error Messages


CM - series

CM0001E Unrecognized command-line option "option"
Description: A command line parameter is incorrect.
  • System action: Operation terminates
  • User response: Ensure that the parameters to the command line are correct and retry.
  • Module:Command line tools
CM0002E Invalid command-line option: option cannot be specified with other options
Description: A command line parameter is incorrect.
  • System action: Operation terminates
  • User response: Ensure that the parameters to the command line are correct and retry.
  • Module:Command line tools
CM0003E Invalid command line: "option" must be the first option
Description: A command line parameter is incorrect.
  • System action: Operation terminates
  • User response: Ensure that the parameters to the command line are correct and retry.
  • Module:Command line tools
Parent topic: Error Messages


CNV - series

CNV00001E File not accessible (file name)
Description: The file specified was not accessible
  • System action: Operation terminates
  • User response: Ensure that the file is available and that permissions to access it are correct
  • Module:seerdfconv
CNV00002E Directory not found (directory name)
Description: Directory was not found
  • System action: Operation terminates
  • User response: Enter the correct path and try again
  • Module:seerdfconv
CNV00003E File not found (file name)
Description: The file was not found
  • System action: Operation terminates
  • User response: Ensure that the file name and path is correct, and that the file exists
  • Module:seerdfconv
CNV00004E File cannot be opened - exception message (file name)
Description: The file cannot be opened
  • System action: Operation terminates
  • User response: Ensure that the file is not in use, and that the permissions to access the file are correct
  • Module:seerdfconv
CNV00005E No input file specified
Description: No input file was specified
  • System action: Operation terminates
  • User response: Specify an input file and retry the command
  • Module:seerdfconv
CNV00006E <configuration> root element not found (file name)
Description: There is a configuration error
  • System action: Operation terminates
  • User response: The root XML element is missing. Check the file for errors and retry
  • Module:seerdfconv
CNV00007E Unexpected element found (element name) in file file name
Description: An invalid xml element was found
  • System action: Operation terminates
  • User response: Fix the xml error and retry
  • Module:seerdfconv
CNV00008E Invalid command line option
Description: An invalid command line option was specified
  • System action: Operation terminates
  • User response: Correct the command line syntax and retry
  • Module:seerdfconv
Parent topic: Error Messages


DP - series

DP0001I Dispatcher is ready to accept service requests
Description: The dispatcher has succesfully initialized and is ready for work.
  • System action: none
  • User response: none
  • Module: seedispatch
DP0002I Listener process started: listener process id
Description: The dispatcher has sucesfully started a listener process with the given process id.
  • System action: none
  • User response: none
  • Module: seedispatch
DP0003E An exception occurred starting the listener: exception message
Description: The dispatcher has tried to start a listener, but an exception was generated.
  • System action: Operation terminates
  • User response: Examine the exception for the reason for the failure, and rectify
  • Module: seedispatch
DP0004I SEP process started: SEP process id
Description: The dispatcher has succesfully started a SEP process with the given process id.
  • System action: none
  • User response: none
  • Module: seedispatch
DP0005E An exception occurred starting a SEP: exception message
Description: The dispatcher has tried to start a SEP but an exception was generated.
  • System action: Operation terminates
  • User response: Examine the exception for the reason for the failure, and rectify
  • Module: seedispatch
DP0006I SEP process SEP process id exited: rc = SEP process return code
Description: The SEP process has terminated with the specified return code.
  • System action: none
  • User response: none
  • Module: seedispatch
DP0007E An exception occurred dispatching a request: exception message
Description: The dispatcher could not dispatch a request.
  • System action: Operation terminates
  • User response: Examine the exception for the reason for failure and rectify
  • Module: seedispatch
DP0008E Region 'region name' is unavailable
Description: The dispatcher cannot interact with the specified region name.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seedispatch
DP0009E Auto-install transaction 'transaction name' not found. Ensure DFHVTAM group is defined.
Description: The transaction specified could not be auto-installed.
  • System action: Operation terminates
  • User response: Ensure that the DFHVTAM group is defined and configured correctly
  • Module: seedispatch
DP0010E Failure opening a session with region 'region name': cause of failure
Description: A session to the specified region could not be opened.
  • System action: Operation terminates
  • User response: Examine the message for the cause of failure and rectify
  • Module: seedispatch
DP0011E Failed to connect to region DB instance\region name to dispatch request request id
Description: The dispatcher is unable to communicate with the region in order to perform the operation.
  • System action: Operation terminates
  • User response: Check that the region is running, and that the communications infrastructure, service configuration is sound
  • Module: seedispatch
DP0012E Failed to connect to region DB instance\region name to output console message Message : console message
Description: The dispatcher is unable to communicate with the region in order to perform the operation.
  • System action: Operation terminates
  • User response: Check that the region is running, and that the communications infrastructure, service configuration is sound
  • Module: seedispatch
DP0013E Failed to connect to region DB instance\region name to close session session id
Description: The dispatcher is unable to communicate with the region in order to perform the operation.
  • System action: Operation terminates
  • User response: Check that the region is running, and that the communications infrastructure, service configuration is sound
  • Module: seedispatch
DP0014E Failed to connect to region DB instance\region name to invoke service service name
Description: The dispatcher is unable to communicate with the region in order to perform the operation.
  • System action: Operation terminates
  • User response: Check that the region is running, and that the communications infrastructure, service configuration is sound
  • Module: seedispatch
DP0015E Discarding empty TN3270 request (session session ID)
Description: The TN3270 request is empty, the dispatcher is discarding the request.
  • System action: The request is discarded
  • User response: Try and find out why an empty request was sent. Examine event logs for communication failures
  • Module: seedispatch
DP0016E Error attempting to queue CICS request Tran id: TranId Session id: SessionId Term id: TermId Database instance: DB instance Region name: region name
Description: The dispatcher is unable to queue a request to the region database.
  • System action: Operation terminates
  • User response: Check the console and event log for errors and exceptions
  • Module: seedispatch
DP0017E Transaction 'Tran id' ABEND Abend code, (Abend description). Backout successful.
Description: A transaction abended.
  • System action: Operation terminates
  • User response: Check the abend code and description for the reason. Fix the error in the transaction and retry
  • Module: seedispatch
DP0018E Error attempting to queue JES request Session id: SessionId Database instance: DB instance Region name: region name
Description: The dispatcher is unable to queue a request.
  • System action: Operation terminates
  • User response: Check the console and event log for errors and exceptions
  • Module: seedispatch
DP0019E An exception occurred scheduling a job: exception message
Description: An attempt was made to schedule a job and an exception was generated.
  • System action: Operation terminates
  • User response: Examine the exception for the failure reason
  • Module: seedispatch
DP0020E Error attempting to schedule job Job class: Job class Database instance: DB instance Region name: region name
Description: An attempt was made to schedule a job and an error was generated.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seedispatch
DP0021E Failed to connect to region DB instance\region name to dispatch spool id spool id
Description: The dispatcher was unable to connect to the region.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seedispatch
DP0022E Failed to connect to region DB instance\region name to handle JES internal reader submission request for dataset name
Description: The dispatcher was unable to connect to the region.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seedispatch
DP0023E An exception occurred scheduling a print: exception message
Description: A print could not be scheduled and an exception was generated.
  • System action: Operation terminates
  • User response: Examine the exception for the failure reason
  • Module: seedispatch
DP0024E Error attempting to schedule print Sysout class: Sysout class Database instance: DB instance Region name: region name
Description: A print could not be scheduled.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seedispatch
Parent topic: Error Messages


DT - series

DT0001E Unable to connect to database: Database name
Description: A connection to the specified database could not be made.
  • System action: Operation terminates
  • User response: Correct the database name. Make sure the connection strings in the machine config are correct
  • Module:seedeploy
DT0002E Unable to open existing binaries table: Table name
Description: The binaries table could not be opened.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seedeploy
DT0003E An exception occurred: exception message
Description: An exception occurred during the deploy operation.
  • System action: Operation terminates
  • User response: Examine the exception for the failure reason
  • Module:seedeploy
DT0004I The operation completed successfully
Description: The operation completed successfully.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0005E Unable to perform the requested operation
Description: The operation could not be performed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seedeploy
DT0006E The URI provided was not formed correctly.
Description: The supplied URI is not valid.
  • System action: Operation terminates
  • User response: Correct the URI and retry the operation. The URI syntax is described in the command line help, as well as the documentation
  • Module:seedeploy
DT0007E Could not create database or table
Description: A database or table could not be created.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seedeploy
DT0008I Application binaries table is now available
Description: The binaries table is now available for use.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0009I The table is empty
Description: The requested table is empty.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0010I count binaries in table
Description: There are count binaries currently in the table.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0011E File file name not found
Description: The requested file name was not found.
  • System action: Operation terminates
  • User response: Correct the file name and try again
  • Module:seedeploy
DT0012I Deploying name to the database
Description: The file name is being deployed.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0013E An item with the name "name of item being deployed" already exists in the table. You must delete it before you can deploy a new one.
Description: The add operation could not be performed because the item is already present.
  • System action: Operation terminates
  • User response: If you wish to replace the item, delete it first using the delete syntax
  • Module:seedeploy
DT0014E This action requires a resource definition file name to be specified
Description: You have requested an action that requires a resource definition file to be passed as a parameter.
  • System action: Operation terminates
  • User response: Provide the resource definition file name and try again
  • Module:seedeploy
DT0015E A resource definition file name should not be specified for this action
Description: A resource definition file name was specified, but the action does not require it.
  • System action: Operation terminates
  • User response: remove the paramaeter and try again
  • Module:seedeploy
DT0016E The cross-region database must be specified for this action
Description: The action specified needs the cross-region database specified.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module:seedeploy
DT0017E Unexpected table name specified for this action
Description: An incorrect table name was specified for this action.
  • System action: Operation terminates
  • User response: Correct the table name and try again
  • Module:seedeploy
DT0018E Invalid action specified for the command category
Description: An invalid action was specified for the command category being used.
  • System action: Operation terminates
  • User response: Correct the parameter and try again
  • Module:seedeploy
DT0019I number of resource definition files in the cross-region database resource definition files in table
Description: Returns the count of definition files in the cross region database.
  • System action: Operation terminates
  • User response: none
  • Module:seedeploy
DT0020I 1 resource definition file in table
Description: There is 1 resource definition in the table.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0021E This action requires a region startup file name to be specified
Description: A region startup file name needs to be provided.
  • System action: Operation terminates
  • User response: Provide the region startup file name and try again
  • Module:seedeploy
DT0022E A region startup file name should not be specified for this action
Description: A region startup file name was provided for an action that does not require one.
  • System action: Operation terminates
  • User response: Remove the file name and try again
  • Module:seedeploy
DT0023I number of resource definition files in the cross-region database region startup files in table
Description: Displays the count of resource definition files in the cross region database.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0025E Binary name not found
Description: The binary file was not found.
  • System action: Operation terminates
  • User response: Correct the file name and try again
  • Module:seedeploy
DT0026E Resource Definition File file name was not found
Description: The specfied file was not found.
  • System action: Operation terminates
  • User response: Correct the file name and try again
  • Module:seedeploy
DT0027E Region Startup File file name not found
Description: The file name specified was not found.
  • System action: Operation terminates
  • User response: Correct the file name and try again
  • Module:seedeploy
DT0028E Unable to open existing datastore datastore name
Description: The datastore could not be opened.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seedeploy
DT0029I 1 file in datastore
Description: The is one file in the datastore.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0030I number of files in the datastore files in datastore
Description: The number of files in the datastore.
  • System action: none
  • User response: none
  • Module:seedeploy
DT0041E Invalid data file URL for an add, delete, or extract operation. The URL must be of the form: sql://host[/instance]/datastore/filename[?folder=folder-spec]
Description: The URI for the data file operation is invalid.
  • System action: Operation terminates
  • User response: Correct the URI syntax and try again
  • Module:seedeploy
DT0042E Invalid data file URL for a create or list operation. The URL must be of the form: sql://host[/instance]/datastore[?folder=folder-spec]
Description: The URI for the data file operation in invalid.
  • System action: Operation terminates
  • User response: Correct the URI syntax and try again
  • Module:seedeploy
Parent topic: Error Messages


EL - series

EL0000E Message number message number not found
Description: The event logger was asked to find a message, and it couldn’t locate it.
  • System action: The message is not emitted.
  • User response: Make a note of the details and contact technical support.
  • Module:Event Logger
Parent topic: Error Messages


EM - series

EM0001E InvokeService failed: exception
Description: The monitor failed whilst attempting to contact a service.
  • System action: Operation terminates
  • User response: Examine the exception for the failure reason. Check the Event logs for further exceptions
  • Module:seemonitor
EM0002E Failed to connect to database DB instance\DB name
Description: The monitor failed to connect to a database on the given database server.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0003E Failed to parse body of message: details
Description: The monitor failed to parse a message body.
  • System action: Operation terminates
  • User response: Examine the details of the error. Examine the event log for further exceptions
  • Module:seemonitor
EM0004W Ignoring message type "service name"
Description: The message type is being ignored.
  • System action: none
  • User response: none
  • Module:seemonitor
EM0005E ProcessEventThread failed: exception message
Description: An exception occurred whilst an event was being processed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0006E Service installation failed: exception
Description: Installing the seemonitor process as a service failed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0007E Service uninstallation failed: exception
Description: Uninstalling the seemonitor process as a service failed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0008I Event Monitor service installed
Description: The monitor service installed successfully.
  • System action: none
  • User response: none
  • Module:seemonitor
EM0009I Event Monitor service uninstalled
Description: Uninstalling the seemonitor service was successful.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem.
  • Module:seemonitor
EM0010E Invalid parameter for service installation "command-line parameter"
Description: An invalid parameter was specified for service installation.
  • System action: Operation terminates
  • User response: correct the command line and try again
  • Module:seemonitor
EM0011E -service_username and -service_password must be specified with -service_account:user
Description: Invalid command line syntax detected.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module:seemonitor
EM0012E -service_username and -service_password are only allowed with -service_account:user
Description: Invalid command line syntax detected.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module:seemonitor
EM0013E Failed to register event monitor in Server instance cross-region database
Description: The event monitor could not register itself into the cross region database on the specified server.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0014W Unable to create Windows event log source for the listener service: details
Description: An event log source could not be created.
  • System action: Events will not be sent to the event logs
  • User response: Examine the details of the error. Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0015W Unrecognized command-line parameter "parameter string"
Description: Invalid command line syntax detected.
  • System action: none
  • User response: Correct the command line syntax and try again
  • Module:seemonitor
EM0016E Unable to duplicate token for user user name into SEP process SEP process ID: (Windows error code) Windows error message
Description: Authentication or impersonation failed.
  • System action: Operation terminates
  • User response: Examine the windows code and message to help rectify the problem
  • Module:seemonitor
EM0017E User token request from unrecognized SEP at SEP endpoint (PID SEP process ID) for user user name rejected. This may be an attempt to violate security.
Description: A security error occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0018E User token request with incorrect process ID SEP process ID (from SEP at endpoint SEP endpoint) for user user name rejected. This may be an attempt to violate security.
Description: A security error occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0019W Unrecognized value "machine.config value" for machine.config key "machine.config key"
Description: A configuration error in the machine.config file has been detected.
  • System action: none
  • User response: Repair the error and retry
  • Module:seemonitor
EM0020E Protocol-transition token creation requires a Windows 2003 or later domain. SEE Monitor configuration specifies impersonation using protocol-transition mode with local user authentication, which will not work.
Description: The system is configured (in the machine.config file) to use local (non-domain) authentication and protocol-transition mode for impersonation. This is an invalid configuration.
  • System action: Operation terminates
  • User response: Change the configuration to use domain authentication or to use credentials-passing mode for impersonation
  • Module:seemonitor
EM0022E User user name not found in domain "domain name". Unable to generate user token.
Description: A user security token could not be generated because the named user is not defined in the domain.
  • System action: Operation terminates
  • User response: Consult the security administrator
  • Module:seemonitor
EM0023E Unable to retrieve User Principal Name for user user name in domain "domain name". Unable to generate user token.
Description: A user security token could not be generated.
  • System action: Operation terminates
  • User response: Consult the security administrator
  • Module:seemonitor
EM0024E Unable to create token for user "user principal name". Unable to generate user token.
Description: A user security token could not be generated.
  • System action: Operation terminates
  • User response: Consult the security administrator
  • Module:seemonitor
EM0025W Unable to promote impersonation token for user "user principal name" to primary token. Some application operations may throw Security exceptions.
Description: A token could not be promoted for the given user. This is a Windows security configuration issue.
  • System action: Operation terminates
  • User response: This may be benign. If other problems occur when using this user account, consult the security administrator
  • Module:seemonitor
EM0026I Token created using protocol transition (no password supplied) for user "user principal name".
Description: A token was created.
  • System action: none
  • User response: none
  • Module:seemonitor
EM0027E A exception type exception occurred while trying to create a token: exception message exception stack trace
Description: An exception occurred during token generation.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0028E Failure updating user authority table for user username in database instance DB instance: details
Description: An update operation on the given database/table was unsuccessful. The user’s information could not be stored for impersonation purposes.
  • System action: Operation terminates
  • User response: Examine the error details for information to help resolve the issue
  • Module:seemonitor
EM0029E Token request for user username rejected: user is not signed on or the user database could not be accessed (additional information)
Description: A user security token could not be relayed to the requesting SEP.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0030E A exception type exception occurred while trying to retrieve user credentials: exception message exception stack trace
Description: An exception occurred retrieving user information for impersonation.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: Seemonitor
EM0031E A exception type exception occurred while trying to find the authority for user username: exception message exception stack trace
Description: An exception occurred retrieving user information for impersonation.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0032E A exception type exception occurred while trying to retrieve a monitor key: exception message at: exception stack trace
Description: An exception occurred retrieving system information for impersonation.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0033E A exception type exception occurred while trying to create an encryptor: exception message at: stack trace
Description: An exception occurred creating a message for impersonation.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0034E A exception type exception occurred while trying to send credentials: exception message at: stack trace
Description: An exception occurred sending a message for impersonation.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0035E A exception type exception occurred while trying to find a user authority: exception message at: stack trace
Description: An exception occurred processing an impersonation request.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0036W DNS lookup failed when attempting to reach endpoint 'event monitor endpoint' to perform an internal transaction request. Ensure that the host name is valid and that the seemonitor service is running on that machine. Alternatively you can use SEE Administration to remove the event monitor from the list of registered event monitors.
Description: An event point could not be reached due to DNS lookup failure.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0037W DNS lookup failed when attempting to reach endpoint 'event monitor endpoint' while stopping region region name. Ensure that the host name is valid and that the seemonitor service is running on that machine. Alternatively you can use SEE Administration to remove the event monitor from the list of registered event monitors.
Description: An event point could not be reached due to DNS lookup failure.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0038E Unable to install signon user exit from assembly: assembly path
Description: A signon exit could not be installed into the system.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem. Make sure that the region configuration is correct, and that the exit assembly exists in the configured location. Ensure that the signon exit is compiled correctly and is working as it should
  • Module:seemonitor
EM0039E Message from signon user exit: message from exit
Description: An error message was received from the signon exit.
  • System action: Operation terminates
  • User response: Examine the message and rectify the problem
  • Module:seemonitor
EM0040E Signon user exit returned with error status. request type request for user username failed.
Description: The signon exit failed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0041I Event monitor starting
Description: Informational message.
  • System action: none
  • User response: none
  • Module:seemonitor
EM0042I Event monitor pre-shutdown starting
Description: Informational message.
  • System action: none
  • User response: none
  • Module:seemonitor
EM0043I Event monitor closing down
Description: Informational message.
  • System action: none
  • User response: none
  • Module:seemonitor
EM0044W DNS lookup failed when attempting to reach endpoint 'event monitor endpoint' while querying SEP status for region region name. Ensure that the host name is valid and that the seemonitor service is running on that machine. Alternatively you can use SEE Administration to remove the event monitor from the list of registered event monitors.
Description: An event point could not be reached due to DNS lookup failure.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0045E Unexpected null or empty password
Description: A password was null or empty.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0046E Unable to install logon provider from assembly: assembly path
Description: The login provider could not be installed from the given assembly.
  • System action: Operation terminates
  • User response: Make sure the assembly is present, and valid
  • Module:seemonitor
EM0047E Service Bus Logon Provider: Required Azure AppFabric Service Bus parameter for parameter description not specified. Set this value in the machine.config file under the key "key name".
Description: Required configuration in machine.config is missing.
  • System action: Operation terminates
  • User response: Make sure that the correct configuration information is in machine.config
  • Module:seemonitor
EM0048E The logon provider name logon provider does not support impersonation. Logon request rejected.
Description: The configured logon provider does not support impersonation.
  • System action: Operation terminates
  • User response: Make sure that the correct logon provider is used
  • Module:seemonitor
EM0049E Logon request to Service Bus Logon service failed: exception type Exception message "exception message" Inner exception inner exception type Inner exception message "inner exception message"
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
EM0050E Unable to connect to Service Bus Logon service: exception type Exception message "exception message" Inner exception inner exception type Inner exception message "inner exception message"
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seemonitor
Parent topic: Error Messages


EP - series

EP0001E An exception occurred: 0
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module:seesep
EP0002I "Exception" or "Inner exception" stack trace: stacktrace
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0003E Transaction 'Transaction name' ABEND abendcode, (resp). Backout successful.
Description: A transaction abended withn exception occurred.
  • System action: none
  • User response: Use the abendcode and resp code to help isolate and rectify the problem.
  • module: sessep
EP0004E Invalid command-line option: -proxy cannot be specified with other options
Description: A syntax error on the command line was detected.
  • System action: Operation terminates
  • User response: Fix the command line and try again
  • module: sessep
EP0005E Invalid command-line option: -session_service value must be in double quotes
Description: A syntax error on the command line was detected.
  • System action: Operation terminates
  • User response: Fix the command line and try again
  • module: sessep
EP0006I Run svcutil.exe to generate SEP proxies. Press OK to terminate
Description: The required SEP proxies do not seem to be in place.
  • System action: none
  • User response: Run the Svcutil utility to rectify the problem and try again
  • module: sessep
EP0007E An exception occurred: exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0008E Invalid command-line option: -configuration_service value must be in double quotes
Description: Invalid command line syntax detected.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module: seesep
EP0009E Invalid command-line option: -event_monitor_service value must be in double quotes
Description: Invalid command line syntax detected.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module: seesep
EP0012E An exception occurred: exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0016E Error invoking program: Program Name Exception
Description: An error was detected running the program.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0017E Details for request Request ID not found
Description: An error was detected processing the request.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0018E Transaction 'Transaction ID' is not recognized. Check that the transaction name is correct.
Description: An error was detected whilst attempting to execute the given transaction.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0019E An exception occurred: exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0020I PLTPI - No PLT Specified
Description: No PLT was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0021I PLTPI - List(PLT list name) Processing Started
Description: Processing started
  • System action: none
  • User response: none
  • Module: seesep
EP0022I PLTPI - List(PLT list name) Processing Completed
Description: Processing completed
  • System action: none
  • User response: none
  • Module: seesep
EP0023W PLTPI - PLT List PLT list name not found
Description: No PLT List was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0024W PLTPI - List(PLT list name) PLT program program name not found
Description: PLT program was not found
  • System action: none
  • User response: Ensure the missing program is available and restart the region
  • Module: seesep
EP0025E PLTPI - List(PLT list name) Program=program name abend
Description: An abend condition was detected during PLTPI processing.
  • System action: Operation terminates
  • User response: Fix the offending program and try again
  • Module: seesep
EP0026I Loaded program program name from path
Description: The specified program was loaded from the location.
  • System action: none
  • User response: none
  • Module: seesep
EP0027E Terminal terminal id does not exist. Unable to start transaction transaction id.
Description: The specified Terminal does not exist, and therefore the system could not start the transaction.
  • System action: The transaction is not run
  • User response: This may be an application error, in an EXEC CICS START request or similar. Correct the application or ensure the required terminal is connected
  • Module: seesep
EP0028E Cannot specify '-configuration_service' or '-session_service' with '-debug'
Description: Invalid command line syntax detected.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module: seesep
EP0029E Invalid '-match" value
Description: Invalid command line syntax detected.
  • System action: Operation terminates
  • User response: Correct the command line syntax and try again
  • Module: seesep
EP0030E Failed to register with event monitor (RC=Return code from event monitor registration)
Description: The SEP could not register with the event monitor.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0031E An exception occurred: exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0032E Region region name is not enabled for dynamic debugging
Description: The specified region is not enabled for dynamic debugging.
  • System action: Dynamic debugging is not allowed
  • User response: Configure the region for dynamic debugging using the administration tool, and retry the operation
  • Module: seesep
EP0033E Failed to connect to region region name
Description: The region requested could not be reached.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0034E Failed to start SEP process
Description: The SEP process could not be started.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0035E Started SEP failed to register with the region region name
Description: The SEP started but could not register itself with the region.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0036I PLTPI Phase 2 - No PLT Specified
Description: No PLT was specified, so no PLT processing occurred.
  • System action: none
  • User response: none
  • Module: seesep
EP0037I PLTPI Phase 2 - List(PLT list name) Processing Started
Description: PLT processing started.
  • System action: none
  • User response: none
  • Module: seesep
EP0038I PLTPI Phase 2 - List(PLT list name) Processing Completed
Description: PLTP processing completed.
  • System action: none
  • User response: none
  • Module: seesep
EP0039W PLTPI Phase 2 - PLT List PLT list name not found
Description: The specified PLT list was not found.
  • System action: none
  • User response: Determine the reason for the missing PLT list and rectify
  • Module: seesep
EP0040W PLTPI Phase 2 - List(PLT list name) PLT program program name not found
Description: The PLT program specified was not found.
  • System action: none
  • User response: Make sure that the PLT program is on one of the configured paths and retry
  • Module: seesep
EP0041E PLTPI Phase 2 - List(PLT list name) Program=program name abend
Description: An abend occurred during PLTP program execution.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0042I PLTSD - No PLT Specified
Description: No PLT was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0043I PLTSD - List(PLT list name) Processing Started
Description: PLT processing started.
  • System action: none
  • User response: none
  • Module: seesep
EP0044I PLTSD - List(PLT list name) Processing Completed
Description: PLT processing completed.
  • System action: none
  • User response: none
  • Module: seesep
EP0045W PLTSD - PLT List PLT list name not found
Description: PLT not found.
  • System action: none
  • User response: Check the configuration and ensure that the specified list is configured
  • Module: seesep
EP0046W PLTSD - List(PLT list name) PLT program program name not found
Description: The program name was not found.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0047E PLTSD - List(PLT list name) Program=program name abend
Description: The program abended.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0048I PLTSD Phase 2 - No PLT Specified
Description: No PLT was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0049I PLTSD Phase 2 - List(PLT list name) Processing Started
Description: LT processing has started.
  • System action: none
  • User response: none
  • Module: seesep
EP0050I PLTSD Phase 2 - List(PLT list name) Processing Completed
Description: PLT Processing completed.
  • System action: none
  • User response: none
  • Module: seesep
EP0051W PLTSD Phase 2 - PLT List PLT list name not found
Description: PLT List not found.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0052W PLTSD Phase 2 - List(PLT list name) PLT program program name not found
Description: PLT program not found.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0053E PLTSD Phase 2 - List(PLT list name) Program=program name abend
Description: PLT processing encountered an abend in the specified program.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0054I native ES message
Description: A message was received from a native enterprise server.
  • System action: none
  • User response: none
  • Module: seesep
EP0055I JCL submit native ES message:1 initiated, type 2
Description: A JCL job was submitted to a native enterprise server.
  • System action: none
  • User response: none
  • Module: seesep
EP0056E JCL submit native ES message:1 failed, type 2 RC=3 request queued
Description: JCL submission failed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0057I JCL Job Number native ES message
Description: Job submitted with native ES job number.
  • System action: Operation terminates
  • User response: none
  • Module: seesep
EP0058I Unable to debug as region region name is not started
Description: Can’t start a debug session as the target region is not running.
  • System action: Operation terminates
  • User response: Start the region and try the operation again
  • Module: seesep
EP0059E The WCF service endpoints could not be opened. Check that you are authorized to use the Net.Tcp Port Sharing Service. See "WCF Authorization" in the Enterprise Server for .NET documentation for more information.
Description: WCF endpoints are not responding.
  • System action: Operation terminates
  • User response: Make sure that the WCF infrastructure has been initialized correctly
  • Module: seesep
EP0060E Unable to retrieve identity for user ID 0.
Description: The SEP could not retrieve information for the user from the Event Monitor.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem. Ensure the user has signed on to the region since it was last started
  • Module: seesep
EP0061E Error releasing ENQ (QNAME=resource QNAME, RNAME=resource RNAME)
Description: A release enq failed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0062E Invalid BMS map location type specified (type=BMS map location type)
Description: A path to BMS map locations is invalid.
  • System action: Operation terminates
  • User response: Correct the BMS path and retry
  • Module: seesep
EP0063E Invalid program location type specified (type=program location type)
Description: An invalid program location was specified.
  • System action: Operation terminates
  • User response: Correct the program locations path and retry
  • Module: seesep
EP0064E No event monitor running and unable to start one
Description: An event monitor is not running and starting a new one failed.
  • System action: Operation terminates
  • User response: Check event monitor configuration. Check the service is installed, and is configured correctly
  • Module: seesep
EP0065W Shared memory reallocated by another transaction Expected memory length : Expected memory length Expected start address: Expected start address Expected end address: Expected end address Expected memory type: Expected memory type Actual memory length: Actual memory length Actual start address: Actual start address Actual end address: Actual end address Actual memory type: Actual memory type
Description: A shared memory area was reallocated by another transaction.
  • System action: none
  • User response: none
  • Module: seesep
EP0066E Error processing request message for request request id Exception message: exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0067E Invalid request for program 'program name'
Description: An invalid request for the specified program was received.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0068E Failed to load JES engine 'JES engine assembly name' EP0069E An exception occurred processing JCL submission request: message
Description: An exception occurred.
  • System action: The JES engine is unavailable for processing.
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0070E JOB Submit JES interface initialization failed. RC=CASSPOOL initialisation return-code
Description: During a job submit operation, the JES interface failed to initialize with the specified return code.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0071E CASA_Sub_JCL: Missing or invalid job submission request
Description: The job submission request was invalid.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0072E Details for spool id spool id of job requested for execution not found
Description: The spool id for the requested job execution does not exist.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0073E JOB execution JES interface initialization failed. RC=CASSPOOLreturn-code
Description: The JES interface failed to initialize during job execution.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0074E An exception occurred while running JOBNAME=Job name,JOBNUM=Job number Exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0075E Error executing program program name exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0076E Job submission failed. No -x parameter received for session 'session identifier'
Description: A job submission request from the administration console, the cassub utility, or another source was rejected because the request was missing required information.
  • System action: The request is rejected
  • User response: Contact Technical Support
  • Module: seesep
EP0077E Invalid CASOUT request CASA_Out_JCL:
Description: A request to the CASA_Out_JCL service is invalid.
  • System action: none
  • User response: Contact Technical Support
  • Module: seesep
EP0078E CASOUT JES interface initialization failed. RC=CASSPOOL initialisation return-code
Description: The JES interface failed to initialize with the given return code.
  • System action: Operation terminates
  • User response: Look up the CASSPOOL return code in the native enterprise server documentation and rectify the problem
  • Module: seesep
EP0079E Invalid input parameter 'invalid input parameter' CASA_Out_JCL:
Description: An invalid input parameter was detected.
  • System action: Operation terminates
  • User response: Correct the input and try again
  • Module: seesep
EP0080E Missing or invalid CASOUT request CASA_Out_JCL:
Description: The casout request is either missing or invalid.
  • System action: Operation terminates
  • User response: Correct the request and try again
  • Module: seesep
EP0081E Unsupported function 'unsupported function' CASA_Out_JCL:
Description: The specified function is unsupported.
  • System action: Operation terminates
  • User response: Consider alternate ways of accomplishing this task. If the unsupported functionality is critical to your application, contact Technical Support
  • Module: seesep
EP0082E Invalid job or dd for 'job number'. Retrieval request ignored CASA_Out_JCL:
Description: An invalid job or dd name was detected.
  • System action: Operation terminates
  • User response: Correct the request and try again
  • Module: seesep
EP0083E Invalid job number: job number CASA_Out_JCL:
Description: An invalid job number was specified.
  • System action: Operation terminates
  • User response: Correct the request and try again
  • Module: seesep
EP0085E Job job number is not on the "Output Hold" queue CASA_Out_JCL
Description: The requested job number is not on the output hold queue.
  • System action: none
  • User response: Correct the request and try again
  • Module: seesep
EP0086E Failure to move job job number to the "Input" queue CASA_Out_JCL:
Description: The specified job number could not be moved to the Input queue.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0087E Job job number0 not found CASA_Out_JCL
Description: The specified job number was not found.
  • System action: Operation terminates
  • User response: Correct the job number and try the operation again
  • Module: seesep
EP0088E Restart processing not enabled CASA_Out_JCL:
Description: Restsart processing is not enabled.
  • System action: Operation terminates
  • User response: If you wish to use restart processing, modify the configuration to do so
  • Module: seesep
EP0089I Job job number removed from input-queue CASA_Out_JCL:
Description: The specified job number was removed from the input queue.
  • System action: none
  • User response: none
  • Module: seesep
EP0090I Kill for job job number issued CASA_Out_JCL:
Description: A kill request for the specified job number has been issued.
  • System action: none
  • User response: none
  • Module: seesep
EP0091W Job job number is not active. Kill request ignored CASA_Out_JCL
Description: A kill request for the specified job number was received, but the job is not active.
  • System action: Operation terminates
  • User response: none
  • Module: seesep
EP0092I Job job number flushed CASA_Out_JCL:
Description: The specified job number was flushed.
  • System action: none
  • User response: none
  • Module: seesep
EP0093W Job 0 not flushed Job number 2 CASA_Out_JCL:
Description: The specified job number was not flushed.
  • System action: Operation terminates
  • User response: none
  • Module: seesep
EP0094I Cannot debug a 'actual region type' region using 'specified region type' match criteria
Description: A CICS SEP must be used to debug a CICS region; a JES SEP must be used to debug a JES region.
  • System action: none
  • User response: Correct the parameters for the debug SEP and try again
  • Module: seesep
EP0095I JESPI - No exit specified
Description: No exit was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0096I JESPI Phase 2 - No exit specified
Description: No exit was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0097I JESSD - No exit Specified
Description: No exit was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0098I JESSD Phase 2 - No exit Specified
Description: No exit was specified.
  • System action: none
  • User response: none
  • Module: seesep
EP0099E Invalid remote catalog request SEE_Catalog:
Description: An invalid remote catalog request was received.
  • System action: The request is ignored
  • User response: If necessary, correct the request and try again
  • Module: seesep
EP0100E PRINT execution JES interface initialization failed. RC= CASSPOOLreturn-code
Description: The JES interface initialization failed for the specified operation with a return code.
  • System action: Operation terminates
  • User response: Look the return code up in the JCL documentaton and fix the problem
  • Module: seesep
EP0101E An exception occurred while printing JOBNAME= Job name,JOBNUM=1 Exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0102E Failed to retrieve spool record spool record for printing
Description: Failed to retrieve the given spool record for printing.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0103I SEP worker role is being stopped - terminating active work
Description: The SEP worker role is being stopped. All active work is being terminated.
  • System action: Active work is being terminated in antipication of the SEP worker role terminating
  • User response: none
  • Module: seesep
EP0104I Job job number released: return code CASA_Out_JCL:,
Description: The job was released with the given return code.
  • System action: none
  • User response: none
  • Module: seesep
EP0105E Job job number is not in the Input Hold queue: return code
Description: The specified job number is not in the input hold queue.
  • System action: Operation terminates
  • User response: Correct the request and try again
  • Module: seesep
EP0106E Job job number does not exist: return code
Description: The specified job number does not exist.
  • System action: Operation terminates
  • User response: none
  • Module: seesep
EP0107I Job job number requeued from class original job class to new job class: return code
Description: The specified job number was requeued to a new class.
  • System action: none
  • User response: none
  • Module: seesep
EP0108E Unknown return code - job job number: return code
Description: The specified job returned an unknown return code.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0108W Failed to pre-load assembly 'assembly name'
Description: The specified assembly could not be preloaded.
  • System action: preload terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0110E Invalid initiator id 'initiator id'
Description: The specified initiator ID is invalid.
  • System action: Operation terminates
  • User response: Specify the correct initiator ID and try again
  • Module: seesep
EP0111E Initiator with id 'initiator id' not found
Description: The specified Initiator ID was not found.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seesep
EP0112I Initiator enabled
Description: The initiator was enabled.
  • System action: none
  • User response: none
  • Module: seesep
EP0113I Initiator disabled
Description: The initiator was disabled.
  • System action: none
  • User response: none
  • Module: seesep
EP0114E Invalid printer id 'printer id'
Description: The specified printer is invalid.
  • System action: Operation terminates
  • User response: Make sure that the requested printer infrastructure exists and retry the operation
  • Module: seesep
EP0115E Printer with id 'printer id' not found
Description: The specified printer is invalid.
  • System action: Operation terminates
  • User response: Make sure that the requested printer infrastructure exists and retry the operation
  • Module: seesep
EP0116I Printer enabled
Description: The Printer is enabled.
  • System action: none
  • User response: none
  • Module: seesep
EP0117I Printer disabled
Description: The printer is disabled.
  • System action: none
  • User response: none
  • Module: seesep
Parent topic: Error Messages


EX - series

EX0001E An exception was detected (internal ID internal exception ID): exception type exception message exception stack trace text Inner Exception Details...
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem.
  • Module: none
EX0002W An exception was detected (internal ID internal exception ID): exception type exception message exception stack trace text Inner Exception Details....
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem.
  • Module: seesep
Parent topic: Error Messages


JA - series

JA0001E Only one of -job, -initiator or -printer may be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0002E -job, -initiator or -printer must be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0003E -job must be specify a valid job number Used by seeout
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0004E Must specify one of -list, -restart, -kill, -modify, -release or -flush
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0005E -step:<stepname> [:<procstepname>] must be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0006E -class: <classes> must be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0007E Must specify one of -create, -enable, -disable or -list
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0008E An initiator id is required for the -disable or -enable option
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0009E An initiator id is not required for the -create or -list option
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0010E A printer id is required for the -disable or -enable option
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0011E A printer id is not required for the -create or -list option
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0012E Invalid -server:machine[:port] specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0013E -name:<name> must be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeout
JA0014I Administration request for server name:port number
Description: An administration request using the server and port specified.
  • System action: none
  • User response: none
  • Module: seeout
JA0015E An exception occurred processing the request: exception message
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seeout
Parent topic: Error Messages


KC - series

KC0009E PCT entry transaction name disabled, cannot execute transaction
Description: The transaction cannot be executed as it is disabled in the PCT.
  • System action: Operation terminates
  • User response: If you wish to run this transaction, enable it in the PCT.
  • Module: SEP
Parent topic: Error Messages


LO - series

LO0001I Service Bus Logon Service starting
Description: The service bus logon service is being started.
  • System action: none
  • User response: none
  • Module: Logon Provider
LO0002E Unable to connect to Service Bus at Service Bus URI: Exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Ensure the URI is correct. Ensure the Windows Azure AppFabric Service Bus at the URI is available. Examine the console output and event log for further information to help resolve the problem
  • Module: Logon Provider
LO0003E Unable to install signon user exit from assembly: assembly path
Description: The signon exit that was configured in the region start up configuration could not be loaded from the assembly.
  • System action: Operation terminates
  • User response: Make sure that the signon exit is specified correctly in the region start up configuration, and that the assembly is valid
  • Module: Logon Provider
LO0004I Service is running press <Enter> to exit
Description: The logon service is now running.
  • System action: none
  • User response: none
  • Module: Logon Provider
LO0005I Service is shutting down
Description: The logon service is shuttiong down.
  • System action: none
  • User response: none
  • Module: Logon Provider
LO0006I Logon request received for user user name
Description: A logon request for the specified user name has been received.
  • System action: none
  • User response: none
  • Module: Logon Provider
LO0007E Required Azure AppFabric Service Bus parameter for parameter description not specified. Set this value in the app.config file under the key "key name".
Description: A configuration error has been detected.
  • System action: none
  • User response: Set this value in the app.config file under the key "key name"
  • Module: Logon Provider
Parent topic: Error Messages


LS - series

LS0001W Unrecognized command-line parameter "parameter string"
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seelistener
LS0006I Response received for: session id
Description: A response for the given session id was received.
  • System action: none
  • User response: none
  • Module: seelistener
LS0007I Worker thread starting for protocol on port port
Description: The worker thread for the given protocol and port was started.
  • System action: none
  • User response: none
  • Module: seelistener
LS0008E Unable to create protocol handler: exception message
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0009W Port configuration in seelistener.exe.config ignored as option '-region' specified
Description: The port configuration in the configuration file was overridden by the -region parameter. The listener will listen on its default ports and send all requests to the specified region.
  • System action: none
  • User response: none
  • Module: seelistener
LS0014E An exception occurred:exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0017I protocol name Listener starting on port port number ,
Description: A listener is starting on the given port for the specified protocol.
  • System action: none
  • User response: none
  • Module: seelistener
LS0019E Exception in protocol handler: exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0020I SEE listener shutting down
Description: The listener is shutting down.
  • System action: none
  • User response: none
  • Module: seelistener
LS0021W The "-was" option is ignored if "-dispatcher:URL" is specified.
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seelistener
LS0023I conversation type listener channel closing
Description: The specified listener channel is closing.
  • System action: none
  • User response: none
  • Module: seelistener
LS0024E A exception type exception occurred while submitting a console message to region region name: exception message The message was: console message that could not be submitted
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0025W TN3270 conversation conversation ID: Discarding NVT data from client
Description: The client sent non-3270 data, which is currently not supported. The data has been discarded.
  • System action: none
  • User response: none
  • Module: seelistener
LS0026E TN3270 conversation conversation ID: Illegal sequence in TN3270E header (x'FF0:X2') 1 = invalid byte in hex
Description: A TN3270 protocol error occurred.
  • System action: The conversation is terminated
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0027E TN3270 conversation conversation ID : Negotiation failed (description of negotiation stage), terminating conversation
Description: TN3270 negotiation failed.
  • System action: The conversation is terminated
  • User response: none
  • Module: seelistener
LS0028E protocol name conversation conversation ID: Unexpected exception (description of where exception occurred) exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0030W Invalid value invalid heartbeat value specified for heartbeat ignored
Description: An invalid value was specified during a heartbeat request.
  • System action: Operation terminates
  • User response: none
  • Module: seelistener
LS0033E protocol name conversation conversation ID: unable to send data: conversation ended
Description: A protocol error for the specified protocol occurred.
  • System action: The conversation is terminated.
  • User response: none
  • Module: seelistener
LS0034E protocol name conversation conversation ID: Transaction insert exception: exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0035I Shutdown initiated
Description: The listener has been asked to shut down.
  • System action: Listener is terminating
  • User response: none.
  • Module: seelistener
LS0036E protocol name conversation conversation ID: exception receiving data: exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0037E protocol name conversation conversation ID: exception sending data: exception message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0039E Unable to process configuration file "filename"
Description: The specified configuration file could not be processed.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0040W Channel "channel name" has an invalid attribute name attribute - skipping it
Description: An error in the configuration has been detected.
  • System action: none
  • User response: Fix the configuration file
  • Module: seelistener
LS0041E Service installation failed: exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0042E Service uninstallation failed:exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seelistener
LS0043I Listener service installed
Description: The listener service was installed.
  • System action: none
  • User response: none
  • Module: seelistener
LS0044I Listener service uninstalled
Description: The listener service was uninstalled.
  • System action: none
  • User response: none
  • Module: seelistener
LS0045E Invalid parameter for service installation "command-line parameter"
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seelistener
LS0046E -service_username and -service_password must be specified with -service_account:user
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seelistener
LS0047E -service_username and -service_password are only allowed with -service_account:user
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seelistener
LS0048W Unable to create Windows event log source for the listener service: details
Description: The listener could not create a Windows event log source to emit events to.
  • System action: Events will not be logged to the event log.
  • User response: Make a note of any details, and attempt to rectify the problem
  • Module: seelistener
LS0049E protocol name conversation conversation ID internal error: description
Description: An error occurred in the specified conversation.
  • System action: The conversation is terminated
  • User response: Make a note of the error, and attempt to fix it
  • Module: seelistener
LS0050W TN3270 conversation conversation ID: Unsupported TN3270E data type data type value - discarding record
Description: An invalid TN3270 data type was received in the conversation.
  • System action: the data is discarded
  • User response: none
  • Module: seelistener
LS0051W TN3270 conversation conversation ID: Unsupported TN3270 command command code ignored
Description: An invalid TN3270 command was received in the specified conversation.
  • System action: the command is ignored
  • User response: none
  • Module: seelistener
LS0052I TN3270 conversation conversation ID: Rejecting invalid device type "device type string"
Description: An invalid device type was received in the conversation.
  • System action: The device type is rejected
  • User response: none
  • Module: seelistener
LS0053W TN3270 conversation conversation ID: Negotiation error (description of error), continuing
Description: An error was detected during negotiation.
  • System action: the error is ignored
  • User response: none
  • Module: seelistener
LS0054I TN3270 conversation conversation ID: Received "DO", "DON'T", "WILL", or "WON'T" for unrecognized option option code, replying with "WON'T" or "DON'T"
Description: An unrecognized option code was received.
  • System action: none
  • User response: none
  • Module: seelistener
LS0055W protocol name conversation conversation ID timed out waiting for client
Description: A protocol timeout occurred.
  • System action: none
  • User response: none
  • Module: seelistener
LS0056W TN3270 conversation conversation ID: Discarding data length bytes of non-record outbound data
Description: the specified number of bytes was discarded in the conversation.
  • System action: Bytes are discarded
  • User response: none
  • Module: seelistener
LS0057E protocol name conversation conversation ID: Terminal autoinstall failed message
Description: The terminal auto install failed.
  • System action: The conversation with the client is terminated
  • User response: Make a note of the error message and attempt to rectify based on its content
  • Module: seelistener
LS0058I protocol conversation conversation number (termid "terminal id") on channel "channel name" from client address
Description: Information about a conversation. This message may be displayed before other messages about the conversation, to identify the client system and other parameters.
  • System action: none
  • User response: Make note of the message if you are investigating other issues related to the listener
  • Module: seelistener
LS0059W TN3270 conversation conversation ID: Proceeding with invalid device type "device type string"
Description: An invalid device type was detected.
  • System action: Processing continues
  • User response: none
  • Module: seelistener
LS0060E Unexpected null response encountered
Description: An unexpected null response was detected.
  • System action: none
  • User response: none
  • Module: seelistener
Parent topic: Error Messages


MS - series

MS0001W Unexpected key received
Description: An unexpected key was received.
  • System action: key is ignored
  • User response: none
  • Module: Dfhzcmap
MS0002W Unexpected PgDn, already at bottom of list
Description: An unexpected PgDn was received and already at the bottom of the list.
  • System action: PgDN is ignored
  • User response: none
  • Module: Dfhzcmap
MS0003W Unexpected PgUp, already at top of list
Description: An unexpected PgUp was received and already at the top of the list.
  • System action: PgUp is ignored
  • User response: none
  • Module: Dfhzcmap
MS0004W Invalid selection
Description: An invalid selection was made.
  • System action: none
  • User response: Make a valid selection
  • Module: Dfhzcmap
MS0006E Unexpected response (EIBRESP) for function EIBFN=function number
Description: An unexpected response was received for the specified function.
  • System action: none
  • User response: Examine the return codes and repair the fault
  • Module: Dfhzcmap
MS0007E Error deleting mapset, RC=return code
Description: The mapset could not be deleted for the reason specified.
  • System action: The mapset is not deleted
  • User response: make a note of the return code
  • Module: Dfhzcmap
MS0008W Internal DFHMSD name (name from DFHMSD macro) does not match mapset (mapset)
Description: The macro specified does not match the mapset.
  • System action: none
  • User response: This indicates a problem with the mapset file. Attempt to correct the file
  • Module: Dfhzcmap
MS0009W Initial mapset mapset not found
Description: The initial mapset specified was not found.
  • System action: The initial mapset is not displayed
  • User response: Make sure that the mapset is on the path and try again
  • Module: Dfhzcmap
MS0010W Initial map map not found in mapset mapset
Description: The initial map was not found in the mapset.
  • System action: The initial map is not displayed
  • User response: Make sure that the mapset contains the specified map and try again
  • Module: Dfhzcmap
MS0011E Internal processing error additional information
Description: An internal processing error was detected.
  • System action: Map processing is terminated
  • User response: Make a note of the additional information and attempt to rectify the problem
  • Module: Dfhzcmap
MS0012I About to delete mapset mapset, press <ENTER> to confirm
Description: The specified mapset is about to be deleted. Click Enter to confirm.
  • System action: none
  • User response: Click Enter to confirm deletion
  • Module: Dfhzcmap
MS0013I Delete mapset request cancelled
Description: A delete mapset request was cancelled.
  • System action: The mapset is not deleted
  • User response: none
  • Module: Dfhzcmap
MS0014I transaction transaction complete
Description: The transaction completed.
  • System action: none
  • User response: none
  • Module: Dfhzcmap
MS0015E Unexpected response (EIBRESP) for function function name
Description: An unexpected response for the specified function was detected.
  • System action: none
  • User response: Make a note of the error code, and attempt to rectify
  • Module: Dfhzcmap
MS0016E Error opening mapset mapset, RC=EIBRESP
Description: The specified mapset could not be opened.
  • System action: mapset processing is terminated
  • User response: Make a note of the error code, and attempt to rectify
  • Module: Dfhzcmap
MS0017I Mapset deletion is not supported
Description: The delete operation requested is not supported.
  • System action: none
  • User response: Delete the mapset manually. Note that the mapset may be stored in the database; see the seedeploy documentation for more information
  • Module: Dfhzcmap
Parent topic: Error Messages


OP - series

OP0001I From (user id,terminal id,transaction id) message text
Description: A message from user on terminal running transaction has asked to display the message upon the console.
  • System action: none
  • User response: none
  • Module: Write to operator
Parent topic: Error Messages


PC - series

PC0001E Program 'program name' disabled for transid transaction name
Description: The specified program associated with the specified transaction has been disabled.
  • System action: none
  • User response: Enable the transaction in the region definition and try again.
  • Module: CICS SEP
Parent topic: Error Messages


PS - series

PS0001I Configuration in seepubsub.exe.config ignored as URL specified on command line
Description: Configuration in the seepubsub.exe.config file is ignored when a URL is specified on the command line.
  • System action: none
  • User response: none
  • Module: pubsub
PS0002I Events from host:port will be passed to exit program "exit program name"
Description: The specified exit name will receive all events from the specified host and port.
  • System action: none
  • User response: none
  • Module: pubsub
PS0003E Internal error: No exit program name for subscription to host:port
Description: An internal error occurred in seepubsub.
  • System action: Subscription processing is terminated
  • User response: Contact Technical Support
  • Module: pubsub
PS0004E Error unsubscribing from host:port: message
Description: The module could not unsubscribe from the given host and port.
  • System action: Unsubscribe failed. The region should eventually detect that the subscriber is no longer connected. If this is a durable subscriber, event messages will be queued for it
  • User response: To prevent messages from being queued, stop and restart the region
  • Module: pubsub
PS0005I Unsubscribed from host:port
Description: The unsubscribe request was successful.
  • System action: none
  • User response: none
  • Module: pubsub
PS0006E URL URL is invalid (must be mfbinp:://host:port); subscription ignored
Description: The specified URL is malformed.
  • System action: The subscription request is ignored
  • User response: Correct the URL and try again
  • Module: pubsub
PS0007E Unable to subscribe to host:port: message
Description: A subscription request to the specified host and port failed.
  • System action: Subscription is terminated
  • User response: Make a note of the message and attempt to fix the problem
  • Module: pubsub
PS0008I Subscribed to host:port
Description: The subscription to the specified host and port was successful.
  • System action: none
  • User response: none
  • Module: pubsub
PS0009E If a URL is supplied, an exit program name must also be provided
Description: If you specify a URL, an exit program must also be given.
  • System action: Service installation fails
  • User response: Correct the command line and try again
  • Module: pubsub
PS0010E Unable to load or initialize exit program "program" for host:port: message
Description: The specified exit program could not be loaded or initialized.
  • System action: Exit program is not in a state to be called
  • User response: Examine the message and fix the problem
  • Module: pubsub
PS0011E Error calling exit program "program" for host:port: message
Description: The specified exit program for the given subscription could not be called.
  • System action: The exit is not called
  • User response: Examine the message and rectify the problem
  • Module: pubsub
PS0012E -service_username and -service_password must be specified with -service_account:user
Description: The command line options for service installation are invalid.
  • System action: The service is not installed
  • User response: Fix the command line
  • Module: pubsub
PS0013E -service_username and -service_password are only allowed with -service_account:user
Description: The command line options for service installation are invalid.
  • System action: The service is not installed
  • User response: Fix the command line
  • Module: pubsub
PS0014E Invalid value "value" for option option
Description: The command line options for service installation are invalid.
  • System action: The service is not installed
  • User response: Fix the command line
  • Module: pubsub
PS0015E No subscriptions specified on the command line or in seepubsub.exe.config; exiting
Description: Either a subscription must be specified on the command line, or one or more subscriptions specified in the configuration file.
  • System action: none
  • User response: Fix the command line or configuration
  • Module: pubsub
PS0016E Service installation failed: exception
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: pubsub
PS0017I Subscription service installed
Description: the service was installed.
  • System action: none
  • User response: none
  • Module: pubsub
PS0018I Subscription service uninstalled
Description: The service was uninstalled.
  • System action: none
  • User response:
  • Module: pubsub
PS0019E Service uninstallation failed: exception
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: pubsub
PS0020W Unable to create Windows event log source for the seepubsub service: details
Description: the pubsub module could not create and event log source.
  • System action: event log messages from this module will be lost
  • User response: Examine the details in the message and attempt to repair
  • Module: pubsub
PS0021W Connection to host:port lost
Description: The connection to the specified host and port have been lost.
  • System action: If this is a durable subscription, events will be cached until the connection is re-established
  • User response: none
  • Module: pubsub
PS0022I Durable subscription to host:port will be periodically retried
Description: A durable subscription has failed, and will be retried.
  • System action: none
  • User response: none
  • Module: pubsub
PS0023I No longer subscribed to host:port
Description: The subscription to the specified host and port has been terminated.
  • System action: none
  • User response: none
  • Module: pubsub
PS0024E Error getting event from host:port: reason
Description: An event could not be retrieved from the specified host and port.
  • System action: none
  • User response: none
  • Module: pubsub
PS0025E Exception in subscriber thread for host:port: message
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: pubsub
PS0026E Exception waiting for subscriber thread for host:port: message
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: pubsub
PS0027E Error processing app.config file "file path": message
Description: The application config file had a configuration error in it.
  • System action: Operation terminates
  • User response: Correct the error in the application configuration file and try again
  • Module: pubsub
PS0028W Subscription is missing URL or program name; ignoring
Description: Some subscription information is missing.
  • System action: the subscription is ignored
  • User response: Correct the configuration and try again
  • Module: pubsub
PS0029E Error processing command line: message
Description: The command line parameters were incorrect.
  • System action: Operation terminates
  • User response: Fix the command line and try again
  • Module: pubsub
PS0031E No subscriptions specified in seepubsub.exe.config or on command line
Description: No subscription information has been configured.
  • System action: Operation terminates
  • User response: provide some configuration and try again
  • Module: pubsub
Parent topic: Error Messages


RD - series

RD0003S Group group name is not found, install request rejected
Description: A configured group is not found.
  • System action: Operation terminates
  • User response: Correct the configuration and retry
  • Module: resource definition
RD0004I Resource definition group group name install initiated from (terminal id)
Description: The resource definition group group name installation was initiated from terminal terminal id
  • System action: none
  • User response: none
  • Module: dfhzcins
RD0006E Group group name is installed with errors, check messages in TS queue TS queue name
Description: Validation errors were found when preparing to install group group-name. The error messages are written to TS queue TS-queue-name. These messages may be reviewed with the utility transaction CEBR.
  • System action: none
  • User response: Review the error messages in the TS queue and attempt to fix the issue
  • Module: dfhzcins
RD0007I Resource definition group group name is successfully installed
Description: The specified resource was installed.
  • System action: none
  • User response: none
  • Module: dfhzcins
RD0008I resource type entry resource name from group group name replaced existing definition
Description: The resource definition for resource-type entry resource-name from group group-name has replaced the previous definition in the current system.
  • System action: none
  • User response: none
  • Module: dfhzcins
RD0009I resource type entry resource name from group group name installed
Description: The resource definition for resource type entry resource name from group group name is installed in the current system.
  • System action: none
  • User response: none
  • Module: dfhzcins
RD0010E resource type entry resource name from group group name install failed, reason: reason text
Description: The resource definition for resource type entry resource name from group group name failed to install. The reason is reason text. Reason codes are return codes.
  • System action: Operation terminates
  • User response: Study the reason text and attempt to repair the problem
  • Module: dfhzcins
RD0011S Resource definition file open error (reason for the file open error)
Description: The resource definition file could not be opened.
  • System action: Operation terminates
  • User response: Verify that the file exists and is reachable
  • Module: dfhzcins
RD0015W resource type entry resource name from group group name not recognized
Description: The resource type entry / name in the specified group is not recognized.
  • System action: none - the group will not be installed
  • User response: correct the configuration and retry
  • Module: dfhzcins
RD0018E resource type entry resource name not CLOSED and either UNENABLED or DISABLED
Description: The resource is not installable.
  • System action: none - group will not be installed
  • User response: Repair the configuration, close or disable the file and retry
  • Module: dfhzcins
RD0019E Extra-partition resource type entry resource name not CLOSED
Description: The resource definition for resource type entry resource name is not installable. The existing installed definition is in use.
  • System action: none - the group will not be installed
  • User response: Close or disable the resource and retry
  • Module: dfhzcins
RD0020E Replace is not supported for general terminal resource name
Description: The resource definition for terminal resource name is not installable. The existing installed definition is not replaceable.
  • System action: none - the group will not be installed
  • User response: none
  • Module: dfhzcins
RD0021E Replace is not supported for ECI requestor resource name
Description: The existing installed definition is not replaceable.
  • System action: none - the group will not be installed
  • User response: none
  • Module: dfhzcins
RD0022E Replace is not supported for SURROGATE terminal resource name
Description: The existing installed definition is not replaceable.
  • System action: none - the group will not be installed
  • User response: none
  • Module: dfhzcins
RD0023E Replace is not supported for SESSION definition resource name
Description: The existing installed definition is not replaceable.
  • System action: none - the group will not be installed
  • User response: none
  • Module: dfhzcins
RD0024E Replace is not supported for definition resource name, type not recognized
Description: The existing installed definition is not replaceable.
  • System action: none - the group will not be installed
  • User response: none
  • Module: dfhzcins
RD0025E 3270 resource type entry resource name is not out of service and/or it is in use
Description: The resource definition is in use.
  • System action: none - the group will not be installed
  • User response: Close or disable the file and retry
  • Module: dfhzcins
RD0026E Connection resource type entry resource name is not out of service and/or it is in use
Description: The resource definition is in use.
  • System action: none - the group will not be installed
  • User response: Close or disable the file and retry
  • Module: dfhzcins
RD0039E Invalid input for install of group group name, error parameter: error text
Description: An invalid parameter was detected for install request.
  • System action: Operation terminates
  • User response: Correct the request and retry
  • Module: dfhzcins
RD0040E resource type entry resource name from group group name not found
Description: The specified resource was not found.
  • System action: Operation terminates
  • User response: Correct the request and retry
  • Module: dfhzcins
RD0043E Resource type supplied resource type not recognized
Description: The resource type you are trying to install is not recognized.
  • System action: Operation terminates
  • User response: Correct the resource and retry
  • Module: dfhzcins
RD0044E Keyword GROUP expected - found unexpected text. Resource will not be installed
Description: A configuration error occurred.
  • System action: Resource will not be installed
  • User response: Correct the resource definition and retry
  • Module: dfhzcins
RD0045E Closing single quote missing or mismatched. hex string Resource will not be installed
Description: A configuration error occurred.
  • System action: Operation terminates
  • User response: Correct the request and retry
  • Module: dfhzcins
RD0046E Closing double quote missing or mismatched. hex string Resource will not be installed
Description: A configuration error occurred.
  • System action: Operation terminates
  • User response: Correct the request and retry
  • Module: dfhzcins
Parent topic: Error Messages


TX - series

TXPC0002E EIBRESP=EIBRESP value invoking program 'program name'
Description: An error occurred invoking the specified program.
  • System action: Operation terminates
  • User response: Study the response code and attempt to fix the problem
  • Module: dfhzrun
TXPC0003I CRUN usage: CRUN <program-name>
Description: The syntax of the CRUN program.
  • System action: none
  • User response: none
  • Module: dfhzrun
TXPC0004I COMMAREA passed to CRUN
Description: A COMMAREA was passed to CRUN.
  • System action: none
  • User response: none
  • Module: dfhzrun
Parent topic: Error Messages


UPG - series

UPG0001E Unrecognized command-line parameter "parameter string"
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0002I -region, -regionfile or -resdef:file name must be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0003E Cannot specify both -region and -regionfile
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0004E Invalid region definition file specification: -regionfile : parameter
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0005E Invalid resource definition file specification: -resdef : parameter
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0006E Cannot specify -resdef:file name with either -region or -regionfile
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0007E Can only specify -resdef with -region or -regionfile
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0008E Invalid region name specification: -region : parameter
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0009E Region file "name of region file" does not exist
Description: The region file does not exist.
  • System action: Operation terminates
  • User response: Correct the region file name and try again.
  • Module: seeupgrade
UPG0010E Error locating region file "name of region file" (reason for error)
Description: The region file could not be found.
  • System action: Operation terminates
  • User response: Ensure that the specified region file is available and try again
  • Module: seeupgrade
UPG0011E XML error loading "configuration file name" (XML error)
Description: An XML error occurred in the configuration file.
  • System action: Operation terminates
  • User response: Fix the XML in the configuration file and try again
  • Module: seeupgrade
UPG0012E Invalid region file. No root "<configuration<" element exists
Description: An configuration error occurred in the region file.
  • System action: Operation terminates
  • User response: Fix the configuration in the region file and try again
  • Module: seeupgrade
UPG0013I Upgraded region file "name of region file"
Description: The region file was upgraded successfully.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0014I Original region file backed up to "name of backed up region file"
Description: The original region file was backed up to the specified location.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0015I No upgrade required for region file "name of region file"
Description: The specified region file does not need upgrading.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0016I Deleted name of region file entry (XML element)
Description: The specified element was deleted.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0017I Added name of region file entry (XML element)
Description: The specified element was added.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0018I Upgraded name of region file entry (XML element)
Description: The specified element was upgraded.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0019E Invalid resource definition file. No root "<configuration>" element exists
Description: The resource definition file is invalid.
  • System action: Operation terminates
  • User response: Make sure that the resource definition is valid and try again
  • Module: seeupgrade
UPG0020E Resource definition file "name of resource definition file" does not exist
Description: The resource definition file does not exist.
  • System action: OTS
  • User response: Specify a correct path to a resource definition file and try again
  • Module: seeupgrade
UPG0021E Error locating resource definition file "name of resource definition file" (reason for error)
Description: The resource definition file could not be found.
  • System action: Operation terminates
  • User response: Examine the reason for the error, fix and try again
  • Module: seeupgrade
UPG0022E Invalid resource definition file. No root "<configuration>" element exists
Description: The resource definition file is invalid.
  • System action: Operation terminates
  • User response: Make sure that the resource definition is valid and try again
  • Module: seeupgrade
UPG0023S Error while upgrading region file "name of region file" (reason for error)
Description: The upgrade of the specified region file failed.
  • System action: Operation terminates
  • User response: Examine the reason for error and repair and try again
  • Module: seeupgrade
UPG0024S Error while upgrading resource definition file "name of resource definition file" (reason for error)
Description: The upgrade of the specified resource definition file failed.
  • System action: Operation terminates
  • User response: Examine the reason for error and repair and try again
  • Module: seeupgrade
UPG0025E Invalid region file "name of region file". No "section name" section exists
Description: The region file is invalid.
  • System action: Operation terminates
  • User response: Make sure that the region file is valid and try again
  • Module: seeupgrade
UPG0026E Invalid resource definition file "name of resource definition file". No "section name" section exists
Description: The resource definition file is invalid.
  • System action: Operation terminates
  • User response: Make sure that the resource definition is valid and try again
  • Module: seeupgrade
UPG0027I Upgraded Resource type group group name entry resource name
Description: the specified resource was upgraded.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0028I Upgraded Resource type entry resource name
Description: The specified resource was upgraded.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0029I Added Resource type group group name entry resource name
Description: The specified resource was added.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0030I Added Resource type entry resource name
Description: The specified resource was added.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0031I Deleted Resource type group group name entry resource name
Description: The specified resource was deleted.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0032I Deleted Resource type entry resource name
Description: The specified resource was deleted.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0033I Upgraded resource definition file "name of resource definition file"
Description: The specified file was upgraded.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0034I Original resource definition file backed up to "name of backed up resource definition file"
Description: The original file was backed up to the specified location.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0035I No upgrade required for resource definition file "name of resource definition file"
Description: The file does not need upgrading.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0036I Run at date /time
Description: The upgrade was run at the specified date and time.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0037I Upgrade log file: name of upgrade log file
Description: The upgrade log file can be located at the specified location.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0038I Processing completed with return code = return code
Description: Upgrade processing has completed with the specified return code.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0039I Command line : command line used to run the seeupgrade utility
Description: The command line specified was used.
  • System action: none
  • User response: none
  • Module: seeupgrade
UPG0040I Current directory : directory from where the seeupgrade utility was run
Description: The specified directory was used.
  • System action: none
  • User response: log
  • Module: seeupgrade
UPG0041E -usedb required to upgrade a cross-region resource definition file
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
UPG0042E -usedb required to upgrade a cross-region region startup file
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seeupgrade
Parent topic: Error Messages


WU - series

WU0001E Unrecognized command-line parameter "command-line parameter"
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seewcfutil
WU0002I Processing settings file pathname:
Description: The specified settings file name was used.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0003E Fatal error: exception message
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seewcfutil
WU0004I Exception details: exception details
Description: An exception occurred.
  • System action: none
  • User response: Examine the console output and event log for further information to help resolve the problem
  • Module: seewcfutil
WU0005E Listen backlog must be between 2 and 100
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seewcfutil
WU0006E Pending connections must be between 2 and 1000
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seewcfutil
WU0007E Pending accepts must be between 2 and 1000
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seewcfutil
WU0008E Only one of -auth and -unauth can be specified
Description: Invalid command line syntax was detected.
  • System action: Operation terminates
  • User response: Correct the command line and try again
  • Module: seewcfutil
WU0009I Adding account account SID (account name) to port-sharing authorized list
Description: The specified account is being added.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0010I Removing account account SID (account name) from port-sharing authorized list
Description: The specified account is being removed.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0011I Changing listen backlog from old value to new value
Description: The listen backlog value is being changed to the specified value.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0012I Changing max pending accepts from old value to new value
Description: The max pending accepts value is being changed to the specified value.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0013I Changing max pending connections from old value to new value
Description: The max pending connections are being changed to the specified value.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0014I Changing receive timeout from old value to new value
Description: The receive timeout is being changed to the specified value.
  • System action: none
  • User response: none
  • Module: seewcfutil
WU0015E The account name "account name" could not be converted to a SID
Description: The account name could not be converted to a SID.
  • System action: Operation terminates
  • User response: Correct the account name and try again
  • Module: seewcfutil
WU0016I The local group group name already exists
Description: The specified group already exists.
  • System action: Operation terminates
  • User response: none
  • Module: seewcfutil
WU0017I Created local group group name
Description: The local group was created.
  • System action: none
  • User response: none
  • Module: seewcfutil
Parent topic: Error Messages


Administrator Role

The following content all applies to the administrator function.

As well as the supplied utilities, it is possible for the User to write their own software to interact with various aspects of the system using a set of public API assemblies.

The documentation for the public API can be found in the .chm file called SeePubApi.chm found in the product help directory.

  • General Administration
  • CICS Administration
  • JES Administration
  • Event Manager
Parent topic: Role-based Contents - Introduction


General Administration

These topics are common to CICS and JES administration.

  • Administering an Enterprise Server for .NET Installation
  • Configuring the Operating Environment
  • Defining Program and Data Locations
  • Configuring Regions and Resources
  • Starting and Stopping a Region
  • Securing the Environment
  • Configuring XA resources
  • Administering from the Command Line
  • Diagnostics
  • Enterprise Server for .NET Context Sensitive Topics
Parent topic: Administrator Role


Administering an Enterprise Server for .NET Installation

The topics in this section describe how to manage and monitor regions that are operating.

  • Monitoring a Region's tasks
  • Using the Region Console
  • Viewing a Region's Statistics
  • Viewing a Region's Sessions
  • Monitoring the Operating environment
  • Administering Using SCOM (System Center Operations Manager)
  • Managing Event Monitors
Parent topic: General Administration


Monitoring a Region's tasks

From the user interface, you can monitor tasks performed by a region.

For a region operating over multiple machines, you can either monitor tasks across the entire region or the tasks running on any particular machine on which the region is operating.

The Monitor Region screen displays task information for a region that is running. Select a task from the list to display task statistics. You can also use the Monitor functionality to stop a task.

  • To Monitor the Tasks Running in a Region
  • To Kill a Task that is Running
Parent topic: Administering an Enterprise Server for .NET Installation


To Monitor the Tasks Running in a Region

The region must be started before monitoring tasks in the region.
Use the following procedure to view the statistics for tasks running in a region.
  1. In the Tree pane under Regions, select the region that you want to monitor.
  2. In the Actions pane, select Monitor.

    The Monitor Region area displays in the Results pane.

  3. In the Monitor Hosts list, select the machine to monitor.

    If a region is operating over multiple machines, use this option to monitor tasks region-wide, or only those tasks running on a particular machine.

    The display changes to reflect the specified settings.

    The list view displays a list of all running tasks. Selecting one of the tasks displays more detailed information about the task in the properties window. Right-click on a task and use the context menu to stop the task.

  4. Click Refresh at the bottom right of the display to update the list of tasks that are running.
Parent topic: Monitoring a Region's tasks


To Kill a Task that is Running

To stop, or kill a task that is running in a region, use the following procedure:
  1. In the Tree pane, under Regions , select the region.
  2. In the Actions pane, select Monitor.

    The Monitor Region area opens in the Results pane.

  3. In the Monitor Hosts list, select the machine running the task to kill, or select All to display all the tasks running across the region.

    This is relevant in a cluster environment, where a region can operate over multiple machines.

    The tasks display changes to reflect your selection.

  4. Right-click the task to kill it. The Kill menu displays.

  5. Click Kill to stop the task

    The task stops and no longer appears on the display after a refresh.

Parent topic: Monitoring a Region's tasks


Using the Region Console

The console displays messages that a region generates as it performs tasks. You can configure information displays and the order of the information columns. Date, Time, and Message columns display by default.

Note: You can also configure the console message level for a region.

You can configure the console to display the following message information:

Date
The date on which the message was generated.
Time
The time that the message was generated.
Host
The host that generated the message. This is relevant in a cluster environment, where a region's processing is handled by multiple machines in a cluster.
Message
The generated message. You can configure the level of messages displayed for each region.
Thread
The processing thread for the task that generated the message.
Process
The process ID that generates the message.
AppDomain
The application domain in which the task is running.
  • To Open and Configure the Region Console
  • Setting the Message Level for a Region
  • To Set a Region's Console Message Level
Parent topic: Administering an Enterprise Server for .NET Installation


To Open and Configure the Region Console

The region to monitor must be running.
Use the following procedure to monitor the processes running in a region.
  1. In the Tree pane of the MMC user interface, select the region you want.
  2. In the Actions pane, select View console.

    The console opens in the Results pane.

  3. Right-click the column heading area, and choose Choose columns from the menu.

    The Choose columns dialog box displays.

  4. Use the Add and Remove buttons to select the columns to display in the Selected Columns field.
  5. Use the Move Up and Move Down buttons to specify the columns order.
  6. Click OK to return to the console display.

    The information diaplays as configured.

You can change the column order by selecting a column heading and dragging it to the position you want.

Parent topic: Using the Region Console


Setting the Message Level for a Region

A region that is running outputs messages to the console as it operates. The level of messages output, or the message verbosity is set in the region's resource file, in the Misc > Console Message Level property of the System Initialization Table (SIT).

You can override this setting at the region level by setting the Console Message Level property in a region's startup file.

Parent topic: Using the Region Console


To Set a Region's Console Message Level

In a region's startup file, you can set the level of messages output, or message verbosity for a region, to override the setting defined in the SIT.
  1. Choose SEE Administration > Configuration Editors > Region startup to start the Region Startup File editor.
  2. In the editor, open the startup file for the region to configure.
  3. Select the Region item at the top of the tree, and in the editor's right pane, select the General > Console Message Level property.
  4. Select the message level from the list. Valid values are:
    • RegionDefault

      Messages display depending on the value set in the SIT. This is the default value.

    • CriticalMessages

      Only those messages that are essential to indicate the state of the region display.

    • AllMessages

      All generated messages display.

When you start and operate the region, the console displays the messages based on the value set in the region startup file, rather than the value defined in the SIT.
Parent topic: Using the Region Console


Viewing a Region's Statistics

From the Enterprise Server for .NET user interface, you can view the statistics for a running region.

The statistics shown are the number of transactions per second, and the average transaction latency. The statistics screen displays the following information:

  1. Use the Intervals radio buttons to set the statistics time length:
    • Select 1 minute to display statistics on transactions that run over each one minute interval.
    • Select 15 minutes to display statistics on transactions that run over each 15 minute interval.
  2. This area displays the color legend for the display.
  3. This is a ruler that shows the latency and the task per second values that the bars indicate.
  4. Horizontal color coded bars represent the statistic values.
  5. Use Auto-refresh time (seconds): field to set the number of seconds between display refreshes.
  • To View the Statistics for a Region
Parent topic: Administering an Enterprise Server for .NET Installation


To View the Statistics for a Region

Use the following procedure to view the operating statistics of a region.
  1. In the Tree pane under Regions, select the region that you want to monitor.
  2. In the Actions pane, select Statistics.

    The Statistics area displays in the Results pane.

  3. In the Statistics area, set the following:
    • Set the Interval to 1 or 15 minutes. Statistics are collected and displayed over the interval that you choose.
    • Set the Auto-refresh time to a number of seconds. The sets the number of seconds between updates to the display. New statistics generated during an interval display with the next update.
    • Click the Refresh button to update the display immediately.
    The statistics display changes to reflect the changed settings.
Parent topic: Viewing a Region's Statistics


Viewing a Region's Sessions

From the Enterprise Server for .NET Administration UI you can view all client sessions currently connected to the region.

The following information is displayed for each session:
  • Device type
  • Net name
  • Session endpoint
  • Session id
  • Terminal id
  • Terminal type
  • Screen size
  • To View the Sessions for a Region
Parent topic: Administering an Enterprise Server for .NET Installation


To View the Sessions for a Region

The Enterprise Server for .NET Administration UI is used to view all client sessions currently connected to the region:
  1. In the Tree pane under Regions, select the region to view. See 1 in the diagram below.
  2. In the Action pane select Sessions. See 2 in the diagram below. The Sessions View is displayed in the Results pane showing each of the connected sessions.
  3. Select one of the connected sessions. Information about the session is displayed in a property window on the right-hand side of the view. See 3 in the diagram below.

Parent topic: Viewing a Region's Sessions


Monitoring the Operating environment

Each machine that runs dispatcher and/or SEP services has a Windows service called seemonitor that monitors the system's state and health. The seemonitor service writes messages to the Windows Event Log when errors occur. The service is also a part of the region administration process. For example, MMC UI uses it to provide information about running tasks.

You can use the Windows Control Panel to access the event log, or you can add the Event Viewer to the MMC for easy access.

  • Viewing Messages in the Windows Event Log
  • Windows Services Used By Enterprise Server for .NET
  • Configuring Windows Performance Counters
Parent topic: Administering an Enterprise Server for .NET Installation


Viewing Messages in the Windows Event Log

Enterprise Server for .NET writes some messages to the Windows Event Log. You can view these messages using the Windows Event Log Viewer utility (eventvwr.exe).

You can find these messages in the Micro Focus Server log, located in the Applications and Services Logs folder of the Event Viewer pane.

The following types of messages display in the log:

  • Messages from the Enterprise Server for .NET seelistener and seemonitor Windows services.

    These messages apply to all of the regions running on the machine rather than to just one region. For this reason, they don’t appear in a region console.

  • Messages that relate to exceptions in Enterprise Server for .NET, or in the COBOL application programs running under it.
  • Messages from Enterprise Server for .NET components. These messages do not include “Enterprise Server for .NET” in their Source field.

In addition to the Event Log, Windows automatically writes entries to the standard Application log in the Windows Logs folder, when either of the Listener or Monitor services starts or stops.

Parent topic: Monitoring the Operating environment


Windows Services Used By Enterprise Server for .NET

AnEnterprise Server for .NET installation uses the following services:

  • was
  • nettcpportsharing
  • netpipeactivator
  • nettcpactivator
  • w3svc
Parent topic: Monitoring the Operating environment


Configuring Windows Performance Counters

Enterprise Server for .NET exposes some windows performance counters that can be used to gather performance information for the processes.

Each of the seelistener, seedispatch and seesep processes can be configured to expose one or more counters.

For the seelistener process, the seelistener.exe.config file contains the configuration for the following counters

  • Puts Per Second

    The number of transactions per second that are being received.

  • Puts Duration

    The average duration of the transaction from the listener viewpoint.

  • TN3270Connections

    The number of concurrent TN3270 connections that the Listener Worker role is handling.

  • TN3270 Number of threads

    The number of active TN3270 threads.

  • TN3270 Number Of Threads Per Second

    The rate at which the TN3270 threads are active.

  • TN3270 Thread Duration

    The average duration of the TN3270 thread's lifetime.

For the dispatcher and sep performance counters, the configuration can be found in one of two places depending on how the dispatcher and sep are run.

  • For WAS hosted ( IIS) SEP and dispatcher

    Performance counters can be enabled/disabled in the web.config file.

  • For self hosted SEP and dispatcher

    Performance counters are enabled/disabled in the process configuration file, e.g. seedispatch,exe.config and seesep.exe.config.

For the SEP , the following performance counters are available

  • Transactions Per Second

    The number of transactions that the SEP worker role is executing per second.

  • Transaction Duration

    The average duration of execution of the transactions executed by this SEP worker.

For the Dispatcher, the following performance counters are available

  • Dispatch Put Requests Per Second

    Shows the rate at which requests are received and queued by the dispatcher worker role.

  • Clear Requests Per Second

    Shows the rate at which the dispatcher worker role is receiving clear requests from the listeners.

  • Dispatch Put Request Duration

    The average time it takes to place a transaction request onto the work queue.

Parent topic: Monitoring the Operating environment


Administering Using SCOM (System Center Operations Manager)

The Enterprise Server for .NET installation software includes a SCOM management pack. In the current release, you can use Microsoft SCOM to monitor an installation's regions and the transactions running in each region.

  • System Requirements for SCOM Implementation
  • Installing Management Pack from Operations Manager
  • To Display Region Details in SCOM
Parent topic: Administering an Enterprise Server for .NET Installation


System Requirements for SCOM Implementation

Using SCOM to monitor an Enterprise Server for .NET installation has the following requirements:

  • A SCOM server configured on your network.

    Refer to the Microsoft SCOM documentation for information on installing SCOM and setting up a SCOM server.

  • The Enterprise Server for .NET SCOM management pack included in the Enterprise Server for .NET installation software.

    The default installation path for this is:

    • For 64-bit systems:

      %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\SCOM\MicroFocus.SEE.System.mp.

    • For 32-bit systems:

      %ProgramFiles%\Micro Focus\Enterprise Developer\etc\SEE\SCOM\MicroFocus.SEE.System.mp.

To use the SCOM management pack, the COMPLUS_Version system environment variable must be set to 4.0.30319.

Parent topic: Administering Using SCOM (System Center Operations Manager)


Installing Management Pack from Operations Manager

To install the Management Pack from Operations Manager:

  1. Open the Operations Console.
  2. Select View > Navigation Pane or press Alt+F1.
  3. Click Administration and select Management Packs from the tree view.
  4. From menu bar, choose Actions > Actions > Import Management Packs
  5. Click Add and browse to the Management Pack to install.
Parent topic: Administering Using SCOM (System Center Operations Manager)


To Display Region Details in SCOM

You must have registered the machines running the monitored regions with the central SCOM server.
Use this procedure to select a region to monitor and to display details of the tasks that the region is running.
  1. On the SCOM Server, start SCOM.
  2. In the SCOM Tree pane, select Discover Inventory.

    A list of the regions operating on machines being monitored displays in the Results pane.

  3. Right-click on the region to be monitored and choose Change target type. The Select Items to Target dialog box appears.
  4. In the Look for field, type CICS Region and click OK.

    A list of the regions operating on the machine displays.

  5. Select the region to monitor to display it.

    A diagram of running SEPs displays. At the bottom of the display, information relating to the SEP displays.

  6. Select a SEP to display details of the processes that are running in the SEP.
Parent topic: Administering Using SCOM (System Center Operations Manager)


Managing Event Monitors

The Event Monitor is the seemonitor.exe Windows service process installed on machines that run a dispatcher and/or SEP services. An event monitor provides administration and management functionality for the SEP and dispatcher services that run on the same machine as the monitor. Typically, event monitors are managed by the system.

When a machine in an installation starts, it registers its Event Monitor with the cross-region database. When you shut down a machine in the installation, it removes this registration from the cross-region database and no further administration action is required.

However when a machine in the installation stops unexpectedly, for example if a process abend causes the machine to stop responding, the event monitor registration is not removed from the cross-region database. As a result, the cross-region database attempts to broadcast events to a non-existent machine.

You can identify this condition by examining the Windows Event Log. The SCOM system manager also identifies this condition. Remove registered event monitor processes where the machine is not running whenever SCOM identifies them. Use the System Event Monitors item to do this.

  • To Delete an Event Monitor Registration from the Cross-Region Database
Parent topic: Administering an Enterprise Server for .NET Installation


To Delete an Event Monitor Registration from the Cross-Region Database

Before you begin this procedure, identify the event monitor process that you want to remove.

Use this procedure when a machine or a cloud instance stops unexpectedly before the shut-down process can delete the registration from the cross-region database.
  1. In the Tree pane, select System > Registered Event Monitors.

    A list of the installation's server instances displays in the Results pane.

  2. Select the server instance that you want, or add a new server instance to use. A list of the registered event monitors for that server instance displays.
  3. Select the event monitor registration to delete, and then click the Erase icon at the top right of the Event Monitor View area. You are prompted to confirm the deletion.
  4. Click Yes to delete the event monitor registration.
The cross-region database no longer sends broadcast events to the event monitor.
Parent topic: Managing Event Monitors


Configuring the Operating Environment

The topics in this section describe how to set up the Enterprise Server for .NET operating environment.

  • Setting Up the User Interface
  • Configuring the Database
  • Configuring a Listener
  • Creating User-Specific Configurations
  • Configuring from File
Parent topic: General Administration


Setting Up the User Interface

Enterprise Server for .NET uses the Microsoft Management Console (MMC) to host the user interface. You add the Enterprise Server for .NET snap-in to the MMC.

Note: After a new installation or a re-boot, follow the first time procedure.

From the Windows Start menu, choose Micro Focus Enterprise Developer > Enterprise Server for .NET > SEE Administration to start the MMC snap-in.

  • To Set Up and Start the User Interface for the First Time
Parent topic: Configuring the Operating Environment
Related concepts
Starting a Region
Related tasks
To Define a New Region With an Existing Region Startup File


Configuring the Database

Enterprise Server for .NET stores regions' configuration and state information in a Microsoft SQL Server database. Use Microsoft SQL Server Express 2008 to evaluate or test an installation.

You supply the database server instance name when you configure a region's startup file.

  • Configuring Database Authentication
  • Changing the User for a Service
Parent topic: Configuring the Operating Environment


Configuring Database Authentication

By default, Enterprise Server for .NET connects to SQL Server using Windows authentication (SSPI), with user login credentials.

You can configure the installation to connect to the database using supplied SQL Server authentication and credentials instead of user login credentials.

This method is useful in situations where:

  • Your installation connects to a database on a different system, and you are running in a workgroup rather than a domain.
  • For security, you need to have Enterprise Server for .NET use a different account when connecting to the database.

Set the database authentication details to use in machine.config.

Important: Use this process when an installation accesses database servers located on remote machines that use different login credentials. If an event monitor attempts to access a database server on a remote machine for which it has no access, the attempt fails.
Note: If your installation uses Windows authentication for SQL Server, ensure that the event monitor service (seemonitor.exe) and the IIS application pool used by Enterprise Server for .NET are configured to run as a Windows user that has database administration privileges for each of the region databases that are to be accessed.
  • To Configure Enterprise Server for .NET to Use SQL Server Authentication
  • Sample Machine Configuration for SQL Authentication
Parent topic: Configuring the Database


To Configure Enterprise Server for .NET to Use SQL Server Authentication

Your Microsoft SQL Server installation must be configured with the authentication details you want to use.
  1. Stop all regions that are running, and close all Enterprise Server for .NET components, services, and the user interface.
  2. Make a backup copy of the machine.config file.

    The file is located in %windir%\Microsoft.NET\Framework\version\Config, where version is the .NET Framework version used by Enterprise Server for .NET. Use the file under Framework when running a 32-bit version of Windows, and the one under Framework64 when running a 64-bit version of Windows.

  3. Open the machine.config file for editing, and add the SQL.credentials setting to the <MicroFocus.SEE> section as follows:
    <add key="SQL.credentials" value="User ID=<username>;
 password=<password>">

    where:

    • <username> is the SQL Server user ID that you configured.
    • <password> is the password that you configured for the SQL Server user ID.
  4. Save and close the file. When you re-start Enterprise Server for .NET, the system uses the configured database authentication details.
Parent topic: Configuring Database Authentication


Sample Machine Configuration for SQL Authentication

The following is a sample of a machine.config file configured for SQL authentication:
<configuration>
  ...
  <configSections>
    ...
    <!-- Added for Micro Focus SEE for .NET -->
    <section name="MicroFocus.SEE"
             type="MicroFocus.SEE.Utils.GlobalConfigurationSection,
             MicroFocus.SEE.Utils,Version=4.0.0.0,
             Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
    ...
  </configSections>
    ...
  <!-- Added for Micro Focus SEE for .NET -->
  <MicroFocus.SEE>
    ...
    <add key="SQL.credentials" value="User ID=abc;password=xyz"/>
    ...
  </MicroFocus.SEE>

</configuration>
Parent topic: Configuring Database Authentication


Changing the User for a Service

If your installation uses Windows authentication for SQL Server, ensure the event monitor service (seemonitor.exe) and the IIS application pool used by Server EE for .NET are configured to run as a Windows user that has database administration privileges for each of the region databases that are to be accessed.

By default the seemonitor service runs under the local system account and only has access to local database server instances. Use the following procedure to change the user that the service runs under.

  1. Open the Windows Services dialog box.
  2. In the services list, select the Micro Focus SEE Monitor service.
  3. Right-click and select Properties.
  4. Select the Log On tab.

  5. Select the This Account radio button, and enter the user id and password details that the service is to run under.
  6. Click OK.
  7. Start or re- start the service.

By default the w3wp.exe process started by IIS that hosts the dispatcher and SEP services can only access local database server instances. Use the following procedure to change the user that w3wp.exe runs as.

  1. Start IIS Manager.
  2. Select Application Pools in the left-hand tree.
  3. Right-click on Micro Focus SEE for .NET v4.0 in the centre-pane and select Advanced Settings ... .
  4. Select the Identity property in the Process Model category.
  5. Click on the ... button at the right-hand side of the property value.
  6. Select the Custom Account radio button and click on Set.
  7. Enter the user id and password details that you require.

  8. Click OK to close the Set Credentials dialog box.
  9. Click OK to close the Application Pool Identity dialog box.
  10. Click OK to close the Advanced Settings dialog box.
  11. Recycle the application pool if it is already started. w3wp.exe uses the configured user the next time it starts.
Parent topic: Configuring the Database


Configuring a Listener

A region’s listener configuration is made up of the region name and the name of an associated database server instance. Once the name and database server instance are specified, one or more channels can be associated with the region. A channel is made up of a logical name, a protocol, and a port number.

For example, in the listener configuration for a region you could define a channel named TN3270, to use the TN3270 protocol on port 9023. This would enable 3270 terminal emulators to connect with the region on port 9023. With TN3270 listeners, you can use the keep-alive functionality to check that the listener is active, and to ensure that it stays alive.

A listener configuration file can include multiple regions, each with multiple channels.

Currently supported protocols are TN3270 for TN3270 terminals, and MFBINP.

MFBINP is an internal Micro Focus protocol. This protocol is used to:

  • monitor the JCL jobs submitted from Enterprise Server for .NET to a native Enterprise Server region.
  • Submit JES jobs to a Enterprise Server for .NETJES region

Listener configurations are stored in the listener configuration file seelistener.exe.config

Note: The default installation has a listener defined for the CICS ESDEMO region, defined on port 9023. You can use this listener to verify the installation. This configuration is not overwritten if you need to re-install the software.

The default seelistener.exe.config file installed in the same location as seelistener.exe is overwritten when the product is re-installed. However, seelistener.exe also looks for a version of seelistener.exe.config in %APPDATA%\Micro Focus\SEE\2.2\Config and will use it if present. This version is not overwritten when the product is re-installed.

  • Ensuring a Listener Remains Active
  • To Configure a Listener
Parent topic: Configuring the Operating Environment


Ensuring a Listener Remains Active

With TN3270 channels, you can configure an optional "heartbeat" or keep-alive feature.

With the heartbeat feature, you configure a time interval in seconds. For idle conversations, the listener sends test messages at the configured time intervals.

Note: Heartbeat configurations are ignored with channel types other than TN3270.

The test messages that this functionality generates have two functions:

  • They check that the client is still available.
  • In an environment that closes idle conversations, the test messages ensure that the conversation remains open.

When starting a listener from the command line, you can specify a default heartbeat with the seelistener.exe command using the -heartbeat:time option. You can also configure heartbeats for individual channels defined in the seelistener.exe.config file, by adding the heartbeat="time" attribute to the <channel> element. Set time as a value in seconds.

You can add, edit, or remove heartbeat parameters from channels when editing a listener configuration file in the Administration snap-in.

To remove a heartbeat, set its value to 0.

Parent topic: Configuring a Listener


To Configure a Listener

This procedure describes how to configure a listener channel to connect to anEnterprise Server for .NET region.
Note: You must stop, then re-start the seelistener service before any changes to the listener configuration take effect.
  1. In the Tree pane, select Configuration Editors > Listener . The Listener Configuration editor opens in the Results pane.
  2. In the Listener Configuration editor, select the File Open icon, and navigate to and select the seelistener.exe.config configuration file.
    • For 32-bit systems, this file is located in:

      %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE

    • For 32-bit run-time only systems, this file is located in:

      %ProgramFiles%\Micro Focus\Enterprise Server\binAnyCPU\SEE

    • For 64-bit systems, this file is located in:

      %ProgramFiles(x86)%\Micro Focus\Enterprise Developer \binAnyCPU\SEE

    • For 64-bit run-time only systems, this file is located in:

      %ProgramFiles(x86)%\Micro Focus\Enterprise Server \binAnyCPU\SEE

    The listener's configuration file settings display in the editor.

  3. In the Listener configuration area, right-click the Regions item and choose Add.

    The Add New Region dialog box appears.

  4. Select a defined region, or in the Region name field, type the name of the region to connect to, and in the Database server instance field, type the database server name, and click OK.

    The region does not need to exist at this point. You can create it later.

    The region appears under Regions.

  5. Right-click the region and click Add to open the Add New Channel dialog box. Enter a name for the channel, and set the port that it is to listen on.
  6. In the Protocol list, select the protocol to use the channel with a TN3270 terminal.
    Supported protocols are:
    • TN3270 (to connect to TN3270 terminals - CICS regions only)
    • MFBINP You use this protocol to configure a listener for use with the casfile and cassub command and a native Enterprise Server or Enterprise Server for .NETregion.
    Important: For TN3270 listeners, you can configure a heartbeat value to ensure that the conversation remains open. When running regions in the Azure cloud, we recommend that you configure a heartbeat time of 30 seconds.
  7. Click OK to close the Add New Channel dialog box.

    The listener is now available for use on the specified port.

  8. Repeat the process to add any additional regions and/or channels.
  9. Stop, then re-start the listener.

    In the editor, use the Options menu to stop and re-start the listener, or use the stop, then start buttons on the toolbar.

    The listener stops and re-starts, and your configurations are now available.
Parent topic: Configuring a Listener


Creating User-Specific Configurations

To protect against unplanned configuration changes, Enterprise Server for .NET configuration files install to a location that has read-only access to users.

However, you can create override configurations that are used only by specific users. When applying configurations, an Enterprise Server for .NET process performs the following:

  • The operating system looks for the executable's application configuration file in the same folder as the executable.

    In a 64-bit system, the Server EE for .NET executables are installed in C:\Program Files (x86)\Micro Focus\product name\binAnyCPU\SEE. For example, the seelistener.exe.config file in this folder processes when seelistener.exe runs.

  • The Enterprise Server for .NET executable then looks for a corresponding configuration file (that is, a configuration file with the same file name) in a location that is specific to the user.
  • The Enterprise Server for .NET executable combines the two configurations, and uses any corresponding settings from the user-specific location file to override the settings in the configuration file.

The user-specific location is %APPDATA%\Micro Focus\SEE\<release number>\Config where <release number> is the release number of the software.

The %APPDATA% environment variable is set by the operating system, and refers to a user-specific folder:

Note: In Microsoft Windows Vista and Microsoft Windows 7, the default value of %APPDATA% is C:\Users\<user name>\AppData\Roaming\ where <user name> is the user's log in ID.

You can create the following user-specific configuration files:

  • seeconsoleviewer.exe.config
  • seedeploy.exe.config
  • seedispatch.exe.config
  • seelistener.exe.config
  • seemonitor.exe.config
  • seerdfconv.exe.config
  • seesep.exe.config
  • seestart.exe.config
  • seestop.exe.config
  • Example: Creating a User-Specific Listener Configuration Port
Parent topic: Configuring the Operating Environment


Example: Creating a User-Specific Listener Configuration Port

This example details how to create a listener configuration file specifically for a user who needs to use a non-standard TN3270 port. For the user, the port settings in the user-specific file override the settings defined in the default listener configuration file.
  1. In the Tree pane, select Configuration > Listener . The Listener Configuration editor opens in the Results pane.
  2. In the Listener Configuration editor, select the File Open icon, and navigate to and select the seelistener.exe.config configuration file.

    For 32-bit systems, the default location is %ProgramFiles%\Micro Focus\Enterprise Server\binAnyCPU\SEE.

    The listener's configuration file settings display in the editor.

  3. Edit the configuration file's TN3270, Port setting to set the port to use.
  4. Use the editor's File > Save As option to save the port location to C:\Users\ <user name> \AppData\Roaming\Micro Focus\SEE\ <release number> \Config.

    where <user name> is the user's login ID, and <release number> is the software release number.

The listener uses the TN3270 port defined in the user-specific configuration file rather than the default.
Parent topic: Creating User-Specific Configurations


Configuring from File

The Enterprise Server for .NET environment maintains the settings you configure in XML-format configuration files. You can change settings by editing these files directly.

Note: Before editing a file to modify a setting, ensure that you are confident that you know what to do, and always back up the file before editing.
  • Changing Inter Role Communication Parameters
Parent topic: Configuring the Operating Environment


Changing Inter Role Communication Parameters

It is possible to change some of the windows network parameters using the application configuration files.

For a WAS ( IIS hosted ) deployment, the SEP and Dispatcher parameters can be found in the web.config file.

The Listener and Monitor roles configuration files can be found in the following locations

  • For 32-bit systems:

    %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE

    • seelistener.exe.config for the listener role
    • seemonitor.exe.config for the monitor role.
  • For 64-bit systems:

    %ProgramFiles(x86)%\Micro Focus\Enterprise Developer \binAnyCPU\SEE

    • seelistener.exe.config for the listener role
    • seemonitor.exe.config for the monitor role.

The following parameters can be configured for each role. The default values are used by the system if no overriding parameter is found in the configuration files.

  • NetNamedPipe.maxConnections
    • Sets the maximum number of connections, both inbound and outbound, that are allowed to endpoints
    • Default value is 250
  • NetTcp.maxConnections
    • The maximum number of concurrent TCP connections allowed.
    • Default value is 250
  • Throttling.maxConcurrentCalls
    • Specifies the maximum number of messages actively processing across a role .
    • Default value is 512
  • Throttling.maxConcurrentSessions
    • specifies the maximum number of sessions a role can accept.
    • Default value is 512
  • NetTcp.maxReceivedMessageSize
    • The maximum size (in bytes) for a received message that is processed by the Role
    • Default value is 200000
  • NetTcp.ReaderQuotas.MaxArrayLength
    • The maximum array length that is created and returned by various API calls.
    • Default value is 150000
The following example configures the Role to increase the default values by 10 of all. The example may not make sense and is for illustrative purposes only.
<services>
      <!-- Sample settings for changing WCF service parameters -->

      <add key="NetNamedPipe.maxConnections" value="260" />
      <add key="NetTcp.maxConnections" value="260" />
      <add key="Throttling.maxConcurrentCalls" value="522" />
      <add key="Throttling.maxConcurrentSessions" value="522" />
      <add key="NetTcp.maxReceivedMessageSize" value="200010" />
      <add key="NetTcp.ReaderQuotas.MaxArrayLength" value="150010" />
    </services>
Note: It is important to understand, in depth, what these parameters do. Please read the relevant Microsoft documentation and white papers before changing any of these. Changing these parameters can have a very bad impact on the system if the values are not thought out carefully. The default values supplied in the product have been calculated to cater for most installations and should rarely need changing.
Parent topic: Configuring from File


Defining Program and Data Locations

The topics in this section describe how program and data locations are defined for use by a region.

  • About Program and Data Locations
  • Adding Configuration Files to the Cross-region Database
  • Adding Programs and BMS Maps to a Database at Region Startup
  • Adding Data Files to a Data Store
  • Adding Programs and BMS Maps to a Data Store
  • Defining Program and Data Locations in the Region Startup File
  • Defining Data Locations
Parent topic: General Administration


About Program and Data Locations

Enterprise Server for .NET allows programs and data files that are used by CICS transactions and batch jobs to be defined on either a local or network file system, or within a database.

When working with a scaled-out system it is important that any given program or file is available to all machines in the scale-out using the same file location URL. This means that to minimise configuration complexities either a network file system or database should be used in preference to a local file system. The benefit of using a database in preference to a file system is that all artefacts associated with a given region (e.g. region startup file, resource definition file, region database, cross-region database, programs and data files) can reside within a single central location, so simplifying their administration.

  • Database Locations
  • File Share Configuration
Parent topic: Defining Program and Data Locations


Database Locations

There are a number of different options available for hosting your programs and data files within a database. These are:
  • Cross-region database

    The cross-region database is the recommended location for region startup and CICS resource definition files. This database can also be used for the deployment of program executables and BMS maps. You would typically deploy programs and maps to this location that are used by two or more regions.

  • Region database

    A region database may be used for the deployment of program executables and BMS maps that are used specifically by that region. However, these files need to be deployed as part of cold-start processing so can have a detrimental affect on the time taken to start the region.

  • Custom database

    A custom database can be used for the deployment of program executables and BMS programs. Like the cross-region database, files in a custom database may be used by two or more regions. However, unlike the cross-region database, files can be categorised (e.g. region specific, staging levels, etc) by deploying them to different tables.

  • Data store database

    A data store is the most flexible of all of the types of database available for the deployment of programs and data files. A data store effectively provides a database hosted file system by allowing files to be categorised using a folder hierarchy. Each data file is represented by a table, whereas all other files such as programs and BMS maps are represented by blobs. Blobs are held within a single table.

Files can be transferred between a file system and any of the database locations above using either the Enterprise Server for .NET Administration UI or the seedeploy command-line utility.

Parent topic: About Program and Data Locations


File Share Configuration

If you are using fileshare, and fileshare is started with the servername in the following format:

,MFPORT:3019

then to connect to this fileshare using FSVIEW you will need to add the following entry to CCI.INI:

[ccitcp-targets]

CCITCPT_SRV1=,MFNODE:0.0.0.0,MFPORT:3019

where MFNODE is the IP address of the machine the fileshare server is started on.

Then use SRV1 as the fileshare server name when using FSVIEW.

Parent topic: About Program and Data Locations


Adding Configuration Files to the Cross-region Database

Region startup and CICS resource definition files may be deployed to the cross-region database using either the Enterprise Server for .NET Administration UI or the seedeploy command-line utility.

  • To Add a Region Startup File to the Cross-region Database using MMC
  • To Add a Region Startup File to the Cross-Region Database using seedeploy
  • To Add a Resource Definition File to the Cross-region Database using MMC
  • To Add a Resource Definition File to the Cross-Region Database using seedeploy
Parent topic: Defining Program and Data Locations


To Add a Region Startup File to the Cross-region Database using MMC

Use the configuration file's editor to add a configuration file to the cross-region database.

  1. Open the file in the appropriate editor: Region Startup, or CICS Resources editor.
  2. Make any changes to the file, and then choose File > Save to to save the file to the cross-region database.
Parent topic: Adding Configuration Files to the Cross-region Database


To Add a Region Startup File to the Cross-Region Database using seedeploy

To add a region startup file to the cross-region database from the command line:

  1. Open an Enterprise Developer command prompt,
  2. Use the seedeploy command.

    For example, to deploy the region_esdemo.config file, use the following command:
    seedeploy regionfile add c:\resourcedir\region_esdemo.config
    sql://localhost/inst/(crdb)
    Tip: In the command above, the parameter (crdb) indicates that the region_esdemo.config file is installed in the installation's cross-region database.

Example

The following command lists the region startup files deployed to the cross-region database.
seedeploy regionfile list sql://localhost/inst/(crdb)
Parent topic: Adding Configuration Files to the Cross-region Database


To Add a Resource Definition File to the Cross-region Database using MMC

To add a resource definition file to the cross-region database, open it in the Resource Definition File editor and save it to the cross-region database.

Parent topic: Adding Configuration Files to the Cross-region Database


To Add a Resource Definition File to the Cross-Region Database using seedeploy

To add a CICS resource definition file to the cross-region database from the command line:

  1. Open an Enterprise Developer command prompt.
  2. Use the seedeploy command.

    For example, to add the resdef.config file, use the following command:
    seedeploy rdo add c:\resourcedir\resdef.config sql://localhost/inst/(crdb)
    Note: In the command above, the parameter (crdb) indicates that the resdef.config file is installed in the installation's cross-region database.

Example

The following command lists the resource definition files deployed to the cross-region database.
seedeploy rdo list sql://localhost/inst/(crdb)
Parent topic: Adding Configuration Files to the Cross-region Database


Adding Programs and BMS Maps to a Database at Region Startup

Region startup files can be configured to deploy programs and BMS maps to the region or the cross-region database automatically during region startup.

Note: You cannot automatically deploy configuration or data files during region startup. You must always deploy these files manually.

You specify which files are auto-deployed in the region startup file. Note the following points:

Files specified for auto-deployment to the region database are always uploaded at region startup, provided the source location is valid.

Files specified for auto-deployment to the cross-region database are uploaded at region startup only if the source location is valid and the file does not already exist in the database. This prevents conflict with other regions using the cross-region database.

Files cannot be auto-deployed to a user-defined database.

Note:

You cannot automatically deploy programs and BMS maps to a user-defined database.

Remember:
  • A program or BMS map auto-deployed to the region database uploads whenever the region is cold-started regardless of whether it already exists in the region database.
  • A program or BMS map auto-deployed to the cross-region database uploads when the region is cold-started only if it does not already exist in the cross-region database. You must either re-load the program or map manually, or remove it from the cross-region database before you cold-start the region.
  • To Add Programs and BMS Maps to a Database at Region Startup
Parent topic: Defining Program and Data Locations


To Add Programs and BMS Maps to a Database at Region Startup

A region startup file can be configured to deploy programs and BMS maps to the region or the cross-region database automatically during region startup
  1. Open the region's startup file in the Region Startup File editor.
  2. In the editor's tree pane, select Region > Deployments and select and expand the database item you want: Region Database or Cross-region Database.
  3. Under the database, right-click Map files or Programs and choose Add.

    The Add Deployment Path dialog box for the selected item appears.

  4. In the Add Deployment Path dialog box, type the filename to upload, or use the browse button to locate the file.
    • The File path field is where you set the location, including the filename, of the file to be loaded.
    • The Override file name is where you set the name that the application uses to invoke the program or map, if it is different from the filename.

      If the name is the same as the filename (for example, the file ACCT00.DLL contains the program ACCT00), you can omit the name.

  5. Click OK. The override filename and the file appear in the editor's Results pane.
  • A program or BMS map auto-deployed to the region database re-loads whenever the region is cold-started irrespective of whether it already exists in the region database.
  • A program or BMS map auto-deployed to the cross-region database re-loads when the region is cold-started only if it does not already exist in the cross-region database. You must either re-load the program or map manually, or remove it from the cross-region database before you cold-start the region.
Parent topic: Adding Programs and BMS Maps to a Database at Region Startup


Adding Data Files to a Data Store

Use one of the following methods to add the data files that your applications use to a data store database:

  • Data Store View in the Enterprise Server for .NET Administration UI
  • seedeploy
  • To Add a Data File using MMC
  • To Add a Data File using seedeploy
Parent topic: Defining Program and Data Locations


To Add a Data File using MMC

Use the following procedure to add a data file to a datastore database:
  1. In the Tree pane, select the SEE Administration > Shared Database Deployment Locations > Application Data Files item.
  2. Right-click the item and choose Add. The Add Deployment Path dialog box appears.
  3. In the Database Server Instance field, use the list to select the database server to use, or type the server details in the field, and click Next.

    For example, for a SQL Express installation on the local machine, type (local)\sqlexpress

    Enterprise Server for .NET connects to the database server and displays confirmation that it can connect.

  4. In the Define Datastore dialog box, click Create New.
  5. In the Data Store Name field, type a name for your datastore, and click Create.

    This is the name used by programs running in a region to locate the data store.

    Enterprise Server for .NET creates the data store, and displays it under the Data Store item.

  6. Choose File > Upload from the Data Store menu or click the Upload icon, then in the Upload File dialog box, locate and upload the VSAM file to import.
  7. Click the Refresh button to display the uploaded file's details in the editor.

    The following details display:

    • Filename
    • Format
    • Number of keys
    • Maximum record length
Parent topic: Adding Data Files to a Data Store


To Add a Data File using seedeploy

To add a data file to a datastore database from the command line:

  1. Open an Enterprise Developer command prompt.
  2. Use the seedeploy command.

    The following commands will create the datastore named VSAM and then add ACCTFIL to the root folder within it:
    seedeploy data create sql://localhost/sqlexpress/VSAM
seedeploy data add c:\datafiles\acctfil sql://localhost/sqlexpress/VSAM/ACCTFIL
Parent topic: Adding Data Files to a Data Store


Adding Programs and BMS Maps to a Data Store

Use one of the following methods to add the programs and BMS maps that your applications use to a data store database:

  • Data Store View in the Enterprise Server for .NET Administration UI
  • seedeploy
  • To Add Programs and BMS Maps to a Data Store using MMC
  • To Add Programs and BMS Maps to a Data Store using seedeploy
Parent topic: Defining Program and Data Locations


To Add Programs and BMS Maps to a Data Store using MMC

Enterprise Server for .NET Administration UI is used to add binary files such as programs and BMS maps to a data store database. To add a binary file:
  1. In the Tree pane under Shared Database Deployment Locations, click on Application Data Files. See 1 in the diagram below.

  2. If you have not previously done so, define the data store database that you want to add programs and/or BMS maps to. To do this:
    1. Select Add in the Actions pane. See 1 in the diagram below. The Define Data Store dialog is displayed.
    2. Enter the name of the database server instance you want to use in the Database server instance field and click on Next. See 2 in the diagram below.

      The next Define Data Store dialog page is displayed.

    3. Either select an existing data store from the list, or click on Create new to create a new data store. See 1 in the diagram below.

      Clicking on Create new displays the Create New Data Store dialog.

    4. Enter the name of the new data store in the Data store name field and click on Create. See 1 in the diagram below.

      The data store is created, the Create New Data Store dialog is dismissed and the name of the data store appears in the list of available data stores in the Define Data Store dialog.

    5. Select the name of the data store that you have just created and click on Finish. See 1 in the diagram below.

  3. Select the data store that you want to add programs and/or BMS maps to. See 1 in the diagram below. The Data Store view is displayed in the Results pane.
  4. Click on the Upload button. See 2 in the diagram below.

    The Upload data files dialog is displayed.

  5. The files to be uploaded are specified as follows:
    1. Enter the names of the files that you want to upload in the Select files to upload field. The names must be separated by a semi-colon (;). The Browse button is available to allow you to navigate the file system to select the files. See 1 in the diagram below.
    2. Specify the name of the data store folder that will contain the uploaded files in the Data store folder field. If this field is left blank the files will be uploaded to the root folder of the data store.
    3. Select the Binary blob radio button. Any binary file, as opposed to a data file, being uploaded to a data store must have this option set. See 2 in the diagram below.
    4. Click on OK. See 3 in the diagram below.

      The selected files will be scheduled for uploading to the data store.

  6. The progress of the files selected for uploading to the data store will be displayed in the File Transfers window of the Data Store view. See 1 in the diagram below.

  7. Once the upload of the files is complete, you can use the Data Store View to navigate to their folder and view their properties and contents. In the example above, the files were uploaded into the ESDEMO folder. Double-click on ESDEMO in the left-hand pane of the Data Store View to navigate to the files in this folder. See 1 in the diagram below.

    The contents of the ESDEMO will be displayed in the left-hand pane of the Data Store View.

  8. Double-clicking on the name of a deployed file will cause its contents to be displayed in the File Viewer window. See 1 and 2 in the diagram below.
  9. Clicking on the Back button will navigate back to the parent folder. See 3 in the diagram below.

Parent topic: Adding Programs and BMS Maps to a Data Store


To Add Programs and BMS Maps to a Data Store using seedeploy

To add a program, BMS map or any other binary file to a data store database from the command line:
  1. Open an Enterprise Developer command prompt.
  2. Use the seedeploy command.

    The following commands will create the data store named BINARIES and then add ACCT00.dll to the ESDEMO/PROGRAMS folder within it:
    seedeploy data create sql://localhost/sqlexpress/BINARIES
seedeploy data add acct00.dll sql://localhost/sqlexpress/BINARIES/acct00.dll?folder=ESDEMO/PROGRAMS;type=blob
    The following command will add ACCTSET.mod to the ESDEMO/MAPS folder of the BINARIES datastore using the following command:
    seedeploy data add acctset.mod sql://localhost/sqlexpress/BINARIES/acctset.mod?folder=ESDEMO/MODS;type=blob
Parent topic: Adding Programs and BMS Maps to a Data Store


Defining Program and Data Locations in the Region Startup File

This section describes how to define the locations in the region startup file for the programs and data that your CICS and JES applications use.

Tip: Use the Region Startup File editor from the Enterprise Server for .NET user interface to define locations in a region startup file.

For a simple system where files are accessed only on the machine on which they reside, you can configure a relative or absolute path to a location in the local machine's file system.

For systems where files are used across different machines, such as in a cluster environment, you can configure a URL to define the locations.

Note: When multiple locations are defined, the order in which they appear indicates the order that will be used at run-time to locate files.
  • Using URLs to Define Program and Data Locations
  • Using Variables to Set Locations
  • Creating a Properties File
Parent topic: Defining Program and Data Locations


Using URLs to Define Program and Data Locations

URLs can be used in region startup files to specify the locations of the program and data files used by the region. It is not necessary to understand the formats of these URLS if you use the Region Startup File Editor in the Enterprise Server for .NET Administration UI to configure the program and data locations as they will be automatically constructed for you. See CICS Region Configuration and JES Region Configuration for details as to how you would do this.

The URL formats supported by Enterprise Server for .NET are:

  • File

    Specifies the location of files on the local disk or a network drive. Format:

    file:///x:/path/to/directory

    For example:

    <location url="file:///c:/MyBinaries" />
  • Cross-region database

    Specifies the location of files deployed to the cross-region database. Format:

    crossRegionDatabase

    For example:

    <location url="crossRegionDatabase" />
  • Region database

    Specifies the location of files deployed to the region database. Format:

    regionDatabase

    For example:

    <location url="regionDatabase" />
  • Custom database

    Specifies the location of files deployed to a user-specified database. Format:

    sql://server[/instance]/database/table

    where:
    • server is the hostname of the SQL Server instance, or localhost to specify the local system.
    • instance is the optional name of the database server instance.
    • database is the name of the database where files have been deployed
    • table is the name of the database containing the deployed files

    For example:

    <location url="sql://localhost/sqlexpress/MYPROGRAMS/ESDEMO" />
  • Data store database

    Specifies the location of ffiles deployed to a data store database. Format:

    sql://server[/instance]/datastore/?folder=/folder-name;type=folder

    where:
    • server is the hostname of the SQL Server instance, or localhost to specify the local system.
    • instance is the optional name of the database server instance.
    • datastore is the name of the data store where files have been deployed
    • folder is the name of the folder within the data store containing the deployed files

    For example:

    <location url="sql://localhost/sqlexpress/BINARIES/?folder=/ESDEMO;type=folder" />
Parent topic: Defining Program and Data Locations in the Region Startup File
Parent topic: Defining the Service Endpoints
Related information
CICS Region Configuration
JES Region Configuration


Using Variables to Set Locations

To define your artifact locations in a region startup file, use environment variables and pseudo-variables.

Define environment variables in your Windows environment. You can use these to define the locations that your applications use.

You can also define names and locations in a properties file. Specify this properties file for a region. The region startup process then creates pseudo-variables for each name - location pair defined in the properties file. The regions that use this startup file can use the pseudo-variables that you define.

For deployment locations such as path locations of configuration files deployed to a database, the pseudo-variable takes precedence over the environment variable when an environment variable and a pseudo-variable of the same name define different paths, For example, when a region startup process locates a configuration file to deploy to the cross-region database, it uses the path specified in the pseudo-variable.

For runtime locations such as path locations of maps and programs, the environment variable takes precedence over the pseudo-variable when an environment variable and a pseudo-variable of the same name define different paths. That is, when an application uses an artifact, it uses the location path specified in the environment variable.

Note:

If no properties file is specified in a region's startup file, the region startup process creates a properties file that contains name/value pairs for each of the environment variables in the environment space. With the seestart command used to start a region, you can use the -noproperties parameter to prevent the implicit creation of the properties file from occurring.

Parent topic: Defining Program and Data Locations in the Region Startup File


Creating a Properties File

A properties file defines pseudo-variables to specify artifact locations. The region startup process reads the properties file set for the region and creates a pseudo-variable for each item in the file that define a path.

You can use pseudo-variables to define artifact locations, or parts of an artifact location in the region startup file. For example $MYVAR/subdir where MYVAR is the pseudo-variable created from the properties file definition.

Use the following procedure to create a properties file.

  1. Create a region startup properties file, and configure pseudo-variables to define the paths to use. Use the Properties File editor to do this.
  2. In the user interface, configure the properties file to use when the region starts. You can also use the seestart command with -properties to specify the properties file.
The format of the region startup properties file that the editor creates is a follows:
<?xml version ="1.0"?>
<configuration>
  <configSections>
    <section name="properties" type="System.Configuration.NameValueSectionHandler" />
  </configSections>

  <properties>
      <add key="VAR1" value="c:\mydir\maps" />
      <add key="VAR2" value="c:\mydir\programs" />
  </properties>
</configuration>

With a region startup using the above properties file:

  • Occurrences of the VAR1 pseudo-variable are replaced with the path c:\mydir\maps.
  • Occurrences of the VAR2 pseudo-variable are replaced with the path c:\mydir\:\mydir\programs.
  • Setting a Region's Properties File
  • To Create or Edit a Region Startup Properties File
Parent topic: Defining Program and Data Locations in the Region Startup File


Setting a Region's Properties File

The way Enterprise Server for .NET sets a region's startup properties file depends on how you start a region.

  • With the user interface, you associate a region with a properties file before you start the region.
  • With the seestart command, you can use the -properties option to specify a region startup properties file.

    This overrides any property file settings in the user interface.

To set a region's properties file through the user interface:

  1. In the Tree pane, under SEE Administration > Regions, select the region to configure.
  2. In the Results pane, select the Properties file location item, and use the browse button to locate and select the file to use.

To set a region's properties file with the seestart command:

  • Use the -properties:<properties file name> parameter to set the properties file.
    For example, the following command starts the DEMO region using the Region_Common.config startup file and the DEMOproperties.config properties file in the C:\Configurations\properties folder.
    seestart -region:DEMO -regionfile:Region_Common.config
  -properties:C:\Configurations\properties\DEMOproperties.config
Parent topic: Creating a Properties File


To Create or Edit a Region Startup Properties File

A properties file contains pseudo-variables that define file and component locations. Use the Properties File Configuration Editor to create new properties files or edit existing properties files.
  1. In the Tree view, under Configuration, select Properties files.

    The Properties File Configuration Editor appears in the Results pane.

  2. Use the editor to either create a new properties file, or to open an existing properties file for editing.

    The editor displays the grid where the name and value of each property is entered.

  3. Use the editor to define the locations you want.
    • In the Name field, type the property name.

      This is the name of the pseudo-variable that is created when the region is started.

    • In the Value field, type the path, or path fragment that corresponds to the name.

      You can use pseudo-variables that define path fragments as part of a location definition, for example:

      $MYVAR/subdir, c:\mydir\$MYVAR, c:\mydir\$MYVAR\subdir

  4. Repeat the process to define properties for each of the pseudo-variables you want to use.
  5. Save and close the file.

    The properties file and the locations it defines are available for use with your region startup files.

Parent topic: Creating a Properties File


Defining Data Locations

For data stores, the method you use to define the location depends on where the data store is located:

  • For data stores deployed to a network drive, specify the location in the region startup file's CICS > Locations > Application VSAM File Paths section.
  • For data stores deployed to a user-defined database, do not configure the location. Specify the data store name the resource definition FCT, in the FCT's File Path property.
Parent topic: Defining Program and Data Locations


Configuring Regions and Resources

The topics in this section describe how to configure your Regions.

For CICS specific configuration topics see CICS - Administrator Role

For JES specific configuration topics see JES - Administration Role

  • About Region Startup and Resource Definitions
  • About Entry Point Name Mapping
Parent topic: General Administration


About Region Startup and Resource Definitions

To be able to start a CICS or JES region, a region startup file must first be created and associated with the region in the Enterprise Server for .NET Administration UI. The region startup file defines the characteristics of the region to be started and the locations of programs and data used by the region at run time.

Region start-up files are created and edited using the Enterprise Server for .NET Administration UI's Region Startup File Editor. These files can be persisted either to a local/network file system or to a cross-region database. A region startup file may be shared by multiple regions.

In addition to region startup files, CICS regions must also have a resource definition file associated with them. The location of the resource definition file is specified in the region startup file. Resource definition files are created and edited using the Enterprise Server for .NET Administration UI's CICS Resources File Editor. These files can be persisted either to a local/network file system or to a cross-region database. A resource definition file may be shared by multiple CICS regions.

A region database is created the first time a region is cold-started. A region database will always be re-configured each time the region is cold-started using the information in the region startup and, for CICS regions, resource definition files. When a region is warm-started, it starts using the configuration held within the region database rather than the region startup and resource definition files.

The installation software includes two sample region startup files:
  • Region_ESDEMO.config. This is the region startup file used by the sample CICS region, ESDEMO and is located in %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.
  • Region_JCLDEMO.config. This is the region startup file used by the sample JES region, JCLDEMO and is located in %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.
Regions administered by the Enterprise Server for .NET Administration UI are displayed in the tree pane under the SEE Administration->Regions->CICS and SEE Administration->Regions->JES nodes. Icons in the Enterprise Server for .NET Administration UI indicate a region's configuration state:
  • The user interface cannot connect to the region database. This typically appears when you first define a region and have not yet started it. The region database for a new region is not created until you start it.
  • An existing region database is not associated with a region startup file.
  • The region has a startup file and an associated database.
  • This icon appears while the system determines the region's state.
  • To Define a New Region With an Existing Region Startup File
  • To Set a Region's Startup File
Parent topic: Configuring Regions and Resources


To Define a New Region With an Existing Region Startup File

  1. In the Tree pane of the Enterprise Server for .NET Administration UI, select Regions. See 1 in the diagram below.
  2. In the Actions pane, click Define Region. See 2 in the diagram below. The first page of the Define Region wizard is displayed.
  3. Enter the name of the database server instance where you want your region database to be created, or where your region database already exists, in the Database server instance entry field. For example, for a SQL Server Express instance on the local machine, type: (local)\SQLEXPRESS. Click Next. See 3 in the diagram below.

    • The syntax for the database server instance follows the standard SQL connection rules.
      • (local) would connect to the main database in the local machine using named pipe .
      • localhost would connect to the main database in the local machine using TCPIP.
      • localhost\sqlexpress would connect to the sqlexpress database instance on the local machine using TCPIP.
      • machineName\MSSQLSERVER would connect to the MSSQLSERVER database running on machine "MachineName" using TCPIP
    • For further information on this syntax, please refer to the SQL server documentation.

    Enterprise Server for .NET Administration UI now connects to the selected database server and the next page of the Define Region wizard is displayed. This page lists all existing region databases on the selected database server that are not currently defined to the UI.

  4. Either select one of the regions listed in the Existing regions in server instance list, or enter the name of a new region in the Region name entry field. Click Next. See 4 in the diagram below.

    The next page of the Define Region wizard is displayed. This page prompts you to select a region startup file to be associated with the region.

  5. Select the region startup file to be associated with the region. Valid locations for the region startup file are:
    Local machine
    Select when the startup file is located on a drive on the local machine.
    Server machine
    Select when the startup file is located on another network machine. You would use this option when, from your local machine, you want to create and manage regions on a remote machine.
    Cross-region database
    Select when the startup file is in the cross-region database of the database server instance that you specified earlier. This is the preferred option for a production or a scale-out environment.

    Use the Browse button to browse for the region startup file in the selected location. See 5 in the diagram below.

    Note:

    The default Region_ESDEMO.config and Region_JCLDEMO.configfiles are installed to %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

    Click Finish to create the region definition. See 6 in the diagram below.

    The region now appears in the Tree pane of the user interface under the Regions->CICS node (because we selected the CICS ESDEMO region startup file in the previous step), with the [image] icon to show that the region database has not yet been created. See 7 in the diagram below.

When the region is started for the first time, the region database will be created and in the user interface, the region entry will appear with the [image] icon.

Parent topic: About Region Startup and Resource Definitions
Related concepts
Setting Up the User Interface
Starting a Region
Related tasks
To Create a CICS Region Startup File
To Create a JES Region Startup File


To Set a Region's Startup File

You can set a region's startup file after creating the region. Use the following procedure to create a region definition without a startup file associated with it and then subsequently associate one.
  1. In the Tree pane of the Enterprise Server for .NET Administration UI, select Regions. See 1 in the diagram below.
  2. In the Actions pane, click Define Region. See 2 in the diagram below. The first page of the Define Region wizard is displayed.
  3. Enter the name of the database server instance where you want your region database to be created, or where your region database already exists, in the Database server instance entry field. For example, for a SQL Server Express instance on the local machine, type: (local)\SQLEXPRESS. Click Next. See 3 in the diagram below.

    Enterprise Server for .NET Administration UI now connects to the selected database server and the next page of the Define Region wizard is displayed. This page lists all existing region databases on the selected database server that are not currently defined to the UI.

  4. Either select one of the regions listed in the Existing regions in server instance list, or enter the name of a new region in the Region name entry field. Click Finish to create the region definition. See 4 in the diagram below.

    The region now appears in the Tree pane of the user interface under the Regions->CICS node (because we selected the CICS ESDEMO region startup file in the previous step), with the [image] icon to show that the region database has not yet been created. See 5 in the diagram below.

  5. To associate a region startup file with the region definition that has just been created, click on Add Region File in the Actions pane. See 6 in the diagram below.

    The Region Startup File Location dialog is displayed

  6. Select the region startup file to be associated with the region. Valid locations for the region startup file are:
    Local machine
    Select when the startup file is located on a drive on the local machine.
    Server machine
    Select when the startup file is located on another network machine. You would use this option when, from your local machine, you want to create and manage regions on a remote machine.
    Cross-region database
    Select when the startup file is in the cross-region database of the database server instance that you specified earlier. This is the preferred option for a production or a scale-out environment.

    Use the Browse button to browse for the region startup file in the selected location. See 7 in the diagram below.

    Note:

    The default Region_ESDEMO.config and Region_JCLDEMO.configfiles are installed to %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

    Click Ok to associate the startup file. See 8 in the diagram below.

    The Region Startup File Location dialog is dismissed

Parent topic: About Region Startup and Resource Definitions


About Entry Point Name Mapping

On the mainframe, programs are compiled and linked into load modules. A compiled program may have one or more entry points (e.g. a COBOL program may have one or more ENTRY statements defining its entry points). When linked into a load module, each of the entry point names is exposed to allow them to be invoked at run time. Before running an application, the load modules required by the application need to be defined to the operating system, typically by allocating them to the JOBLIB or STEPLIB DD name. At run time, the operating system searches through the defined set of load modules, in the order in which they have been defined, for the name of a program requested to be invoked (e.g. the program name specified by the PCT entry associated with a CICS transaction, or the program name specified by an EXEC PGM=pgmname statement in a batch job). Any program subsequently dynamically invoked by the application will be located in exactly the same way

For example, a COBOL program MYUID.SOURCE.COBOL(A) could have the entry points X, Y and Z defined as follows:
       IDENTIFICATION DIVISION.
       PROGRAM-ID. A.
       ...
       PROCEDURE DIVISION.
       ...
       ENTRY 'X'.
       ...
       ENTRY 'Y'.
       ...
       ENTRY 'Z'.
       ...
When compiled and linked on the mainframe, the resulting load module (e.g. MYUID.TEST.LOAD) would have the main entry point A and the alternate entry points X, Y and Z exposed as MYUID.TEST.LOAD(A), MYUID.TEST.LOAD(X), MYUID.TEST.LOAD(Y) and MYUID.TEST.LOAD(Z). The following snippet of JCL shows how entry point Y would be invoked in batch:
...
//MYSTEP   EXEC PGM=Y
//STEPLIB  DD DSN=MYUID.TEST.LOAD,DISP=SHR
...

Using Enterprise Server for .NET, the program A in the example above would typically be compiled to an assembly named A.dll and deployed to one of the program locations defined in the region startup file to make it available for run-time invocation. However, by default, only the main entry point A (i.e. the name of the assembly that was created when the source was compiled) would be visible to Enterprise Server for .NET. The entry points X, Y and Z would not be visible until the assembly A.dll had been loaded. This would mean that the example JCL snippet above would result in an S806 abend (program not found) at run-time if A.dll had not been loaded.

To resolve this problem, Enterprise Server for .NET provides the capability for associating entry point names with the assembly in which they reside through use of Entry Point Name Mappings in the Region Startup File Editor.

  • To Define Entry Point Name Mappings
Parent topic: Configuring Regions and Resources


To Define Entry Point Name Mappings

This procedure demonstrates how to define Entry Point Name Mappings using the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the CICS or JES region you are configuring with the Region Startup File Editor editor. See To Edit a CICS Region Configuration and To Edit a Region Startup File Associated with a JES Region .
  2. In the Results pane expand the Region node and select the Entry Point Name Mappings node. See 1 in the diagram below.
  3. Right-click and select Add. See 2 in the diagram below.

    The Define Entry Point Mapping dialog is displayed.

    1. Enter the name of the entry point that you want to map in the Entry point name field
    2. Enter the name of the program that must be on the call stack for this mapping to take place, or '*' for any program, in the Program name field
    3. Enter the name of the subprogram or assembly that contains the entry point in the Subprogram name field
    4. If you want to map the entry point name on to an entry with a different name in the containing assembly, check Aliased entry point and enter the aliased name in the Aliased entry point name field
    5. Click on OK. See 3 in the diagram below.

    The dialog is dismissed and the entry point mapping appears in the right-hand side of the Results pane. See 4 in the diagram below.
  5. Choose File > Save, or click the Save icon in the toolbar to save the file. See 5 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: About Entry Point Name Mapping


Starting and Stopping a Region

You can start and stop regions either on the local server, or on a remote server.

  • Starting a Region
  • Stopping a Region
Parent topic: General Administration


Starting a Region

You can start a region on the local machine or on a remote machine. The event monitor on the target machine can be used to start regions. You can also start a region from the Enterprise Server for .NET user interface, or by using the seestart command.

To start a region, you can perform either a cold start or a warm start.

With a cold start, the region's database is created if it does not already exist. If it exists, all its tables and stored procedures are dropped. The cold start re-creates all required tables (some fixed, some transient) and installs stored procedures.

With a warm start, a region database must exist. The start uses the existing versions of fixed tables, such as the CSA and resource definitions.

Only transient tables only and re-created, for example the request queue and the connected sessions table.

Note: You can perform a warm start only if the region was previous stopped normally, using the Normal stop option. If the region had previously been stopped with an "Immediate stop" or a "Force stop", only a cold start is allowed.
  • To Start a Region
Parent topic: Starting and Stopping a Region
Related concepts
Setting Up the User Interface
Related tasks
To Define a New Region With an Existing Region Startup File


To Start a Region

Use this procedure to start a region from the Enterprise Server for .NET user interface.
  1. In the Tree pane, under Regions, select the region to start.
  2. In the Action pane, select Start/Stop Region.

    The Start/Stop Server field appears in the Results pane, and the Start button appears at the bottom of the user interface.

  3. Do one of the following:
    • To start the region on the local machine, leave the Start/Stop Server field blank.
    • To start the region on a remote machine, in the Start/Stop Server field, enter the name of the machine on which the region is to start, or select the machine name from the pull-down list.
  4. Select whether to Cold start or Warm start the region, and click Start.

    Messages display in the Results pane that indicate the region startup progress. Error messages display if the region fails to start.

Parent topic: Starting a Region


Stopping a Region

You can stop a region on the local machine or on a remote machine. The event monitor on the target machine can be used to stop a region.

Enterprise Server for .NET provides different options for stopping regions.

To stop a region, you can perform a Normal stop, an Immediate stop, or a Force stop:

  • With a Normal stop:
    • New transaction requests are blocked.
    • Transactions that are running are allowed to complete.
    • After the tasks complete, the PLTSD shutdown procedure runs.
  • With a Immediate stop:
    • New transactions are blocked.
    • Transactions that are running are aborted.
    • The PLTSD shutdown procedure runs.
  • With a Force stop, the system does whatever is necessary to stop the region immediately. The PLTSD shutdown procedure does not run.
Note: For each of these stop types, any connected terminals are disconnected.
  • To Stop a Region
Parent topic: Starting and Stopping a Region


To Stop a Region

Use this procedure to stop a region from the Enterprise Server for .NET user interface.
  1. Under Regions in the Tree pane, click the region to stop.

    The Start/Stop Region option appears in the Actions pane.

  2. Select the Start/Stop Region option.

    The Stop button appears at the bottom of the Results pane.

  3. Select the stop type you want, and click Stop.

    Messages display in the Actions pane to show the progress, and the region shuts down.

Parent topic: Stopping a Region


Securing the Environment

Topics in this section cover the issues and procedures involved in securing the Enterprise Server for .NET application environment, and the programs and resources that the environment uses.

By default, Enterprise Server for .NET runs applications under the account in which the hosting session was started. Configure user impersonation to override this default. User impersonation lets you set application and resource access to either the environment's default user, or the session's CICS signed on user.

  • About User Impersonation
  • Controlling Impersonation Behavior
  • Authenticating CICS SQL Operations
  • Using EXEC CICS SIGNON and SIGNOFF
  • Troubleshooting Impersonation Issues
  • Using Logon Providers
  • Reducing the Attack Surface
    Remove unneeded configuration items
Parent topic: General Administration


About User Impersonation

User impersonation functionality allows you to configure the environment's hosting account to either the default user account, or to the session's CICS signed on user account. The signed on user account is controlled using EXEC CICS SIGNON and EXEC CICS SIGNOFF.

Applications host under the account that started the session by default. User impersonation allows you to avoid the following situations:

  • The hosting account may have inappropriate privileges for normal applications. For example, self-hosted SEPs can run in an administrative account with access to the operating system. This can lead to dangerous situations.
    Note: Typically, SEPs are hosted in an IIS w3wp.exe process that runs under a system administrator account. Self-hosted SEPs are used mainly for debugging.
  • Some applications may need access to sensitive resources to which they do not have access under the hosting account. User impersonation lets you set required application privileges as the application requires it.

The user impersonation that you configure applies to a session, which is generally equivalent to a terminal connection, ISC conversation, or MFBINP conversation.

  • About the Default User Account
  • Configuring Security in a Multi-Machine Environment
  • Configuring User Access Across Domains
  • Configuring Surrogate User Authority
  • Setting the Windows Logon Type
Parent topic: Securing the Environment


About the Default User Account

Impersonation lets you switch between a signed on user and a default user account. The default user account is a normal Windows user account with a default ID of mfuser, and a password of mfuser. You can configure the account name and password.

Note: You must create the default user account if enabling default-user impersonation. It must be created by a local or domain administrator, depending on whether the system is part of a domain. The account must have sufficient permissions to log on to Windows interactively.

To reduce the privileges available to user-written code (and increase security), the default user account should have minimal privileges. For example, it can only be a member of the built-in Guests group.

Important: The default user account is configured in the machine.config file, so it is relatively easy for users with access to anEnterprise Server for .NET system to retrieve the default username and password. Consequently, the default user account should not be an account with elevated privileges.
Parent topic: About User Impersonation


Configuring Security in a Multi-Machine Environment

In a multi-machine environment, a region can operate across multiple systems. For example in a cluster environment, network load balancing uses SEPs running on more than one system.

Users typically sign on once during a session. The event monitor on the signed-on system accesses the user's credentials (username and password) and generates user impersonation tokens as needed.

In a multi-machine environment, SEPs can run on machines other than the signed-on system. These SEPs do not have access to the user's credentials. In these environments, there are additional considerations for user impersonation.

Enterprise Server for .NET provides two mechanisms to support this architecture. Both use the Server EE for .NET monitor service (seemonitor.exe) to obtain user tokens for SEPs. In a scale-out environment with user-impersonation enabled, you can use one of the following mechanisms:

  • Protocol transition (PT)

    Protocol transition uses a feature of Windows 2003 (and later) domains to create tokens for users without having their passwords. This is the default mode for monitors in a scale-out environment. If all of your systems are joined to a Windows 2003 domain, and the monitor process is running under a trusted account (the default SYSTEM account for Windows services is trusted in a standard installation), you can generally use PT mode without any further configuration.

    Note: This refers specifically to Windows 2003 domains, and not about Windows 2003 machines running Enterprise Server for .NET, as this is an unsupported execution environment. Enterprise Server for .NET is supported only on Server 2008, VIsta and Windows 7
  • Credential passing (CP)

    In environments where you cannot use PT, you can enable CP mode. CP mode is more complex, and involves transmitting encrypted user passwords between event monitor processes. CP can be used in non-domain configurations.

    Note: CP mode requires that event monitors retain and transmit user passwords. This can be a security exposure.

You configure the token creation mode in machine.config:

  • For PT mode, set the Security.users.tokenCreationMode option in machine.config to: transition
    This is the default mode. For example:
    <MicroFocus.SEE>
    ...
    <add key="Security.users.tokenCreationMode" value="transition"/>
    ...
 </MicroFocus.SEE>
  • For CP mode set the Security.users.tokenCreationMode option in machine.config to: credentials
    For example:
    <MicroFocus.SEE>
    ...
    <add key="Security.users.tokenCreationMode" value="credentials"/>
    ...
</MicroFocus.SEE>
Parent topic: About User Impersonation


Configuring User Access Across Domains

You can configure user credentials verification across domains. You can configure user log on to locations other than the default. By default, Windows attempts to log a user on to the domain the system is attached to, or to the local system if it is not part of a domain. If the user does not exist in the default location, you can configure the system to try:

  • The local system.
  • A domain other than the one the local system belongs to.
  • Any other domains trusted by the local system's domain.

    With this option, the process searches for a corresponding user ID in the local system and the domain forest, and tries the log on in the first domain where the user ID is located.

Parent topic: About User Impersonation


Configuring Surrogate User Authority

Surrogate user authority is the ability to start work on behalf of another user. If user A has surrogate authority for user B, then user A can start a task that runs under user B’s user account.

By default, users do not have surrogate authority. You can specify that all users are granted surrogate authority. Enterprise Server for .NET does not currently let you selectively grant surrogate authority either to or for individual users.

Surrogate authority allows users to specify any recognized user name in the USERID parameter of the EXEC CICS START macro: EXEC CICS START USERID(. . .)

See the CICS documentation for more information on surrogate users.

Parent topic: About User Impersonation


Setting the Windows Logon Type

You can set the Windows logon type for impersonated users that your applications use. When an impersonated user logs on to access a program or a resource, it uses the logon type that you set. The Windows logon type is recorded in the logon/logoff category of the Windows security log. See the Microsoft documentation for more information on Windows logon types.

Parent topic: About User Impersonation


Controlling Impersonation Behavior

To control user impersonation in the machine.config file, you enable or disable the following impersonation settings:

  • Security.users.impersonateUsers controls the impersonation of the default user.
  • Security.users.impersonateDefaultUser controls whether EXEC CICS SIGNON changes the session's impersonated identity.

You enable or disable these options in conjunction with each other to set the configuration that you want. The four combinations available are detailed below:

impersonateUsers False, impersonateDefaultUser False
This is the default setting. All code runs under the user account that started the session.
impersonateUsers False, impersonateDefaultUser True

Sessions always run under the default user account. EXEC CICS SIGNON verifies user credentials, but does not change the session's impersonation identity.

This setting is useful when you want to run all application code under a reduced-privilege account and stitching identities it is not necessary.

impersonateUsers True, impersonateDefaultUser True

Impersonation is fully enabled, and sessions run under the default user account. EXEC CICS SIGNON changes the user account to the logged on user account.

impersonateUsers True, impersonateDefaultUser False

Sessions run under the user account that started the session. EXEC CICS SIGNON changes the user account to the logged on user account.

This configuration is useful for testing user-based security or if only some applications need to run under a special account.

  • Settings for User Impersonation Security
  • To Set Impersonation Options using machine.config
  • Activating User Impersonation Changes
Parent topic: Securing the Environment


Settings for User Impersonation Security

This topic covers the machine.config settings to configure user impersonation.

Setting impersonation behavior

Use these settings together to configure user impersonation behavior.

Security.users.impersonateUsers

Set to True to enable impersonation of explicitly logged on users. The default is false.

For example:
<MicroFocus.SEE>
    ...
    <add key="Security.users.impersonateUsers" value="true">
    ...
 </MicroFocus.SEE>
Security.users.impersonateDefaultUser

Set to True to enable impersonation of the default user. The default is false.

For example:
<MicroFocus.SEE>
    ...
    <add key="Security.users.impersonateDefaultUser" value="true">
    ...
</MicroFocus.SEE>

You enable or disable these options in conjunction with each other to set the configuration that you want. The four combinations available are detailed below:

impersonateUsers False, impersonateDefaultUser False
This is the default setting. All code runs under the user account that started the session.
impersonateUsers False, impersonateDefaultUser True

Sessions always run under the default user account. EXEC CICS SIGNON verifies user credentials, but does not change the session's impersonation identity.

This setting is useful when you want to run all application code under a reduced-privilege account and stitching identities it is not necessary.

impersonateUsers True, impersonateDefaultUser True

Impersonation is fully enabled, and sessions run under the default user account. EXEC CICS SIGNON changes the user account to the logged on user account.

impersonateUsers True, impersonateDefaultUser False

Sessions run under the user account that started the session. EXEC CICS SIGNON changes the user account to the logged on user account.

This configuration is useful for testing user-based security or if only some applications need to run under a special account.

Setting the default user

Use these settings to configure the default user for impersonation functionality.

Important: The default user that you configure must exist on your system, and must have sufficient permissions to log on to Windows interactively (or using the configured logon type, if you change the logon type with Security.users.logonType).
Security.users.defaultUser

Set to the name of the default user. The default is: mfuser

For example:
<MicroFocus.SEE>
    ...
    <add key="Security.users.defaultUser" value="cicsuser">
    ...
</MicroFocus.SEE>
Note: For this example to work, you need to create the cicsuser user ID.
Security.users.defaultUserPassword

Set to the password of the default user. The default is: mfuser

For example:
<MicroFocus.SEE>
    ...
    <add key="Security.users.defaultUserPassword" value="password">
    ...
</MicroFocus.SEE>

Setting the token creation method

For multiple-machine environments such as clusters, these settings control how user tokens are created to handle log ins across the multiple machines.

Security.users.tokenCreationMode
  • transition

    Sets user impersonation on a multiple machine system to Protocol Transition (PT) mode. This is the default mode for event monitors in a scale-out environment

  • credentials

    Sets user impersonation on a multiple machine system to Credentials (CP) mode.

For example, the following line sets user impersonation on a multiple machine system to Credentials (CP) mode.
<MicroFocus.SEE>
    ...
    <add key="Security.users.tokenCreationMode" value="credentials">
    ...
</MicroFocus.SEE>

Setting user domain options

Use these settings to configure how the system performs log ons across domains.

Security.users.domain
Set this to authenticate users in a domain other than the one the system belongs to. Event monitor processes running on a computer not joined to a domain will authenticate users locally. This can also be set to . (a period or full-stop character) to force systems to authenticate locally.
Security.users.searchDomains
If this is set to true, and a log on request for a user finds the user is not defined in the default domain, the event monitor process searches the local system and any other domains trusted by the system for the user, and attempt to authenticate in the first domain where the user is found.
Security.users.tryLocalLogon
  • If set to true, the event monitor process attempts to authenticate the user first in the default domain, then in the local system.
  • If set to first, the event monitor process attempts to authenticate the user first in the local system, then the specified domain or domain search.

If neither of these options are set, the system attempts to log users on to the local domain if the computer is joined to one, or to the local system if it is not.

Setting the Windows logon type

By default, Enterprise Server for .NET logs users on to Windows using the LOGON32_LOGON_INTERACTIVE logon type. For impersonated users, you can configure the Windows logon type by setting security.users.logonType to one of the following:

security.users.logonType
Type | Value
LOGON32_LOGON_INTERACTIVE (This is the default type.) | interactive
LOGON32_LOGON_BATCH | batch
LOGON32_LOGON_SERVICE | service
LOGON32_LOGON_NETWORK | network
LOGON32_LOGON_NETWORK_CLEARTEXT | cleartext

See the Microsoft Windows SDK documentation for the LogonUser API for more information on logon types.

Setting a surrogate user

You can specify that all users are granted surrogate authority.

allowSurrogate
  • True

    All user accounts are granted surrogate authority. That is, all users can specify any recognized user name in the USERID parameter of the EXEC CICS START macro.

  • Any other value, or not set

    The only values that are accepted in the USERID parameter are:

    • The name of the user who is currently signed on in the session where the application is running.
    • The default user.
Parent topic: Controlling Impersonation Behavior


To Set Impersonation Options using machine.config

You need administrator access to perform this task.

User impersonation options are set in the .NET Framework's machine.config file. Impersonation options are set as key/value pairs using the add element in the file's MicroFocus.SEE section.

  1. Make a backup copy of machine.config.

    The file is in %windir%\Microsoft.NET\Framework\version\Config or %windir%\Microsoft.NET\Framework64\version\Config, where version is the .NET Framework version used by Enterprise Server for .NET.

    Use the file in Framework when running a 32-bit version of Windows, or the file in Framework64 when running on 64-bit Windows.

  2. Open machine.config for editing.
  3. If the MicroFocus.SEE section is not defined in the file, add a <section> element to the configSections section as follows.
    <!-- Added for Micro Focus SEE for .NET -->
<section name="MicroFocus.SEE"
             type="MicroFocus.SEE.Utils.GlobalConfigurationSection,
             MicroFocus.SEE.Utils,Version=4.0.0.0,
             Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
  4. At the end of the file, just before the closing tag, add the MicroFocus.SEE section.
    <!-- Added for Micro Focus SEE for .NET -->
<MicroFocus.SEE>
</MicroFocus.SEE>
  5. Add your configurations inside the MicroFocus.SEE section as required.

    Use the following syntax to add a key.

    <add key=key to add value=key value>

    For example, the following key enables user impersonation of logged on users.

        ...
    <add key=" Security.users.impersonateUsers" value="true"/>
    ...
  </MicroFocus.SEE>
  6. Save and close the file.
machine.config is processed when a process starts, so changes are picked up by a SEP when its hosting process starts.
  • For self-hosted SEPs, restart the process to pick up changes.
  • For WAS-hosted SEPs, use the wasreset.cmd script to restart WAS.
Parent topic: Controlling Impersonation Behavior
Parent topic: Configuring Logon Providers


Activating User Impersonation Changes

You configure users impersonation behavior in the machine.config file. Configurations specified in this file apply when a SEP or event monitor process starts.

To ensure that a SEP applies your changes:

  • For WAS-hosted SEPs, use the wasreset.cmd script to restart WAS.
  • For self-hosted SEPs, these processes are normally started as child processes of the dispatcher and event monitor, or by Visual Studio when debugging.

The domain options that you set are processed by the event monitor process:

  • Security.users.domain
  • .searchDomains
  • .tryLocalLogon)
  • Multi-machine environments: Security.users.tokenCreationMode

The domain settings you configure take effect when the event monitor process restarts. The event monitor usually runs as a Windows service. Restart it using the Services control panel.

Note: Stop all local SEPs, dispatcher and the MMC Enterprise Server for .NET Administration user interface processes before restarting the event monitor process.
Parent topic: Controlling Impersonation Behavior


Authenticating CICS SQL Operations

CICS applications can perform SQL operations using the EXEC SQL statement. By default CICS manages the connection to the database used by EXEC SQL statements within an application program. The connection string used by CICS to connect to a database is defined as part of an XA resource definition (seeAbout XA Resources ). This prevents having to hard-code connection strings within your CICS applications.

The first time a CICS application executes an EXEC SQL statement, the connection string defined by the XA resource definition is used to establishes the database connection. The connection is used for all subsequent SQL operations that the application makes.

Note:

The following SQL operations are not supported in the source for your CICS application when using the XA resource definition:

  • CONNECT
  • DISCONNECT
  • BEGIN TRANSACTION
  • COMMIT
  • ROLLBACK
Parent topic: Securing the Environment


Using EXEC CICS SIGNON and SIGNOFF

Once you have enabled and configured user impersonation, you can change the user account for a session by invoking EXEC CICS SIGNON.

After successfully invoking EXEC CICS SIGNON, all subsequent transactions in that session run under the logged on user's identity.

You can immediately revert the session to the default identity by invoking EXEC CICS SIGNOFF.

Note: EXEC CICS SIGNON takes effect with the next transaction, whereas EXEC CICS SIGNOFF takes effect immediately, in mid-transaction if a transaction is running. This is the same behavior as EXEC CICS SIGNON/SIGNOFF on the mainframe.
Parent topic: Securing the Environment


Troubleshooting Impersonation Issues

To identify the causes of impersonation issues:

  • Look for SEP console log messages regarding impersonation and user identity. These messages can indicate the cause of the problem.

    For example:

    EP0060E: Unable to retrieve identity for user ID {0}. Request for transaction {1} on session {2} terminated.

    where: {0} = user ID; {1} = transaction name; {2} = session ID

  • Use the Windows Event Log console to check the Micro Focus Server event log. The event monitor raises events in that event log for various impersonation failures. For example:

    EM0020E Protocol-transition token creation requires a Windows 2003 or later domain. SEE Monitor configuration specifies impersonation using protocol-transition mode with local user authentication, which will not work.

  • Resolving Transaction Abend Issues
  • Tracing User Impersonation Issues
Parent topic: Securing the Environment


Resolving Transaction Abend Issues

Issues with security access to transactions and resources can cause transactions to abend.

Transaction abends

If a SEP cannot associate the session with the appropriate user when running a transaction, the transaction abends with code AIC0. This can happen before executing a user program at the start of a link level, or during processing of EXEC CICS SIGNOFF.

Abends accessing resources

Impersonation may also cause various abends when transactions try to access resources. Typically, these problems are configuration issues. A user has attempted to access a resource such as a file or a system API for which the log on ID is not authorized.

To resolve these issues, check the access rights of the impersonation users that you use.

Parent topic: Troubleshooting Impersonation Issues


Tracing User Impersonation Issues

Use the Consolidated Tracing Facility (CTF) if the console and Windows Events logs do not reveal the source of user impersonation issues.

To trace security issues, enable tracing for the #security feature in the SEP and event monitor. The most information is available at the debug tracing level.

For example:

For seesep.exe.config, or the IIS Web.config:
  <MicroFocus.COBOL.Tracing>
    <mftrace_config>
      <![CDATA[>
...
mftrace.level.mf.see.sep           = debug
mftrace.comp.mf.see.sep#securit y  = true
...
      <]]>
    </mftrace_config>
  </MicroFocus.COBOL.Tracing>
For seemonitor.exe.config:
  <MicroFocus.COBOL.Tracing>
    <mftrace_config>
      <![CDATA[>
...
mftrace.level.mf.see.monitor           = debug
mftrace.comp.mf.see.monitor#security   = true
...
      <]]>
    </mftrace_config>
  </MicroFocus.COBOL.Tracing>
Parent topic: Troubleshooting Impersonation Issues


Using Logon Providers

Enterprise Server for .NET uses a logon provider to validate user credentials (user ID and password) for APIs such as EXEC CICS SIGNON. With user impersonation enabled, the logon provider also supplies the token used to impersonate the user.

  • What is a Logon Provider?
  • Logon Providers in Enterprise Server for .NET
  • Configuring Logon Providers
  • To Use Service Bus Log On with Windows Azure
    Service Bus log on lets Enterprise Server for .NET running in the Windows Azure cloud validate user log on requests against a computer running on a private network. Users can authenticate as local computer users or domain users.
Parent topic: Securing the Environment


What is a Logon Provider?

When Enterprise Server for .NET needs to obtain a user token for impersonation, or to validate a set of user credentials, such as to respond to an EXEC CICS SIGNON request, it invokes the logon provider. The logon provider is a plug-in module that handles these functions. It's loaded into the Event Monitor process, and is mostly invoked to handle requests from Service Execution processes, as shown in the following graphic.

Putting logon functions in a separate module gives Enterprise Server for .NET the flexibility to use different security systems or provide special mechanisms for user authentication. Logon providers are configured on a per-system basis, so all regions running on a given host or Windows Azure role use the same logon provider.

Parent topic: Using Logon Providers


Logon Providers in Enterprise Server for .NET

Enterprise Server for .NET includes a default Windows logon provider and a service bus logon provider which lets Windows Azure roles authenticate against a Windows system or domain on a private network.

The Windows logon provider is the default provider. It is used when the system configuration provides no other provider. The Windows logon provider can also be explicitly configured. It uses the Windows LogonUser API to verify user credentials and create impersonation tokens. It has a variety of configuration options.

The Service Bus logon provider is primarily used in some Windows Azure deployment configurations, but can also be used on non-Azure systems. It lets Enterprise Server for .NET authenticate users against a Windows system running on a different network, by connecting the Event Monitor to a Windows service running on the target system through the Windows Azure AppFabric Service Bus. The AppFabric Service Bus connects applications running on separate networks. It is useful when the service is running on a system not directly accessible from outside the network. For more information on the Service Bus, see https://www.windowsazure.com/en-us/home/tour/service-bus/.

When Enterprise Server for .NET uses the Service Bus logon provider, user log on requests are sent over the service bus to a Windows service, seesvcbuslogon, running on another system. This is typically a system inside your corporate Windows domain. seesvcbuslogon verifies user credentials and the result is sent back to the Service Bus logon provider module running under the Event Monitor on the Enterprise Server for .NET system.

The Service Bus log on provider is typically used with a Windows Azure deployment of Enterprise Server for .NET, when you want the users of your emulated mainframe regions to be able to sign on using their user names and passwords from your Windows corporate domain. Configure Enterprise Server for .NET in your Azure roles to use the Service Bus log on provider, and run the seesvcbuslogon service on a system in your Windows domain.

In most other configurations you would simply use the Windows log on provider.

Parent topic: Using Logon Providers


Configuring Logon Providers

You select a logon provider by adding an entry to machine.config (Windows deployment) or see.azure.config (Windows Azure deployment). The topic To Set Impersonation Options using machine cfg explains how to edit the machine.config file. If you do not configure a logon provider, the Windows logon provider is used by default. Note that the configured logon provider is used for all regions running on that system or Azure role instance.

To specify a logon provider, set the Security.users.logonProvider option to the name of the logon provider assembly. The logon providers supplied with Enterprise Server for .NET are MicroFocus.SEE.Logon.Windows and MicroFocus.SEE.Logon.ServiceBus. For example:

<MicroFocus.SEE>
    ...
    <add key="Security.users.logonProvider" value="MicroFocus.SEE.Logon.Windows"/>
    ...
 </MicroFocus.SEE>

Several of the options for controlling user impersonation (token creation mode, domain logon options, and Windows logon type) apply to the Windows logon provider. Since the Windows logon provider is used by the seesvcbuslogon service that handles requests from the Service Bus Logon Provider, it also uses those options.

The Service Bus Logon Provider and seesvcbuslogon have some additional configuration settings for the Windows Azure AppFabric Service Bus.

  • To Set Impersonation Options using machine.config
  • Settings for the Service Bus Logon Provider
Parent topic: Using Logon Providers


Settings for the Service Bus Logon Provider

This topic covers the settings that configure the Service Bus logon provider in machine.config, see.azure.config, and seesvcbuslogon.exe.config. The file you add these settings to depends on what you are configuring:

  • To enable Service Bus log on for Enterprise Server for .NET on Windows, edit machine.config.
  • To enable Service Bus log on for a Windows Azure role, edit see.azure.config.
  • To configure the seesvcbuslogon service to connect to the Windows Azure AppFabric Service Bus, edit seesvcbuslogon.exe.config. In this case, only the settings for the Service Bus connection are needed.

Enabling the Service Bus Logon Provider

This setting configures Enterprise Server for .NET to use the Service Bus logon provider.

Security.users.logonProvider

Set this to MicroFocus.SEE.Logon.ServiceBus to use the Service Bus logon provider. The default is MicroFocus.SEE.Logon.Windows.

For example:
<MicroFocus.SEE>
    ...
    <add key="Security.users.logonProvider" value="MicroFocus.SEE.Logon.ServiceBus">
    ...
 </MicroFocus.SEE>

Configuring the Windows Azure AppFabric Service Bus connection

The Service Bus Logon Provider and its corresponding Windows service, seesvcbuslogon, use the Windows Azure AppFabric Service Bus to communicate with one another. You have to set the AppFabric Service Bus parameters for all systems / Azure role instances using the Service Bus logon provider, and for the system where seesvcbuslogon is running. These settings specify the AppFabric Service Bus parameters. Find the values for these parameters from your Windows Azure AppFabric management console.

Security.servicebus.issuer
Set this to the AppFabric Service Bus issuer name. The default is owner.
Security.servicebus.secret
Set this to the AppFabric Service Bus secret, which is a Base64-encoded string. There is no default.
Security.servicebus.namespace
Set this to the AppFabric Service Bus namespace. There is no default.
For example:
<MicroFocus.SEE>
    ...
      <!-- issuer and secret are the AppFabric Service Bus credentials -->
      <add key="Security.servicebus.issuer" value="owner" />
      <add key="Security.servicebus.secret" value="YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnf=" />
      <!-- namespace is the Service Bus namespace -->
      <add key="Security.servicebus.namespace" value="mycorp-es-dotnet" />
    ...
 </MicroFocus.SEE>
Parent topic: Configuring Logon Providers


To Use Service Bus Log On with Windows Azure

Before starting this task, you should have a working Enterprise Server for .NET Azure deployment solution, as described in Configuring the CICS System, and an Azure account to deploy it to.
  1. Download the Microsoft Windows Azure AppFabric SDK (version 1.5 or later) and install it on the system you use to deploy Enterprise Server for .NET to Windows Azure. This is a free download. The Service Bus logon provider requires Microsoft.ServiceBus.dll. This is not currently licensed for redistribution, so you must add this assembly to the collection deployed to Azure.
  2. Open a command prompt window and change to the binAnyCPU\SEE\Azure folder under your Enterprise Server for .NET product installation folder. The environment variable SEEAZUREDIR should contain the path to this folder. Copy the file %Program Files%\Windows Azure AppFabric SDK\V1.5\Assemblies\NET4.0\Microsoft.ServiceBus.dll to that folder.
  3. Use a zip archive update tool such as WinZIP to add Microsoft.ServiceBus.dll to the zip file EnterpriseServerDotNetAzure.zip. The file EnterpriseServerDotNetAzure.zip now includes Microsoft.ServiceBus.dll.
  4. Connect to the Microsoft Windows Azure Management Portal. Follow the Service Bus, Access Control & Caching link. You should now be on the management portal for Azure AppFabric, which includes the Service Bus feature.
  5. Select Service Bus. If you already have a suitable namespace, skip to the next step. Click the New button on the Service Namespace toolbar. The Create a New Service Namespace dialog box appears.
  6. Make sure the Service Bus checkbox is selected. Give your namespace a name. This name must be unique, so it may be useful to include your organization name and possibly a project name or similar (for example mycorp-es-dotnet). Use the Check Availability button to confirm that the name is available. Select an appropriate country / region and Azure subscription (both typically the same as your Azure deployment). Click Create Namespace. The namespace is created.
  7. Display the Properties pane if not already visible. Note the service bus namespace. You need namespace to configure the logon provider and logon service.
  8. In the Properties pane under Default Key, click View button. The issuer and key display. The default issuer is "owner". Unless you need to use a different issuer for some reason, you do not need to record this. Make a note of the key. You can use the Copy to Clipboard button and then paste it into a temporary document. You need the key to configure the logon provider and logon service. You should now have your service namespace and key.
  9. Open the binAnyCPU\SEE\seesvcbuslogon.exe.config file in your Enterprise Server for .NET product directory for editing on the system where seesvcbuslogon service runs. Typically this is a Windows server system connected to your corporate domain, but can be any Windows system that has Enterprise Server for .NET installed and can authenticate your users. seesvcbuslogon does not require anEnterprise Server for .NET region to run, but currently cannot be installed separately.
  10. In the MicroFocus.SEE section, add the AppFabric Service Bus connection settings for the Service Bus logon provider. You do not need to set the Security.users.logonProvider parameter. You do not need to set Security.servicebus.issuer if your Service Bus uses the default issuer of owner. Save the file. seesvcbuslogon.exe.config should now include lines similar to the following:
    <MicroFocus.SEE>
    ...
      <add key="Security.servicebus.namespace" value="mycorp-es-dotnet" />
      <add key="Security.servicebus.secret" value="YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnf=" />
    ...
 </MicroFocus.SEE>
  11. Test the configuration by opening a command prompt and running the seesvcbuslogon command. You should see output similar to the following:
    Micro Focus Enterprise Server for .NET - Service Bus Logon Version a.b.cc
Copyright (C) Micro Focus 1984-2012. All rights reserved.

LO0001I Service Bus Logon Service starting
LO0004I Service is running; press <Enter> to exit
  12. Edit the see.azure.config file for your Enterprise Server for .NET Azure deployment solution. In the MicroFocus.SEE section, add the AppFabric Service Bus settings for the Service Bus logon provider. You must set the Security.users.logonProvider parameter to MicroFocus.SEE.Logon.ServiceBus. This lets Enterprise Server for .NET use the Service Bus logon provider. You do not need to set Security.servicebus.issuer if your Service Bus uses the default issuer of owner. Save the file. see.azure.config should contain something similar to the following:
    <MicroFocus.SEE>
    ...
      <add key="Security.users.logonProvider" value="MicroFocus.SEE.Logon.ServiceBus"/>
      <add key="Security.servicebus.namespace" value="mycorp-es-dotnet" />
      <add key="Security.servicebus.secret" value="YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnf=" />
    ...
 </MicroFocus.SEE>
  13. Use your Enterprise Server for .NET Azure deployment solution to deploy to Azure. You should have a running Enterprise Server for .NET deployment in Azure.
  14. Start a CICS region hosted in your new Azure deployment. You have a CICS region running under Azure, in the deployment configured to use the Service Bus logon provider.
  15. Connect a TN3270 terminal session to your Azure-hosted CICS region. Run the CESN transaction to sign on to CICS if not already running already. Log on using a username and password known to Windows on the system where seesvcbuslogon is running.
    Note: CICS currently restricts usernames and passwords to 8 ASCII characters, so your Windows credentials must meet those restrictions.
    You should see messages in the window where seesvcbuslogon is running, indicating that it is processing a log on request.
  16. (Optional) Configure seesvcbuslogon to run as a Windows service:
    1. In the window where seesvcbuslogon is running, press Enter key to stop execution.
    2. Run seesvcbuslogon -i to install it as a Windows service.
    3. (Optional) Open the Windows Services control panel. Open the Properties dialog for Micro Focus SEE Service Bus Logon and set the startup type to Automatic for the service to start automatically when the system boots. This is recommended if you intend to use the Service Bus logon provider in production.
Parent topic: Using Logon Providers


Reducing the Attack Surface

It is a good idea, particularly for production regions or other regions that run on shared systems or have access to sensitive data (such as testing or QA regions), to edit the configuration and disable features your applications do not use. This is called reducing the attack surface, because it leaves fewer things exposed to malicious users or accidental misuse.

The sample configurations provided with Enterprise Server for .NET enable many optional features. This is convenient for developers who may want to try those features or run sample programs included with the product, and it helps to document configuration options. While you can use those samples as a starting point for your own region configurations, we recommend reviewing their contents and removing items you don't need.

The following topics suggest some items you may wish to remove from various configuration files.

  • Optional Items in the CICS Region Startup File
    Configuration items that can be removed from a CICS Region Startup file
  • Optional Items in the JES Region Startup File
    Configuration items that can be removed from a JES Region Startup file
  • Optional Items in the CICS Resources Definition File
    Configuration items that can be removed from a CICS Resources Definition file
  • Optional Items in the Listener Configuration File
    Configuration items that can be removed from a Listener configuration file
Parent topic: Securing the Environment


Optional Items in the CICS Region Startup File

Micro Focus recommends disabling features you don't need, particularly for production regions, by editing your various Enterprise Server for .NET configuration files. These are items you can disable in the region startup file for a CICS region.

  • VSAM file, program, and map locations that are not used by your CICS applications. This is a small exposure if your filesystems and databases are already secured.
  • Web Services paths that you do not use. This is a larger exposure, since Web Services let any client invoke a matching CICS transaction using an HTTP request.
Parent topic: Reducing the Attack Surface


Optional Items in the JES Region Startup File

Micro Focus recommends disabling features you don't need, particularly for production regions, by editing your various Enterprise Server for .NET configuration files. These are items you can disable in the region startup file for a JES region.

  • Application Program Paths that are not used by your JES applications. This is a small exposure if your filesystems and databases are already secured.
  • EXCI APPLIDs that are not used by your JES applications. (If you do not use EXCI, you can remove all the APPLIDs.) This is a small exposure, since EXCI security should primarily be enforced by the target CICS regions.
  • EXCI Default URL and User Exit, if your JES applications do not use those features. This is also a small exposure.
Parent topic: Reducing the Attack Surface


Optional Items in the CICS Resources Definition File

Micro Focus recommends disabling features you don't need, particularly for production regions, by editing your various Enterprise Server for .NET configuration files. These are items you can disable in the resources definition file used by one or more CICS regions.

A CICS resources definitions file contains many types of resources. Resources are collected into groups. At region startup, a region's system initialization table (SIT) specifies a startup list of groups, and all the resources from the groups on that list are installed (made available). Some of these will be system resources that are required for CICS operation or are normally present (though some of the latter can be disabled if the administrator wants to restrict user access more than normal). Others are resources that have been created for your CICS applications.

The sample CICS resources definition file contains a large number of system and sample resources, and several startup lists and SITs. Administrators typically create the SIT and startup list for their regions by copying and modifying entries from the sample resources definition file, which may leave your regions defining and installing resources they don't need. You can remove unneeded resources by removing unnecessary groups from your startup list or deleting the groups or resources entirely. Note that if users have access to the CICS system transaction CINS or the EXEC CICS CREATE system APIs, they can install additional resources after startup, so removing groups from the startup list may not be sufficient, depending on your threat model.

Groups you may wish to remove from your CICS regions include:

DFH$ACCT
ACCT sample application.
DFH$APCT
CICS PL/I sample application. PL/I is not currently supported in Enterprise Server for .NET (so this sample cannot be used anyway).
DFH$IMQS and DFHMQS
IBM MQ sample application and MQ trigger transaction. MQ is not currently supported in Enterprise Server for .NET.
DFH$IVP
This group currently contains only a TN3270 printer definition.
DFHBRDG
Samples for the 3270 Bridge, which is not currently supported in Enterprise Server for .NET.
DFHCDDE, DFHCIPX, DFHCNETB, and DFHCTCP
Empty groups included for compatibility with the sample resource definitions for the native Enterprise Server product.
DFHCIVP
Samples for Distributed Program Link (DPL) and Function Shipping (FS). Enterprise Server for .NET does not currently support DPL or FS.
DFHELCG
Samples for Micro Focus Enterprise Link Component Generator, which is not currently supported by Enterprise Server for .NET.
DFHEXCI
The CPMI system transaction for EXCI, and the HR01 sample for CICS REST web services. If you do not use EXCI or REST web services, you do not need to install this group for your region.
DFHEZA
Definitions for IBM EZ Sockets APIs. EZ Sockets is not currently supported in Enterprise Server for .NET.
DFHISC
Used for Micro Focus Inter-System Communication, a CICS-to-CICS communication protocol for native Enterprise Server. It is not currently supported by Enterprise Server for .NET.
DFHSPI
The CINS transaction for dynamically installing resources, and the CFCR transaction for creating VSAM files. Normally these are included in a region, but an administrator might remove them to make these operations unavailable to users.
IMSGRP
CICS/IMS sample. IMS is not currently supported by Enterprise Server for .NET.
MCOASM
Assembler program sample. Assembler is not currently supported by Enterprise Server for .NET.
MCOGROUP
A single transaction, CMAP, which is used to display BMS maps on the terminal. Usually there is no exposure associated with this utility, but administrators might want to remove it from a locked-down region for completeness.
Parent topic: Reducing the Attack Surface


Optional Items in the Listener Configuration File

Micro Focus recommends disabling features you don't need, particularly for production regions, by editing your various Enterprise Server for .NET configuration files. These are items you can disable in a listener configuration file.

Most of the settings in a listener configuration file tell the listener how to connect to the dispatchers for one or more regions, or configure listener operating parameters. Reducing the listener attack surface is simply a matter of disabling any listener channels that are not required by the applications you run in Enterprise Server for .NET and the utility programs you use. The listener channel types are:

HTTP
The HTTP channel is currently used only for making REST web services and EXCI requests (which are implemented using REST) to Enterprise Server for .NET CICS regions. If you do not have client programs invoking CICS transactions or programs using REST or EXCI, you can disable or remove this type of channel. HTTP channels are not currently useful for JES regions and should not be configured for them.
MFBINP
The MFBINP channel is used by various utility programs supplied with the product. For CICS regions, this includes the casfile command, used to manipulate CICS files. For JES regions, it is used for cassub (to submit JCL) and casout (to retrieve JES output, start and stop initiators, etc). The MFBINP channel is also used by the Event Manager publish/subscribe mechanism and JES scheduler integration (MFBSI). CICS regions that do not use any of these features do not need an MFBINP channel; JES regions need an MFBINP channel to be useful.
TN3270
CICS regions use a TN3270 channel to permit terminal sessions to connect to the region. While it's possible to have a CICS region that does not allow TN3270 connections (and receives all its work via REST or EXCI, for example), this is not a typical configuration for Enterprise Server for .NET. (The scale-out features of Enterprise Server for .NET make the TOR/AOR architecture often seen with mainframe CICS much less desirable.) CICS reegions will usually have a TN3270 channel. TN3270 channels are not useful for JES regions and should not be configured for them.
Parent topic: Reducing the Attack Surface


Configuring XA resources

Topics in this section explain how XA resources are created and managed, and how regions are configured to make use of them.

  • About XA Resources
  • To Create an XA Resource Definition
Parent topic: General Administration
Related tasks
To Create an XA Resource Definition
To Associate an XA Resource with a CICS Region Startup File
To Associate an XA Resource with a SIT
To Associate an XA Resource with a PCT
Related information
About XA Resources


About XA Resources

Enterprise Server for .NET requires an XA resource definition to be used when a CICS transaction or batch application uses a SQL database. An XA resource definition identifies the region it is associated with, the database connection string, and optionally the plan, package path or package set to be used. XA resource definitions are persisted in the cross-region database.

For CICS regions, an XA resource definition can be associated with a region or a PCT. A region association is made by naming the XA resource to be used as property of the SIT or region start-up file. When specified in both the SIT and region start-up file, the region start-up file takes precedence. By default the XA resource definition associated with the region will be used when a transaction uses a SQL database. However, if an XA resource definition is defined for a PCT, that definition will be used in preference to the one associated with the region when the transaction is invoked.

For JES regions, an XA resource definition is required for each named system used when calling DSNALI or when invoking the TSO DSN command. No additional configuration is required for JES regions.
Note:
DSNRLI is not currently supported by Enterprise Server for .NET.
Parent topic: Configuring XA resources
Related tasks
To Create an XA Resource Definition
To Associate an XA Resource with a CICS Region Startup File
To Associate an XA Resource with a SIT
To Associate an XA Resource with a PCT
Related information
Configuring XA resources
DB2 Call Attach Facility


To Create an XA Resource Definition

The Enterprise Server for .NET Administration UI is used to create, modify and delete XA resource definitions. XA resource definitions are persisted in the cross-region database. To create an XA resource definition:
  1. In the Tree pane under System, click on XA Resource Defintions. See 1 in the diagram below.

  2. If you have not previously done so, define the database server instance where your cross-region database resides. To do this,
    1. Select Add server instance in the Actions pane. See 1 in the diagram below. The Select Database Server Instance dialog is displayed
    2. Enter the name of the database server instance you want to use in the Database server instance field and click on OK. See 2 in the diagram below.

      The dialog is dismissed and the database server instance is listed in the Results pane. See 1 in the diagram below.

  3. To add a new XA resource definition:
    1. Click on the name of the database server instance where your cross-region database resides in the Tree pane under XA Resource Definitions. See 1 in the diagram below. The XA Resource Definitions view is displayed in the Results pane
    2. Click on Add new XA Resource. See 2 in the diagram below. The New XA Resource Definition dialog is displayed.
    3. Enter the name of the resource definition you are creating in the Name field and, optionally, the name of the region that you want associated with the definition in the Region field. If you do not enter a region name, the definition will be associated with all regions.
    4. A connection string now needs to be associated with the definition. To do this, click on the button at the end of the Connection String field. See 3 in the diagram below.

      The Edit Connection String dialog is now displayed. By default, this dialog will assist you in creating a connection string for a SQL Server database, but a different database provider can be selected by clicking on the Change button at the end of the Provider field. Once you have provided all the information required for your database connection string, you can verify that it works by clicking on the Test Connection button. Click on OK to complete the creation of the connection string and return to the New XA Resource Definition dialog.

    5. Click on OK to dismiss theNew XA Resource Definition dialog and complete the creation of the definition.
    6. Click on the newly created definition in the Results pane. A properties window is now displayed to the right-hand side of the Results pane. This window contains additional properties, such as database application plan or package path, that may now be additonally configured for the XA resource definition.

Parent topic: Configuring XA resources
Related tasks
To Associate an XA Resource with a CICS Region Startup File
To Associate an XA Resource with a SIT
To Associate an XA Resource with a PCT
Related information
About XA Resources
Configuring XA resources


Administering from the Command Line

The topics in this section describe how to use the administration command line tools.

Administer an Enterprise Server for .NET installation from the command line using one of the following:

  • Command utilities from an Enterprise Server for .NET command prompt.
  • cmdlets available in a Microsoft PowerShell session.
  • General Command Line Utilities
  • PowerShell
Parent topic: General Administration


General Command Line Utilities

There are command line utilities that you can use as an alternative to the Enterprise Server for .NET Administration UI to configure an Enterprise Server for .NET installation and to administer region execution.

Tip: You can run all of the Enterprise Server for .NET utilities from the command line in either self-hosted, or Windows Authentication Services (WAS) modes.
  • seeazure: Administration of Azure deployments and Services
  • seeconsoleviewer: start a console viewer
  • seedeploy: deploy configuration files and programs to a database or Azure Drive
  • seedispatch: start a dispatcher
  • seelistener: start a communications listener
  • seemmc: launch the Microsoft Management Console (MMC) SEE Administration UI
  • seemonitor: start an event monitor
  • seestart: start a region
  • seestop: stop a region
  • seeupgrade: upgrade from an earlier version
  • seewcfutil : Windows Communication Framework configuration
    Configure the WCF parameters .
  • wasreset: reset IIS and WAS
  • wassetup: set up IIS and WAS
Parent topic: Administering from the Command Line
Related information
CICS Command Line Utilities
JES Command Line Utilities


seeazure: Administration of Azure deployments and Services

Seeazure is a command line utility that can be used to deploy packages to Azure and control aspects of the Azure environment and the deployments therein. Whilst not exhaustive in functionality, it is rich enough to perform the required tasks .

seeazure  -command [-resourcetype:resourcename] [optional_parameters]

Configuration Settings

All operations need the following settings specified in seeazure.exe.config:

  • SubscriptionID : Your subscription ID. You can find this in the "Account" tab of the Windows Azure Developer Portal.
  • CertificateThumbprint : Hex thumbprint of a X509 certificate previously uploaded in the "API Certificates" section of the Windows Azure developer portal.

    See the Azure documentation for how to generate and store these certificates.

These values can be overridden by using command line switches:

  • -subscription_id:<subscription id>
  • -subscription_cert_thumbprint:<thumbprint>

Resources

Specific operations will require one of the following resources to be defined:

  • -storage_service:<storage_account_name>

    Specifies the storage service/account name for commands that deal with storage account operations.

  • -hosted_service:<hosted_service_name>

    Specifies the hosted service name for commands that deal with hosted service operations.

  • -affinity_group:<affinity_group_name>

    Specifies the affinity group for commands that deal with affinity groups.

  • -location:<location_constraint_name>

    Specifies the location constraint for commands that deal with locations.

Commands

  • General Operations:
    • -?

      Display this message

    • -get_operation_status -op_id:<operation_id>

      Shows status of specified operation_id.

  • Affinity Group Operations:
    • -view_affinity_group_properties -affinity_group<affinity_group_name>

      Lists the properties for the affinity group .

    • -list_affinity_groups

      Lists all affinity groups in the subscription. Use view_properties to display details on any particular affinity group.

  • Storage Account Operations:
    • -view_storage_service_properties -storage_service:<storage_service_name>

      Lists the properties for the storage_service.

    • -list_storage_services

      Lists all storage services underneath the subscription.

    • -view_keys

      Acts on storage accounts only. Displays the primary and secondary keys for the account. Should have the storage account resource specified.

    • -regenerate_key -key_type:primary|secondary

      Acts on storage accounts only. Regenerates storage keys with the key_type parameter specifying which key to regenerate. Should have the storage account resource specified.

    • -deploy_file -file:name:<full path to file> -container_name:<containername> -target_file_name:<targetfilename>

      Deploys the file name pointed to by the full path to a container identified with <containername> with a target filename identified by <targetfilename>.

      The primary key of the storage_service identified by the -storage_service parameter is retrieved and used to store the file in blob storage.

  • Hosted Service Operations:
    • -view_hosted_service_properties -hosted_service:<hosted_service_name>

      Lists the properties for the hosted_service.

    • -create_hosted_service -hosted_service:<name> -label:<label> [-description:<description>] [-affinity_group:<affinitygroupname> -location:<locationconstraintname>]

      Creates a hosted service.

    • -list_hosted_services

      Lists all hosted services under the subscription. Use -view_properties to view details on a particular hosted service.

    • -update_hosted_service -hosted_service:<name> [-label:<label>] [-description:<description>]

      Updates a hosted service.

    • -delete_hosted_service

      Deletes hosted service. Should have the hosted_service resource specified.

  • Deployment Operations:

    The deployment operations require that the hosted service resource is specified.

    • -view_deployment -slot:staging|production

      View details of a specified deployment. You can specify the deployment either by slot type or by name.

    • -view_deployment -name:<deployment_name>

      View details of a specified deployment. You can specify the deployment either by slot type or by name.

    • -create_deployment -name:<name_of_deployment> -label:<label> -package:<blob_uri> -config:<filename> -slot:staging|production [-warnings_as_error]

      Create a new deployment. The package parameter should have the URI to a .cspkg in blob storage whose storage account is part of the same subscription-project. The -config parameter should specifiy a .cscfg file on disk. Note that there shouldn't be a deployment of the same name or in the same slot when executing this command. If -warnings_as_error is specified, warnings are returned and operation is terminated.

    • -swap_deployment -production_slot:<deployment_name_in_production> -source_deployment:<deployment_name_in_staging>

      Swaps the deployments in production and stage. To make sure the command works on the deployments you expect them to, you need to pass the name of the deployment currently in production and the name of the deployment currently in staging. If you don't have any resource in production, you can leave it empty.

    • -delete_deployment -name:<deployment_name>

      Deletes the specified deployment. Note that the deployment should be in suspended state.

    • -delete_deployment -slot:production|staging

      Deletes the specified deployment. Note that the deployment should be in suspended state.

    • -update_deployment -status:running|suspended -name:<deployment_name>

      Change deployment status to running or suspended.

    • -update_deployment -status:running|suspended -slot:production|staging

      Change deployment status to running or suspended.

    • -change_deployment_config -config:<filename> -slot:production|staging [-warnings_as_error]

      Change the deployment's configuration.

    • -change_deployment_config -config:<filename> -name:<deployment_name> [-warnings_as_error]

      Change the deployment's configuration.

    • -upgrade_deployment -mode:auto|manual -label:<label> -config:<config_filename> -name:<deployment_name> [-warnings_as_error]

      Initiates an in_place upgrade of the specified deployment.

    • -upgrade_deployment -mode:auto|manual -label:<label> -config:<config_filename> -slot:staging|production [-warnings_as_error]

      Initiates an in place upgrade of the specified deployment.

    • -walk_upgrade_domain -domain:<update_domain_number> -slot:production|staging

      Walks the specified upgrade domain.

    • -walk_upgrade_domain -domain:<update_domain_number> -name:<deployment_name>

      Walks the specified upgrade domain.

    • -reboot_deploymentroleinstance -slot:<staging|production> -role_instance_name:<roleinstancename>

      Requests the reboot of a single role instance in the deployment.

    • -reboot_deploymentroleinstance -name:<deploymentname> -role_instance_name:<roleinstancename>

      Requests the reboot of a single role instance in the deployment.

    • -reimage_deploymentroleinstance -slot:<staging|production> -role_instance_name:<roleinstancename>

      Requests the reimaging of a single role instance in the deployment.

    • -reimage_deploymentroleinstance -name:<deploymentname> -role_instance_name:<roleinstancename>

      Requests the reimaging of a single role instance in the deployment.

  • Certificate Operations:

    These operations require that the hosted service resource is specified.

    • -list_certificates

      Lists certificate thrumbprints for a hosted service.

    • -add_certificate -cert_file:<path_to_cert_file> -cert_format:[pfx] -cert_password:<password>

      Adds a certificate to the specified hosted service. . pfx is the only format supported currently

    • -delete_certificate -cert_thumbprint:<thumbprint> -algorithm:<algorithm>

      Deletes certificate with specified thumbprint and algorithm.

  • Operating System Operations:
    • -list_operating_systems

      Lists all operating systems that can be used when creating deployments in Windows Azure.

    • -list_operating_system_families

      Lists all operating system families and the operating systems that belong to them.

  • Location Operations:
    • -list_locations

      Lists all locations accessible from a given subscription.

Examples

Deploying a package file to Azure Storage mfcics1 in preparation for a deployment

seeazure -deploy_file
               -storage_service:mfcics1
               -file_name:"d:\dev\app.publish\SEECloud.cspkg"
               -container_name:vsdeploy -target_file_name:SEECloud.cspkg

Creating a new deployment in staging

This assumes that there is a storage account called 'myaccount' under the same subscription and a package in the 'packages' container. It also uses a SEECloud.cscfg config file in the current working directory.

seeazure -create_deployment
               -slot:staging
               -hosted_service:testhostedservice
               -name:testdep
               -label:testlabel
               -config:.\SEECloud.cscfg
               -package:http://myaccount.blob.core.windows.net/vsdeploy/SEECloud.cspkg

Updating deployment status to running

seeazure -update_deployment
               -slot:staging
               -hosted_service:testhostedservice
               -status:running
We could replace the last parameter with a -name parameter as well.

Swapping staging and production

seeazure -swap_deployment
               -hosted_service:testhostedservice
               -source_deployment:testdep
               -production_slot:somedeploymentinprod

Changing configuration number of instances

We'll assume the configuration file has the number of role instances specified.

seeazure -change_deployment_config
               -hosted_service:testhostedservice
               -slot:production
               -config:./SEECloud.cscfg
Parent topic: General Command Line Utilities


seeconsoleviewer: start a console viewer

Syntax

seeconsoleviewer parameter parameter . .

Starts a console viewer for a CICS region.

Parameters

-nobanner
Do not display utility welcome and copyright messages.
-region:<region-name>
Name of the region to associate with the viewer. Default is ESDEMO.
-showtime:<number-of-columns>
Prefix each console message with the date and time created. You can also enter a numeric value to specify the console window width.

If the value for <number-of-columns> is greater than the maximum width supported for a Windows Console, the value is set to the maximum width.

-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Example

This example creates a console viewer process for the ESDEMO region name. The (local)\SQLEXPRESS database server name hosts the region database. The command creates a 132-column wide console window. The creation date and time prefixes each message output.

seeconsoleviewer -region:ESDEMO -usedb:(local)\SQLEXPRESS
-showtime:132
Parent topic: General Command Line Utilities


seedeploy: deploy configuration files and programs to a database or Azure Drive

Syntax

seedeploy [Options][Category]Action Parameters

Depending on the command's action, deploys, extracts or deletes items in the region database, cross-region database, user-defined database, or an Azure Cloud drive (discussed in the Hosting CICS and Batch Applications in Windows Azure section). This includes:

  • Region startup files
  • Resource definition files
  • Programs (.dll files)
  • BMS Mapset files (.mod files)
  • Program symbols for debugging (.PDB files)

Option parameter

For all actions, Option can have the following values:

Option
  • -nobanner

    Display minimal output, same as -quiet.

  • -quiet

    Display minimal output.

  • -urlhelp

    Display information about the URL syntax.

  • -verbose

    Display additional information in the list output.

Category parameter

The category parameter defines the item to be acted upon. Valid values are:

  • binary

    • The item acted upon is a binary file, for example a DLL file. This is the default.

  • rdo or resdef

    • The item acted upon is a resource definition file.

  • regionfile

    • The item acted upon is a region startup file.

  • clouddrive
    • The action specified is to be done against an Azure cloud drive hosted in a monitor worker role, deployed into Azure.

Action parameter

The action parameter defines the process performed on the specified item. It can have the following values. Each performs a specific function.

  • create

    Creates a table in a specified database.

    There is no create action for cloud drive operations.

  • add

    Deploys the specified file to the database, or Azure cloud drive.

  • delete

    Deletes the specified item from the database, or Azure cloud drive.

  • extract

    Copies the specified item from the database or Azure cloud drive to a file.

  • list

    Lists the contents of the specified database table or directory on an Azure cloud drive.

Refer to the See Also link at the end of this topic for information on defining a component's URL location.

create action

seedeploy [Option][Category]create <url>

Creates a table in a database such as a cross-region database, a region database, or a user-defined database. If the specified database does not exist, the action creates a simple database and adds the table to it.

Note: This action is not supported with the rdo and regionfile category parameters.
url
The name of the new or existing database in URL format.
name
The name of the table to create.

add action

  • For binary category:
    seedeploy Option category add file  url[#name]
  • For rdo and regionfile categories:
    seedeploy [option] [category] add file sql://host[/inst]/(crdb)/filename
For Azure cloud drive:
seedeploy [option] clouddrive  add file cdrv://host/FullFilePath

Adds an item to the database or Azure cloud drive. You can use wildcards in the filename to add multiple files for database targets, not for Azure cloud drives currently.

Note:
  • With binary files and cloud drive targets, first use the delete action to remove the old file.
  • With region startup and resource definition files, the add action overwrites the existing file. You do not need to remove the file first.
file
The path and filename of the file to be loaded. Filenames can include wildcards to specify multiple files.
URL

The database location in URL format.

If the URL includes the #name fragment, the first matching file only is stored in the specified table using the name that #name defines. You typically use this format to save a file in the database under a different name.

Otherwise, the base filename or filenames of matching files are used as the row names. If name includes an extension, the extension defines the row's file type.

where <FullFilePath> is the full path to the target file, including the file name, e.g. "m:/programfolder/transactions/acct.dll

FullFilePath
The full path to the Azure cloud drive target file, including the file name, e.g. "m:/programfolder/transactions/acct.dll
The following command deploys the pgm.dll.old assembly to the db database on the host\inst database server instance.
seedeploy add pgm.dll.old sql://host/inst/db/Programs#pgm.dll
The following command deploys the resdef.config resource definition file to the cross-region database on the myhost\inst1 database server instance.
seedeploy rdo add c:\resourcedir\resdef.cfg sql://myhost/inst1/(crdb)
The following command deploys the regiondef.config region definition file to the installation's cross-region database on the myhost\inst1 database server instance:.
seedeploy regionfile add c:\regiondir\regiondef.config sql://myhost/inst1/(crdb)

Syntax

The following command deploys the acct.dll to an Azure drive configured as M: to a folder /programfolder/transactions.
seedeploy clouddrive add c:\transactions\acct.dll
                 cdrv://example.cloudapp.net/m:/programfolder/transactions/acct.dll

delete action

Deletes the specified item in the region or cross-region database. If the name has an extension, for example ACCT01.DLL, this command deletes only the item with the matching name and file type. Otherwise, it deletes all matching items.

seedeploy [Option] [category] delete url#name
URL

The item to delete's database location in URL format.

  • The following command delete ACCT00.DLL from the cross-region database.
    seedeploy delete sql://localhost/(crdb)#ACCT00.DLL
  • The following command deletes all files starting with ACCT00, regardless of file type, for example ACCT00.DLL and ACCT00.PDB.
    seedeploy delete sql://localhost/(crdb)#ACCT00
  • The following command deletes the resource definition file myResourceDef deployed to the cross-region database.
    seedeploy rdo delete sql://localhost/(crdb)/myResourceDef>
  • The following command delete ACCT00.DLL from the Azure cloud drive.
    seedeploy clouddrive delete cdrv://example.cloudapp.net/m:/programfolder/transactions/ACCT00.DLL

extract action

Extracts the contents of the specified item to a file. The name part of the URL must include the file type.

  • For binary category:
    seedeploy [Option] [category] extract  url#name path
  • For rdo and regionfile categories:
    seedeploy [option] [category] extract sql://host[/inst]/(crdb)/filename
  • for Azure cloud drive
    seedeploy [Option]  clouddrive extract  cdrv://host/FullFilePath file
path
The location and name of the file to hold the extracted data.
URL

The database location in URL format of the item to be extracted.

FullFilePath

The full path to the file to be extracted.

The following command extracts the data from the row named pgm with the DLL file type, and saves it in the file pgm-from-db.dll in the current folder.

seedeploy extract sql://host/inst/db/Programs#pgm.dll pgm-from-db.dll

The following command extracts the resource definition file myResourceDefs.config from the cross-region database and saves it in the file resourcedef-from-db.config in the current folder.

seedeploy rdo extract sql://localhost/(crdb)/myResourceDefs resourcedef-from-db.config

The following command extracts the ACCT00.DLL file from the Azure cloud drive.and saves it in the file ACCT00.DLL in the current folder.

seedeploy clouddrive extract cdrv://example.cloudapp.net/m:/programfolder/transactions/ACCT00.DLL .\ACCT00.DLL

list action

Lists the contents of the specified table. Use the -verbose to display additional information.

seedeploy [Option] [category] list url
Note: The list format is different for binary and rdo/resdef resources. The -verbose option displays additional columns.
URL

The database location in URL format of the item to be extracted.

URL

The table's database location in URL format.

The following command lists the contents of the Programs table in the SEEApps database on the local machine.
seedeploy list sql://localhost/SEEApps/Programs
The following command lists the resource definition files deployed to the cross-region database on the local machine.
seedeploy rdo list sql://localhost/ (crdb)
The following command lists the region startup files deployed to the cross-region database on the local machine.
seedeploy regionfile list sql://localhost/(crdb)

The following command lists the contents of the m:/programfolder/transactions folder on the Azure cloud drive.
seedeploy  clouddrive list cdrv://example.cloudapp.net/m:/programfolder/transactions
Parent topic: General Command Line Utilities


seedispatch: start a dispatcher

Syntax

seedispatch parameter parameter . .

Starts a self-hosted dispatcher and optional start listener, SEP, and console viewer processes. An event monitor starts if one is not already started.

Parameters

-automatic
Automatically start self-hosted SEP process.
-listener
Automatically start a listener process.
-manual
A self-hosted SEP process must be started manually. This is the default.
-nobanner
Do not display utility welcome and copyright messages.
-nocv
Do not start a console viewer process. If this parameter is omitted, a console viewer process starts automatically.
-nocvchild
Starts the console viewer in a separate console window.
-nowait
Do not wait for key press before existing. Used in conjunction with -was.
-region:<region-name>
Name of the region to associate with a started listener and console viewer. The default is ESDEMO.
-showtime:<number-of-columns>

Passed to the started console viewer process, or ignored if -nocv is specified. Prefixes each console message with the date and time it was created.

You can also enter a numeric value to specify the width of the console window. If the value for <number-of-columns> is greater than the maximum width supported for a Windows Console, the value is set to the maximum width.

-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.
-was
Use a WAS-hosted dispatcher instead of self-hosting. With this parameter, seedispatch starts the console viewer and/or listener, depending on other command-line parameters. A WAS process running under IIS handles dispatching.
-wassep
Use a WAS-hosted SEP. This parameter is only required if -was is not specified. A WAS-hosted dispatcher always uses a WAS-hosted SEP.

Using a configuration file with seedispatch

You can use a seedispatch.config configuration file to configure the behavior of seedispatch. In the current release, the maximum TCP and named pipe connections supported by the exposed WCF services, the default port for the WCF services, and CTF tracing can be configured.

The following statements show how to use a configuration file to specify a maximum of 20 connections for each protocol.
<configSections>
  <sectionGroup name="MicroFocus.SEE.Dispatch">
    <section name="services" type="System.Configuration.NameValueSectionHandler" />
  </sectionGroup>
</configSections>
...
<MicroFocus.SEE.Dispatch>
  <services>
    <add key="NetNamedPipe.maxConnections" value="20" />
    <add key="NetTcp.maxConnections" value="20" />
  </services>
</MicroFocus.SEE.Dispatch>
...

Example: Starting a self-hosted dispatcher

The following command:
  • Starts a self-hosted dispatcher
  • Automatically starts a self-hosted SEP
  • Automatically starts a listener and console viewer for the ESDEMO region
seedispatch -region:ESDEMO -usedb:(local)\SQLEXPRESS -automatic
 -listener

Example: configuring a WAS-hosted dispatcher and SEP

The following command configures a WAS-hosted Dispatcher and SEP. This example starts a listener and console viewer for the ESDEMO region. The console viewer starts with a 132-column wide window and the date and time of creation prefixes each message output.

Note: The -nowait parameter terminates the seedispatch process once the other processes start.
seedispatch -was -nowait -region:ESDEMO -usedb:(local)\SQLEXPRESS
-automatic -listener -showtime:132
Parent topic: General Command Line Utilities


seelistener: start a communications listener

Syntax

seelistener parameter parameter . .

Starts a communications listener.

Parameters

-heartbeat:time
Configures the keep-alive functionality for TN3270 channels. The time variable is a value in seconds. For channels other than TN3270, the setting is ignored. This can also be configured using the configuration file, which the preferred method.
Note: When running in the Azure cloud, we recommend configuring a heartbeat time of 30 seconds.
-i
Install the seelistener Windows service.
-nobanner
Do not display utility welcome and copyright messages.
-region:<region-name>
Name of the region viewer requests will be dispatched to. This is normally specified using the configuration file. The default is ESDEMO.
-u
Uninstall the seelistener Windows service.
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.
-was
Use a WAS-hosted dispatcher instead of a self-hosted one.

Using a configuration file with seelistener

You can use a seelistener.config configuration file to configure seelistener behavior. The configuration file specifies database connections, regions, communications channels and their options, WCF service connection options, and CTF tracing settings.

Examples

In the following command, the ESDEMO region name and (local)\SQLEXPRESS database server name pass to the dispatcher with each client request. When the conversation between the client and the listener is idle, the listener sends a probe message to the client every 30 seconds to keep the conversation open.

seelistener -region:ESDEMO -heartbeat:30 -usedb:(local)\SQLEXPRESS
Parent topic: General Command Line Utilities


seemmc: launch the Microsoft Management Console (MMC) SEE Administration UI

Syntax

seemmc filename

Launches the MMC SEE Administration UI.

By default, the command uses the seemsc.msc file to configure the MMC. This file is installed to \Micro Focus\Enterprise Developer\2.2 \SEE\SEE.msc
Note: This location has read-write access so you can edit the .msc file to configure multiple snap-ins.

The command:

  • Sets the .NET 4.0 framework to COMPLUS_Version=v4.0.30319
  • Opens the MMC

Parameters

filename
Opens the MMC using the specified .msc file.

The default file is seemsc.msc.

Example

This command opens the MMC SEE Administration UI using the c:\snapins\mysnapin.msc file to configure the MMC.
seemmc c:\snapins\mysnapin.msc
Parent topic: General Command Line Utilities


seemonitor: start an event monitor

Syntax

seemonitor parameter parameter . .

Starts an event monitor.

Parameters

-i
Install the seemonitor Windows service.
-nobanner
Do not display utility welcome and copyright messages.
-u
Uninstall the seemonitor Windows service.
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
Note: This command-line option is effectively redundant as SEP pool processes implicitly register database server instances with the event monitor when they first have traffic for them.
-verbose
The command output displays all of the messages that the command generates.

Example

This command starts an event monitor specifying that the cross-region database on the (local)\SQLEXPRESS database server instance is to be monitored for database events.

seemonitor -usedb:(local)\SQLEXPRESS
Parent topic: General Command Line Utilities


seestart: start a region

Syntax

seestart parameter parameter . .

Starts a region on the SQL Server instance running either on the local machine or on a specified remote machine.

The event monitor processseemonitor.exe performs region startup processing. By default, the event monitor performing region startup is on the machine invoking the seestart command. However, you can use the -server parameter to specify a remote machine to perform the startup process.

Parameters

-coldstart
Cold-start the region. The region initializes using region startup and resource definition file information.
-nobanner
Do not display utility welcome and copyright messages.
-noproperties

Do not use any properties for region startup processing.

If neither -noproperties nor -properties: is specified, each variable/value in the current environment space is passed as a property to the region startup processing.

-properties:<properties file name>

You can define properties used by region startup processing to replace pseudo-variables that specified in a region startup file's <location> sections. Pseudo-variables are replaced by the value associated with a property of the same name. If the property does not exist, the value of an environment variable of the same name is used.

If neither -noproperties nor -properties: is specified, each variable/value in the current environment space is passed as a property to the region startup processing.

-region:<region-name>

Name of the region to be started. If -regionfile is omitted, the command uses the first region startup file with the name Region_<region-name>.config that it finds in the following locations:

  • %APPDATA%\Micro Focus\SEE\2.2\Data\Config
  • %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\files\sys

    This is the path on a 64-bit operating system.

Note: If both -region and -regionfile are omitted, the command opens the ESDEMO region, using -region:ESDEMO.
-regionfile:[(local)|(server)] <region definition file>
The name of the region startup file to be used. The optional (local)/(server) prefix identifies the location of the region startup file.

If (local) is specified, the region startup file is on the local machine. If (server) is specified, the region startup file is on the machine specified by the -server parameter.

If (server) is specified, but the -server parameter is not, (local) is assumed.

The default is (local).

If the -region parameter is not specified, the value of the region startup file's region element's name property is used as the name of the region to be started.

If no region startup path file is specified, the command searches for region startup and resource definition files in the following locations in turn, and uses the first one that it finds:

  • %APPDATA%\\Micro Focus\Enterprise Developer\SEE\2.2\Config
  • %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\files\sys

    This is the path on a 64-bit operating system.

Note: If both -region and -regionfile are omitted, the command opens the ESDEMO region using the -region:ESDEMO option.
The following examples use the -regionfile and the -server parameters in conjunction.
  • This example starts the region on the local machine and uses the local region startup file.
    -regionfile:c:\mydir\region_myregion.config
  • This example starts the region on the server and uses the local region startup file.
    -regionfile:c:\mydir\region_myregion.config -server:myserver
  • This example starts the region on the local machine and uses the local region startup file.
    -regionfile:(local)c:\mydir\region_myregion.config
  • This example starts the region on the server and uses the local region startup file.
    -regionfile:(local)c:\mydir\region_myregion.config -server:myserver
  • This example starts the region on the server and uses the server region startup file.
    -regionfile:(server)c:\mydir\region_myregion.config -server:myserver
-sit:<SIT-name>
Name of the SIT to start the region with. This overrides the SIT specified in the region startup file.
-server:<machine-name>[:<port>]
The name of the machine where performing the start region operation. Specify <port> if the event monitor on the target machine is not listening on the default 9186 port.
The default is localhost:9186.
-was
Use a WAS-hosted SEP instead of spawning a seesep process to perform PLT processing.
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.
-warmstart
-ws

Warm-start the region. The region initializes using information provided by the region startup file. The resource definition file is not used as the resources created by the previous cold-start (and optionally installed by CINS) are used.

A region can only be warm-started if it has previously been stopped normally. If the region is stopped using the force or immediate option, the region must be cold-started and an error is reported if you attempt a warm-start.

Examples

seestart
Uses the Region_ESDEMO.config file to start the ESDEMO region.
seestart -region:TESTDB
Uses the Region_TESTDB.config file to start the TESTDB region.
seestart -region:DEMO -regionfile:Region_Common.config
Uses the Region_Common.config file to start the DEMO region.
seestart -sit:TESTSIT
Uses the Region_ESDEMO.config file to start the ESDEMO region, using TESTSIT instead of the SIT defined in Region_ESDEMO.config.
seestart -usedb:(local)\SQLEXPRESS
Uses the Region_ESDEMO.config to start the ESDEMO region using the (local)\SQLEXPRESS database instance instead of the database instance defined in Region_ESDEMO.config.
Parent topic: General Command Line Utilities


seestop: stop a region

Syntax

seestop parameter parameter . .

Stops or disables a region, either on the local machine or on a specified remote machine.

Parameters

-force
Unconditional (or 'forced') region shutdown. The region must be cold started when using this parameter.
immediate
Stops the region immediately. The region must be cold started when using this parameter.
-nobanner
Do not display utility welcome and copyright messages
-region:<region-name>
Name of the region to be stopped.
-server:<machine-name>[:<port>]
The name of the machine performing the stop region operation. Specify <port> if the event monitor on the target machine is not listening on the default 9186 port.
The default setting is localhost:9186.
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Examples

seestop
Perform a normal shutdown of the ESDEMO region.
seestop -region:TESTDB
Uses Region_TESTDB.config to stop the TESTDB region.
seestop -usedb:(local)\SQLEXPRESS
Performs a normal shutdown of the ESDEMO region using the (local)\SQLEXPRESS database instance.
seestop -force -region:TESTDB
Performs a forced shutdown of the TESTDB region.
seestop -immediate -region:ESDEMO
Performs an immediate shutdown of the ESDEMO region.
Parent topic: General Command Line Utilities


seeupgrade: upgrade from an earlier version

Syntax

seeupgrade parameter

Upgrades the Enterprise Server for .NET region configuration files installing a new release. Use this command after installing new versions so the region startup and resource definition files can use the new release functionality.

If a file path is not specified with either the -regionfile or -resdef parameters, the command searches for region startup and resource definition files in the following locations in order, using the first one it finds:

  • %APPDATA%\Micro Focus\SEE\2.2\Data\Config
  • %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\files\sys

    This is the path on a 64-bit operating system.

The command creates:

  • Backup files of the configuration files it updates.
  • A log file of the command's output.

The output from the command displays the names and locations of the backup files it creates.

Note: As with any region startup or resource definition file change, you need to re-start the region for the changes to take effect.

Parameters

Note: Running the command with no parameters displays information on the command syntax.
-nobanner
Suppresses utility name and copyright notice display.
-region:regionname
Upgrades the region startup file for the regionname region. This command assumes that the region's startup file is named Region_regionname.config, where regionname is the region's name.

The command searches for the file in the search locations in turn and uses the first version that it finds.

-regionfile:filename
Upgrades the region startup file filename.
Note: The -region and -regionfile parameters are mutually exclusive. You cannot use both with the same command.

If the path or database details are not specified, the command searches for the file in the search locations in order and upgrades the first version that it finds.

-resdef
-rdo
Both upgrade the specified resource definition file.

When used in conjunction with the -region and -regionfile parameters, locate and upgrade the resource definition file specified in the region startup configuration file. That is, both the region startup and the resource definition files are upgraded.

If either the path or the database URL is not specified, the command searches for the files in the search locations in order and uses the first version it finds.

-resdef:resourcefilename
-rdo:resourcefilename
Both upgrade the specified resource definition file, where resourcefilename is the resource definition file name.
If either the path or database details is not specified, the command searches for the files in the search locations in order and uses the first version that it finds.
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Examples

This command upgrades the first myregion region's startup file, Region_myregion.config that it finds in one of the locations the command searches.
seeupgrade -region:myregion
This command upgrades the first myregion region's startup file Region_myregion.config that it finds in one of the locations that the command searches, and the resource definition file the region uses.
seeupgrade -region myregion-resdef
This command upgrades the first resource definition file MyResourceDef.config, in one of the search locations.
seeupgrade -resdef MyResourceDef.config
Parent topic: General Command Line Utilities


seewcfutil : Windows Communication Framework configuration

Syntax

seewcfutil parameter parameter . .

Sets various WCF parameters for use by the system.

Enter the actual information in this section (optional).

Parameters

-nobanner
Does not display utility welcome and copyright messages.
-status

Displays the current WCF information.

-quiet

Displays minimal console output.

-verbose

Displays more console output.

-auth<:name>
Authorizes the account for port sharing. If name is omitted, the "Micro Focus SEE Users" is used.
-unauth<:name>
Removes authorization for port sharing for the given user.
-addgroup
Adds the account for -auth as a local group , if it does not exist.
-accept<:num>
Sets the maximum pending accepts for port shared net.tcp. If num is omitted, it is set to 20.
-conn<:num>
Sets maximum pending connections for port shared net.tcp. If num is omitted , it is set to 100.
-listen<:num>
Sets the listen backlog for port shared net.tcp. If num is omitted, it is set to 20.
-timeout<:ts>
Sets the receive timeout for port shard net.tcp. If ts is omitted , set it to 1:00:00.
seewcfutil -status
WU0002I Processing C:\Windows\Microsoft.NET\Framework\v4.0.30319\SMSvcHost.exe.config:
   Listen backlog:      10
   Pending connections: 100
   Pending accepts:     2
   Receive timeout:     00:00:30
   Allowed accounts:
      S-1-5-32-568 (BUILTIN\IIS_IUSRS)
      S-1-5-18 (NT AUTHORITY\SYSTEM)
      S-1-5-32-544 (BUILTIN\Administrators)
      S-1-5-19 (NT AUTHORITY\LOCAL SERVICE)
      S-1-5-20 (NT AUTHORITY\NETWORK SERVICE)
WU0002I Processing C:\Windows\Microsoft.NET\Framework64\v4.0.30319\SMSvcHost.exe.config:
   Listen backlog:      10
   Pending connections: 100
   Pending accepts:     2
   Receive timeout:     00:00:30
   Allowed accounts:
      S-1-5-32-568 (BUILTIN\IIS_IUSRS)
      S-1-5-18 (NT AUTHORITY\SYSTEM)
      S-1-5-32-544 (BUILTIN\Administrators)
      S-1-5-19 (NT AUTHORITY\LOCAL SERVICE)
      S-1-5-20 (NT AUTHORITY\NETWORK SERVICE)

seewcfutil -nobanner -conn:100 , sets the maximum pending connections to 100.
Parent topic: General Command Line Utilities


wasreset: reset IIS and WAS

Syntax

wasreset parameter

Re-cycles IIS and WAS.

Parameters

(No parameter)
This is the default. Using this command with no parameters:
  • Shuts down IIS
  • Kills WAS worker processes
  • Delete any binary copies from the IIS cache
  • Restarts IIS
/full
Same as the default action, but also stops and restarts the WAS netpipeactivator and nettcpactivator services
Note: Use this parameter with caution. It can be useful if the IIS or WAS services are behaving inconsistently. You can use this parameter to ensure all services are stopped, then re-started.
Parent topic: General Command Line Utilities


wassetup: set up IIS and WAS

Syntax

wassetup parameter

Configures IIS and WAS for Enterprise Server for .NET installation. The command:

  • Checks that IIS is installed, and displays a message if it is not.
  • Enables and starts the following services if not already started:
    • netpipeactivator
    • nettcpactivator
    • was
    • w3svc
    • nettcpportsharing

The command includes a parameter to uninstall the IIS/WAS configuration.

Note: It is a good idea to run wassetup with no parameters after a system shutdown and re-start. This ensures that all the services that Enterprise Server for .NET requires are installed and operating correctly.
Attention: If IIS is not installed, the error messages generated by this command do not indicate the cause of the problem. If your error messages are not helpful, check that IIS is installed.

Parameters

-i
This is the default. It configures the IIS and WAS requirements for Enterprise Server for .NET installation, and starts all required services. It also removes existing WAS configurations performing the same function as with the -u parameter before it begins.
An error generates if any of the required services are not installed or do not start successfully.
-r
Repairs WCF. This option will invoke the servicemodelreg.exe utility on Windows 7 and Windows Server 2008, or the dism utility on Windows 8 and Windows Server 2012 or later, to repair the WCF components installed on the machine.
-u
Uninstalls the IIS and WAS configuration created using the command with the -i parameter.
-x
Prevents the IIS application pool from recycling the w3wp.exe instances. This may be required if you have conversational CICS transactions or batch jobs that could run for a period longer than that configured for application pool recycling.

Example

This command configures the IIS and WAS requirements for anEnterprise Server for .NET installation.
wassetup -i
Parent topic: General Command Line Utilities


PowerShell

The MicroFocus.SEE.PowerShell assembly provides PowerShell cmdlets for starting/stopping regions, as well as other administrative functions. This assembly installs as a PowerShell snap-in during a product installation or development build of PowerShell.sln. To use the SEE cmdlets, powershell.exe must be started with the COMPLUS_Version environment variable set to the 4.0 .NET framework in its environment space. For example:

set COMPLUS_Version=v4.0.30319
start powershell.exe

If this command returns an error regarding PowerShell and the .NET framework v2.0 not being installed, then find the powershell.exe install location (normally \Windows\System32\WindowsPowerShell\<release>) and create a file called powershell.exe.config that contains the following lines.

<?xml version="1.0"?>
   <configuration>
      <startup useLegacyV2RuntimeActivationPolicy="true">
         <supportedRuntime version="v4.0.30319"/>
         <supportedRuntime version="v2.0.50727"/>
         </startup>
      </configuration>
  • Adding the PowerShell SnapIn
  • PowerShell Cmdlets
Parent topic: Administering from the Command Line


Adding the PowerShell SnapIn

You must add the MicroFocus.SEE.PowerShell snap-in to your PowerShell session to use SEE cmdlets. Use the Add-PSSnapin cmdlet. At the PowerShell command prompt, type the following and press Enter.

Add-PSSnapin MicroFocus.SEE.PowerShell

If an error occurs running the Add-PSSnapin, the following message appears.

Add-PSSnapin : Windows PowerShell snap-in "MicroFocus.SEE.Powershell" is loaded
 with the following warnings:  There were errors in loading the format data fil
e:
MicroFocus.SEE.Powershell, , MicroFocus.SEE.PowerShell.format.ps1xml : File skipped because of the following validation exce
ption: File MicroFocus.SEE.PowerShell.format.ps1xml cannot be loaded because the execution of scripts is disabled on this sy
stem. Please see "get-help about_signing" for more details..
At line:1 char:13
+ Add-PSSnapin <<<<  MicroFocus.SEE.Powershell
    + CategoryInfo          : InvalidData: (MicroFocus.SEE.Powershell:String)
   [Add-PSSnapin], PSSnapInException
    + FullyQualifiedErrorId : AddPSSnapInRead,Microsoft.PowerShell.Commands.Ad
   dPSSnapinCommand

If this error occurs, run the following cmdlet, then close your PowerShell session and restart a new one:

Set-Execution-Policy unrestricted

The execution policy persists from session to session until changed again using Set-Execution-Policy. Use Get-ExecutionPolicy without any parameters to see your current execution policy.

If you needed to set the execution policy, be aware that it is system wide, and you should set it back to its original value if required.

Parent topic: PowerShell


PowerShell Cmdlets

You can use the PowerShell cmdlets to configure the environment.

  • Database Server Instance Discovery
  • Get-SEERegions: return regions
  • Get-SEERegionStatus: return the status of a region
  • Get-SEESEPPools: return registered SEP pools
  • Start-SEERegion: start a Region
  • Stop-SEERegion: stop a region
  • PowerShell Cmdlet Example
    An example of PowerShell Azure cmdlet use.
Parent topic: PowerShell


Database Server Instance Discovery

By default, Get-SEERegions cmdlet SEE discovers SQL Server instances and regions on the machine where it is installed (as part of the MicroFocus.SEE.PowerShell snap-in). This cmdlet is used by the SEE SCOM support to discover regions.

However, if it is not possible to have the MicroFocus.SEE.PowerShell snap-in installed on machines hosting SQL Server instances, regions can still be discovered on those machines using SCOM.config. This file is installed to %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

In this file, you configure the names of SQL Server instances on which you want regions to be discovered.

The following example configures the server instances mymachine\instance1 and mymachine\instance2 for region discovery.

<?xml version="1.0" encoding="us-ascii"?>
<configuration>
  <database>
    <server name="mymachine\instance1" />
    <server name="mymachine\instance2" />
  </database>
</configuration>
Parent topic: PowerShell Cmdlets


Get-SEERegions: return regions

Syntax

Get-SEERegions parameter parameter . .

Returns all available CICS and JES regions and their current states.

Note: This cmdlet is primarily used by SCOM support for discovering regions. It either requires a link to the Database Server Instance Discovery section, or the contents of that section need to be included as part of the cmdlet description.

Parameters

Note: All parameters have these properties:
  • Required: false
  • Position: named
  • Default value: none
  • Accept pipeline input: false
  • Accept wildcard characters: false
-verbose
The command output displays all of the messages that the command generates.

Outputs

The object returned is an array of region objects. Each region object includes:

  • Name: The name of the Region.
  • DBInstance: The SQL Server instance under which the region operates.
  • RegionState: The current state of the region.
class SEERegion
{
   System.String Name
   System.String DBInstance
   System.String RegionState
}

Example

Get-SEERegions
Returns an array of region objects with all regions and their current states.
Parent topic: PowerShell Cmdlets


Get-SEERegionStatus: return the status of a region

Syntax

Get-SEERegionStatus parameter parameter . .

Returns region information and lists tasks running in the region.

Parameters

Note: All parameters have these properties:
  • Required: false
  • Position: named
  • Default value: none
  • Accept pipeline input: false
  • Accept wildcard characters: false
-region:<region-name>

Name of the region whose status is to be queried.

-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb "(local)"
Specific database server on the local machine: -usedb "(local)\SQLEXPRESS"
Default database server instance on a specific machine (SC1 used in example) | -usedb "SC1"
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb "SC1\SQLEXPRESS"
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Outputs

Get-SEERegionStatus returns an array of two objects:

  • The object at Index 0 contains complete region information:
    • Name: The name of the region.
    • DBInstance: The database server instance on which the region resides.
    • RegionState: The current state of the region.
    class CICSRegion
{
   System.String Name
   System.String DBInstance
   System.String RegionState
}
  • The object at index 1 contains information on the tasks running on the region.

Task information can also be accessed using the first object in the returned object array using SepTasksStatus.

Example

This command returns all the information for region ESDEMO residing on database server instance SQLEXPRESS on the local computer. It also lists all running tasks with details on ESDEMO.

Get-SEERegionStatus -UseDB "(local)\SQLEXPRESS" -Region "ESDEMO"
Parent topic: PowerShell Cmdlets


Get-SEESEPPools: return registered SEP pools

Syntax

Get-SEESEPPools parameter parameter . .

Returns registered SEP Pools in a given database instance.

Parameters

-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb:(local)
Specific database server on the local machine: -usedb:(local)\SQLEXPRESS
Default database server instance on a specific machine (SC1 used in example) | -usedb:SC1
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb:SC1\SQLEXPRESS
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Outputs

Get-SEESEPPools returns the following object:

class RegisteredSEPPool
{
   string EventMonitorEndpoint
   string Host
   string Region
   string SEPPoolEndpoint
   DateTime TimeRegistered
}

Example

This command returns information on all the registered SEP Pools.

Get-SEESEPPools -UseDB "(local)\SQLEXPRESS"
Parent topic: PowerShell Cmdlets


Start-SEERegion: start a Region

Syntax

Start -SEERegion parameter parameter . .

Starts a region, either on the local machine or on a specified server.

Start-SEERegion encapsulates the seestart command line utility.

The region startup processing is performed by the event monitor process seemonitor.exe. By default, the event monitor that performs region startup is on the machine invoking the seestart command.

  • Use the -server parameter to specify that an event monitor on a remote server, rather the local machine, performs the region startup.
  • With the -server parameter, you can use the -regionfile parameter's (local) or (server) switch to specify whether the region startup file (and associated resource definition file) is located on the local or server machine.

If no server or local region startup path is specified, the command searches for region startup and resource definition files in the following locations in order, and uses the first version it finds:

  • %APPDATA%\Micro Focus\SEE\2.2 \Config

  • %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\SEE\files\sys

Parameters

Note: All parameters have these properties:
  • Required: false
  • Position: named
  • Default value: none
  • Accept pipeline input: false
  • Accept wildcard characters: false
-coldstart/-warmstart
-cs / -ws
Cold-starts or warm-starts the region.

With -coldstart, the region is re-created from the startup file if it exists. -coldstart is the default value.

For the -warmstart parameter to work, the region must have been stopped normally. You cannot warmstart a region that has been force-stopped or immediate-stopped. You must cold-start regions stopped in this manner.

-nobanner
Do not display utility welcome and copyright messages.
-properties <properties file name> / -noproperties

You can define properties to be used by region startup processing to replace pseudo-variables that you have specified in a region startup file's <location> sections. Pseudo-variables are replaced by the value associated with a property of the same name. If the property does not exist, the value of an environment variable of the same name replaces the pseudo-variable.

If neither -noproperties nor -properties is specified, each variable/value in the current environment space passes as a property to the region startup processing.

-region "<region-name>:

Name of the region to be started. If -regionfile is omitted, the command uses the first region startup file with the name Region_<region-name>.config that it finds in the search paths.

Note: If both -region and -regionfile are omitted, the command opens the ESDEMO region using -region:ESDEMO.
-regionfile "<(local)/(server)>"<region-definition-file>"
The region startup file to be used. The (local)/(server) switch identifies the region startup file location. This is either the local machine or the server identified by the -server parameter. The default is (local).
If -region is omitted, the value of the file's region element's name property is used as the name of the region to be started.

The command uses the first region startup file with the specified name that it finds in the search paths.

Note: If both -region and -regionfile are omitted, the command opens the ESDEMO region using -region:ESDEMO.
The following show how the -regionfile and -server parameters work in conjunction.
This command starts the region on the local machine and uses the local region startup file.
-regionfile "c:\mydir\region_myregion.config"
This command starts the region on the server and uses the local region startup file.
-regionfile "c:\mydir\region_myregion.config -server:myserver"
This command starts the region on the local machine and uses the local region startup file.
-regionfile "(local)c:\mydir\region_myregion.config"
This command starts the region on the server and uses the local region startup file.
-regionfile "(local)c:\mydir\region_myregion.config" -server "myserver"
This command starts the region on the server and uses the server region startup file.
-regionfile "(server)c:\mydir\region_myregion.config" -server "myserver"
-sit:<SIT-name>
Name of the SIT to start the region with. This overrides the SIT that is specified in the region startup file.
-server:<machine-name>[:<port>]
The name of the machine performing the start region operation. Specify <port> if the event monitor on the target machine is not listening on the default 9186 port.
The default is localhost:9186
For example:
-was
Use a WAS-hosted SEP instead of spawning a seesep process to perform PLT processing.
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb "(local)"
Specific database server on the local machine: -usedb "(local)\SQLEXPRESS"
Default database server instance on a specific machine (SC1 used in example) | -usedb "SC1"
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb "SC1\SQLEXPRESS"
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Examples

This command uses the Region_ESDEMO.config file to start the ESDEMO region.
Start-SEERegion
This command uses the Region_TESTDB.config file to start the TESTDB region.
Start-SEERegion -region "TESTDB"
This command uses the Region_Common.config file to start the DEMO region.
Start-SEERegion -region "DEMO" -regionfile "Region_Common.config"
This command uses the Region_ESDEMO.config file to start the ESDEMO region, using TESTSIT instead of the SIT defined in Region_ESDEMO.config.
Start-SEERegion -sit "TESTSIT"
This command uses the Region_ESDEMO.config file to start the ESDEMO region using the (local)\SQLEXPRESS database instance instead of the database instance defined in Region_ESDEMO.config.
Start-SEERegion -usedb "(local)\SQLEXPRESS"
Parent topic: PowerShell Cmdlets


Stop-SEERegion: stop a region

Syntax

Stop -SEERegion parameter parameter . .

Stops or disables a region, either on the local machine or on a specified remote machine.

Parameters

Note: All parameters have these properties:
  • Required: false
  • Position: named
  • Default value: none
  • Accept pipeline input: false
  • Accept wildcard characters: false
-force
Unconditional (or 'forced') region shutdown.
Note: The region must be cold started when using this parameter.
immediate
Stops the region immediately.
Note: The region must be cold started when using this parameter.
-nobanner
Does not display utility welcome and copyright messages.
-region "<region-name>"
The name of the region to be stopped.
-server "<machine-name>"[:<port>]
The name of the machine performing the stop region operation. Specify <port> if the event monitor on the target machine is not listening on the default 9186 port.
The default is localhost:9186
-usedb:<database-server-instance>
Name of the database server instance that hosts the region database. For example:
Default database server on the local machine: -usedb
Default database server on the local machine, identical to -usedb: -usedb "(local)"
Specific database server on the local machine: -usedb "(local)\SQLEXPRESS"
Default database server instance on a specific machine (SC1 used in example) | -usedb "SC1"
Specific database server instance on a specific machine (SC1, SQLEXPRESS used in example for machine name, database server name) | -usedb "SC1\SQLEXPRESS"
Note: Parameter values are not case sensitive.
-verbose
The command output displays all of the messages that the command generates.

Examples

This command shuts down the ESDEMO region.
Stop -SEERegion
This command uses the Region_TESTDB.config file to stop the TESTDB region.
Stop-SEERegion -region "TESTDB"
This command performs a normal shutdown of the ESDEMO region using the (local)\SQLEXPRESS database instance.
Stop-SEERegion -usedb "(local)\SQLEXPRESS"
This command performs a forced shutdown of the TESTDB region.
Stop-SEERegion -force -region "TESTDB"
This command performs an immediate shutdown of the ESDEMO region.
Stop-SEERegion -immediate -region "ESDEMO"
Parent topic: PowerShell Cmdlets


PowerShell Cmdlet Example

This Powershell script will query a given Region / Database combination and retrieve some status.

$Region = “ESDEMO”
$DBInstance = “(local)”
$SeeRegions = Get-SEERegions

foreach ($SEERegion in $SEERegions)
{
    # if it is the region name / database we are interested in.
    if($SEERegion.Name.Contains($Region) -and $SEERegion.DBInstance.Contains($DBInstance))
    {
  # get the region status
  $RegionStatus = get-SEERegionstatus -region $Region -usedb $DBInstance
  # and emit some interesting stuff about the region.
  write-host "Region $Region is  $($SEERegion.RegionState)"
  write-host "               has $($RegionStatus.ActiveTasks) Active Tasks"
  # and then get what each SEP instance is busy with.
  foreach($SepStatus in $RegionStatus.SepTasksStatus)
  {
      # write out some interesting SEP stuff.
   write-host " Request ID $($SepStatus.RequestID) processing transaction id $($SepStatus.CicsTranId) from terminal $($SepStatus.CicsTermId) "
        }

    }

}
Parent topic: PowerShell Cmdlets


Diagnostics

Topics in this section explain what diagnostics are available in Enterprise Server for .NET and how to use them.

  • Local Trace Tables
  • Windows Event Log
  • Consolidated Tracing Facility (CTF)
  • Diagnostic Collection Utility
Parent topic: General Administration


Local Trace Tables

A local trace table is an in-memory collection of the most recent key events to have occurred within a SEP. Any given SEP may contain one or more local trace tables depending on the activity that has occurred within it. For example, there will be a separate trace table for each region's CICS transaction or JCL activity.

Trace tables may be viewed in the following ways using the Enterprise Server for .NET Administration UI:
  • From the SEP Traces view
  • From the Monitor view for a selected transaction or job
  • To View Local Trace Tables from the SEP Traces View
  • To View Local Trace Tables from the Monitor View
Parent topic: Diagnostics


To View Local Trace Tables from the SEP Traces View

  1. Select a running region from within the Enterprise Server for .NET Administration UI and click on SEP Traces in the Action pane. See 1 in the diagram below. The SEP Traces view is displayed. A tree in the left-hand side of the Results pane displays the machines, processes and SEPs which have local trace tables for the running region.
  2. Select one of the SEP instances. The trace table associated with that SEP is displayed in the right-hand side of the Results pane.
  3. The tree of SEPs and trace table contents can be refreshed by clicking on the Refresh button. See 2 in the diagram below.

Parent topic: Local Trace Tables


To View Local Trace Tables from the Monitor View

  1. Select a running region from within the Enterprise Server for .NET Administration UI and click on Monitor in the Action pane. See 1 in the diagram below. The Monitor view is displayed.
  2. Select a running task, right-click to display the context menu and select View Trace Table. See 2 in the diagram below.

    The local trace tables associated with the running task are now displayed in the bottom part of the Monitor view.
  3. Select one of the trace tables to view its contents

Parent topic: Local Trace Tables


Windows Event Log

Enterprise Server for .NET outputs key events and exceptions to the Micro Focus Server section of the Windows event log.

To view these events you will need to start the Windows Event Viewer from Windows Administrative tools, or type eventvwr.exe at a Windows command prompt. The diagram below shows where to find the Enterprise Server for .NET events in the viewer:

Parent topic: Diagnostics


Consolidated Tracing Facility (CTF)

The topics in this section describe the Enterprise Server for .NET CTF trace functionality. For detailed information on CTF tracing, see the Consolidated Tracing Facility section in the base product documentation.

You can use CTF to:

  • Diagnose implementation and deployment problems.
  • Diagnose applications you are maintaining or developing.
  • Enabling Trace Functionality
  • Component Tracing Properties Reference
  • Emitter List
Parent topic: Diagnostics


Enabling Trace Functionality

Enable CTF tracing functionality in one of the following ways:

  • The recommended way to configure CTF tracing Enterprise Server for .NET is to modify the relevant configuration files. These files can be found in the following folders.
    • For IIS/WAS hosted dispatcher and seps , the web.config file found in the in the WAS folder of your Enterprise Server for .NET installation folder.
    • Trace configuration is in the application configuration files. These are located in the following folders:
      • For 32-bit: %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE.
      • For 64-bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE.
        • E.g seelistener.exe.config, seemonitor.exe.config, seesep.exe.config or seedispatch.exe.config.
    • Changes to the CTF configuration are not picked up dynamically. Restart the relevant processes. For example, if using IIS/WAS hosted environments, then run wasreset /full.
  • Alternatively , set the MFTRACE_CONFIG environment variable to the fully-qualified name of a CTF configuration file.
    • This method is not considered the primary way of configuring ctf in Enterprise Server for .NET.
    • The environment variable should be set as a system wide environment variable so that all processes of interest will use the configuration.
Parent topic: Consolidated Tracing Facility (CTF)


Component Tracing Properties Reference

Configure tracing behavior by setting the tracing properties for each component to trace.

  • mf.see.admin Component Trace Properties
  • mf.see.comms.isc Component Trace Properties
  • mf.see.configuration Component Trace Properties
  • mf.see.dispatch Component Trace Properties
  • mf.see.listener Component Trace Properties
  • mf.see.monitor Component Trace Properties
  • mf.see.sep Component Trace Properties
  • mf.see.utils Component Trace Properties
  • mf.see.vsam Component Trace Properties
Parent topic: Consolidated Tracing Facility (CTF)


mf.see.admin Component Trace Properties

The mf.see.admin component is used to specify the tracing required for the MicroFocus.SEE.UI.Admin and MicroFocus.SEE.UI.SnapIn assemblies. It contains the following options:
mftrace.level.mf.see.admin
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.admin#region
Enables or disables region operations tracing:
  • True: Enables region operations tracing.
  • False: Disables region operations tracing.
mftrace.comp.mf.see.admin#services
Enables or disables service invocation tracing:
  • True: Enables service invocation tracing.
  • False: Disables service invocation tracing.
Note: To trace the MMC administration user interface, the trace configuration must be included in the MMC app.config file \windows\system32\mmc.exe.config.
The following shows a sample mmc.exe.config file that specifies tracing for the mf.see.admin and mf.see.configuration components.
<?xml version ="1.0"?>
<configuration>
  <configSections>
    <sectionGroup name="MicroFocus.COBOL.Tracing">
      <section name="mftrace_config" type="MicroFocus.COBOL.Runtime.CdataSectionHandler,MicroFocus.COBOL.Runtime.Win32,Version=4.0.0.0,Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
    </sectionGroup>
  </configSections>

  <MicroFocus.COBOL.Tracing>
    <mftrace_config>
      <![CDATA[>
mftrace.emitter.binfile#file               = see.ctb
mftrace.emitter.binfile#location           = c:\logs
mftrace.emitter.binfile#multiproc          = true

mftrace.level.mf.see.admin                 = debug
mftrace.comp.mf.see.admin#region           = true
mftrace.comp.mf.see.admin#services         = true

mftrace.level.mf.see.configuration         = debug
mftrace.comp.mf.see.configuration#region   = true
mftrace.comp.mf.see.configuration#services = true

mftrace.level.mf.see.utils                 = debug
mftrace.comp.mf.see.utils#services         = true
      <]]>
    </mftrace_config>
  </MicroFocus.COBOL.Tracing>

</configuration>
Parent topic: Component Tracing Properties Reference


mf.see.comms.isc Component Trace Properties

The mf.see.comms.isc component specifies the tracing required for the MicroFocus.SEE.Comms.ISC assembly. It contains the following options:

mftrace.level.mf.see.comms.isc
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal

mf.see.comms.Isc component trace example

The following sets mf.see.comms.Isc tracing to the debug level.

mftrace.level.mf.see.comms.isc = debug
Parent topic: Component Tracing Properties Reference


mf.see.configuration Component Trace Properties

The mf.see.configuration component specifies tracing required for the MicroFocus.SEE.Configuration assembly. It contains the following options:
mftrace.level.mf.see.configuration
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.configuration#region
Enables or disables dispatch region operations tracing:
  • True: Enables region operations tracing.
  • False: Disables region operations tracing.
mftrace.comp.mf.see.configuration#services
Enables or disables service invocation tracing:
  • True: Enables service invocation tracing.
  • False: Disables service invocation tracing.

mf.see.configuration component trace example

The following example sets mftrace.comp.mf.see.configuration tracing to the debug level and enables WCF service tracing.

mftrace.level.mf.see.configuration = debug
mftrace.comp.mf.see.configuration#services =  true
Parent topic: Component Tracing Properties Reference


mf.see.dispatch Component Trace Properties

The mf.see.dispatch component specifies tracing required for the MicroFocus.SEE.Dispatch assembly. It contains the following options:
mftrace.level.mf.see.dispatch
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.dispatch#services
Enables or disables dispatch WCF service tracing:
  • True: Enables dispatch service tracing.
  • False: Disables dispatch service tracing.
mftrace.comp.mf.see.dispatch#task
Enables or disables task-related tracing:
  • True: Enables task-related tracing.
  • False: Disables task-related tracing.

mf.see.dispatch component trace example

The following example:

  • Sets mf.see.dispatch assembly tracing to the debug level.
  • Enables WCF service tracing.
  • Enables task-related tracing
mftrace.level.mf.see.dispatch = debug
mftrace.comp.mf.see.dispatch#services = true
mftrace.comp.mf.see.dispatch#task = true
Parent topic: Component Tracing Properties Reference


mf.see.listener Component Trace Properties

The mf.see.listener component specifies tracing required for the seelistener utility and mf.see.listener assembly. It contains the following options:

mftrace.level.mf.see.listener
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.listener#services
Enables or disables listener service tracing:
  • True: Enables listener service tracing.
  • False: Disables listener service tracing.

mf.see.listener component trace example

The following sets mf.see.listener tracing to the debug level and enables listener tracing.

mftrace.level.mf.see.listener = debug|
mftrace.comp.mf.see.listener#services =  true
Parent topic: Component Tracing Properties Reference


mf.see.monitor Component Trace Properties

The mf.see.monitor component specifies the tracing required for the seemonitor utility and microfocus.see.monitor assembly. It contains the following options:

mftrace.level.mf.see.monitor
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.monitor#services
Enables or disables monitor service tracing:
  • True: Enables monitor service tracing.
  • False: Disables monitor service tracing.

mf.see.monitor component trace example

The following sets mf.see.monitor tracing to the debug level and enables monitor tracing. .

mftrace.level.mf.see.monitor = debug|
mftrace.comp.mf.see.monitor#services =  true
Parent topic: Component Tracing Properties Reference


mf.see.sep Component Trace Properties

The mf.see.sep component specifies tracing required for the MicroFocus.SEE.SEP and MicroFocus.SEE.SEP.Service assemblies. It contains the following options:

mftrace.level.mf.see.sep
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.sep#cicsapi
Enables or disables CICS API tracing:
  • True: Enables CICS API tracing.
  • False: Disables CICS API tracing.
mftrace.comp.mf.see.sep#services
Enables or disables WCF service tracing:
  • True: Enables WCF service tracing.
  • False: Disables WCF service tracing.
mftrace.comp.mf.see.sep#task
Enables or disables task-related service tracing:
  • True: Enables task-related service tracing.
  • False: Disables task-related service tracing.

mf.see.sep component trace example

The following example:

  • Sets mf.see.sep tracing to the debug level.
  • Enables CICS API tracing.
  • Enables WCF service tracing.
  • Enables task-related tracing.
mftrace.level.mf.see.sep = debug
mftrace.comp.mf.see.sep#cicsapi = true
mftrace.comp.mf.see.sep#services = true
mftrace.comp.mf.see.sep#task = true
Parent topic: Component Tracing Properties Reference


mf.see.utils Component Trace Properties

The mf.see.utils component is used to specify the tracing required for the MicroFocus.SEE.Utils assembly. It contains the following options:
mftrace.level.mf.see.utils
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.utils#services
Enables or disables file handler operations tracing:
  • True: Enables utils tracing.
  • False: Disables utils tracing.

mf.see.utils component trace example

The following sets mf.see.utils tracing to the debug level and enables WCF service tracing.

mftrace.level.mf.see.utils = debug
mftrace.comp.mf.see.utils#services =  true
Parent topic: Component Tracing Properties Reference


mf.see.vsam Component Trace Properties

The mf.see.vsam component specifies tracing required for the MicroFocus.SEE.Vsam assembly. It contains the following options:
mftrace.level.mf.see.vsam
Sets the trace level:
  • debug
  • info
  • warn
  • error
  • fatal
mftrace.comp.mf.see.vsam#fhop
Enables or disables file handler operations tracing:
  • True: Enables dispatch tracing.
  • False: Disables dispatch tracing.

mf.see.vsam component trace example

The following sets mf.see.vsam tracing to the debug level and enables VSAM tracing.

mftrace.level.mf.see.vsam = debug|
mftrace.comp.mf.see.vsam#fhop=  true
Parent topic: Component Tracing Properties Reference


Emitter List

The Consolidated Tracing Facility can output its trace information using any of the emitters listed below:

  • TEXTFILE Emitter Properties
    Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.
  • BINFILE Emitter Properties
    Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.
Parent topic: Consolidated Tracing Facility (CTF)


TEXTFILE Emitter Properties

Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.

A text trace file is the default format when a trace is run.

To control the behavior and the appearance of the file, set the following TEXTFILE emitter properties in the Consolidated Tracing Facility configuration file:

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "run".
$(EMITTER)
Always "TEXTFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
dotnet
For Microsoft .NET processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(APPNAME).$(EMITTER).$(PID).log, or $(APPNAME).$(EMITTER).$(PID).log_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the TEXTFILE emitter is being used to output trace events for run.exe executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.textfile.3456.log .
  • If the TEXTFILE emitter is being used to output trace events for myapp.exe executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.textfile.1975.log_1, myapp.textfile.1975.log_2, and myapp.textfile.1975.log_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warning
  • 3: error
  • 4: fatal
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)
HEXBLOCKSIZE The number of hexadecimal bytes to be output in each block when outputting binary trace data. Each block of hexadecimal characters will be separated by a '-' character. For example, if HEXBLOCKSIZE is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it would be formatted as follows:
31323334-35363738-393A3B3C-3D3E3F
 8
LOCATION The folder where the trace files are to be written. On Windows platforms, the folder is specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.
Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.

If the folder specified by the LOCATION property does not exist, the Consolidated Tracing Facility tries to create it. If this fails, the Consolidated Tracing Facility uses the default location (as specified by the MFTRACE_LOGS environment variable). If this fails, the current folder is used.

MAXFILESIZE | The maximum amount of data (in Kb) that will be written to the trace file before the file is closed and the next trace file in the generation sequence is opened. The first trace file in a generation sequence results in the $(GEN) pseudo-variable (see the description of the FILE property, above) being set to 1, the second in the sequence results in it being set to 2, and so on until MAXGENERATION is exceeded. Once the MAXGENERATION number of files has been reached, the generation number reverts to 1 and the first trace file in the generation is overwritten. This is only used if MAXGENERATION > 1. | 0x00002800, indicating a maximum file size of 10 Mb.
MAXGENERATION | The maximum number of trace files that will be written to while tracing is enabled. Use this property in conjunction with the MAXFILESIZE property. | 1, indicating that only a single trace file will be created.
MultiProc Controls whether trace events are written to the trace file by a single process or multiple processes. If enabled for multiple processes, the File property must also be specified without the $(PID) pseudo-variable embedded in its name.

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).log

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

Parent topic: Emitter List


BINFILE Emitter Properties

Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.

The format of the trace files is platform independent.

To enable the BINFILE emitter, specify the following statement in the Consolidated Tracing Facility configuration file:

mftrace.dest = BINFILE

The following list shows the properties you can set to control the behavior of the BINFILE emitter:

Property | Description | Default
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "run".
$(EMITTER)
Always "BINFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
dotnet
For Microsoft .NET processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(APPNAME).$(EMITTER).$(PID).ctb, or $(APPNAME).$(EMITTER).$(PID).ctb_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the BINFILE emitter is being used to output trace events for run.exe executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.binfile.3456.ctb .
  • If the binfile emitter is being used to output trace events for myapp.exe executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.binfile.1975.ctb_1, myapp.binfile.1975.ctb_2, and myapp.binfile.1975.ctb_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
FORMAT
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
LOCATION The folder where the trace files are to be written. The folder specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.
Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.

If the folder specified by the LOCATION property does not exist, the Consolidated Tracing Facility tries to create it. If this fails, the Consolidated Tracing Facility uses the default location (as specified by the MFTRACE_LOGS environment variable). If this fails, the current folder is used.

MAXFILESIZE | The maximum amount of data (in Kb) that will be written to the trace file before the file is closed and the next trace file in the generation sequence is opened. The first trace file in a generation sequence results in the $(GEN) pseudo-variable (see the description of the FILE property, above) being set to 1, the second in the sequence results in it being set to 2, and so on until MAXGENERATION is exceeded. Once the MAXGENERATION number of files has been reached, the generation number reverts to 1 and the first trace file in the generation is overwritten. This is only used if MAXGENERATION > 1. | 0x00002800, indicating a maximum file size of 10 Mb.
MAXGENERATION | The maximum number of trace files that will be written to while tracing is enabled. Use this property in conjunction with the MAXFILESIZE property. | 1, indicating that only a single trace file will be created.
MultiProc Controls whether trace events are written to the trace file by a single process or by multiple processes. If enabled for multiple processes, the File property must also be specified without the $(PID) pseudo-variable embedded in its name.

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
Rununitid | Controls whether the RunUnit information is included in the trace. | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).ctb

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

Parent topic: Emitter List


Diagnostic Collection Utility

When Micro Focus development help customers with issues, it is often very useful to have access to some of the information in the running Enterprise Server for .NET instance .

The seediag.ps1 diagnostic collection utility is provided with the product . It is provided to enable the customer to gather relevent data that will help Micro Focus customer care and development progress a support incident.

Seediag will collect the following information :

  • Database contents on selectable databases used by the Enterprise Server for .NET system.
  • Local trace table information from running regions.

Running the seediag utility.

  • Seediag.ps1 is a powershell script and needs to be run in a powershell environment .
    • Invoke powershell in one of two ways
      • start powershell and run the seediag utility interactively
      • run powershell and invoke from the command line directly
        • e.g. powershell -ExecutionPolicy Unrestricted -File .\seediag.ps1 <parameters>
  • Getting help on the command line
    • from a powershell command prompt type get-help ./seediag.ps1.

Parameters to seediag.ps1

mode

is used to specify what should be collected for diagnostics.

The following are valid modes :

  • DB - Collect database information.
  • TRACE - Collect trace information .

The default mode is DB

outdir
Use in all modes

outdir specifies the folder location that is is used by the script to store the colelcted restults.

It defaults to the <currentdirectory>/collection location, where currentdirectory is the location from

where the script is run.

-outdir c:\temp\collection
usedb

Use in DB mode.

Use in TRACE mode

Specifies the target SQL server to be used for the collection .

Defaults to local machine.

-usedb .\sqlexpress
-usedb someothermachine\MySQLInstance
-usedb (local)

dbfilter

Use in DB mode.

Specifies a filter to restrict the databases for which information is collected.

-dbfilter "ESDEMO|crossregion"
Will only collect information for a database that contains the word ESDEMO or crossregion

Defaults to all databses containing "MicroFocus"

user

Use in DB mode.

Specifies the user name to be used to log onto the SQL server .

If this parameter is absent, the domain credentials are used to authenticate.

-user fred
pass

Use in DB mode.

Specifies the password to be used to log onto the SQL server.

Must be used if User is specified.

region

Use in TRACE mode.

Specifies the Region from which trace information should be retrieved.

Default is all regions.

        -region ESDEMO
Will collect trace information for the ESDEMO region only.
server

Use in TRACE mode.

Specifies the target server running a seemonitor process to co-ordinate the retrieval.

Parameter is in the format <machine>:<port>

Default is localhost:9186

        -server localhost:9186
iname

Specifies an text file name to read the input parameters from .

The text file should contain a list of parameter names without the preceding - , and values seperated by an =.

and example parameter line might be dbfilter=esdemo .

        -iname seediag.txt

It is also possible to set an environment variable called iname set to the filename used

excludetab

Specifies the tables within the selected databases to EXCLUDE from the collection.

By default, any table with "binaries" are excluded as these can contain customer proprietary artifacts.

 -excludetabs "binaries|mydata" would exclude tables with binaries or mydata in the table name
Examples
    The following will collect diagnostics for a sqlexpress database on localhost using normal authentication and putting
    the output zip(s)  into c:\temp\collections
    ./seediag.ps1 -mode DB -usedb localhost\sqlexpress - dbfilter ESDEMO -user fred -pass fredpass -outdir c:\temp\collections

The following will collect TRACE data from a running region ESDEMO running on machine nwb-test port 9186

    ./seediag.ps1 -mode TRACE -usedb localhost\sqlexpress - region ESDEMO -server nwb-test:9186
Parent topic: Diagnostics


Enterprise Server for .NET Context Sensitive Topics

These topics describe the Enterprise Server for .NET user interface screens. You can access each screen directly from the application by clicking the Help button in the Actions pane.

  • Add Files to Deployment List
  • CICS Resource Files: Deployed to a Cross-region Database
  • Console: View Region Console
  • Create New Data Store
  • Data Store View: Deployed Datastores
  • Define Data Store: List Existing
  • Define Data Store: Select Database Instance
  • Define Region: Region Name
  • Define Region: Select Database Instance
  • Define Region: Startup file
  • Deployment List: Components Deployed to a Region Database
  • Deployment List: Components Deployed to Cross-region Database
  • Deployment List: Components Deployed to Custom Database
  • Edit CICS Resources
  • Edit Property File: Define Pseudo-variables
  • Edit Region Startup File
  • Dynamic Debugging
  • JES: Submit JCL to JES
  • Listener Configuration
  • Monitor Region
  • Properties: View and Edit Region Properties
  • Region Startup File Location: Add Region File
  • Region Startup Files: Deployed to a Cross-region Database
  • Regions: View Defined Regions
  • Registered Event Monitors: Remove
  • Remove from Region List confirmation
  • Remove Region File Confirmation
  • Start/Stop Region
  • Statistics: View Statistics for a Region
  • Azure Deployment : Global Configuration View
    Global Configuration View
  • Azure Deployment : Run-time Environment View
    Run-time Environment
  • Azure Deployment : Performance Monitoring View - Dispatcher
  • Azure Deployment : Performance Monitoring View - Listener
    Performance Monitoring configuration - Listener
  • Azure Deployment : Performance Monitoring View - SEP
    Performance Monitoring View - SEP
  • Azure Deployment : Service Configuration View - Dispatcher
    Dispatcher Service configuration
  • Azure Deployment : Service Configuration View - Listener
    Listener Service Configuration .
  • Azure Deployment : Service Configuration View - Monitor
    Service Configuration monitor View
  • Azure Deployment : Service Configuration View - SEP
    Service Configuration View - SEP
  • Azure Deployment : Configuration Editor
    Azure configuration Editor
  • Azure Deployment : Publish View
    Publish View
  • Azure Deployment : Azure Certificate View
    Azure Certificate View
  • Azure Deployment : Location View
    Location View
  • Azure Deployment : Database View
    Database view
  • Azure Deployment : Diagnostics View
    Diagnostic View
  • Azure Deployment : Region Definition View
  • Azure Deployment : Storage View
    Storage View
  • Azure Deployment : Azure Drives View
    Azure Drives
  • Azure Deployment : Tracing View
    Tracing View.
  • Azure Deployment : Local Resources View
    Azure Deployment Local Resources
  • Azure Deployment : Build Instructions view
    Build instructions view.
  • Azure Deployment : Endpoints View
    Endpoint view.
  • Azure Deployment : Startup Tasks View
    Startup Tasks
  • Azure Deployment : Remote Access View
    Remote Access
  • Azure Deployment : Database Connection Strings View
    Database Connection Strings
  • Azure Deployment : Role Configuration View
    Role Configuration
Parent topic: General Administration


Add Files to Deployment List

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select the region to view.
  3. In the Actions pane, select Deployed Files.
  4. On the Deployment List screen, click the [image] icon.

Description

Use this screen to select files to deploy to the database.

File name
The name of the file as it appears in the database.
File path
Use the browse button (...) to locate the file to deploy.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


CICS Resource Files: Deployed to a Cross-region Database

To locate this screen

In the Tree pane under SEE Administration, select Shared Database Deployment Locations > Configuration Administration > CICS Resources.

Description

Use this screen to view resource definitions deployed to the cross-region database.

Add icon
Displays the Select Database Server Instance dialog box, used to add a database server to the list.
Remove option: right-click menu
Right-click a database server in the list and choose Remove to remove the server.
CICS resource files
Lists the CICS resource files deployed to the cross-region database on the selected server.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Console: View Region Console

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. From the list, select the region to monitor.
  3. In the Actions pane, select View console.

Description

Displays the console messages that the region generates.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Create New Data Store

To locate this screen

From the Define Data Store: List Existing screen, click Create new.

Description

Use this screen to create the new data store name.

This is the third screen in the Define Data Store process.

Data store name
Type the name of the new data store.
Create
Closes the Create New Data Store dialog box and adds the new data store to the Existing data stores in this server instance list on the Define Data Store screen.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Data Store View: Deployed Datastores

To locate this screen

  1. In the Tree pane under SEE Administration, select Shared Database Deployment Locations > Application VSAM Files to display a list of existing data stores.
  2. From the list, select the data store to view.

Description

This screen shows the contents of the data store and lets you upload and download VSAM files.

icon
Updates the display with any changes.
File > Upload, [image] icon
Opens the Upload File dialog box, used to browse for and select a VSAM file to upload.
Delete
Accessed by right-clicking a file in the left pane. Prompts to confirm, then removes the selected data store.
Download As ...
Accessed by right-clicking a file in the left pane. Opens a file browse dialog box and lets you download the VSAM file to disk.
File Properties area
Displays the details of the currently selected and uploaded file.
File > Reinstall Stored Procedures menu option
Re-installs the datastore's shared procedures, created when the datastore was created. Use this option after a software upgrade to install any stored procedures updated in the upgraded software release.
Note: Perform this for all datastores after a software upgrade.
File transfers tab
Displays a list of files that have been uploaded or downloaded in the current session. This list clears when you re-start a region.
Files tab
Created when double-clicking a file in the left pane. Displays a list of the file's contents. Right-click and choose Close to close the display.
Left pane file list
Displays a list of files uploaded into the data store. Select a file in the list to display the File Properties area below the list. Double-click a file to create a tab in the right pane that displays the file's contents.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Define Data Store: List Existing

To locate this screen

Complete the Define Data Store: Select Database Instance screen and click Next.

Description

This screen lists the existing data stores. use it to configure items that display in the SEE Administration user interface.

This is the second screen in the Define Data Store process.

Existing data stores in this server instance
Lists the existing data stores and allows you to select the ones to display in the Tree pane.
Note:

Clearing a data store and completing a task or clicking Finish does not delete the data store. It no longer appears in the Tree pane, but you can re-instate it by accessing this screen again and selecting the data store's checkbox.

Create new
Displays the screen used to create the new datastore name.
Finish
Closes the screen and configures Application VSAM files with the selected list names.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Define Data Store: Select Database Instance

To locate this screen

  1. In the Tree pane under SEE Administration > Shared Database Deployment Locations, right-click to select Application VSAM Files.
  2. Choose Add from the menu.

Description

Use this screen to select a database instance.

Database server instance

Listener configurations are stored in the listener configuration file seelistener.exe.config

Note: The default installation has a listener defined for the CICS ESDEMO region, defined on port 9023. You can use this listener to verify the installation. This configuration is not overwritten if you need to re-install the software.

Enter the details of the database server instance to host the region. For example, to configure a SQL Server Express installation on the local machine, you would enter:

(local)\sqlexpress

Refresh
Refreshes the list of database servers
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Define Region: Region Name

To locate this screen

Complete the Define Region: Select Database Instance screen and click Next.

Description

Use this screen to configure a name for a new region or select an existing region database from the list to add to the user interface.

This is the second screen in the Define Region process.

Note:

If selecting an existing region in the database, you must configure a startup file even if the region is running. The region uses this startup file the next time it starts.

Existing regions in server instance
Lists any existing region databases not configured on the user interface. To add an existing region database to the user interface, select the entry to add its name to the Region name field.
Region name
Type a name for the new region if not selecting an existing region database.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Define Region: Select Database Instance

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the Actions pane, select Define Region.

Description

Use this screen to select a database server instance.

This is the first screen in the create new region process.

Database server instance

Listener configurations are stored in the listener configuration file seelistener.exe.config

Note: The default installation has a listener defined for the CICS ESDEMO region, defined on port 9023. You can use this listener to verify the installation. This configuration is not overwritten if you need to re-install the software.

Enter the details of the database server instance to host the region. For example, to configure a SQL Server Express installation on the local machine, you would enter:

(local)\sqlexpress

Refresh
Refreshes the list of database servers
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Define Region: Startup file

To locate this screen

Complete the Define Region: Region name screen and click Next.

Description

Use this screen to configure the startup file for the new region.

This is the third screen in the Define Region process.

Note:

If selecting an existing region in the database, you must configure a startup file even if the region is running. The region uses this startup file the next time it starts.

Region startup file location: Local machine
Select this if the region startup file is on the local machine.
Region startup file location: Server machine
Select this if the region startup file is on a network machine. You must know the path to the region startup file for this option.
Region startup file location: Cross-region database
Select this if the region startup file is deployed to the cross-region database.
Browse
Click this button to browse for the file either on the local machine or in the cross-region database.
Note:

This button is disabled if selecting Server machine as the region startup file location. You must enter the fully-qualified path on the server with this option.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Deployment List: Components Deployed to a Region Database

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select the region to view.
  3. In the Actions pane, select Deployed Files.

Description

Use this screen to view map files and programs deployed to the database, and to add map files and programs to the deployment list.

Plus icon:
Displays the Add File to Deployment List dialog, that you use to configure files to load.
Remove icon:
Prompts to remove the selected item in the list.
Save icon:
Saves the configuration.
Item list
Lists the map files and programs deployed to the region database. Select an item to display its details in the right hand pane.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Deployment List: Components Deployed to Cross-region Database

To locate this screen

  1. In the Tree pane under SEE Administration, select Shared Database Deployment Locations, Application Programs / Maps, Cross-region.
  2. In the list, select the SQL Server instance to view.

Description

Use this screen to view map files and programs deployed to the database, and to add map files and programs to the deployment list.

Plus icon:
Displays the Add File to Deployment List dialog, that you use to configure files to load.
Remove icon:
Prompts to remove the selected item in the list.
Save icon:
Saves the configuration.
Item list
Lists the map files and programs deployed to the region database. Select an item to display its details in the right hand pane.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Deployment List: Components Deployed to Custom Database

To locate this screen

  1. In the Tree pane under SEE Administration, select Shared Database Deployment Locations, Application Programs / Maps, Custom.
  2. In the list, select the SQL Server instance to view.

Description

Use this screen to view map files and programs deployed to the database, and to add map files and programs to the deployment list.

Plus icon:
Displays the Add File to Deployment List dialog, that you use to configure files to load.
Remove icon:
Prompts to remove the selected item in the list.
Save icon:
Saves the configuration.
Item list
Lists the map files and programs deployed to the region database. Select an item to display its details in the right hand pane.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Edit CICS Resources

To locate this screen

  • To edit a region's resource file:
    1. In the Tree pane under SEE Administration, select Regions, and select the region to configure.
    2. In the Actions pane, select Edit CICS Resources.
  • To create or edit a resource file:
    1. In the Tree pane under SEE Administration, select Configuration Editors > CICS Resources.
    2. Choose from the File menu items or use the icons to open or create a resources file to edit.

Description

Use this screen to create and edit the CICS resource files to use with your regions.
Note: When accessing the option from Configuration Editors, you can open existing definitions, create new resource definitions, and save to either a file or to the cross-region database. You can also edit multiple definitions concurrently. Each definition appears as tab in the editor. When editing a region's resource file, these options are not available.
Add New
Available from the right-click menu. Lets you add a new item at the cursor.
Edit > Copy
Available from the right-click menu. Copies the currently selected item.
Edit > Paste
Available from the right-click menu. Pastes the copied item. This is available only when the cursor is in a valid location for the copied item.
File > New
Creates a new default resource definition.
File > Open
Opens an existing resource definition, either from file, or from the cross-region database.
File > Save
Saves the open resource definition.
File > Save To
Save an existing resource definition, either to a network drive, or to the cross-region database.
File > Close
Closes the open resource definition.
Remove
Available from the right-click menu. Removes the currently selected item.
Rename
Available from the right-click menu when a non-system group item is selected. Changes the name of the currently selected item.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Edit Property File: Define Pseudo-variables

To locate this screen

  • In the Tree pane under SEE Administration, select Configuration Editors > Region Startup Properties.

Description

Use this screen to create and edit property files, to define pseudo-variables to use in your region startup files. Move the cursor over the icons to display tool tips.

Name
Type a pseudo-variable name. This is the name to use in region startup definitions.
Value
Type the corresponding value for the pseudo-variable name.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Edit Region Startup File

To locate this screen

  • To edit a region's startup file:
    1. In the Tree pane under SEE Administration, select Regions, and select the region to configure.
    2. In the Actions pane, select Edit Region Startup File.
  • To create or edit a region startup file:
    1. In the Tree pane under SEE Administration, select Configuration Editors > Region Startup.
    2. Chose from the File menu items or use the icons to open or create a region startup file to edit.

Description

Use this screen to create and edit region startup files.
Note: When accessing this option from Configuration Editors, you can open existing region startup files, create new region startup files, and save to either a file or to the cross-region database. You can also edit multiple region startups concurrently. Each startup file appears as tab in the editor. When editing an existing region's startup file, these options are not available.
Add
Available from the right-click menu. Adds a new item at the cursor point.
Edit > Copy
Available from the right-click menu. Copies the currently selected item.
Edit > Paste
Available from the right-click menu. Pastes the copied item. This is available only when the cursor is in a valid location for the copied item.
File > New
Creates a new default region startup.
File > Open
Opens an existing region startup, either from file, or from the cross-region database.
File > Save
Saves the currently open region startup.
File > Save To
Saves an existing region startup, either to a network drive, or to the cross-region database.
File > Close
Closes the open region startup.
Remove
Available from the right-click menu. Remove the currently selected item.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Dynamic Debugging

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select the region to debug.
  3. In the Actions pane, select Dynamic Debugging.

Description

Use this screen to enable dynamic debugging, and to view the active debugging sessions.

Active Debugging Sessions
Lists the active debugging sessions operating for the current region.
Enable/Disable button
Depending on the current state, enables or disables dynamic debugging for the selected region.
Refresh
Refreshes the display of active debugging sessions operating for the current region.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


JES: Submit JCL to JES

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select the region to which you want to submit the JCL.
  3. In the Actions pane, select JES.

Description

Use this screen to select and submit a JCL file to an Enterprise Server for .NET region that has been connected to a native Enterprise Server region.

Browse
Opens a File Open dialog box to locate the JCL file to submit.
JCL type radio buttons
Use these to select the JCL type for the submitted file:
  • JES2
  • JES3
  • VSE
Message
Displays the output from the JCL generated region.
Submit
Submit the selected file.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Listener Configuration

To locate this screen

  1. In the Tree pane under SEE Administration, select Configuration Editors > Listener.
  2. Choose from the File menu items or use the icons to open or create a listener configuration file to edit.

Description

Use this screen to create and edit listener configuration files.

Edit > Copy
Also available from the right-click menu. Copies the currently selected item.
Edit > Paste
Also available from the right-click menu. Pastes the currently copied item. This is available only when the cursor is in a valid location for the copied item.
File > New
Creates a new default listener configuration.
File > Open
Opens an existing listener configuration file.
File > Save
Saves the currently open listener configuration.
File > Close
Closes the open listener configuration.
Options > Start Listener
Starts a listener using the configurations.
Options > Stop Listener
Stops the listener.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Monitor Region

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions, and select a region monitor.
  2. In the Actions pane, select Monitor.

Description

Use this screen to view the operating statistics of a running region.

Active tasks
The current number of active tasks.
Left pane task display
Lists details of the running tasks.
Max tasks
The maximum number of tasks the region is configured to run.
Max active tasks
The maximum number of tasks that have run at once during the current session.
Monitor Host
A list containing all hosts running event monitors for the selected region. Select a host or All.
Next tasks id
The id of the task scheduled to run next.
Region start time
The time the region started.
Region stop time
The time that the region was last stopped.
Right pane task display
Lists further details of the task selected in the left pane.
Refresh
Click this to update the display.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Properties: View and Edit Region Properties

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select any region.
  3. In the Actions pane, select Properties.

Description

Use this screen to assign a properties file for a region, to define pseudo-variables, and to configure a server other than the current one on which to run the region.

Properties file location
Type a path and filename for a properties file or use the ... browse button to locate a file.
Region startup file location
Displays the path and filename of the region startup file. This is display-only.
Start/stop server name
Type the name of the server that starts the region. When the region starts, the region's event monitor runs on this server.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Region Startup File Location: Add Region File

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions, and select a region that does not have an associated region startup file. These regions appear in the list with the [image] icon.
  2. In the Actions pane, select Add Region File.

Description

Use this screen to configure the location and name of the startup file used for the region.

Location radio buttons
  • Local machine

    Select this to browse for a startup file on the local machine.

  • Server machine
    Select this to type the fully qualified path and filename for a startup file on a network machine.
    Note: The ... browse button is not available with this option. You must type a fully qualified path.
  • Cross-region database

    Select this and then use the ... button to browse for a startup file in the cross-region database.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Region Startup Files: Deployed to a Cross-region Database

To locate this screen

  1. In the Tree pane under SEE Administration, select Shared Database Deployment Locations > Configuration Administration > Region Startup.
  2. In the Server instances list, select the server to view or use the [image] icon to add the desired server.

Description

Use this screen to view region startup files deployed to the cross-region database.

Add icon:
Displays the Select Database Server Instance dialog box to add a database server to the list.
Remove option: right-click menu
Right-click a database server in the list and choose Remove to remove the server.
Region startup files
Lists region startup files deployed to the cross-region database in the server that you selected.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Regions: View Defined Regions

To locate this screen

In the Tree pane, under SEE Administration, click Regions.

Description

This screen lists each region defined to the SEE Administration user interface and its status.

In the Tree pane, an icon shows each region's configuration state as follows:

  • : The user interface cannot connect to the region database. This typically appears when you first create a region and have not yet started it. The region database for a new region is not created until you start it.
  • : An existing region database is not associated with a region startup file.
  • : The region has a startup file and an associated database.
  • : Appears while the system determines the state of the region.

The region details display in the Actions pane. This includes the server instance, date and time started, and region startup file location.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Registered Event Monitors: Remove

To locate this screen

In the Tree pane under SEE Administration, select System > Registered Event Monitors.

Description

Use this screen to remove event monitors registered for machines that have stopped unexpectedly.

Add icon:
Displays the Select Database Server Instance dialog box to add a database server to the list.
Remove
Removes the selected event monitor.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Remove from Region List confirmation

To locate this screen

  • Select a region and in the Actions pane, click Remove from region list.

Description

Region removal confirmation screen.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Remove Region File Confirmation

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select a region with an allocated startup file. These are shown with the [image] icon.
  3. In the Actions pane, select Remove Region File.

Description

Use this screen to confirm removal of a region's startup file.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Start/Stop Region

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions, and select a region to start or stop.
  2. In the Actions pane, select Start/Stop Region.

Description

Use this screen to start a region, or to stop a region that is running. Displayed options depend on the region status.

Start/Stop server
If the region was started from a machine other than the current machine, type the region details or select it from the list. Leave this field empty to use the current machine.
Normal stop
Performs a normal stop by doing the following:
  • Blocks any new transaction requests.
  • Allows completion of running transactions.
  • Runs the PLTSD shutdown procedure after running transactions complete.
Immediate stop
Performs an immediate stop by doing the following:
  • Blocks any new transaction requests.
  • Aborts any running transactions.
  • Runs the PLTSD shutdown procedure.
Force stop
performs a forced stop. The system does whatever is necessary to stop the region immediately. The PLTSD shutdown procedure does not run.
Stop
Click this to stop the region with the selected option.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Statistics: View Statistics for a Region

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions.
  2. In the list, select the region to view.
  3. In the Actions pane, select Statistics.

Description

This screen displays the statistics for a region. The screen displays Active when the region is started, or Not Active when the region is not started.

Auto-refresh time
The frequency for updating the display.
Intervals
The time interval over which the collected statistics apply.
Display legend
The colors used for each statistics item displayed:
  • Average latency color
  • Average tasks color
  • Tasks per second color
Latency Task
A ruler that lets you determine the latency and the task per second values that the bars indicate.
Display area
A graphical representation of the statistics values.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Global Configuration View

Description

Use this screen to configure the basic azure deployment configuration.

DNS Name
This is the fully qualified dns name that will be used by the system. For example:
mycics.cloudapp.net
Micro Focus Reference Directory
This is the path to the reference binaries that are used to construct the deployable package.
The build instructions that are used within each role reference this path to harvest binaries, configuration files etc.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Run-time Environment View

Description

This view allows you to configure the run-time environment for each of the worker roles.

By default, Micro Focus uses an environment variable called MF_DOTNET_PLATFORM set to a value "Azure". This must be set, otherwise Enterprise Server for .NET will not run.

You can add extra environment variables by adding rows to the table.

Click Add Environment Variable to add a startup task, or to delete an environment variable click the Delete icon to the left of the row.

The run-time Execution Context can be elevated or lowered using the execution context radio button.

For each environment variable, the following needs to be configured:

Name
The name of the environment variable to define.
Value
The value of the environment variable.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Performance Monitoring View - Dispatcher

Description

Each of the SEP, Dispatcher and Listener roles are instrumented with various windows performance counters that can be used to track throughput and performance.

By checking a check box, the system will configure that performance counter to gather statistics when the worker role is started, and put them into diagnostics storage where they can be retrieved with something like SCOM.

The following counters are available for the Dispatcher Role
Dispatch Put Requests Per Second
This counter shows the rate at which requests are received and queued by the dispatcher worker role.
Clear Requests Per Second
This counter shows the rate at which the dispatcher worker role is receiving clear requests from the listeners.
Dispatch Put Request Duration
This is the average time it takes to place a transaction request onto the work queue.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Performance Monitoring View - Listener

Description

Each of the SEP, Dispatcher and Listener roles are instrumented with various windows performance counters that can be used to track throughput and performance.

By checking a check box, the system will configure that performance counter to gather statistics when the worker role is started, and put them into diagnostics storage where they can be retrieved with something like SCOM.

The following counters are available for the Listener worker role:

Puts Per Second
The number of transactions per second that are being received
Puts Duration
The average duration of the transaction from the listener viewpoint
TN3270Connections
The number of concurrent TN3270 connections that the Listener Worker role is handling
TN3270 Number of threads
The number of active TN3270 threads
TN3270 Number Of Threads Per Second
The rate at which the TN3270 threads are active
TN3270 Thread Duration
The average duration of the TN3270 thread's lifetime
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Performance Monitoring View - SEP

Description

Each of the SEP, Dispatcher and Listener roles are instrumented with various windows performance counters that can be used to track throughput and performance.

By checking a check box, the system will configure that performance counter to gather statistics when the worker role is started, and put them into diagnostics storage where they can be retrieved with something like SCOM.

The following counters are available for the SEP worker role.

Transactions Per Second
The number of transactions that the SEP worker role is executing per second.
Transaction Duration
The average duration of execution of the transactions executed by this SEP worker role.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Service Configuration View - Dispatcher

Description

This view allows you to configure some of the service-related configuration. It is not normally necessary to change these parameters.
Maximum Received Message Size
Change this to modify the maximum size of a received message by a WCF service.
ReaderQuotas Maximum Array Length
Change this to modify the maximum array length received by a WCF service.
Default SEP
This is the address of the default SEP endpoint that the dispatcher will use. By default, this is set to the external load balanced endpoint configured in the SEP role.
net.tcp://$(DnsName):<External Port>/MicroFocus/SEE/SEP

where:

$(DnsName) is automatically expanded at package creation time to include the DNS name of the deployment as defined in the Global Configuration View. <External Port> is the endpoint external port of the SEP, and is normally 65002.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Service Configuration View - Listener

Description

This view allows you to configure some of the service-related configuration. It is not normally necessary to change these parameters.
Maximum Received Message Size
Change this to modify the maximum size of a received message by a WCF service.
ReaderQuotas Maximum Array Length
Change this to modify the maximum array length received by a WCF service.
Default dispatcher
This is the address of the default dispatcher endpoint that the listener will use.
By default, this is set to the external load balanced endpoint configured in the Dispatcher role.
net.tcp://$(DnsName):<External Port>/MicroFocus/SEE/DispatcherSessionService

where:

$(DnsName) is automatically expanded at package creation time to include the DNS name of the deployment as defined in the Global Configuration View. <External Port> is the endpoint external port of the dispatcher, and is normally 65001 .

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Service Configuration View - Monitor

Description

This view allows you to configure some of the service-related configuration. It is not normally necessary to change these parameters.
Maximum Received Message Size
Change this to modify the maximum size of a received message by a WCF service.
ReaderQuotas Maximum Array Length
Change this to modify the maximum array length received by a WCF service.
Default dispatcher
This is the address of the default dispatcher endpoint that the monitor will use.
By default this is set to the external load balanced endpoint configured in the Dispatcher role.
net.tcp://$(DnsName):<External Port>/MicroFocus/SEE/DispatcherSessionService

where:

$(DnsName) is automatically expanded at package creation time to include the DNS name of the deployment as defined in the Global Configuration View. <External Port> is the endpoint external port of the dispatcher, and is normally 65001.

Default sep
This is the address of the default sep endpoint that the monitor will use.
By default, this is set to the external load balanced endpoint configured in the Dispatcher role.
net.tcp://$(DnsName):<External Port>/MicroFocus/SEE/SEP

where:

$(DnsName) is automatically expanded at package creation time to include the DNS name of the deployment as defined in the Global Configuration View. <External Port> is the endpoint external port of the SEP, and is normally 65002.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Service Configuration View - SEP

Description

This view allows you to configure some of the service-related configuration. It is not normally necessary to change these parameters.
Maximum Received Message Size
Change this to modify the maximum size of a received message by a WCF service.
ReaderQuotas Maximum Array Length
Change this to modify the maximum array length received by a WCF service.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Configuration Editor

Description

The azure configuration editor is used to customize the azure deployment.

All of the mandatory aspects required to deploy a region into Azure can be modified/customized here.

The editor has two modes of operation which can be switched from the Options menu in the view:

  • A basic mode, which is default behavior, hides a lot of the complex information that normally does not change.
  • An advanced mode that exposes all of the configuration.
When you create a new deployment, a wizard will guide you through the mandatory configuration. Once completed, the system will generate the configuration views.

To edit the configuration, select the appropriate view and change as required.

To save the configuration, use File /Save .

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Publish View

Description

Once a deployment has been configured, select this view to publish a new deployment, or control / delete an existing deployment.

To publish a new deployment.
Click the blue arrow to publish the deployment into Azure.
After confirming, the system will take all the configured information and create a deployment package. It will then copy the deployment package into Azure storage and then deploy the package to Azure.
The status of the deployment is monitored every few seconds.
Controlling a deployment
Once the deployment is running you can perform the following operations:
  • Delete the deployment.
  • Increase or decrease the instances.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Azure Certificate View

Description

This view enables you to manage the management certificate that is used for the deployment.

The management certificate is used by the configuration and deployment process to interact with the Azure subscription to retrieve and configure information for the deployment.

The name, thumb print, subscription ID and expiration date are informational fields associated with the certificate.

Certificate Generation
To generate a new management certificate that can be imported and used for the deployment, click Generate New Azure Management Certificate. You will be taken to the Azure portals certificate generation portal. Log in with your azure subscription credentials and generate and download the certificate.
Import a Certificate

To import an existing management certificate, click Import Existing Azure Management Certificate. Navigate to the certificates location and click Open. The selected certificate will be imported and used for the deployment.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Location View

Description

The location is the physical location of the datacenter that will host the deployment. It is usually a good idea to use the same location that is used to host the SQL database for the system. This limits the network lag that would be apparent if the deployment was hosted in one geographical location and the database in another.

Location
Enter a valid location, or click the ellipsis button to select from the valid locations for your subscription.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Database View

Description

The database server instance configuration view is used to configure the SQL database that is associated with the deployment.
Database Server Instance
This is the name or address of the SQL server instance that will be used by this deployment. If you are using SQL Azure as the database server, you can click on the ellipsis button for a list of SQL Azure databases available to your subscription. For example:
wzi3brmt

or

127.123.1.54
User ID
Enter the user id that will be used by the deployment to access the SQL server database.
Password
Enter the password associated with the user id that allows access to the SQL server database.

If the database instance is online, you can test the connection using the Test Connection button.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Diagnostics View

Description

Diagnostic information that is generated by the azure deployment includes CTF trace information and Windows Event logs.

The diagnostic data needs to be stored within an azure storage account. This page allows the storage account information to be configured.
Storage Account Name
The name of the storage account to be used. Click on the ellipsis button to retrieve a list of storage accounts associated with the subscription used for the deployment.
The storage account can be one associated with a different subscription, but you cannot browse for it.
Storage Account Key
The storage account key for the storage account that is to be used. This is automatically populated if the storage account was selected from the subscription.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Region Definition View

Description

This view is used to define the system information required in Azure.

By default, two regions are defined when creating a new deployment. ESDEMO is a CICS demonstration region, and JCLDEMO is a JCL batch demonstration region. If you don't need to use the demonstration regions, feel free to delete them.

Click Add Region to add a region, or to delete a region click the Delete icon to the left of the row.

For each region in the system, the following needs to be defined:
Region Name
The name of the region. This is the same name as defined in the region startup file associated with the region.
Database Instance ( advanced mode only)
The name of the database associated with the region. By default, the $(DBInstance) parameter will be expanded automatically to the value defined in the Global Configuration views during packaging and deployment .
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Storage View

Description

Azure drives and other system resource need access to an Azure Storage Account. This storage account can be the same as the diagnostics storage account, but could equally be different.

Storage Account Name
The name of the storage account to be used. Click the ellipsis button to retrieve a list of storage accounts associated with the subscription used for the deployment.
The storage account can be one associated with a different subscription, but you cannot browse for it.
Storage Account Key
The storage account key for the storage account that is to be used. This is automatically populated if the storage account was selected from the subscription.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Azure Drives View

Description

An azure drive is a virtual hard drive (VHD) that is stored in an azure storage account, and is mounted as a network shared drive by the worker roles. This enables shared artifacts to be used from an azure drive, e.g, transaction programs, data files etc.

If you don't need to use an azure drive, delete any existing rows in the table.

If the specified VHD does not exist in azure storage, one is created automatically and used.

Click the Add Drive icon to add an azure drive

To delete a drive, click the Delete icon to the left of the row.

For each azure drive, the following needs to be configured.
Drive Letter
The windows file system drive letter to be associated with this drive. The worker roles will allocate a network drive with this letter.
VHD file
The name of the VHD file to be used for this drive.
AzureDrive.VHD
Drive Size
The size of the drive in MB.
User ID
The user ID that is used by the worker role to access this drive.
Password
The password that is used by the worker role to access this drive.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Tracing View

Description

This view is used to configure the Consolidated Tracing Facility (CTF) for the Worker Role.

Please refer to Trace Functionality for more information on the CTF functionality in general.

Each one of the Worker Roles has specific tracing that can be enabled or disabled.

This trace information is stored in the diagnostics storage account configured in the Global Configuration views.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Local Resources View

Description

If using an azure drive, you can improve the performance of the drive by allocating more local cache for its use.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Build Instructions view

Description

This view is used to configure the files that are included in the deployment package shipped to Azure.

The files that are included automatically when creating a new deployment are required for the deployment to operate correctly. Modifying them can have severe consequences.

Each row configures a copy operation.

Click Add to add a region.

To delete a row, click the Delete icon to the left of the row.

Source Name
The full path to the file that needs to be copied.
The $(mfrefdir) variable is auto expanded from the configuration in the Global configuration views.
Target Location
The full path to the target location for packaging.
$(targetdir) is auto expanded to the system location where the package is created. If you want to copy files to a subfolder, $(targetdir)\folder can be used.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Endpoints View

Description

An endpoint in Azure describes a network connection and its characteristics.

Click Add Endpoint to add an endpoint, or to delete an endpoint click the Delete icon to the left of the row.

For each endpoint, the following needs to be configured:
Name
A unique name for the external endpoint.
When creating a new deployment, the endpoints for the Micro Focus system are pre-defined. They are prefixed by MicroFocus.SEE and their settings should not be changed unless you absolutely understand what you are doing.
Type
Input is a port that is defined to be accessible externally, and is load balanced.
Internal is a port that is useable internally, and is not available for public use. It is not load balanced by Azure.
Protocol
The protocol associated with the port. This is normally set to TCP.
Public Port
The number of the port that is external/publicly available. If the port type is internal, this field cannot be set.
Private Port
The number of the port that is used internally. If set to 0, the same port number as the public port will be used.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Startup Tasks View

Description

A startup task defines a command file that is run when the virtual machine hosting the worker role is started.

By default, Micro Focus uses a command file called 1 which must be run first. This command file must be run or the Enterprise Server for .NET will not run.

You can add extra actions by adding rows to the table. They will be run in sequence. You might want to do this, for example, to install a third party service for printer support.

Click Add Startup Task to add a startup task, or to delete a startup task click the Delete icon to the left of the row.

For each Start up task, the following needs to be configured:

Command Line
The name of the batch or command file to be run.
Execution Context
The execution context within which the command file will be run. Permitted values are limited, elevated.
Task Type
The type of task. Permitted values are simple, foreground or background.

Refer to the Azure documentation for further information on these options.

Parent topic: Enterprise Server for .NET Context Sensitive Topics
1 startup.cmd


Azure Deployment : Remote Access View

Description

Azure worker roles can be accessed by using the remote desktop whilst the instances are running. This view is used to configure the required remote desktop information.
Enable Remote Access checkbox
Check this box if you want to enable remote desktop access for all the worker roles instances in deployment.
Account User Name
Enter a user name to access running instances using the remote desktop.
Certificate
Click the certificate to select a certificate for remote desktop use.
Account Password
Enter the password to be used for access.
Confirm Account Password
Enter the password to be used for access.
This field is compared with the first password field to ensure consistency.
Account expiration date
Enter the date after which access will be denied.
Setting this to short will mean that a re-deploy would be required to reset this period.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Database Connection Strings View

Description

The connections to the various database tables used by the region are configured here. These connection strings are put into the azure package, and are also appended to the machine.config so access to the databases can be done from the command line tooling.

Click Add to add a new database connection string, or the Delete icon next to the row to delete a connection string.

Each connection string requires the following fields:
Key
The database name.
In basic edit mode, this just consists of the database name.
In advanced mode, the full connection syntax is displayed. The $(DbInstance) variable is autoexpanded during the publish step to include the configuration from the Global Configuration view.
Value
In advanced mode only.
Contains the full connection configuration string required to connect to the database.

The connection string is similar to the following:

Server=tcp:[servername].database.windows.net;
                Database=master;
                User ID=[username]@[servername];
                Password=[userpassword];
                Trusted_Connection=False;
                 Encrypt=True;
where:
  • [servername] is the name of your SQL Azure database server (for example iwek9v4j6a).
  • [username] is your SQL Azure user name and [userpassword] is your SQL Azure password.

The connection string for each of your SQL Azure databases has the same format, but with master replaced by the appropriate database name.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Azure Deployment : Role Configuration View

Description

This configuration view allows you to configure the roles' basic properties.
Instance Count
The number of instances that should be started. Increase or decrease this value to allow more or fewer instances to be available to the region.
VM Size
Select the appropriate virtual machine size to be used to host the role.

It is important to remember that there are cost implications associated with numbers of instances and their sizes.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


CICS Administration

  • CICS Region Configuration
    The topics in this section describe how to configure CICS regions.
  • CICS Command Line Utilities
    Command line utilities used specifically for administering CICS regions.
Parent topic: Administrator Role


CICS Region Configuration

  • CICS Region Startup Files
  • Defining and Configuring Resources
  • Configuring a CICS Region's Program/Map Location and Search Order
  • Configuring Data Stores Located in a Database or File System
  • Configuring the CICS Terminal Type
  • Configuring HCO for SQL Server Connections
  • Configuring REST Web Services and EXCI
  • Migrating a native Enterprise Server Resource Definitions File
Parent topic: CICS Administration


CICS Region Startup Files

To be able to start a CICS region, a region startup file must first be created and associated with the region in the Enterprise Server for .NET Administration UI. The region startup file defines the characteristics of the region to be started and the locations of programs and data used by the region at run-time. This topic describes how CICS region startup files are created and managed.

  • To Create a CICS Region Startup File
  • To Edit a Region Startup File Associated with a CICS Region
  • To Set The Artifact Location and Search Order
  • To Associate a Resource Definition File with a Region Startup Definition File
  • To Add an Existing Region to the User Interface
  • To Associate an XA Resource with a CICS Region Startup File
Parent topic: CICS Region Configuration
Related concepts
About Region Startup and Resource Definitions


To Create a CICS Region Startup File

Enterprise Server for .NET Administration UI's Region Startup File Editor is used to create CICS region startup files. Region startup files residing in either the local/network file system or a cross-region database can be created and modified using this editor.
  1. In the Tree pane under Configuration Editors, click on Region Startup. See 1 in the diagram below.
  2. Choose File > New , or click the Create new file icon in the toolbar. See 2 in the diagram below.

    The Create Region Startup File dialog is displayed.

  3. Select the CICS region type on the dialog. See 3 in the diagram below.
  4. Enter the name of the region that the startup file will be used with in the Region name entry field and click on OK. See 4 in the diagram below.

    The dialog is dismissed and a new CICS region startup file is opened in the editor. However, this file has not yet been persisted to disk or to a cross-region database as indicated by the [New File] tab. See 5 in the diagram below.

  5. To save the file to disk, choose File > Save To > File ... . See 6 in the diagram below.

    A standard file dialog is now displayed to allow you to specify the location on disk where the startup file is to be saved.

  6. To save the file to a cross-region database, choose File > Save To > Cross-region Database ... . See 7 in the diagram below.

    A Save To dialog is now displayed. In the Server instance entry field, enter the name of the database server instance of the cross-region database where the file is to be saved. If you want to view the region startup files already deployed to the cross-region database, click on Browse. See 8 in the diagram below. If you want to overwrite one of the displayed files, select it from the list and click OK. Otherwise click Cancel to dismiss the dialog and enter the new name for the region startup file you want saved in the Region startup file name entry field.

    Click on Save to save the file to the cross-region database. See 9 in the diagram below.

    The dialog is dismissed and the name of the CICS region startup file that has been saved replaces [New File] in the file tab. See 10 in the diagram below.

The created region startup file can now be associated with any CICS region.

Parent topic: CICS Region Startup Files
Related concepts
About Region Startup and Resource Definitions
Related tasks
To Create a JES Region Startup File


To Edit a Region Startup File Associated with a CICS Region

The Enterprise Server for .NET Administration UI's Region Startup File Editor is used to edit CICS region startup files. Region startup files residing in either the local/network file system or the cross-region database can be modified using this editor.
  1. In the Tree pane under Regions, select the CICS region to edit. See 1 in the diagram below.
  2. In the Actions pane, select Edit Region Startup File. See 2 in the diagram below.

    The CICS region startup file appears in the editor in the Results pane.

  3. Make any required changes using the editor. For example, region properties such as Allow Dynamic Debugging can be modified by changing the associated value in the properties window.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See 3 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: CICS Region Startup Files
Related concepts
About Region Startup and Resource Definitions
Related tasks
To Edit a Region Startup File Associated with a JES Region


To Set The Artifact Location and Search Order

You need either the artifact location URLs or network drive and path details for this task.

This procedure sets the locations used by CICS applications to search for data files, map files, and programs deployed on disk or in a database.
  1. Open the region startup file in the Enterprise Server for .NET region startup editor.
  2. From the Tree pane, select Region > CICS > Locations.

    The Application VSAM File Paths, Application Map Paths, and Application Program Paths items appear.

  3. Right-click the item you want and choose Add.

    A menu lists available location types:

    • For Application Data File Paths, the only valid location type type is Folder Location.
    • For Application Map Paths and Application Program Paths, vald location types are:
      • Folder Location
      • Region Database Location
      • Cross-region Database Location
      • Custom Database Location
    Note: For VSAM files, the only valid location type is Folder Location. For VSAM files deployed to a user-defined database, configure the data store name in the resource definition's FCT.
  4. Select the location, type then configure the location in the dialog box.

    The configured path or URL is added to the locations list in the Results pane.

  5. In the Results pane, drag and drop the location items to configure the search order that you want.
  6. Save the Region startup file, and cold start the region.

    The CICS application now uses the locations and search order that you set when it searches for program or map files to use.

Parent topic: CICS Region Startup Files


To Associate a Resource Definition File with a Region Startup Definition File

When you create or edit a region startup file, you can add or change the associated resource definition file. The file can reside in the local/network file system, or in the cross-region database.
  1. Open the region startup file for editing.
  2. In the Region Startup editor's Tree window, select the top-level Region heading. In the Properties window, the region startup's General settings display.
  3. Under General, select Resource Definition File. The name of the current resource definition file if any displays in the right hand column.
  4. Click the ... button at the right of the resource definition file name.

    A message prompts you to select a file from disk, or from the cross-region database.

  5. Select the option to access the resource definition file that you want.
    • Select Config File On Disk to browse for a file on the local/network file system.
    • Select Cross-Region Database to select the database to use that contains the file.
  6. Select the resource definition file and click OK to configure it.
If you changed the resource definition file for a region, you must cold-start the region for the changes to take effect.
Parent topic: CICS Region Startup Files


To Add an Existing Region to the User Interface

  • The region database must exist on an available database server.
  • You should know the name and location of the region's startup definition file.
Use the following procedure to add an existing region database to the Administration user Interface.
  1. In the Tree pane of the Enterprise Server for .NET, select Regions, and in the Actions pane, click Define Region. The Define Region dialog box appears.
  2. In the Database Server Instance field, select the database server to use from the list, or type your server name in the field. Click Next.

    For example, for a SQL Server Express installation on the local machine, type (local)\sqlexpress.

    Enterprise Server for .NET connects to the database server and confirms the connection. The Define Region dialog box lists the available regions on the selected database server.

  3. Select the region to add.

    The Define Region dialog box displays options for the region startup file location. Valid locations are:

    Local machine
    Select when the startup file is located on a drive on the local machine.
    Startup Server machine
    Select when the startup file is located on another network machine. You would use this option when, from your local machine, you want to create and manage regions on a remote machine.
    Cross-region database
    Select when the startup file is in the cross-region database of the database server instance that you specified earlier. This is the preferred option for a production or a scale-out environment.
  4. Use the Browse button to locate and select the region startup file in the location that you specified. Click OK to load it.
  5. Click Finish.

    The region appears under the Regions item in the user interface.

Parent topic: CICS Region Startup Files


To Associate an XA Resource with a CICS Region Startup File

When a transaction uses a SQL database, the connection string defined in the XA resource definition associated with the region will, by default, be used to connect to that database. An XA resource definition can be associated with a region at either the SIT or region startup file level. When specified in both the SIT and region start-up file, the region startup file takes precedence. To associate an XA resource definition with a region startup file:
  1. Open the region startup file using the Enterprise Server for .NET Administration UI's Region Startup File Editor
  2. Select the Region node in the Results pane. See 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the SQL category in the properties window and enter the XA resource definition name that you want associated with the region as the value of the XA resource name property. See 2 in the diagram below.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See 3 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: CICS Region Startup Files
Related tasks
To Create an XA Resource Definition
To Associate an XA Resource with a SIT
To Associate an XA Resource with a PCT
Related information
About XA Resources
Configuring XA resources


Defining and Configuring Resources

The topics in this section describe how to define and configure CICS resources.

  • About CICS Resource Definitions
  • Copying and Pasting Resource Definitions Items
  • Renaming a Resource Definitions Item
  • To Create a New Resource Definition File
  • To Open a Resource Definition File for Editing
  • To Edit a Resource Definitions File
  • To Create or Edit a System Initialization Table
  • To Create or Edit a Startup List
  • To Create or Edit a Group
  • To Associate an XA Resource with a SIT
  • To Associate an XA Resource with a PCT
Parent topic: CICS Region Configuration


About CICS Resource Definitions

In the Enterprise Server for .NET environment, a resource configuration is maintained as an XML file.

The installation software includes a sample resource configuration file named ResourceDefinitions.config. The sample region ESDEMO uses this resource definition file. This is installed in %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

Enterprise Server for .NET definition files are in a different format from those used in native Enterprise Server. Studio Enterprise Edition includes utilities that migrate native Enterprise Server definition files to a format used by Enterprise Server for .NET.

You can deploy resource definition files:

  • As a file on a network location accessible to the installation's regions.
  • To the cross-region database.

Use the Resource Editor to configure resource definition files. The Resource Editor lets you add and delete items, copy and paste items, and re-name group items.

Parent topic: Defining and Configuring Resources


Copying and Pasting Resource Definitions Items

The Resource Editor lets you copy and paste either from the Resource File Editor's Edit menu or by right-clicking an item.

You can copy and paste all items in a resource definition file. When you paste an item, you can choose to paste it with the same name as the original file, or you can paste it with a new name.
Tip:

Where allowed, you can allocate a hexadecimal name to a pasted item.

  • To copy an item, right-click it and choose Copy.

  • To copy multiple items, hold down the Control key and select each, then right-click and choose Copy.

To paste items, access the target area, right click and choose Paste. The Paste items dialog box appears. You can use this dialog box to edit the items to be pasted.

When pasting items:

  • Use the check boxes to select and clear items to be pasted.
  • Select an item's name to edit it.
  • To enter a name in hexadecimal format, prefix the hexadecimal number with 0X. For example, the name 0XFD allocates the hexadecimal number FD as the item name.
  • The OK button is not enabled until you resolve all conflicts shown in the dialog box.
Parent topic: Defining and Configuring Resources


Renaming a Resource Definitions Item

In a CICS resource definition, you can rename group items that do not have a DFH prefix. Items with a DFH prefix are system resources. You can use a hexadecimal name when renaming group items.

Use the following procedure to rename an item.

  1. In the Resource Editor, right-click the item to rename and choose Rename.

    The Rename dialog box appears.

  2. In the Rename dialog box, select Text name or Hexadecimal name.
  3. Type the new resource name and click OK.

Parent topic: Defining and Configuring Resources


To Create a New Resource Definition File

You can create a new resource definition file to use with your regions. You can use the editor to create new, or edit existing resource definitions.
  1. In the Enterprise Server for .NET user interface, select Configuration > CICS Resources .

    The Resource Editor opens in the Results pane.

  2. Choose File > New to create a new resource definition, or choose File > Open to open an existing resource definition. The resource definition appears in the editor.
Parent topic: Defining and Configuring Resources


To Open a Resource Definition File for Editing

  1. In the Tree pane under Regions, select the region with the resource definition you want to edit.
  2. In the Actions pane, click Edit CICS Resources.

    The Resource Definitions Editor opens in the Results pane.

To open a resource definition file which is not attached to a region, or a resource definition file which is deployed to the cross-region database.

  1. In the Tree pane, under Configuration Editors, select CICS Resources to open the CICS Resources File Editor in the Results pane.
  2. Choose File > Open to locate and open the resource definition. You can open a file from the file system, or from a cross-region database running on a network SQL server.
  3. Use the CICS Resources File Editor to edit the file.
  4. Click Save to save the file.
    Note: Restart any regions that use the resource definition for changes to take effect.
Parent topic: Defining and Configuring Resources


To Edit a Resource Definitions File

  1. Depending on how the resource definition file is deployed, open the file in the resource definition editor.
  2. Use the editor to select and modify the resource settings.
    Use the tabs at the bottom of the editor to select the category of items to modify: PCT, FCT, or SIT.
    Note: You cannot change any resource that is prefixed with DFH. These are required by the Enterprise Server for .NET system.

    You can copy items and paste them into valid locations either in the same configuration file, or in other configuration files that are open for editing. The copy and paste functionality allows you to re-name copied items before you paste them.

  3. From the list of items, select the item to modify.

    The item's settings appear in the editor's Properties window.

  4. Edit the items as required.
  5. Choose File > Save or File > Save As to save changes.
Parent topic: Defining and Configuring Resources


To Create or Edit a System Initialization Table

  1. Open the Resource Definitions file in the editor.
  2. Select the SIT tab.

    The SITs configured in the resource definitions file display.

  3. To filter the SIT display, right-click in the Results pane and choose Filter.

    You can select to display all SITs, or active SITs only.

  4. Do one of the following:
    • To edit an existing SIT, select it from the list.
    • To create a new SIT, right-click in the SIT area and choose Add. Then in the SIT name field of the Add new SIT dialog box, type a name for the SIT and click OK.

    The SIT appears in the list. The SIT properties display in the Properties window.

  5. Edit properties as needed to configure the SIT.
  6. Choose File > Save, or use the File Save icon to save the resource definitions file.

    The resource definitions are saved.

Cold-start regions that use this configuration for changes to take effect.

Parent topic: Defining and Configuring Resources


To Create or Edit a Startup List

  1. Open the Resource Definitions file in the editor.
  2. Select the General View tab.
  3. Select and expand Startup Lists.
  4. Do one of the following:
    • To edit an existing startup list, select it from the list.
    • To create a new startup list, right-click Startup Lists and choose Add. Then in the Startup List name field of the Add New Group dialog box, type a name for the startup list and click OK.
    The startup list appears in the list. The startup list's properties display in the Properties window.
  5. Edit properties as needed to configure the startup list.
  6. Choose File > Save, or use the File Save icon to save the resource definitions file.

    The resource definitions are saved.

Cold-start regions that use this configuration for changes to take effect.

Parent topic: Defining and Configuring Resources


To Create or Edit a Group

  1. Open the Resource Definitions file in the editor.
  2. Select the General View tab.
  3. Select and expand Groups.
  4. Do one of the following:
    • To edit an existing group, select it from the list.
    • To create a new group, right-click Groups and choose Add. Then in the Group name field of the Add New Group dialog box, type a name for the group and click OK.
    The group appears in the list. The group's properties display in the Properties window.
  5. Edit properties as needed to configure the group.
  6. Choose File > Save, or use the File Save icon to save the resource definitions file.

    The resource definitions are saved.

Cold-start regions that use this configuration for changes to take effect.

Parent topic: Defining and Configuring Resources


To Associate an XA Resource with a SIT

When a transaction uses a SQL database, the connection string defined in the XA resource definition associated with the region will, by default, be used to connect to that database. An XA resource definition can be associated with a region at either the SIT or region startup file level. When specified in both the SIT and region start-up file, the region startup file takes precedence. To associate an XA resource definition with a SIT:
  1. Open the resource definition file using the Enterprise Server for .NET Administration UI's CICS Resources File Editor
  2. Select the SIT you want to configure in the Results pane. See 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the SQL category in the properties window and enter the XA resource definition name that you want associated with the SIT as the value of the XA resource name property. See 2 in the diagram below.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See 3 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: Defining and Configuring Resources
Related tasks
To Create an XA Resource Definition
To Associate an XA Resource with a CICS Region Startup File
To Associate an XA Resource with a PCT
Related information
About XA Resources
Configuring XA resources


To Associate an XA Resource with a PCT

When a transaction uses a SQL database, the connection string defined in the XA resource definition associated with the region will, by default, be used to connect to that database. An XA resource definition can be associated with a region at either the SIT or region startup file level. When specified in both the SIT and region start-up file, the region startup file takes precedence. However, if an XA resource definition is defined for a PCT, that definition will be used in preference to the one associated with the region when the transaction is invoked. To associate an XA resource definition with a PCT:
  1. Open the resource definition file using the Enterprise Server for .NET Administration UI's CICS Resources File Editor
  2. Select the PCT you want to configure in the Results pane. See 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the SQL category in the properties window and enter the XA resource definition name that you want associated with the PCT as the value of the XA resource name property. See 2 in the diagram below.
    Note: If you specify the database application plan, package path or package set property in the PCT's SQL category, this will override the database application plan, package path or package set property that has been configured for the XA resource definition specified in the XA resource name property
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See 3 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: Defining and Configuring Resources
Related tasks
To Create an XA Resource Definition
To Associate an XA Resource with a CICS Region Startup File
To Associate an XA Resource with a SIT
Related information
About XA Resources
Configuring XA resources


Configuring a CICS Region's Program/Map Location and Search Order

User programs and BMS maps used by a CICS region may reside in a file system folder, the region database, the cross-region database, custom database or data store database folder. The procedures for defining program locations and search order, and BMS map locations and search orders, using the Enterprise Server for .NET Administration UI are both the same.

  • To Configure a CICS Region's Program Location and Search Order
    The CICS system needs to know where to locate user programs at run time and in what order these locations are to be searched. This topic describes how this information is defined in a CICS region startup file.
Parent topic: CICS Region Configuration


To Configure a CICS Region's Program Location and Search Order

User programs used by a CICS region may reside in a file system folder, the region database, the cross-region database, custom database or data store database. This procedure demonstrates how to define each of these location types and how their run-time search order is specified for programs using the Enterprise Server for .NET Administration UI:
Note: With the exception of selecting Application Map Paths instead of Application Program Paths in the steps below, the procedure for configuring a CICS region's BMS map location and search order is exactly the same as that described for programs.
  1. Open the startup file of the CICS region you are configuring with the Region Startup File editor. See To Edit a CICS Region Configuration.
  2. In the Results pane expand the Region node and select the Application Program Paths node. See 1 in the diagram below.
  3. To add a file system program folder location, right-click on the Application Program Paths node and choose Add > Folder Location... from the context menu. See 2 in the diagram below.

    The Add Program Path dialog is displayed.

    Enter the name of the folder containing the user programs to be used by the region in the Folder entry field. Alternatively, use the Browse button to select a folder from a standard file dialog. Note that the folder specified should be on a network drive to ensure that it is available to any machine in a scaled-out system. Click on OK. See 3 in the diagram below.

    The dialog is dismissed and the folder specified appears in the program folder list.

  4. To add the region database as a program location, right-click on the Application Program Paths node and choose Add > Region Database Location... from the context menu. See 4 in the diagram below.

    The region database appears in the program folders list. Note that the region database can only be added once to the program folders list, so will not be available as a location for a subsequent Add operation.

  5. To add the cross-region database as a program location, right-click on the Application Program Paths node and choose Add > Cross-region Database Location... from the context menu. See 5 in the diagram below.

    The cross-region database appears in the program folders list. Note that the cross-region database can only be added once to the program folders list, so will not be available as a location for a subsequent Add operation.

  6. To add a custom database (i.e. a user specified database) as a program location, right-click on the Application Program Paths node and choose Add > Custom Database Location... from the context menu. See 6 in the diagram below.

    The Add Program Database Location dialog is displayed.

    Enter the name of the machine hosting the database in the Server entry field, the name of the database server instance in the Instance entry field, the name of the database in the Database entry field and the name of the table where the programs will reside in the Table entry field. Click on OK. See 7 in the diagram below.

    The dialog is dismissed and the custom database location specified appears in the program folder list.

  7. To add a data store database folder as a program location, right-click on the Application Program Paths node and choose Add > Data Store Folder Location... from the context menu. See 8 in the diagram below.

    The Data Store Browse dialog is displayed.

    Enter the name of the database server instance in the Server instance entry field, the name of the data store in the Data store name entry field and the name of the data store folder where the programs will reside in the Folder entry field. Click on OK. See 9 in the diagram below.

    The dialog is dismissed and the custom database location specified appears in the program folder list.

  8. The order in which the program locations are listed indicates the order in which they will be searched at run time (i.e. the location at the top of the list will be searched first, the second in the list searched second and so on). To change the search order, select a location in the list, see 10 in the diagram below, and drag and drop it to the required position in the list. See 11 in the diagram below.

    The selected item in the previous diagram is moved to the top of the list and will now be the first location to be searched at run time. See 12 in the diagram below.

  9. Choose File > Save, or click the Save icon in the toolbar to save the file. See 13 in the diagram below.

You must cold-start the region for the changes to take effect.
Parent topic: Configuring a CICS Region's Program/Map Location and Search Order


Configuring Data Stores Located in a Database or File System

You can configure data Stores located in a user-defined database, or located on the file system.

  • To Configure a Data Store in a User-defined Database
  • To Configure a Resource Definition for a VSAM File On Disk
  • To Configure a Resource Definition for a Fileshare Server
Parent topic: CICS Region Configuration


To Configure a Data Store in a User-defined Database

The VSAM database file must first be imported into a datastore under the Enterprise Server for .NET installation's database.
Use this procedure to make a data store located in a user-defined database available for use.
  1. Open the resource definition file in the Resource File Editor.

    The resource definitions display in the editor.

  2. Click the FCT tab.

    The File Control Table settings display.

  3. In the Name column, locate and select the resource item to associate with the data store.

    The item's settings display in the General pane.

  4. Set the value of the item to the data store name.

    By default, a CICS program attempts to use the VSAM data store if the name is not set.

  5. Locate the FileFormat item, and use the list to set the value to RDBMS.
    Tip: A value of RDBMS specifies that the VSAM file is loaded into the database.
  6. Save the resource definition file, and cold-start the region.

Operating regions using the resource definition must be stopped and cold-started before they can use the settings.

Parent topic: Configuring Data Stores Located in a Database or File System


To Configure a Resource Definition for a VSAM File On Disk

Use this procedure to make a VSAM database stored on a network drive or a local disk available for use.
Note: For VSAM files located on disk, you must configure the location in the region startup file.
  1. Copy the data file to a network shared folder.
  2. Open the resource definition file in the Resource File Editor.

    The resource definitions display in the editor.

  3. Select the FCT tab.

    The File Control Table settings display in the editor.

  4. In the Name column, locate and select the resource item that you want to associate with the VSAM file.

    The settings for the item display in the editor's Properties window.

  5. Locate the item. Set the file name only if it is different from the FCT entry name. By default, a CICS application looks for a data file of the same name as the FCT entry.
  6. Locate the Path item and ensure that it is clear.

    Use the region startup file to set the search paths for the data file.

  7. Locate the FileFormat item, and use the list to set the value.
    Note: A value of RDBMS specifies that the VSAM file is loaded into the database, so do not use this value for VSAM files on disk.
  8. Save the resource definition file.

You need to configure the location for the data file.

Operating regions using the resource definition must be stopped and cold-started before they can use the settings.

Parent topic: Configuring Data Stores Located in a Database or File System


To Configure a Resource Definition for a Fileshare Server

You need to have the host name and port details for the Fileshare server.
Complete this task to make a Fileshare server available to anEnterprise Server for .NET region.
  1. Open the resource definition file in the Resource File Editor.

    The resource definitions are displayed in the editor.

  2. Select the FCT tab.

    The File Control Table settings display in the editor.

  3. In the Name column, locate and select the resource item in the data store that you want to associate with the Fileshare server.

    The settings for the item display in the editor's Properties window.

  4. In the right pane under Misc, locate theitem and set the value to the hostname and port of the Fileshare server. Enter the information in the format <server name>:<Port number>.

    For example, to configure a Fileshare server with host name server1 on port 3019, type server1:3019 .

  5. Under Misc, locate the item and set the value to the data file's format.
  6. Save the resource definition file and cold-start the region.

Operating regions using the resource definition must be stopped and cold-started before they can use the settings.

For compatibility with Enterprise Server for .NET, the native Enterprise Server Fileshare server must be started with a command in a format which specifies the port, such as fs /s ServerEE,MFPORT:3019.

Parent topic: Configuring Data Stores Located in a Database or File System


Configuring the CICS Terminal Type

Enterprise Server for .NET contains auto-exit functionality to configure the client terminal type.

When it first receives a request, the TN3270 listener assigns a unique terminal netname and terminal ID, and configures handling for the basic IBM 3270 models — model 2, 3, 4, or 5, all of which have different screen sizes. It bases this terminal model configuration on the terminal type name that the client connection sends.

A client connection can also request a netname with a corresponding terminal ID. If the name, and the corresponding terminal ID, are in use, the request is rejected and the conversation terminates.

The CICS region can be configured to allow you to use the auto-install exit to override this behavior. This provides a simple way to override the terminal model based on the netname requested by the client.

When the auto-install exit is enabled, the terminal installation process, Enterprise Server for .NET looks for a program named mfaiexit. If mfaiexit exists, it is invoked with a commarea with the following parameters:

  • Netname
  • ID
  • Device type currently assigned to the terminal

You can create an mfaiexit program to change any of these fields, and you can configure the program to set flags telling Enterprise Server for .NET to set these changes in the TCTTE.

Note: The mfaiexit program must be in a path visible to the system.

An example mfaiexit program is supplied in the Samples folder. By default, this is in the following location:

%PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\MFAIEXIT

  • To Enable the Auto-install Exit
    The auto-install exit must be enabled in the CICS region's SIT before it can be used
Parent topic: CICS Region Configuration


To Enable the Auto-install Exit

This procedure demonstrates how the auto-install exit is enabled for a CICS region using the Enterprise Server for .NET Administration UI:
  1. In the Tree pane under Regions, select the CICS region to edit. See 1 in the diagram below.
  2. In the Actions pane, select Edit CICS Resources. See 2 in the diagram below.

    The CICS resource definition file appears in the editor in the Results pane.

  3. Expand the SIT node and select the region's SIT. The Properties window will display the selected SIT's properties.
  4. Toggle the value of the Terminal Auto-install property in the User Exits category from False to True. See 3 in the diagram below.
  5. Choose File > Save, or click the Save icon in the toolbar to save the file. See 4 in the diagram below.

You must cold-start the region for the changes to take effect.
Parent topic: Configuring the CICS Terminal Type


Configuring HCO for SQL Server Connections

The Enterprise Server for .NET software includes a user exit program to enable the configured HCO for SQL Server connections. These are then accessible to your applications.

To use this user exit, configure the region startup file for the region that runs the application. The application can then use the connections to access the HCOSS data.

The user exit is named MicroFocus.SEE.SqlExit.dll, and is located in the system bin folder %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE.

You specify the name MicroFocus.SEE.SqlExit in the region startup file.

Note: You do not need to specify the fully qualified name, as CICS applications use this system bin location for the user exit.
  • To Configure an HCO for SQL Server Connection
Parent topic: CICS Region Configuration


To Configure an HCO for SQL Server Connection

You can configure a region startup file so that applications running in the region can use the configured HCOSS connections.
  1. From the Tree pane of the Enterprise Server for .NET user interface, select SEE Administration > Configuration > Region Startup .

    The Region Startup editor appears in the Results pane.

  2. Choose File > Open to locate and open the startup file for the region to configure.

    The file's settings display in the editor.

  3. Select the top-level Region item, and under General in the Properties window, locate the SQLUser Exit item.
  4. For the SQLUser Exit item, type MicroFocus.SEE.SqlExit.
    Note: You do not need to specify the fully qualified name, as CICS applications use the system bin location for the user exit, and the exit program is installed in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE.
  5. Save the region file.
The region must be cold-started before the changes take effect.
Parent topic: Configuring HCO for SQL Server Connections


Configuring REST Web Services and EXCI

CICS REST Web Services let non-CICS applications invoke CICS transactions using HTTP requests. EXCI (External Call Interface) lets non-CICS applications call programs running under CICS. You can configure a region to support either or both of these features.

  • About CICS REST Web Services
  • About CICS External Call Interface
  • Configuring REST Web Services
  • Configuring EXCI
Parent topic: CICS Region Configuration


About CICS REST Web Services

Enterprise Server for .NET CICS supports invoking CICS transaction programs over HTTP as REST Web Services. A REST (Representational State Transfer) service is a simple form of web service, much less complex than traditional SOAP services. HTTP clients, which can be application programs or even scripts on web pages, can exchange a CICS commarea with the transaction they invoke. The commarea is encoded as a JSON (Javascript Object Notation) object, and can be either a text string or a binary area such as a COBOL group item.

The invoked transaction runs without a primary facility (terminal), and is restricted to the DPL subset of CICS commands. It can perform most CICS operations that do not require a terminal.

Because REST web services use standard protocols such as HTTP and JSON, clients don't require any Micro Focus software (though Micro Focus does provide a convenience class that can be used in COBOL for .NET and other .NET languages, when Micro Focus Visual COBOL for Visual Studio is installed on the client system).

Configuring REST support involves specifying a listener channel for HTTP conversations, and specifying one or more REST service URL paths in the region. These URL paths can use wildcards to control which transactions can be invoked, and there are various communications and processing options. REST service URLs are configured in the region startup file.

The CICS EXCI (External Call Interface) support in Enterprise Server for .NET uses an HTTP REST service.

Parent topic: Configuring REST Web Services and EXCI
Parent topic: REST Web Services and EXCI
Related concepts
About CICS External Call Interface


About CICS External Call Interface

The CICS External Call Interface, or EXCI, lets a non-CICS program invoke a CICS program, locally or on a remote system. It acts much like the EXEC CICS LINK macro except that it's used from a program which is not running under CICS. The caller can be a standalone application, a program running in a JES region, part of the code for an ASP.NET web page, and so on. The calling program and the CICS program it invokes communicate using a CICS commarea.

There are several ways to make a call using EXCI. Enterprise Server for .NET supports the EXCI DFHXCIS API specified by IBM, with some limitations. DFHXCIS is a procedural API and is useful with migrated applications that used EXCI on the mainframe. It also provides an object-oriented API for a more natural programming style when EXCI is used from OO COBOL programs or programs written in other .NET languages. Finally, procedural COBOL programs can be compiled with the CICSECM(EXCI=YES) compiler directive and use the EXEC CICS LINK macro to make EXCI calls.

EXCI is particularly suited for standalone procedural COBOL programs and for programs running in an Enterprise Server for .NET JES region. For COBOL programs, the EXEC CICS LINK macro is a very convenient way to make calls to CICS programs.

In Enterprise Server for .NET, EXCI is implemented using CICS REST web services. An EXCI client makes a REST request to the EXCI mirror transaction, CPMI, which in turn links to the program specified by the EXCI request.

In Enterprise Server, EXCI is implemented using the IBM CICS Transaction Gateway (CTG) protocol. Enterprise Server for .NET includes client support for CTG, which lets .NET programs (including COBOL for .NET programs running in Enterprise Server for .NET JCL regions, for example) make EXCI requests to native-code Enterprise Server regions. Client programs use the same interfaces (DFHXCIS, the EXCI client class, and EXEC CICS LINK) for both the REST protocol (to invoke programs under Enterprise Server for .NET CICS) and the CTG protocol (for Enterprise Server CICS). The application configuration file determines which protocol is used, and an application can make EXCI requests to both types of regions. See the Enterprise Server documentation for information on configuring a CTG listener.

Parent topic: Configuring REST Web Services and EXCI
Parent topic: REST Web Services and EXCI
Related concepts
About CICS REST Web Services


Configuring REST Web Services

A REST web service configuration consists of a URL path, which can contain wildcards, and optional attributes.

The URL path shows what request URLs the service configuration will apply to. The path can include the wildcard characters "?", which matches any single character in a path element, and "*", which matches zero or more characters in a path element. A path element is one part of the URL path; it ends at the next slash ("/") or other special character, or at the end of the URL. If the URL of an HTTP request matches more than one web service configuration, the best (closest) matching service configuration will be used. For example, if you have service configurations /abc/* and /abc/d*, a request for /abc/xyz will use the former configuration, but one for /abc/def will use the latter. Because wildcards only apply within a path element, neither of those configurations would match /abc/def/g. If an HTTP request doesn't match any of your service configurations, it is rejected with an HTTP 403 (Forbidden) error.

Options you can set for a REST web service configuration include:

  • Minimum size, maximum size, and encoding of the commarea. The minimum size is useful when the server program may generate a response that's longer than the request.
  • Additional HTTP headers for the response. This is particularly useful when invoking CICS REST web services from web pages using Javascript, as explained in the topic Configuring REST Web Services for AJAX.

For more information, see To Configure a REST Web Service.

  • Configuring REST Web Services for AJAX
  • Configuring a REST Web Service for EXCI
  • To Configure a REST Web Service
Parent topic: Configuring REST Web Services and EXCI


Configuring REST Web Services for AJAX

CICS REST web services can be invoked from a web page using Javascript. This is usually known as AJAX (Asynchronous Javascript and XML), though in the case of CICS web services it does not actually involve XML, and the Javascript can invoke the service synchronously or asynchronously. (Usually asynchronous invocation is preferred, so the page does not "hang" if the server doesn't respond quickly.) Some additional configuration is required for a REST web service that will be invoked with AJAX.

See To Configure a REST Web Service for more information.

The Access-Control-Allow-Origin header

When a web page script tries to invoke a service, the Same Origin Policy (SOP) is applied. If the service is hosted by a server other than the one the script was downloaded from, the script is not allowed to process the response unless the response message from the server indicates that it trusts the client. This is a security feature implemented in all of the major browsers, to prevent malicious scripts from performing actions on other servers that the user has access to. The SOP will block scripts from using the results of CICS REST web services, since Enterprise Server for .NET is not the server the script was loaded from.

CICS can tell the browser that the script is allowed to use the results of the service by setting the Access-Control-Allow-Origin HTTP response header. The value of the header can be the origin of the web page making the request, or the wildcard *, which lets any script invoke the service. The origin of a web page is typically the first part of the URL used to fetch it, such as "http://example.com"; it should match the value of the Origin header in the request made by the script. It may be easier to simply set the * value, though this can be a security risk if the service can be accessed by untrusted clients.

Commarea size and encoding

A Javascript client will generally want to exchange data with the CICS transaction program in string form, since Javascript is not suited to defining COBOL group items. That means the server's response may be longer than the client's request. To ensure the commarea is large enough for the server's response, the service configuration should set the optional commarea minimum size attribute, to the size of the largest response the transaction program may generate.

Similarly, it is generally useful to set the commarea response encoding attribute to "text", to indicate that the transaction program's response should always be treated as a text string.

Parent topic: Configuring REST Web Services


Configuring a REST Web Service for EXCI

Enterprise Server for .NET uses a REST web service to implement the EXCI feature, so in order to use EXCI you must add its REST configuration to the region.

EXCI uses REST to invoke the mirror transaction CPMI. It uses a binary commarea which needs to be large enough for the response returned by any transaction you will invoke, plus XXXX bytes of overhead.

The EXCI client class gets the URL for the REST request from its EXCI client configuration, as explained in Configuring EXCI, so you can use the URL path of your choice for the service configuration. Assuming you use /rest/exci, and your largest EXCI response is under 3KB, you might configure a REST service with these parameters:

  • A URL path of /rest/exci/CPMI. (This is an exact path, with no wildcards, because it only applies to the EXCI mirror transaction.)
  • A commarea minimum size of 4096.
  • A commarea response encoding of binary. This is not required but it avoids some unnecessary processing.

See To Configure a REST Web Service for more information.

Parent topic: Configuring REST Web Services


To Configure a REST Web Service

Use this procedure to create or modify a REST web service configuration for an Enterprise Server for .NET CICS region.
  1. Open the region startup file in the editor, and expand the Region item.
  2. Right-click on the Web Services item and choose Add. The Add New REST Path dialog appears.
  3. Enter the path for the REST service or services. The path may include ? and * wildcard characters. For example, /rest/default/AB* would let clients invoke any transaction with a name that starts with AB, using a URL like http://hostname:port/rest/default/AB00.
  4. Optionally, after dismissing the dialog, select the path you added to change its properties. The properties pane for the service is displayed.
  5. Using the properties pane you can:
    • Specify the commarea encoding. Possible encodings are Default, Auto, Text, and Binary. If the commarea contents for the service will always be text or binary, choosing the corresponding option may improve performance. Most services should work correctly regardless of this setting. The Default and Auto settings are the same, and cause Enterprise Server for .NET to determine a usable encoding dynamically for each request.
    • Set a minimum and maximum size for the commarea. The minimum size setting is useful if the server may need to send back a commarea that is larger than the one used in the request. The maximum size setting can be used to prevent a client from requesting an excessively large commarea.
    • Add headers to the HTTP response. To add a header, click the + toolbar button in the lower part of the properties pane, then specify the name and value of the header in the dialog. This is most often used to set an Access-Control-Allow-Origin header for an AJAX service.
To make the web service available, restart the region.

The region must have an HTTP listener channel for clients to invoke the web service.

Parent topic: Configuring REST Web Services


Configuring EXCI

EXCI (CICS External Call Interface) requires configuration for both the server (the CICS region where programs will be invoked using EXCI) and the client (the program that will be invoking the CICS programs). The client can be a standalone .NET application, a program running under a JES region, code for an ASP.NET web site, or any other .NET program. Because the EXCI client uses Micro Focus classes, Enterprise Server for .NET must be installed on the client system.

EXCI configuration for the client

EXCI clients specify the region containing the program they are invoking using a short name called an APPLID, which is usually the same as the region name. The EXCI client class needs to convert the APPLID into an HTTP or CTG URL which it can use to invoke the EXCI web service on the target region. It uses a list of APPLIDs and associated URLs, and optionally a user exit program, which are specified in the program's application configuration (program.exe.config) file, web configuration (web.config) file, or for programs running under JES, the JES region configuration file (Region_name.config).

For a standalone program, put the EXCI configuration in the program's application configuration file. To use EXCI from applications running in an Enterprise Server for .NET JES region, put it in the region configuration file, either by editing the file directly in a text editor or using the Enterprise Server for .NET administration console, and restart the region. For clients running under IIS, such as ASP.NET pages, put the configuration in the web configuration file.

In any of those configuration files, EXCI client configuration takes the form of a MicroFocus.SEE.EXCI section, which contains one or more <applid> elements and optionally a <dfhxcurm> element which configures the EXCI user exit. You must add a section-group element for the section, if one does not already exist, and then the group itself. The applid element specifies a region name and the corresponding URL; the dhfxcurm element specifies the path to the user exit module, which if configured is invoked at various times by the EXCI client and can change the APPLID specified by the application (letting you redirect the EXCI call without changing the application code).

Here is an example EXCI client configuration.

<configuration>
  <configSections>
    <sectionGroup name="MicroFocus.SEE.EXCI">
      <section name="client"
       type="MicroFocus.SEE.Comms.ExciClientSection,MicroFocus.SEE.Comms.EXCI,Version=4.0.0.0,Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
    </sectionGroup>
...
  <MicroFocus.SEE.EXCI>
    <client>
      <!--
        An applid element maps a CICS applid (region name) to the URL
        used to send EXCI requests to it. This example maps the ESDEMO
        applid to the default ES for .NET HTTP channel on the local system.
        There can be any number of applid elements.
      -->
      <applid region="ESDEMO" url="http://localhost:6265/rest/default/CPMI" />

      <!--
        The dfhxcurm element configures the path to a user-supplied
        assembly that implements the DFHXCURM EXCI user exit. This user
        exit can change the applid that the client program specifies in
        its request. Environment variables in the value are expanded
        using the .NET Framework's Environment::ExpandEnvironmentVariables
        method.
      -->
      <dfhxcurm file="%RexBin%/DFHXCURM.dll" />
    </client>
  </MicroFocus.SEE.EXCI>
...
</configuration>
  • Configuring EXCI for the server
  • Configuring EXCI for the client
  • To Add a Client EXCI Configuration
  • To Add a Client EXCI Configuration to a JES Region
  • To Configure an EXCI User Exit
Parent topic: Configuring REST Web Services and EXCI


Configuring EXCI for the server

An Enterprise Server for .NET CICS region that will handle incoming EXCI requests needs the following configuration:

  • A CICS REST web service that will execute the CPMI transaction, with appropriate parameters. See Configuring a REST Web Service for EXCI.
  • The system CPMI transaction configured to invoke the system program dfhzcpmi and installed in the region. A suitable PCT entry is included in the DFHISC group in the sample resource definitions supplied with Enterprise Server for .NET.

To configure a native Enterprise Server CICS region for EXCI, refer to the documentation for that product.

Parent topic: Configuring EXCI


Configuring EXCI for the client

EXCI clients specify the region containing the program they are invoking using a short name called an APPLID, which is usually the same as the region name. The EXCI client class needs to convert the APPLID into an HTTP URL which it can use to invoke the EXCI web service on the target region. It uses a list of APPLIDs and associated URLs, and optionally a user exit program, which are specified in the program's application configuration (program.exe.config) file, web configuration (web.config) file, or for programs running under JES, the JES region configuration file (Region_name.config).

For a standalone program, put the EXCI configuration in the program's application configuration file. To use EXCI from applications running in an Enterprise Server for .NET JES region, put it in the region configuration file, either by editing the file directly in a text editor or using the Enterprise Server for .NET administration console, and restart the region. For clients running under IIS, such as ASP.NET pages, put the configuration in the web configuration file.

In any of those configuration files, EXCI client configuration takes the form of a MicroFocus.SEE.EXCI section, which contains one or more <applid> elements and optionally a <dfhxcurm> element which configures the EXCI user exit. You must add a section-group element for the section, if one does not already exist, and then the group itself. The applid element specifies a region name and the corresponding URL; the dhfxcurm element specifies the path to the user exit module, which if configured is invoked at various times by the EXCI client and can change the APPLID specified by the application (letting you redirect the EXCI call without changing the application code).

Here is an example EXCI client configuration.

<configuration>
  <configSections>
    <sectionGroup name="MicroFocus.SEE.EXCI">
      <section name="client"
       type="MicroFocus.SEE.Comms.ExciClientSection,MicroFocus.SEE.Comms.EXCI,Version=4.0.0.0,Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
    </sectionGroup>
...
  <MicroFocus.SEE.EXCI>
    <client>
      <!--
        An applid element maps a CICS applid (region name) to the URL
        used to send EXCI requests to it. This example maps the ESDEMO
        applid to the default ES for .NET HTTP channel on the local system.
        There can be any number of applid elements.
      -->
      <applid region="ESDEMO" url="http://localhost:6265/rest/default/CPMI" />

      <!--
        This applid refers to a native Enterprise Server region, so it
        specifies a CTG URL.
      -->
      <applid region="NATIVE" url="ctg://localhost:9004" />

      <!--
        The dfhxcurm element configures the path to a user-supplied
        assembly that implements the DFHXCURM EXCI user exit. This user
        exit can change the applid that the client program specifies in
        its request. Environment variables in the value are expanded
        using the .NET Framework's Environment::ExpandEnvironmentVariables
        method.
      -->
      <dfhxcurm file="%RexBin%/DFHXCURM.dll" />
    </client>
  </MicroFocus.SEE.EXCI>
...
</configuration>

For more information, see To Add a Client EXCI Configuration.

Parent topic: Configuring EXCI


To Add a Client EXCI Configuration

Use this procedure to add or modify an EXCI client configuration for a standalone client program, a JES region, or application program code running under IIS. For a JES region, you can also use the Enterprise Server for .NET administration console; see To Add a Client EXCI Configuration to a JES Region.
  1. Open the appropriate configuration file in a text editor. See Configuring EXCI for the client to determine which file to edit. Create the file if it does not exist.
  2. If you have just created the file, add the XML declaration line and <configuration> element, and its <configSections> child element. The file will contain these lines:
    <?xml version ="1.0"?>
<configuration>
  <configSections>
  </configSections>
</configuration>
  3. Add a <sectionGroup> element for the EXCI configuration section, if one does not already exist, as a child of the <configSections> element. Specify client for the name and MicroFocus.SEE.Comms.ExciClientSection,MicroFocus.SEE.Comms.EXCI,Version=4.0.0.0,Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0 for the type. The configSections section of the file will contain the entry
    <section name="client"
type="MicroFocus.SEE.Comms.ExciClientSection,MicroFocus.SEE.Comms.EXCI,
Version=4.0.0.0,Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
  4. Add a <MicroFocus.SEE.EXCI> element to the file as a child of the <configuration> element, and its child element <client>, if they do not already exist. The file will include these lines:
      <MicroFocus.SEE.EXCI>
    <client>
    </client>
  </MicroFocus.SEE.EXCI>
  5. Add the <applid> element for your new configuration as a child of the <client> element. The region attribute specifies the APPLID string your application will use in its EXCI request (often this is the target region name, but it can be any string up to 8 characters), and the value of the url attribute is the URL for the CPMI REST service in your CICS region (for an Enterprise Server for .NET region), or the URL for the region's CTG listener (for an Enterprise Server region). An EXCI configuration might look like this:
    <applid region="ESDEMO" url="http://localhost:6265/rest/exci/CPMI" />
  6. Save the file.
Restart the application, JES region, or IIS pool to enable the new configuration.
Parent topic: Configuring EXCI


To Add a Client EXCI Configuration to a JES Region

You can use this procedure to add or modify an EXCI client configuration for programs running in a JES region. You can also do this by editing the region file; see To Add a Client EXCI Configuration.
  1. Open the region startup file in the editor, and expand the Region item.
  2. Expand the EXCI item.
  3. Right-click on the Applids item and choose Add. (You can also use Edit > Add.) The Add New Applid dialog appears.
  4. Enter a name (1-8 characters) for the applid; this is often the name of the region to connect to, but does not need to be.
  5. Enter the URL for the region:
    • If the target region is Enterprise Server for .NET, specify the HTTP URL for the EXCI REST service. This will be something like http://localhost:6265/rest/default/CPMI.
    • If the target is a native Enterprise Server region, specify a CTG URL with the hostname and port of the region's CTG listener, for example ctg://localhost:9004.
After updating the region configuration, restart the region for the changes to take effect.
Parent topic: Configuring EXCI
Parent topic: JES Region Configuration


To Configure an EXCI User Exit

The configuration file you are editing should already have at least one EXCI client configuration. (The EXCI user exit cannot do anything useful unless there is at least one APPLID it can return.) See Configuring EXCI for the client.
Use this procedure to enable an EXCI user exit module. An EXCI user exit is a routine supplied by the customer which can change the APPLID (EXCI destination) specified by the application. This lets you redirect EXCI clients to a different region without changing the application source. (You can also change what region an EXCI client connects to by changing the target URL of the APPLID in the client configuration.)
  1. Open the configuration file for editing.
  2. Add a <dfhxcurm> element as a child of the <client> element. (Modify the <dfhxcurm> element if it already exists. Only one <dfhxcurm> element is permitted per configuration file.) Set the file attribute to the path to the DLL that implements your DFHXCURM routine. (The DLL file may have any name, but it must have an entry point named DFHXCURM.) The value can include environment variables in the form %name%, which will be expanded using the .NET Framework's Environment::ExpandEnvironmentVariables method. Here is a sample <dfhxcurm> element:
    <dfhxcurm file="%MyApp%/userexit.dll" />
  3. Save the file.
Restart the application, JES region, or IIS pool to enable the new configuration.
Parent topic: Configuring EXCI


Migrating a native Enterprise Server Resource Definitions File

You can migrate a native Enterprise Server resource definitions file, then use it with regions in the Enterprise Server for .NET environment. Resources are the only item you can migrate from the native Enterprise Server environment.

  • To Migrate a native Enterprise Server Resource Definitions File
Parent topic: CICS Region Configuration


To Migrate a native Enterprise Server Resource Definitions File

You can use existing native Enterprise Server resource definitions with Enterprise Server for .NET. Studio Enterprise Edition contains a utility to migrate a resource definitions file for use with Enterprise Server for .NET.
  1. Open a command prompt in Studio Enterprise Edition.
  2. Use the casrdtex utility to export the existing resource definitions file into an intermediate XML format.

    By default the casrdtex utility exports the resource definitions in IBM assembler macro format using the default dfhurdex exit. However, by overriding the default exit with the dfhurdexxml exit (with the /ue command line option), the resource definitions are exported in an XML format. You use this in the second step of the migration process.

    For example, the following command converts the native Enterprise Server resource definition dfhurdexxml to the esdefs.xml file.
    casrdtex /v /ue:dfhurdexxml /ip.\ /oc:\mydir\esdefs.xml
/i /g /x /e /l /s /f /d /z /t /y /m
    Cut and paste the following version to an editor, then edit to suit your requirements:
    casrdtex /v /ue:dfhurdexxml /ip.\ /oc:\mydir\esdefs.xml /i /g /x /e /l /s /f /d /z /t /y /m
  3. Open a command prompt in Enterprise Developer.
  4. Use the seerdfconv utility to convert the XML file you created.

    For example, to convert the intermediate XML file from the previous step's example, use the following command.

    seerdfconv.exe -in:c:\mydir\esdefs.xml -out:ResourceDefinitions.config

    The resulting file, ResourceDefinitions.config, can be used as anEnterprise Server for .NET resource definitions file.

You can copy the resource definitions file to a location that is visible from the Enterprise Server for .NET Resource Editor to modify it. You can use it with Enterprise Server for .NET regions that you define. See information on the casrdtex Studio Enterprise Edition utility included in this help set for details.
Parent topic: Migrating a native Enterprise Server Resource Definitions File
Related reference
casrdtex
seerdfconv: migrate an Enterprise Server resource definition file


CICS Command Line Utilities

  • casrdtex
    Exports CICS resources to a Resource Definition Table (.rdt) file.
  • seerdfconv: migrate an Enterprise Server resource definition file
    Converts a native Enterprise Server configuration file into a format suitable for Enterprise Server for .NET.
Parent topic: CICS Administration
Related concepts
General Command Line Utilities
Related information
JES Command Line Utilities


casrdtex

Exports CICS resources to a Resource Definition Table (.rdt) file.

Syntax:

casrdtex /ofile-name [/a] [/e] [/ipresource-file-path] [/uuserid] [/ppassword] [/q] [/v]
 [/s[sit1[,sit2]...]] [/l[list1[list2]...]]
 [/n[snt1[,snt2]...]] [/g[grp1[,grp2]...]]
 [/m] [/x] [/f] [/t] [/y] [/d] [/j] [/i] [/z] [/c] [/b] [/ue:{exit-name}] [/ur] [/tc] [/ws] [/pl] [/dt] [/tl]

Parameters:

/ofile-name | The RDT file to export to. This parameter is mandatory.
/a | Append to an existing file
/e | Include non-IBM-compatible entries (Micro Focus extensions to the format, which all begin with an underscore)
/ipresource-file-path | The directory containing the CICS resource definition file, dfhdrdat, from which to export. This defaults to %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas .
/uuserid | User ID
/ppassword | Password
/q | Run in quiet mode
/v | Run in verbose mode
/s[sit1[,sit2]...] | Include the specified SITs in the export. If you specify just the switch, all are exported.
/l[list1[list2]...] | Include the specified startup lists (GRPLIST) in the export. If you specify just the switch, all are exported.
/n[snt1[,snt2]...] | Include the specified sign-on entries in the export. If you specify just the switch, all are exported.
/g[grp1[,grp2]...] | Include the specified groups in the export. If you specify just the switch, all are exported.

The remaining parameters select which table entries for the selected group(s) are to be included:

/m | Processing program table (PPT)
/x | Program control table (PCT)
/f | File control table (FCT)
/t | Terminal (TRM)
/y | Terminal type (TTY)
/d | TD queue (TDQ)
/i | Program list (PLT)
/j | Journal (JCT)
/z | Temporary storage (TST)
/c | Connection
/b | X/Open DB compatibility
/ue:{exit-name} | Name of user exit
/ur | URI map
/tc | TCPIP service
/ws | Web service
/pl | Pipeline
/dt | Doctemplate
/tl | Transaction class

Dependencies:

Run casrdtex from an Enterprise Developer command prompt to ensure that all of the necessary paths are available.

Comments:

If a path or filename contains spaces, it should be enclosed in quotation marks. For example, "e:\dev mto\files".

Example:

casrdtex /oresfile.rdt /ggroup1,group3 /m /x /ip"e:\dev mto\files"

The above command exports the PPT and PCT entries for the groups group1 and group3, from the dfhdrdat file in "e:\dev mto\files", to the file resfile.rdt.

casrdtex /oresfile.rdt /s /g /f /ip"e:\devmto\files"

The above command exports all SITs, and the FCT entries for all groups, to the file resfile.rdt.

Parent topic: CICS Command Line Utilities


seerdfconv: migrate an Enterprise Server resource definition file

Converts a native Enterprise Server configuration file into a format suitable for Enterprise Server for .NET.

Syntax

seerdfconv parameter parameter . .

Parameters

-in: input filename
The input filename created using the casrdtex utility.
-out: output filename
The converted file that the command creates.

Examples

seerdfconv.exe -in:c:\mydir\esdefs.xml -out:ResourceDefinitions.config

In this example, the esdefs.xml configuration file generates the Enterprise Server for .NET ResourceDefinitions.config file.

Parent topic: CICS Command Line Utilities


JES Administration

  • JES Region Configuration
    The topics in this section describe how to configure JES regions.
  • Running JCL Jobs
  • JES Command Line Utilities
  • Using REXX
    This topic describes how to configure and run REXX EXECs under JCL
Parent topic: Administrator Role


JES Region Configuration

  • To Create a JES Region Startup File
    A region startup file is required to be able to start a region. This topic describes how to create a JES region startup file.
  • To Edit a Region Startup File Associated with a JES Region
    This topic describes how to edit a region startup file that already exists for a JES region.
  • To Configure a JES Region's Catalog Location
    A catalog and default data allocation folder need to be defined in a JES region's startup file before the region can be successfully started.
  • To Configure a JES Region's Program Location and Search Order
    The JES system need to know where to locate user programs at run-time and in what order these locations are to be searched. This topic describes how this information is defined in a JES region startup file.
  • To Configure Initiators in a JES Region Startup File
    One or more initiators need to be defined for a JES region before jobs submitted to it can be run. This topic describes how to configure initiators in a region startup file before the region is started.
  • To Configure Initiators in a Running JES Region
    One or more initiators need to be defined for a JES region before jobs submitted to it can be run. This topic describes how to configure initiators in a region that is already running.
  • To Configure Printers in a JES Region Startup File
    One or more Printers need to be defined for a JES region before jobs submitted to it can utilize a printer. This topic describes how to configure printers in a region startup file before the region is started.
  • To Configure Printers in a Running JES Region
    One or more printers need to be defined for a JES region before jobs submitted to it can print to a printer. This topic describes how to configure printers in a region that is already running.
  • To Configure VSE Job Execution
    The region startup file can specify VSE configuration values that are available to any job run on the system until shut down.
  • To Add a Client EXCI Configuration to a JES Region
Parent topic: JES Administration


To Create a JES Region Startup File

Enterprise Server for .NET Administration UI's Region Startup File Editor is used to create JES region startup files. Region startup files residing in either the local/network file system or a cross-region database can be created and modified using this editor.
  1. In the Tree pane under Configuration Editors, click on Region Startup. See 1 in the diagram below.
  2. Choose File > New , or click the Create new file icon in the toolbar. See 2 in the diagram below.

    The Create Region Startup File dialog is displayed.

  3. Select the JES region type on the dialog. See 3 in the diagram below.
  4. Enter the name of the region that the startup file will be used with in the Region name entry field and click on OK. See 4 in the diagram below.

    The dialog is dismissed and a new JES region startup file is opened in the editor. However, this file has not yet been persisted to disk or to a cross-region database as indicated by the [New File] tab. See 5 in the diagram below.

  5. To save the file to disk, choose File > Save To > File ... . See 6 in the diagram below.

    A standard file dialog is now displayed to allow you to specify the location on disk where the startup file is to be saved.

  6. To save the file to a cross-region database, choose File > Save To > Cross-region Database ... . See 7 in the diagram below.

    A Save To dialog is now displayed. In the Server instance entry field, enter the name of the database server instance of the cross-region database where the file is to be saved. If you want to view the region startup files already deployed to the cross-region database, click on Browse. See 8 in the diagram below. If you want to overwrite one of the displayed files, select it from the list and click OK. Otherwise click Cancel to dismiss the dialog and enter the new name for the region startup file you want saved in the Region startup file name entry field.

    Click on Save to save the file to the cross-region database. See 9 in the diagram below.

    The dialog is dismissed and the name of the JES region startup file that has been saved replaces [New File] in the file tab. See 10 in the diagram below.

The created region startup file can now be associated with any JES region.

Parent topic: JES Region Configuration
Related concepts
About Region Startup and Resource Definitions
Related tasks
To Configure VSE Job Execution
To Edit a Region Startup File Associated with a JES Region
To Create a CICS Region Startup File
Related information
VSE JCL Configuration Files


To Edit a Region Startup File Associated with a JES Region

The Enterprise Server for .NET Administration UI's Region Startup File Editor is used to edit JES region startup files. Region startup files residing in either the local/network file system or the cross-region database can be modified using this editor.
  1. In the Tree pane under Regions, select the JES region to edit. See 1 in the diagram below.
  2. In the Actions pane, select Edit Region Startup File. See 2 in the diagram below.

    The JES region startup file appears in the editor in the Results pane.

  3. Make any required changes using the editor. For example, region properties such as Allow Dynamic Debugging can be modified by changing the associated value in the properties window.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See 3 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: JES Region Configuration
Related concepts
About Region Startup and Resource Definitions
Related tasks
To Configure VSE Job Execution
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a CICS Region
Related information
VSE JCL Configuration Files


To Configure a JES Region's Catalog Location

This procedure demonstrates how to define the catalog and default data allocation folder locations using the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the JES region you are configuring with the Region Startup File editor. See To Edit a JES Regions Configuration.
  2. In the Results pane expand the Region node and select the Catalog node. See 1 in the diagram below. The properties window for the region's catalog and default data allocation folder is displayed.
  3. Enter the default data allocation location in the value field associated with the Data File Location property. See 2 in the diagram below. This location should either be on a network filesystem or in a database to ensure that the location is available to any scaled-out machine in the system. When a database location is specified it should be of the form:
    sql://<db server instance name>/<datastore name>?folder=/<folder name>
    Where <db server instance name> may be of the form <machine name>, <machine name>/<instance name> or (dbinst). When (dbinst) is specified, the database server instance on which the region database resides is used. For example:
    sql://(dbinst)/JES?folder=/JCLDEMO
    specifies that the default data allocation folder for this region is the /JCLDEMO folder in the JES datastore (database) residing on the same database server instance as the region's database.
  4. Enter the name of the catalog to be used by the region and its location in the value field associated with the System Catalog Location property. See 3 in the diagram below. This location should either be on a network filesystem or in a database to ensure that the location is available to any scaled-out machine in the system. When a database location is specified it should be of the form:
    sql://<db server instance name>/<datastore name>/<catalog name>?folder=/<folder name>
    Where <db server instance name> may be of the form <machine name>, <machine name>/<instance name> or (dbinst). When (dbinst) is specified, the database server instance on which the region database resides is used. For example:
    sql://(dbinst)/JES/catalog.dat?folder=/JCLDEMO
    specifies that the catalog for this region is catalog.dat in the /JCLDEMO folder in the JES datastore (database) residing on the same database server instance as the region's database.
  5. Choose File > Save, or click the Save icon in the toolbar to save the file. See 4 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: JES Region Configuration
Related tasks
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region


To Configure a JES Region's Program Location and Search Order

User programs invoked by a JES region may reside in a file system folder, the region database, the cross-region database or custom database. This procedure demonstrates how to define each of these location types and how their run-time search order is specified using the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the JES region you are configuring with the Region Startup File editor. See To Edit a JES Regions Configuration.
  2. In the Results pane expand the Region node and select the Application Program Paths node. See 1 in the diagram below. Any existing configured paths are listed in the displayed window.
  3. To add a file system program folder location, right-click on the Application Program Paths node and choose Add > Folder Location... from the context menu. See 2 in the diagram below.

    The Add Program Path dialog is displayed.

    Enter the name of the folder containing the user programs to be used by the region in the Folder entry field. Alternatively, use the Browse button to select a folder from a standard file dialog. Note that the folder specified should be on a network drive to ensure that it is available to any machine in a scaled-out system. Click on OK. See 3 in the diagram below.

    The dialog is dismissed and the folder specified appears in the program folder list.

  4. To add the region database as a program location, right-click on the Application Program Paths node and choose Add > Region Database Location... from the context menu. See 4 in the diagram below.

    The region database appears in the program folders list. Note that the region database can only be added once to the program folders list, so will not be available as a location for a subsequent Add operation.

  5. To add the cross-region database as a program location, right-click on the Application Program Paths node and choose Add > Cross-region Database Location... from the context menu. See 5 in the diagram below.

    The cross-region database appears in the program folders list. Note that the cross-region database can only be added once to the program folders list, so will not be available as a location for a subsequent Add operation.

  6. To add a custom database (i.e. a user specified database) as a program location, right-click on the Application Program Paths node and choose Add > Custom Database Location... from the context menu. See 6 in the diagram below.

    The Add Program Database Location dialog is displayed.

    Enter the name of the machine hosting the database in the Server entry field, the name of the database server instance in the Instance entry field, the name of the database in the Database entry field and the name of the table where the programs will reside in the Table entry field. Click on OK. See 7 in the diagram below.

    The dialog is dismissed and the custom database location specified appears in the program folder list.

  7. The order in which the program locations are listed indicates the order in which they will be searched at run-time (i.e. the location at the top of the list will be searched first, the second in the list searched second and so on). To change the search order, select a location in the list, see 8 in the diagram below, and drag and drop it to the required position in the list. See 9 in the diagram below.

    The selected item in the previous diagram is moved to the top of the list and will now be the first location to be searched at run-time. See 10 in the diagram below.

  8. Choose File > Save, or click the Save icon in the toolbar to save the file. See 11 in the diagram below.

You must cold-start the region for the changes to take effect.
Parent topic: JES Region Configuration
Related tasks
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region


To Configure Initiators in a JES Region Startup File

Initiators may be defined in the region startup file to ensure that they are immediately available once the region has been started. If initiators are not defined in the region startup file they can be defined once the region has been started using the Enterprise Server for .NET Administration UI's Initiators view or from the command-line using the casout utility. This procedure demonstrates how to define initiators in a JES region startup file using the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the JES region you are configuring with the Region Startup File editor. See To Edit a JES Regions Configuration.
  2. In the Results pane expand the Region node and select the Initiators node. See 1 in the diagram below. A window is displayed showing the initiators already configured for the region.

  3. The properties of an existing initiator can be modified by expanding the Initiators node, selecting the initiator to be modified and changing the properties in the displayed Properties window. See 2 in the diagram below.

  4. To define a new initiator, right-click on the Initiators node and select Add... from the context menu. See 3 in the diagram below.

    The Add New JES Initiator dialog is displayed.

  5. Enter the name of the new initiator in the Initiator name entry field and click OK. See 4 in the diagram below.

    The new initiator now appears under the Initiators node. See 5 in the diagram below.

  6. To modify the properties of the initiator just created, select it and change the properties in the displayed Properties window.
  7. Once all changes have been made, choose File > Save, or click the Save icon in the toolbar to save the file. See 6 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: JES Region Configuration
Related tasks
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region
To Configure Initiators in a Running JES Region
Related reference
casout: administer a batch job or JES region


To Configure Initiators in a Running JES Region

Initiators can be defined or modified once the region has been started, using the Enterprise Server for .NET Administration UI's Initiators view, or from the command-line using the casout utility. Normally initiators would be defined in the region startup file to ensure that they are immediately available to run jobs once the region starts. However, there may be a need to modify the properties of existing initiators or start new ones after a region has been started, due to a change in workload, for example. This procedure demonstrates how to define initiators in a running JES region from the Enterprise Server for .NET Administration UI's Initiators view:
  1. Select the running JES region from the Tree pane under Regions > JES, and click on Initiators in the Actions pane. See 1 in the diagram below. The Initiators view is displayed in the Results pane, showing each of the initiators currently configured.
  2. An initiator may be enabled or disabled by selecting it in the list and clicking on the Enabled check box. See 2 in the diagram below. If the initiator being disabled is currently running a job, the job is allowed to complete, but no further jobs will be scheduled for execution on it until it is enabled again.
  3. To create a new initiator, click the Add Initiator icon in the toolbar. See 3 in the diagram below.

    The Add JES Initiator dialog is displayed.

  4. Enter the name of the new initiator in the Initiator name entry field, the job classes (A-Z, 0-9) to be run by this initiator in the Classes entry field, and click on the Enabled check-box to indicate whether or not the initiator is to be created enabled or disabled. An optional description of the initiator may also be entered in the Description text box. Click on OK to create the initiator. See 4 in the diagram below.

    The newly created initiator now appears in the list of initiators in the Results pane. See 5 in the diagram below.

Note that any changes made in this view will be lost at the next cold-start of the region unless the corresponding changes are made to the initiator configuration in the region startup file. However, changes made in this view will be retained across subsequent warm-starts of the region.

Parent topic: JES Region Configuration
Related tasks
To Edit a Region Startup File Associated with a JES Region
To Configure Initiators in a JES Region Startup File
Related reference
casout: administer a batch job or JES region


To Configure Printers in a JES Region Startup File

Printers may be defined in the region startup file to ensure that they are immediately available once the region has been started. If printers are not defined in the region startup file, they can be defined once the region has been started, using the Enterprise Server for .NET Administration UI's Printers view, or from the command-line using the casout or seeout utility. This procedure demonstrates how to define printers in a JES region startup file, using the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the JES region you are configuring, with the Region Startup File editor. See To Edit a JES Regions Configuration.
  2. In the Results pane, expand the Region node and select the Printers node. See 1 in the diagram below. A window is displayed showing the printer already configured for the region.

  3. The properties of an existing printer can be modified by expanding the Printers node, selecting the printer to be modified, and changing the properties in the displayed Properties window. See 2 in the diagram below.

  4. To define a new printer, right-click on the Printers node and select Add... from the context menu. See 3 in the diagram below.

    The Add New JES Printer dialog is displayed.

  5. Enter the name of the new printer in the Printer name entry field , or click Browse (...) to browse to an installed printer ,and click OK. See 4 in the diagram below.

    The new printer now appears under the Printers node. See 5 in the diagram below.

  6. To modify the properties of the printer just created, select it and change the properties in the displayed Properties window.
  7. Once all changes have been made, choose File > Save, or click the Save icon in the toolbar to save the file. See 6 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: JES Region Configuration
Related tasks
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region
To Configure Printers in a JES Region Startup File
Related reference
casout: administer a batch job or JES region


To Configure Printers in a Running JES Region

Printers can be defined or modified once the region has been started, using the Enterprise Server for .NET Administration UI's Printers view, or from the command-line using the casout or seeout utility. Normally, printers would be defined in the region startup file to ensure that they are immediately available to run jobs once the region starts. However, there may be a need to modify the properties of existing printers, or start new ones after a region has been started, due to a change in workload, for example. This procedure demonstrates how to define printers in a running JES region, from the Enterprise Server for .NET Administration UI's Printers view:
  1. Select the running JES region from the Tree pane under Regions > JES, and click on Printers in the Actions pane. See 1 in the diagram below. The Printers view is displayed in the Results pane, showing each of the printers currently configured.
  2. A printer may be enabled or disabled by selecting it in the list and clicking on the Enabled check box. See 2 in the diagram below. If the printer being disabled is currently being spooled to, the print operation is allowed to complete, but no further spooling to it will be allowed until it is enabled again.
  3. To create a new printer, click the Add Printer icon in the toolbar. See 3 in the diagram below.

    The Add JES Printer dialog is displayed.

  4. Enter the name of the new printer in the Printer name entry field, the job classes (A-Z, 0-9) to be run by this printer in the Classes entry field, and click the Enabled check-box to indicate whether or not the printer is to be created enabled or disabled. An optional description of the printer may also be entered in the Description text box. An Optional User program can be entered in the User exit: text box. This program will be run each time a job spools to this printer. Click OK to create the printer. See 4 in the diagram below.

    The newly created printer now appears in the list of printers in the Results pane. See 5 in the diagram below.

Note that any changes made in this view will be lost at the next cold-start of the region unless the corresponding changes are made to the printer configuration in the region startup file. However, changes made in this view will be retained across subsequent warm-starts of the region.

Parent topic: JES Region Configuration
Related tasks
To Edit a Region Startup File Associated with a JES Region
To Configure Printers in a JES Region Startup File
Related reference
casout: administer a batch job or JES region


To Configure VSE Job Execution

This procedure demonstrates how to define VSE configuration using the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the JES region you are configuring, with the Region Startup File editor. See To Edit a Region Startup File Associated with a JES Region.
  2. In the Results pane, expand the Region node and select the VSE node. See 1 in the diagram below. The VSE configuration window is displayed.
  3. Enter VSE configuration values in the text box labelled Configuration statements. See 2 in the diagram below.
  4. Choose File > Save, or click the Save icon in the toolbar to save the file. See 3 in the diagram below.

You must cold-start the region for the changes to take effect.

Parent topic: JES Region Configuration
Related tasks
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region
Related information
VSE JCL Configuration Files


Running JCL Jobs

From the Enterprise Server for .NET user interface, you can configure and run native Enterprise Server JCL jobs. The topics in this section describe this functionality.

  • Submitting JCL from the command line
  • Submitting JCL from the Enterprise Server for .NET Administration UI
Parent topic: JES Administration


Submitting JCL from the command line

Jobs are submitted to a JES region from the command line using the cassub utility.

Parent topic: Running JCL Jobs
Related reference
cassub: submit JCL to a JES region


Submitting JCL from the Enterprise Server for .NET Administration UI

JCL can be submitted to any started JES region that has been defined to the Enterprise Server for .NET Administration UI.

Before JCL can be submitted to a JES region, the name of the machine running the communications listener process and the MFBINP port associated with the region in that process need to be configured in the region start-up file prior to the region being started. To do this:
  1. Open the Enterprise Server for .NET Administration UI.
  2. If the JES region to which you want to submit jobs does not exist in the tree-pane, you must first define the region to the UI. See To Define a New Region.
  3. Select the JES region in the tree-pane and click the Edit Region Start-up File action in the actions-pane. See 1 in the diagram below.
  4. Select the Region node in the results-pane to display the Properties window.
  5. Set the Host property in the JES category to the name of the machine running the communications listener process to which JCL will be submitted. See 2 in the diagram below.
  6. Set the Port property in the JES category to the MFBINP port number associated with the region in the communications listener process. See 3 in the diagram below.
  7. Save the changes to the region start-up file.

To submit JCL to a JES region:
  1. Start the region, if it is not already started, by selecting the region in the tree-pane and clicking the Start/Stop Region action in the actions-pane. See Starting a Region.
  2. Click Submit JCL in the actions-pane to display the Submit JCL view in the results-pane.
  3. Select the type of JCL to be submitted: JES2, JES3 or VSE. See 1 in the diagram below.
  4. Specify the name of the JCL file to be submitted to the region in the Submit JCL to ES entry field.
  5. Click Submit to submit the JCL to the JES region. See 2 in the diagram below. Messages will be displayed in the ES Messages area of the view indicating the progress and success or failure of the operation.
Parent topic: Running JCL Jobs
Related concepts
Setting Up the User Interface
Starting a Region
Related tasks
To Define a New Region With an Existing Region Startup File


JES Command Line Utilities

Command line utilities used specifically for administering JES regions

  • casout: administer a batch job or JES region
  • seeout: administer an Enterprise Server for .NET JES region
  • cassub: submit JCL to a JES region
Parent topic: JES Administration
Related concepts
General Command Line Utilities
Related information
CICS Command Line Utilities


casout: administer a batch job or JES region

Syntax

casout parameter parameter . .

This command can be used to administer a batch job in either a native Enterprise Server or Enterprise Server for .NET JES region. However, only a sub-set of the command line parameters supported by native Enterprise Server is supported when used to administer jobs in an Enterprise Server for .NET JES region. The parameters supported by Enterprise Server for .NET are detailed below.

Parameters

-shost:port
URL of the JES region to connect to, where host is the name of the machine running the communications listener process and port is the MFBINP port associated with the region. This parameter must be specified. For example:
-slocalhost:9022
-doutput-dsn
Output DSN for sysout retrieval. The -d option must precede the -gnumber:reldd option
-fnumber
Flush the output of job number number
-gnumber
Displays all sysouts for job number number
-gnumber:reldd
Retrieve the relative DD for job number number
-iclasses
Start an initiator to run jobs of the named classes
-jnumber:step:procstep
Restart job number number at the given step/procstep. :procstep is optional
-knumber
Kill job number number
-mnumber:class
Modify job number to use class class
-mnumber:@
Release job number
-v
View initiators and printers
-nprinter-name
Specifies that printer-name is the name of the physical device to be used by a new batch printer. This option is used with the -b and-x options.
-boutput-classes
Specifies that output-classes will be handled the new batch printer. This option is used with the -n and -x options
-xprinter-exit
Specifies that printer-exit will be associated with the new batch printer. This option is used with the -n and -x options

Examples

  1. List the status of job number 1001 and all of its sysouts. Each sysout listed has an associated sequence number that can be used with the -gnumber:reldd command line parameter. The job log is always assigned sequence number 1
    casout.exe -slocalhost:9022 -g1001
  2. Download the contents of the sysout with sequence number 3 for job number 1001 into the file c:\mydir\myfile.dat
    casout.exe -slocalhost:9022 -dc:\mydir\myfile.dat -g1001:2
  3. Flush all of the output for job number 1001
    casout.exe -slocalhost:9022 -f1001
  4. Start an initiator for job classes E, J and 8
    casout.exe -slocalhost:9022 -iEJ8
  5. Restart job number 1010 at step STEP05
    casout.exe -slocalhost:9022 -j1010:STEP05
  6. Kill job number 1009
    casout.exe -slocalhost:9022 -k1009
  7. Modify job number 1009 to use class A
    casout.exe -slocalhost:9022 -m1009:A
  8. Release job number 1009
    casout.exe -slocalhost:9022 -m1009:@
  9. List printers and initiators
    casout.exe -slocalhost:9022 -v
  10. Create a new printer for device "DomainLaser1" to handle classes "ABC" and use a printer exit program called "LASEREX"
    casout.exe -slocalhost:9022 -nDomainLaser1 -bABC -xLASEREX
Parent topic: JES Command Line Utilities


seeout: administer an Enterprise Server for .NET JES region

Syntax

seeout
                 -job:<jobno> action options
                 -initiator action options
                 -initiator:<id> action options
                 -printer action options
                 -printer:<id> action options

This command can be used to administer jobs, printers and initiators in an Enterprise Server for .NET JES region.

It is similar in function to the native casout tool, but is specific to Enterprise Server for .NET, contains enhanced functionality specific to Enterprise Server for .NET, and cannot be used against a native region.

Actions

-create
Create an initiator or printer.
Used with the -initiator and - printer commands.
-disable
Disable an initiator or printer.
Used with the -initiator and -printer commands.
-enable
Enable an initiator or printer.
Used with the -initiator and -printer commands.
-flush
Flush a job.
Used with the -job command.
-kill
Kill a job.
Used with the -job command.
-list
List DD's, initiators, printers.
Used with the -job, -initiator and -printer commands.
-modify
Modify a job's class.
Used with the -job command.
-release
Release a job.
Used with the -job command.
-restart
Restart a job.
Used with the -job command.

Options

-class:<classes>
Job or sysout classes.
Used together with the -create and -modify actions.
-dd:<DD id>
List the DDs for a job using the -list action.
-name:<printer-name>
Printer name for the -create action.
-exit:<exit name>
Printer exit name to associate with the new printer.
-out:<output-file>
Output file name.
-server:<machine>[:port>]
Define the machine name and port address of JES region listener.

Default : -server:localhost:9022

-step:<step-name>[:<proc-step>]
Define the step name and optional proc-step used for -restart.

Examples

  1. Kill a job with job number 1000
    seeout -job:1000 -kill
  2. Restart job 1000 from step step01
    seeout -job:1000 -restart -step:step01
  3. Restart job 1000 from proc proc01 proc-step pstep01
    seeout -job:1000 -restart -step:proc01:pstep01
  4. Modify job 1000's class to class x for JES region operating on machine dom-001 port 9122
    seeout -job:1000 -modify -class:x -server:dom-001:9122
  5. Create a new printer for a device called LaserPrinter to service classes x y and z to use a printer exit called MODPRINT
    seeout -printer -create -class:xyz -name:LaserPrinter -exit:MODPRINT
  6. List the available printers in the JES region hosted on machine dom-001 port 9122
    seeout -printer -list -server:dom-001:9122
  7. Disable the printer with id of 3 as listed in -printer -list
    seeout -printer:3 -disable
  8. Create a new initiator to service classes a ,b and c
    seeout -initiator -create -class:abc
  9. Enable initiator with id of 3 as listed by -initiator -list
    seeout -initiator:3 -enable
Parent topic: JES Command Line Utilities


cassub: submit JCL to a JES region

Syntax

cassub parameter parameter . .

This command can be used to submit JCL to either a native Enterprise Server or Enterprise Server for .NET JES region. However, only a sub-set of the command line parameters supported by native Enterprise Server are supported when used for job submission to an Enterprise Server for .NET JES region. The parameters supported by Enterprise Server for .NET are detailed below.

Parameters

-shost:port
URL of the JES region to connect to, where host is the name of the machine running the communications listener process and port is the MFBINP port associated with the region. This parameter must be specified. For example:
-slocalhost:9022
-jjobfile-name-by-content
Name of the file containing the JCL to be submitted. The contents of the file are sent to the JES region
-vversion
The version of the job control system to use, where version is one of the following values:
1
VSE/Power
2
JES2 (default)
3
JES3
-xjobfile-name-by-reference
Name of the file containing the JCL to be submitted. The file name is sent to the JES region.

N.B. this option should be used with care when the region is scaled-out across multiple machines as the file location may not be available to all machines

Examples

  1. Submit a JES2 job by content
    cassub.exe -slocalhost:9022 -jc:\mydir\myfile.jcl
  2. Submit a JES2 job by reference
    casout.exe -slocalhost:9022 -xc:\mydir\myfile.jcl
  3. Submit a VSE job by content
    cassub.exe -slocalhost:9022 -jc:\mydir\myvsefile.jcl -v1
Parent topic: JES Command Line Utilities


Using REXX

  • Introduction
  • Configuring the REXX Execution Environment
  • Running REXX Under IKJEFT01
  • Running REXX Under IRXJCL
  • Restrictions
Parent topic: JES Administration


Introduction

Enterprise Server for .NET provides an emulation of IBM's TSO/E REXX language. See the z/OS TSO/E REXX Reference and z/OS TSO/E REXX User's Guide for more details about the language.

REXX EXECs can be run under JCL using either the IKJEFT01 or IRXJCL utilities.

CLISTs are not supported under Enterprise Server for .NET, so we recommend that you convert any CLISTs you have to REXX EXECs.

Parent topic: Using REXX
Related information
Configuring the REXX Execution Environment
Running REXX Under IKJEFT01
Running REXX Under IRXJCL
Restrictions


Configuring the REXX Execution Environment

The REXX execution environment for an Enterprise Server for .NET JES region is configured within the region startup file. To modify the REXX configuration in the Enterprise Server for .NET Administration UI:
  1. Open the startup file of the JES region you are configuring, with the Region Startup File editor. See To Edit a JES Regions Configuration.

  2. In the Results pane, select the Region node and scroll the Properties Window until the REXX category is displayed. Change the values of the properties within the REXX category to those required for the execution of EXECs within the region. See 1 in the diagram below.

  3. Choose File > Save, or click the Save icon in the toolbar to save the file. See 2 in the diagram below.

Parent topic: Using REXX
Related tasks
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region


Running REXX Under IKJEFT01

IKJEFT01 is the mainframe utility program that allows TSO commands to be run under JCL. When a REXX EXEC is run under IKJEFT01, the default host command environment is set to "TSO" by the REXX run-time system. This means that any external commands that are specified in the EXEC will be passed to the TSO command processor for execution. For example:

/* REXX */
"lista"
exit 0
would cause the "lista" command to be executed by the TSO command processor and would result in the display of each of the DD names allocated to the current job step being displayed.
When running under IKJEFT01, the EXEC may use the ADDRESS instruction to specify alternative host command environments to be used for the execution of external commands. However, Enterprise Server for .NET supports only the "TSO" and "MVS" host command environments. Attempting to use any other host command environment, normally supported on the mainframe, will result in a return code of -3 being set, indicating that the command cannot be found. For example:
/* REXX */
"lista"                         /* Will be executed by the TSO host command environment as "TSO" is the default */
address mvs                     /* Switches the current host command environment to "MVS" */
"execio * diskr datain (finis"  /* Will be executed by the MVS host command environment */
address ispexec                 /* Switches the current host command environment to "ISPEXEC" */
"select service"                /* Will result in the command completing with return code -3 */
exit 0
Example JCL used to run REXX under IKJEFT01:
//REXXTSO JOB 'IKJEFT01 REXX',CLASS=A,MSGCLASS=A
//*
//CREATE    EXEC  PGM=IEBGENER
//SYSIN     DD  DUMMY
//SYSPRINT  DD  SYSOUT=A,HOLD=YES
//SYSUT2    DD  DSN=&TEMPREX(REXTSO),DISP=(,PASS),
// SPACE=(CYL,(1,1,1)),UNIT=3390,
// DCB=(LRECL=80,RECFM=FB,DSORG=PO)
//SYSUT1    DD   *
  /* REXX */
 trace all

 "lista"

 exit 0
/*
//RUN       EXEC PGM=IKJEFT01,PARM='REXTSO'
//SYSEXEC   DD DSN=&TEMPREX,DISP=(SHR,PASS)
//SYSTSPRT  DD SYSOUT=A,HOLD=YES
//SYSTSIN   DD DUMMY
//
Parent topic: Using REXX
Related information
Running REXX Under IRXJCL


Running REXX Under IRXJCL

IRXJCL is the mainframe utility program that allows REXX EXECs to be run under JCL. When a REXX EXEC is run under IRXJCL, the default host command environment is set to "MVS" by the REXX run-time system. This means that any external commands that are specified in the EXEC will be passed to the MVS command processor for execution. For example:

/* REXX */
"execio * diskr datain (finis"
exit 0
would cause the "execio" command to be executed by the MVS command processor and would result in the all of the records read from the datatset allocated to the DD named DATAIN being put on to the data stack.
When running under IRXJCL, the EXEC may use the ADDRESS instruction to specify alternative host command environments to be used for the execution of external commands. However, Enterprise Server for .NET supports only the "TSO" and "MVS" host command environments. The use of the "TSO" host command environment under IRXJCL is invalid, and attempting to use any other host command environment, normally supported on the mainframe, will result in a return code of -3 being set, indicating that the command cannot be found. For example:
/* REXX */
"execio * diskr datain (finis"  /* Will be executed by the MVS host command environment as "MVS" is the default */
address attach                  /* Switches the current host command environment to "ATTACH" */
"testpgma varid"                /* Will result in the command completing with return code -3 */
exit 0
Example JCL used to run REXX under IRXJCL:
//REXXIRX JOB 'IRXJCL REXX',CLASS=A,MSGCLASS=A
//*
//*  DELETE ALL OF THE FILES BEING USED
//*
//STEP1     EXEC PGM=IDCAMS
//SYSOUT    DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//AMSDUMP   DD SYSOUT=*
//SYSIN     DD *
     DELETE MFRXMVS.IN.DATA PURGE
     DELETE MFRXMVS.OUT.DATA PURGE
     SET MAXCC = 0
/*
//*
//STEP2     EXEC PGM=IEFBR14
//A         DD DSN=MFRXMVS.IN.DATA,DISP=(,CATLG),
//          SPACE=(TRK,(20,20)),UNIT=SYSDA,
//          DCB=(LRECL=80,RECFM=FB,DSORG=PS)
//B         DD DSN=MFRXMVS.OUT.DATA,DISP=(,CATLG),
//          SPACE=(TRK,(20,20)),UNIT=SYSDA,
//          DCB=(LRECL=84,RECFM=VB,DSORG=PS)
//*
//STEP3     EXEC  PGM=IEBGENER
//SYSIN     DD  DUMMY
//SYSPRINT  DD  SYSOUT=*
//SYSUT2    DD  DSN=&TEMPREX(REXXTEST),DISP=(,PASS),
//          SPACE=(CYL,(1,1,1)),UNIT=3390,
//          DCB=(LRECL=80,RECFM=FB,DSORG=PO)
//SYSUT1    DD   *
  /* REXX */
  trace i

  dsns.0 = 2
  dsns.1 = "'MFRXMVS.IN.DATA'"
  dsns.2 = "'MFRXMVS.OUT.DATA'"

  /*********************************************************************/
  /*  Set up input dataset                                             */
  /*********************************************************************/
  do i = 1 to 10
    queue "Record" i
  end

  queue ""

  "execio * DISKW DATAIN (FINIS"

  /*********************************************************************/
  /*  Copy dataset                                                     */
  /*********************************************************************/
  "NEWSTACK"         /* Create a new data stack for input only */

  "EXECIO * DISKR DATAIN (FINIS)"
  QUEUE ""           /* Add a null line to indicate the end of data */
  "EXECIO * DISKW DATAOUT (FINIS"

  if queued() \= 0 then
    do
        say "FAIL - EXECIO DISKW has left records on the stack"
    end

  "DELSTACK"         /* Delete the new data stack */
  EXIT 0
/*
//STEP4		   EXEC PGM=IRXJCL,PARM='REXXTEST'
//SYSEXEC   DD DSN=&TEMPREX,DISP=(SHR,PASS)
//SYSTSPRT  DD SYSOUT=*
//SYSTSIN   DD DUMMY
//DATAIN    DD DSN=MFRXMVS.IN.DATA,DISP=OLD
//DATAOUT   DD DSN=MFRXMVS.OUT.DATA,DISP=OLD
//
Parent topic: Using REXX
Related information
Running REXX Under IKJEFT01


Restrictions

The following mainframe REXX capabilities are not supported by Enterprise Server for .NET:
  • Sequence numbers in the last eight bytes of fixed-length source records are recognized, but no checking is done on the order of these numbers
  • Sequence numbers in variable length source records
  • The TRACE S instruction is syntactically allowed, but does not trace the remaining clauses in the EXEC. The EXEC is fully syntax checked when it is first loaded
  • Numeric options entered during interactive debugging
  • CICS REXX
  • Compiled REXX
  • APPCMVS, ATTACH, ATTACHMVS, ATTACHPGM, CONSOLE, CPICOMM, ISPEXEC, ISREDIT, LINK, LINKMVS, LINKPRM, LU62 and DSNREXX host command environments
  • User-defined host command environments
  • REXX programming services (IRXEXCOM, IRXEXEC, IRXHLT, IRXINIT, IRXLIN, IRXRLT, IRXSAY, IRXSUBCM, IRXTERM, IRXTXT, etc)
  • Replaceable routines and exits
  • DBCS
Parent topic: Using REXX


Event Manager

Enterprise Server for .NET provides an event subscription mechanism that allows third party software to subscribe to events published from activity within a region.

  • Event Manager Architecture
  • Events Supported
  • seepubsub Client
  • Event Manager Samples
Parent topic: Administrator Role


Event Manager Architecture

A publish – subscribe or pubsub architecture is used to facilitate notification of events. A client subscribes to an event or range of events either directly, or using an exit provided within the seepubsub utility (described further in this documentation Event Manager - SEEPubSub Client). As the events occur they are pushed to the client side for consumption.

Event Manage Architecture

The client connects to the region through a listener using the Micro Focus BINP protocol on a pre-configured port.

Once connected, the subscription request is sent to the region, and an acknowledgement that the subscription was successful is sent back.

A subscription can be either durable or non-durable.

A durable subscription will persist even if the connection to the region is lost. If the connection is lost, all events subscribed will be stored into the database for subsequent retrieval. If the connection is reestablished, the stored events will be pushed to the client. A durable client can even be stopped and restarted without losing events, if it uses the same subscription identifier when it re-subscribes.

  • There are two types of durability:
    • If a subscription is not configured as durable and the client process is running, and the network connection to the listener fails and later corrects whilst the client is running, the running client can re-subscribe and get the missing events.
    • If the subscription is configured as durable and the client process is terminated, the client can reconnect with the same subscription details, and the events will resume from where they left off.

The seepubsub utility is provided with theEnterprise Server for .NET distribution. It can be configured to subscribe to multiple events within multiple regions, and then feed those events to a user exit (a user program written to handle the events) per subscription.

A user program can also subscribe directly to events. A simple example called "subscribe" demonstrating this is included in the samples provided with the product. Please use the samples browser to locate the example.

Parent topic: Event Manager


Events Supported

Enterprise Server for .NET currently supports the following events.

Event Type | Sub Event Name | Sub Event Type
System Events Type 1 | SEP Termination | 3
Shutdown Started | 1
Shutdown Complete | 4
CICS Events Type 2 | Not currently Supported
JES Events

Job Ready

1

Job Concluded

2

Job Started

3

Job Purged

4

Job Ended

5

Tso Started

6

Tso Ended

7

Step Ready

8

Step Started

9

Step Ended

10

Step Bypassed

11

Call Ready

12

Call Started

13

Call Ended

14

Run Ready

15

Run Started

16

Run Ended

17

Before Program Call

18

After Program Call

19

Jes Monitor General

20

Jes Monitor Initiator

21

Jes Monitor Printer

22

Jes Monitor Last Job

23

Jes Monitor Last Print

24

Job Statement Info

Note that Job Statement Info is not currently sent to the Event Manager

25

User Exit Changed Job Name

26
ES for .NET events type 4 Subscriber connected

No Event Data Returned

1
Subscriber Disconnected

No Event Data Returned

2
Console Message
Offset | Length | Type | Description
0 | 4 | Integer | Message Length
4 | Variable | Character | Message Text
 3
Parent topic: Event Manager


seepubsub Client

seepubsub is a client application that can be configured to connect to running regions via the SEE Listener Service to subscribe to and receive events.

These events are then sent to the customer application via a configurable exit.

  • Using seepubsub from the Command Line
  • Using seepubsub as a Service
  • seepubsub Configuration File
  • Walkthrough with MFBSI
Parent topic: Event Manager


Using seepubsub from the Command Line

  • seepubsub can be run from the command line using the following syntax:
    • seepubsub [options] [URL exit-program [subscriber-options]]
    • seepubsub -i [service-options] [URL exit-program [subscriber-options]]
    • seepubsub -u
  • Options:
    -i | Install as a Windows service
    -u | Uninstall Windows service
    -interval: Seconds to wait between attempts to subscribe to unavailable regions
    -nobanner | Do not display the banner at startup
    -quiet | Display minimal output
    -verbose | Display events as they are received

If URL and exit-program are not specified, seepubsub will look in its application configuration file (seepubsub.exe.config) for a list of subscriptions, including their URLs, exit programs, and options. This is the normal operating mode.

Alternatively, you can specify a single subscription on the command line, using the URL and exit-program parameters.

The URL parameter is a URL in the form "mfbinp://host:port", pointing to an MFBINP channel for an Enterprise Server for .NET region. If the URL parameter is supplied, the name of the exit program must also be specified on the command line. Along with them you can specify the following subscriber options:
-description: | Provide a description of this subscriber
-durable | Events will be archived if the connection is lost
-filter: | Control what events are received (overrides filter set by exit program)
-nounsubscribe | Do not unsubscribe when the process exits. Useful with -durable and -subscriberid
-subscriberid: | Set the subscriber ID. With -durable, this can be used to recover events even if the process is restarted
Parent topic: seepubsub Client


Using seepubsub as a Service

In order to install seepubsub as a service, invoke the executable with the -i parameter.

You can also use any of the following service options:

  • -service_account:

    The account the service will run under. Can be "localservice", "networkservice","localsystem", or "user".

  • -service_username:

    If -service_account:user is specified, use this option to specify the user name.

  • -service_password:

    If -service_account:user is specified, use this option to specify the password.

  • -service_startup:

    Set the service startup mode; can be "manual","automatic", or "disabled".

When started as a service, seepubsub will read configuration parameters from the seepubsub.exe.config file in the directory that the service executable is installed and run from.

For the configuration syntax, please refer to seepubsub Configuration File.

Parent topic: seepubsub Client


seepubsub Configuration File

When seepubsub is invoked as a command line executable, it will default to configuration in the configuration file unless command line parameters are used to override it.

When seepubsub is invoked as a service, the service will read its configuration from the configuration file.

The configuration file is an XML file called seepubsub.exe.config, and should exist in the same directory as the executable.

Within the config file there is a section called <MicroFocus.SEE.SeePubSub> which contains the relevant subscription information.

 <MicroFocus.SEE.SeePubSub>
  <subscriptions>

      <subscription
        url="mfbinp://localhost:9022"
        program="mfbsiemx"
        filter="*:*"
        description="MFBSI Scheduler interface"
        subscriberid="normally-only-used-for-durable-subscribers"
        durable="false"
        nounsubscribe="false"
       />
       <environment>
          <set name="REGION" value="JCLDEMO" />
          <set name="ES_SERVER" value="$REGION" />
          <set name="MFBSI_DIR" value="c:/tmp/mfbsi/$REGION" />
        </environment>
      </Subscriptions>

  </MicroFocus.SEE.SeePubSub>

where :

  • The URL parameter is a URL in the form "mfbinp://host:port", pointing to an MFBINP channel for an Enterprise Server for .NET region.
  • program is the user exit that seepubsub will call when an event needs to be consumed.
  • filter is a string containing a filter used to select the event types that are to be subscribed.

    It has the following syntax :

    type:subtype-classification[,subtype-classification…][&type:subtype-classification…]

    where:

    type is a number or * to indicate all types

    subtype-classification is a comma-delimited number or range, * indicates all subtypes

    Example:

     1:*&2:1,2,3&3:1-10,15

All subtypes for type 1
Subtypes 1,2 & 3 for type 2
Subtypes 1,2,3,4,5,6,7,8,9, & 15 for type 3
  • description is a description of the subscription
  • subscriberid is a unique identifier that identifies the subscription. This is used to reconnect in the case of a durable subscription.
  • durable is set to "true" if a durable subscription is required. Events will be archived if connection is lost, and retrieved on subsequent re-connection.
  • nounsubscribe is set to true if the subscription is not to be unsubscribed when a process exits. Used in conjunction with the durable and subscriptionid parameters.

Each subscription can have a set of environment variables set to it.

The environment section contains a list of name value pairs.

Parent topic: seepubsub Client


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 the section 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, this should be set 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 - this should be set 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 earlier in this 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=JobN

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 like this:
    • <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 environment variables described above in your system environment and reboot, or configure them in the subscription - environment section in the configuration file as describedseepubsub Configuration File
  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 should be 0 if the job ran successfully.
  4. Check the MFBSI work directory. There should be a file named JOBnumber.log. Check that it contains the JES log for the job.

Parent topic: seepubsub Client


Event Manager Samples

Enterprise Server for .NET is shipped with some exit examples and an example of direct subscription.

Use the Start > All Programs > Micro Focus Enterprise Developer > Samples > Mainframe Samples browser to access them.

Parent topic: Event Manager


Deployment

Information in this section applies to the deployment role.

  • Deployment Planning
  • Scaling Out an Enterprise Server for .NET Installation
  • Deployment Best Practice
Parent topic: Role-based Contents - Introduction


Deployment Planning

This section deals with topics that should be borne in mind when deploying Enterprise Server for .NET.

  • The Location of Artifacts
  • Scale Out Versus Scale Up Deployments
  • Azure Deployment
Parent topic: Deployment


The Location of Artifacts

An artifact is defined as including but not limited to any of the following:

  • System program assemblies
  • Customer program assemblies and debug information (PDB files)
  • Region configuration and resource definitions
  • BMS files
  • COBOL Data Files
  • JES Catalog

When planning a deployment, it is important to place artifacts in the correct location.

For a scale out deployment (multiple machines hosting listeners, dispatchers and SEPs), it is necessary to put these files into a central location.

A central location can be the SQL database or a network drive. If placing COBOL data files onto a network drive, file-share should be used to provide data integrity.

We recommend placing artifacts into a data store hosted in the database, where they can be accessed centrally.

Further information on defining program and data locations can be found at Defining Program and Data Locations.

Further information on defining the location of the JES Catalog can be found at To Configure a JES Region's Catalog Location.

Parent topic: Deployment Planning


Scale Out Versus Scale Up Deployments

A scale up production deployment is where all of the Enterprise Server for .NET roles ( Listener, Dispatcher , Monitor and SEP) are hosted on a single machine, typically an enterprise class blade. As more resource is required (disk, CPU, memory), it is added to the machine. The problem with scale up architecture is that once the upgrade capacity of the single machine is reached, a newer machine with more capacity needs commissioning, with the associated downtime and costs.

A scale out deployment is where each role can be hosted on multiple, cheaper machines, or even in a cloud deployment. As more capacity is required, e.g. SEP roles, then more machines can be added to the deployment to host more SEPs. When the extra resource is no longer required, they can be removed.

If network load balancers (NLBs) are used between the roles, introducing and removing these machines need not prevent work continuing on the remaining infrastructure. The use of an NLB will also ensure that if a machine or role is removed from the deployment, the remaining machines will be given more share of the load.

Enterprise Server for .NET architecture was designed with scale out in mind and should be thought of as a scale out solution . It will work in a scale up scenario, but the advantages of scale out would be lost.

Please refer to the Scaling out topic for further information.

Parent topic: Deployment Planning


Azure Deployment

One of the fundamental design decisions used during the development of Enterprise Server for .NET is that a deployment can be deployed on-premise (in the customer's domain on customer hardware), and in the cloud in Azure with equal ease.

Deploying a CICS or JES system is no more difficult, if not easier than deploying locally. The Enterprise Server for .NET core functionality is exactly the same using exactly the same code base, just running in a different host environment.

Enterprise Server for .NET can be deployed as either worker roles or into virtual machines running in Azure. Virtual machines in Azure can also be used to host 3rd party applications that cannot be integrated into Azure worker roles, e.g. schedulers, printer management , etc.

Some advantages and disadvantages to keep in mind when deploying Enterprise Server for .NET system and applications to Azure are discussed below.

  • Advantages
    • No hardware or operating system maintenance issues.
    • Network load balancing for free.
    • Microsoft guarantees roles will be up 99.98 percent of the time via their SLA, provided each role has two or more instances.
    • Ability to scale up and down dynamically.
    • Running costs are very well defined and predictable.
  • Disadvantages
    • Performance is lower than on-premise.
    • Cannot debug Enterprise Server for .NET applications. This is a Microsoft restriction and is the main reason why we recommend an on-premise staging/testing deployment before deploying into Azure.
    • Data in the cloud is contentious, and serious thought as to where the data lives must be given.
    • Using SQL Azure as the database has limitations ( , performance). However it is possible to use a full blown SQL server installation running on a virtual machine in a Microsoft Azure virtual network.

    Refer to the azure section of this help set for more information on deploying to Azure. Windows Azure Support.

Parent topic: Deployment Planning


Scaling Out an Enterprise Server for .NET Installation

Scale-out involves running an Enterprise Server for .NET installation across multiple, clustered machines. In a cluster environment:

  • The setup uses a single Microsoft SQL Server installation that operates on one or more machines.
  • The setup uses a load balancer to distribute processing between machines in the cluster.

The machines in the cluster can be either physical or virtual.

Scaling out involves:

  • Setting up an installation to run on multiple machines.
  • Setting up network load balancing to define the cluster.
  • Configuring the service endpoints, that is configuring the locations of the various Enterprise Server for .NET services operating on the cluster machines, so that they can communicate with each other.
  • Configuring network load balancing to handle distribution of traffic.
  • Scale Out Configuration
  • Scale Out Configuration Options
  • Scale Out Example
  • Defining the Service Endpoints
Parent topic: Deployment


Scale Out Configuration

Clustering allows a single listener to distribute requests to dispatchers on multiple machines. It also allows a single dispatcher to distribute requests to SEPs on multiple machines. When scaling out, the listener, dispatcher and SEP can operate on different machines.

For the event monitor service:

  • Each machine running dispatcher and/or a SEP requires a running event monitor service.
  • A machine running only a listener does not require a running event monitor service.

The cross-region database and region databases must exist in the same database server instance. That is, a region database operating in one database server instance cannot work with a cross-region database operating in a different database server instance.

A database server instance can exist on the same machine as the listener, dispatcher or SEP processes, although in a live environment, this can have performance and security implications.

Parent topic: Scaling Out an Enterprise Server for .NET Installation


Scale Out Configuration Options

There are various Enterprise Server for .NET component combinations possible for machines in a scaled out installation. For example:

  1. A machine configured with a listener only operates with configurations 2 and 5, or with configurations 3, 4, and 5. Network load balancers manage traffic between the listener and the dispatchers on the other machines in the installation.
  2. A machine configured with an event monitor, a dispatcher and one or more SEPs operates with configurations 1 and 5.
  3. A machine configured with an event monitor and a dispatcher operate with configurations 1, 4, and 5. Network load balancers manage traffic between:
    • The listeners and the dispatcher.
    • The dispatcher and the SEPs on a configuration 4 machine.
  4. As described in configuration 3, a machine configured with an event monitor and an SEP operates with configurations 1, 3, and 5.
  5. You can configure the installation's database server on a single machine, or it can operate over multiple machines.
Parent topic: Scaling Out an Enterprise Server for .NET Installation


Scale Out Example

The scale out example in this section relates to a configuration set up as shown in the following graphic:

Implementing a scale out installation involves the following stages. Each of these stages is explained in detail in subsequent topics:

  1. Set up each machine to be used.
  2. Install Enterprise Server for .NET on each machine in the cluster.
  3. On each machine in the cluster, configure access to the database server.
  4. On each machine in the cluster, configure the firewall.
  5. Test each machine to ensure that it can connect to the region database.
  6. Set up network load balancing for the cluster, and verify that the cluster operates.
  • Setting Up the Cluster Machines
  • Installing Enterprise Server for .NET on a Cluster
  • Setting Up Database Access for a Cluster
  • Configuring the Firewall for a Cluster Installation
  • Testing the Database Connection
  • Setting Up and Testing Network Load Balancing
Parent topic: Scaling Out an Enterprise Server for .NET Installation


Setting Up the Cluster Machines

Use this procedure to set up each machine in the Enterprise Server for .NET cluster.
  1. Install and activate Windows as per the requirements for an Enterprise Server for .NET installation.
  2. Assign static IP addresses to each machine in the cluster. If using cloning to set up a cluster of virtual machines, ensure that each virtual machine has a unique NetBIOS name.
  3. Using the Server Management Wizard, add the following server roles and features:
    • Application Server Role
    • Web Server Role
    • WCF Activation (HTTP and Non-HTTP) Feature
    • WPAS Feature
    • Network Load Balancing Feature
Parent topic: Scale Out Example


Installing Enterprise Server for .NET on a Cluster

Each machine in the cluster requires an installation of Enterprise Server for .NET. Follow the instructions for a normal Enterprise Server for .NET installation.
Parent topic: Scale Out Example


Setting Up Database Access for a Cluster

By default, Enterprise Server for .NET connects to SQL Server using Windows authentication (SSPI), with the user's log on credentials. For cluster operations running in a workgroup rather than a domain, configure each machine to connect using supplied SQL Server authentication credentials.
  1. Open SQL Server Management Studio and connect to the database server instance used by the cluster.
  2. In the Management Studio left pane, expand the Security item, then expand the Logins item.
  3. Right-click in the Logins area and choose New Login. The Login - New dialog box appears.
  4. Use the Login - New dialog box to create an account with SQL Server authentication. When configuring credentials, ensure that you clear the following options:
    • Enforce password policy
    • Enforce password expiration
    • User must change password at next logon
  5. Right-click the account you created and select Properties. On the Login Properties dialog box, grant sufficient access to create databases and tables such asPublic and Sysadmin. Click OK to close the dialog box.
  6. In the Management Studio left pane, right-click the top-level server item and choose Properties. The Server Properties dialog box appears.
  7. Under Server Authentication, select SQL Server and Windows Authentication mode, and click OK.
  8. Set the following system environment variable:
    REX_SQLCREDS
    User ID=<database login>; password=<login password>
Reboot the machine to restart the database server and set the new system environment variable.
Parent topic: Scale Out Example


Configuring the Firewall for a Cluster Installation

A cluster machine requires specific firewall settings to operate.
Configure the Windows firewall to allow the following ports:
8002
The listener callback service
6265
Listener default port
9022
Listener default port
9023
Listener default port
Parent topic: Scale Out Example


Testing the Database Connection

After configuring all cluster machines, ensure each can connect to the region database before configuring network load balancing.
  1. On one of the cluster machine, start the test region supplied with the installation software.
  2. On each of the remaining cluster machines, open a console. The console displays messages from the test region started from the machine starting the region.
Any machines in the cluster that cannot display the console messages can not operate as part of the scale out installation.
Parent topic: Scale Out Example


Setting Up and Testing Network Load Balancing

Each machine must have Enterprise Server for .NET installed and configured to connect to the SQL Server database.
  1. On the first machine, run Network Load Balancing and use it to create a new cluster. For the cluster you create, do the following:
    • Assign the cluster IP address and name.
    • Set the cluster mode to Multicast.
    • Check that the Network Load Balancing Manager shows the machine as Enabled.
  2. Remove the default cluster rule, and create two new rules:
    • Balance traffic on port 80, to allow cluster testing.
    • Balance traffic on port 9023 for system traffic.
  3. Repeat the process for the remaining machines to define them to the cluster.
  4. Test that the network recognizes the cluster. You can ping the cluster IP address to test. For testing purposes, you may need to add an entry for the cluster to the %WINDIR%\system32\drivers\etc\hosts files on each machine.
  5. On each cluster machine, use IIS to create a default, unique web page under the web root that lets you recognize the machine.
  6. To test network load balancing, connect a browser to the cluster IP address, for example: http://192.168.10.10. Refresh the screen multiple times. If the cluster is operating successfully, web pages from different machines in the cluster appear after each refresh.
Start an Enterprise Server for .NET region such as ESDEMO, and connect 3270 clients to the cluster IP address. Each connection is assigned to a cluster machine depending on the load balancing.
Parent topic: Scale Out Example


Defining the Service Endpoints

An Enterprise Server for .NET installation consists of various components that run as Windows services, interacting with each other. By default, these services operate on the same machine using a default port. If scaling out an installation over multiple machines, or if you do not want to use the default port configuration, define the service endpoints so Enterprise Server for .NET services can transfer information as required.

  • About Service Endpoints
  • Using URLs to Define Program and Data Locations
  • Default Service URLs
  • Service Location Order of Precedence
  • Configuring Custom Locations for Services
Parent topic: Scaling Out an Enterprise Server for .NET Installation


About Service Endpoints

A service endpoint is the Windows Communication Foundation (WCF) location of an Enterprise Server for .NET component running as a service. The default configuration is a port on the local machine, that is, all components operating on a single machine.

Key WCF service interactions an installation uses include:

  • Dispatcher-to-SEP, to submit requests for processing.
  • SEP-to-dispatcher, to register an SEP as available for processing requests (self-hosted SEPs only).
  • SEP-to-listener, to send responses back to clients and receive data from specific client conversations.
  • SEP-to-monitor, to register database and server instances, register special SEPs (such as debug SEPs) and SEP pools, and process certain CICS APIs.
  • Monitor-to-dispatcher, to submit requests generated by events such as timers.
Note: The listener always sends its WCF service location to the dispatcher, so you do not have to configure the listener's endpoint for the dispatcher.

For a system operating on a cluster, service endpoints are defined as URLs. The URL defines the endpoint's protocol, hostname, port, and path.

Parent topic: Defining the Service Endpoints


Default Service URLs

These are the default service URLs:

Monitor service
net.tcp://host[:port]/MicroFocus/SEE/MonitorService/Endpoint
Self-hosted Dispatcher service
net.tcp://host[:port]/MicroFocus/SEE/DispatcherSessionService/Endpoint
WAS-hosted Dispatcher service
net.tcp://host/MicroFocus/SEE/DispatchSession.svc

Service names differ between the self-hosted and WAS-hosted dispatcher.

Self-hosted SEP service
net.tcp://host[:port]/MicroFocus/SEE/SEP/Endpoint
WAS-hosted SEP service
net.tcp://host/MicroFocus/SEE/SEP.svc
Parent topic: Defining the Service Endpoints


Service Location Order of Precedence

You can set multiple locations for a service. Where there are multiple locations, the order of precedence from highest to lowest is:

  1. Command-line options, such as -dispatcher:url, where supported.
  2. For the listener, the optional attributes of the <region> element in order:
    1. the url attribute
    2. the host and port attributes
  3. Default.dispatcher, Default.sep, and Default.monitor URL settings in the <services> section of the service's name.exe.config configuration file or the web.config file.

    Each service has a configuration file such as listener.exe.config and monitor.exe.config. The default path for these configuration files is %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

  4. Default.remoteHost and Default.port in the configuration file's <services> section. Default.port also sets the port used when exposing self-hosted services.
  5. Default.port in the MicroFocus.SEE section of machine.config. This also sets the port used when exposing self-hosted services.
  6. The built-in defaults. These include the default service URLs for self-hosted and WAS-hosted services, the default remote hostname localhost, and the default port of 9186.
Parent topic: Defining the Service Endpoints


Configuring Custom Locations for Services

Configure non-default service locations with the user interface or with the configuration files used by the services.

The topics in this section describes how to modify the configuration files. Modifying configuration files is more suitable for large installations since you do not need to individually configure each component.

  • Changing the Default Service Port using machine.config
  • Configuring the SEP Endpoint for the Dispatcher
  • Configuring the Monitor Endpoint
Parent topic: Defining the Service Endpoints


Changing the Default Service Port using machine.config

This procedure requires administrator access.

The default port for the event monitor and listener WCF services is 9186. Add a configuration section to the .NET Framework system-wide configuration file machine.config to change this default port .

Use this procedure if port 9186 is already in use on your system.

Tip: From the user interface, you can start and stop processing, and monitor a region's processing. The user interface connects to an event monitor using the default port.
  1. Close all Enterprise Server for .NET components, services, and the user interface.
  2. Make a backup copy of the machine.config file.

    The file is in %windir%\Microsoft.NET\Framework\version\Config, where version is the .NET Framework version used by Enterprise Server for .NET. Use the file in Framework with a 32-bit version of Windows, and in Framework64 with a 64-bit version Windows.

  3. Open machine.config for editing.
  4. If the MicroFocus.SEE section is not defined in the file, add a <section> element to the configSections section as follows:
    <!-- Added for Micro Focus SEE for .NET -->
<section name="MicroFocus.SEE"
   type="System.Configuration.NameValueSectionHandler, System.Configuration, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
  restartOnExternalChanges="false"
  requirePermission="false"/>
  5. At the end of the file, just before the </configuration> closing tag, add the MicroFocus.SEE section with the Default.port setting:
       <!-- Added for Micro Focus SEE for .NET -->
   <MicroFocus.SEE>
      <add key="Default.port" value="9186"/>
   </MicroFocus.SEE>
  6. In that section, change 9186 to the port used for self-hosted services.
  7. Save the file and restart all processes.
The components, services, and the user interface use the new port that you configure on the next time that you start them.
Note: The default port or URL settings in a component's .exe.config file, or the web.config file overrides the value set in machine.config.
Parent topic: Configuring Custom Locations for Services


Configuring the SEP Endpoint for the Dispatcher

You can configure the SEP endpoint used by the dispatcher in the application's web.config file. For 32-bit installations, this file installs to %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE\WAS. For 64-bit installations, this file installs to %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE\WAS.

To configure the SEP endpoint, edit the entries in the web.config file's <appsettings> section. For example:
<add key="Default.sep" value="net.tcp://localhost/MicroFocus/
  SEE/SEP.svc" />
Note: In a cluster, the version of web.config with the SEP endpoint settings needs to be installed on all machines that use the SEP.
Parent topic: Configuring Custom Locations for Services


Configuring the Monitor Endpoint

The monitor connects to dispatchers and SEPs, and SEPs connect back to the monitor. A monitor process runs on every machine with a dispatcher and/or SEPs. Connections to and from the monitor are local.

You do not need to configure the monitor with service locations for dispatchers and SEPs. The monitor gets these from the database.

Since monitors are always self-hosted, it is not necessary to change the service location, except to use a different port if the default (9186) is unavailable.

Set the monitor default port in the <services> section of the seemonitor.exe.config file. By default, seemonitor.exe.config is installed to %ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

The following sets the monitor port to 9185.
<services>
    <add key="Default.port" value="9185" />
</services>
Parent topic: Configuring Custom Locations for Services


Deployment Best Practice

This topic contains some best practice principles that Micro Focus recommends.

  • Deploy artifacts (region definition, resource definition, executables etc) to a database (a data-store is ideal), rather than a disk. This enables central control of the artifacts, and artifacts can be used by multiple regions and machines.
    • Deployment of artifacts (new programs for example) can be automated using the command line tools supplied. Look at the seedbdeploy.cmd batch program as an example of how to do this.
  • An Enterprise Server for .NET deployment can host one or more regions. Each region can be configured to look for artifacts in different locations. It is possible therefore to have the same infrastructure (same listeners, dispatchers and SEPs ) hosting a production and a test environment.
  • If you are planning on using Azure to host your deployments, get it all working in an on-premise deployment first. Once everything is working on-premise, deploying to Azure is simple. All the executables are the same, so no need to recompile. You also then have a debug environment that can be used to help locate application faults in Azure.
  • Use the Enterprise Server for .NET administration tool to administer configuration. Configuration entered this way is validated to a high degree and the likelihood of errors is minimized.
Parent topic: Deployment


Development Role

Information in this section applies to the Developer Role.

  • The SDLC
  • Developing Mainframe Managed Subsystem Applications
Parent topic: Role-based Contents - Introduction


The SDLC

  • Problem Determination
  • Enterprise Server for .NET Reference Information
Parent topic: Development Role


Problem Determination

  • Common Problems
Parent topic: The SDLC


Common Problems

These are some of the problems that can arise in an Enterprise Server for .NET installation.

Note: Running the wassetup command with no parameters can fix many configuration problems. The wassetup command verifies the existing configuration. If not correct, wassetup either configures the environment correctly, or displays a message indicating what needs to be done.

  • Dispatcher or SEP Invoke Failure
  • MMC: Error Adding Enterprise Server for .NET Snap-in
  • MMC: Open With a .msc File Error
  • Region Startup: Error Invoking DFHZPLT
  • Region Startup: No SEP Endpoint
  • IIS and WAS problems
  • SQL Server: Cannot Connect to remote SQL Server
  • Cannot start tasks or trigger transactions
Parent topic: Problem Determination


Dispatcher or SEP Invoke Failure

Enterprise Server for .NET generates errors when it attempts to invoke the Dispatcher or create an SEP.

Possible Causes and Resolutions

This error could be caused by one of the following:

  • One or more MicroFocus.SEE.xxx system assemblies have been uninstalled from the GAC.

    Repair or re-install Enterprise Server for .NET.

  • One or other of the PipelineSegments.store or AddIns.store files in %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU and %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\AddIns respectively are corrupt or out of sync with the pipeline assemblies.

    Repair or re-install Enterprise Server for .NET.

  • WAS/IIS needs recycling.

    Use the Windows Services control panel or an equivalent tool to stop and restart the World Wide Web Publishing Service and the Windows Process Activation Service.

  • Check the Windows Services control panel and ensure that the Net.Tcp Listener Adapter Service and Net.Tcp Port Sharing Service are is started.

    View the Windows event log for further clues.

Parent topic: Common Problems


MMC: Error Adding Enterprise Server for .NET Snap-in

An error occurs when trying to add the SEE Administration snap-in to the MMC.

Possible causes

The SEE Administration snap-in requires .NET framework 4.0 to run and MMC is running with an earlier framework version.

To resolve this, in the environment space used by the MMC, set the COMPLUS_Version environment variable to v4.0.30319. For example, in the command window before you run mmc.exe, use the following command:

set COMPLUS_Version=v4.0.30319
Parent topic: Common Problems


MMC: Open With a .msc File Error

An error occurs when trying to open the MMC from the command line and specifying the .msc file to use.

Possible causes

The SEE Administration snap-in requires .NET framework 4.0 to run and MMC is running with an earlier framework version.

To resolve this, in the environment space used by the MMC, set the COMPLUS_Version environment variable to v4.0.30319. For example, in the command window before you run mmc.exe, use the following command:

set COMPLUS_Version=v4.0.30319
Parent topic: Common Problems


Region Startup: Error Invoking DFHZPLT

The following error occurs when trying to start a region:
EP0016E Error invoking program: DFHZPLT
173     Called program file not found in drive/directory [DFHZPLT]
CF0002E Failed to configure region

Possible Cause and Resolution

This can occur if the REXBASE environment variable has not been set to the rex trunk location.

If this error occurs when running under IIS, ensure that the REXBASE environment variable is set in the system environment space. Environment variables expand at execution time rather than region startup time. Previously it would need to be set in the seestart or MMC environment space.

Parent topic: Common Problems


Region Startup: No SEP Endpoint

The following type of error messages appear at region startup:
seestart
Micro Focus .NET Enterprise Server - Region Startup Version 1.000.0000
 Copyright (C) 1984-2012 Micro Focus

CF0052I Cold start of region 'ESDEMO' starting CF0020I
SQL Server instance created using Standard Edition (64-bit)
CF0021I Using datasource "(local)"
CF0023I Using database "MicroFocus$SEE$Region$ESDEMO"
CF0027I Using SIT "DFH$IVP"
CF0009E An exception occurred creating region "ESDEMO":
There was no endpoint listening at URL
Endpoint that could accept the message.
This is often caused by an incorrect address or SOAP action.
See InnerException, if present, for more details.
CF0002E Failed to configure region

Possible Causes and Resolutions

This can be caused by either of the following:

  • The TCP port sharing service has not been started.

    See How to Enable the Net.TCP Port Sharing Service on the Microsoft Developer Network for instructions on starting the TCP port sharing service.

  • If the user has attempted to start the region with a non-administrative ID, or has UAC enabled, the problem could be due to a TCP port sharing permissions issue.

    See Configuring the Net.TCP Port Sharing Service on the Microsoft Developer Network for more details.

Parent topic: Common Problems


IIS and WAS problems

If a WAS-hosted region does not start and "cannot contact" messages or thread abort messages appear, a good first step is to ensure that the WAS infrastructure is set up correctly.

As part of the initial setup, wassetup should be run. If it was not, then run it now.

If IIS or WAS is behaving inconsistently, the first thing to do is to use the wasreset command to reset the environment. The command kills all Enterprise Server for .NET processes and re-cycles IIS and WAS.

Note: Running wasreset with the /full option removes all active w3wp processes and terminates any active transactions.

Other steps to take include the following:

  • Check that the pool definitions in the IIS console are correct.
  • Check that the port sharing service is running.
  • Check that seemonitor service can be started in the services console.
  • Ping the local machines host name to check for DNS or network issues.
  • Ping the database host machine, if the database is not local, to check DNS or network issues.
  • Open a browser and check that navigation to http://localhost/MicroFocus/SEE/SEP.svc sends back the "metadata publishing is disabled" page.
The following steps could be used with Micro Focus SupportLine:
  • See if anything relevant appears in the event logs.
  • Activate and use the Micro Focus common tracing facility.
Parent topic: Common Problems


SQL Server: Cannot Connect to remote SQL Server

The following error occurs:

SQL Server: Cannot connect to remote sql server instance using SQL Server Management Studio

Possible causes

Check the following:

  • Make sure the SQL Server Browser service is running. It will be listening on UDP port 1434 if it is active.
  • Check the firewall.
  • In SQL Server Configuration Manager, check that TCP/IP is enabled.
  • If receiving login failed errors, see Understanding Login Failed error messages on the Microsoft Developers Network.
Parent topic: Common Problems


Cannot start tasks or trigger transactions

CICS tasks scheduled to start using the START API, or TDQ triggered transactions, fail to start.

Possible Causes and Resolutions

This problem typically occurs if SQL Server Service Broker has been disabled for the region and/or cross-region database. Enterprise Server for .NET will detect whether SQL Server Service Broker has been disabled for either of these databases during region start up processing and will attempt to re-enable it. However, re-enablement will only succeed if no other connections to these database exist. A warning message will be output to the system console and an event written to the Windows event log if re-enablement fails.

SQL Server Service Broker can be re-enabled manually by doing the following:
  1. Open SQL Server Management Studio
  2. Connect to the database server instance where the region and/or cross-region database resides
  3. Select the database in Object Explorer and right-click on Properties

    This will display the Database Properties dialog

  4. Select the Options page and then set the Broker Enabled property to True

    Click on OK to save the change

Parent topic: Common Problems


Enterprise Server for .NET Reference Information

This section contains reference information used in the Enterprise Server for .NET environment.

  • CICS APIs Supported
  • CICS Supplied Transactions
  • Resource Definitions Available in Enterprise Server for .NET
  • Abend Codes in CICS Transactions
Parent topic: The SDLC


CICS APIs Supported

The topics in this section cover the CICS APIs supported in Enterprise Server for .NET.

  • Application Programming CICS APIs
  • Supported CICS System Programming APIs
  • Overriding ASSIGN and INQUIRE Values
Parent topic: Enterprise Server for .NET Reference Information


Application Programming CICS APIs

The following Application Programming APIs are supported:

  • Supported Base APIs.
  • Supported BMS APIs
  • Supported File Control APIs
  • Supported IntervalControl APIs
  • Supported TaskControl APIs
  • Supported TerminalControl APIs
  • Supported TSTD APIs
Parent topic: CICS APIs Supported


Supported Base APIs.

The following Base APIs are supported:

  • ABEND
  • ADDRESS
  • ADDRESS SET
  • ASSIGN
  • BIF DEEDIT
  • CHANGE PASSWORD
  • Freemain
  • Getmain
  • HANDLE ABEND
  • HANDLE AID
  • IGNORE CONDITION
  • HANDLE CONDITION
  • SIGNOFF
  • Signon
  • SYNCPOINT
  • VERIFY PASSWORD
  • WRITE OPERATOR
  • PUSH HANDLE
  • POP HANDLE
Parent topic: Application Programming CICS APIs


ABEND

The ABEND function is supported.

Operand | Support
ABCODE (data-value) | Full
CANCEL | Full
NODUMP | Full
Parent topic: Supported Base APIs.


ADDRESS

The ADDRESS function is supported.

Operand | Support
ACEE (ptr-ref) | Full
COMMAREA (ptr-ref) | Full
CSA (ptr-ref) | Validated
CWA (ptr-ref) | Full
EIB (ptr-ref) | Full
TCTUA (ptr-ref) | Full
TWA (ptr-ref) | Full
Parent topic: Supported Base APIs.


ADDRESS SET

The ADDRESS SET function is supported.

Operand | Support
SET (ptr-ref) | Full
USING (ptr-ref) | Full
Parent topic: Supported Base APIs.


ASSIGN

The ASSIGN function is supported

Operand | Support
ABCODE (data-area) | Full
ABDUMP (data-area) | Partial: returns user defined default or 0x00
ABPROGRAM (data-area) | Partial: returns user defined default or spaces
ACTIVITY (data-area) | Validated
ACTIVITYID (data-area) | Validated
ALTSCRNHT (data-area) | Full
ALTSCRNWD (data-area) | Full
APLKYBD (data-area) | Partial: returns user defined default or 0x00
APLTEXT (data-area) | Partial: returns user defined default or 0x00
APPLID (data-area) | Full
ASRAINTRPT (data-area) | Partial: returns user defined default or 0x00
ASRAKEY (data-area) | Validated
ASRAPSW (data-area) | Partial: returns user defined default or 0x00
ASRAREGS (data-area) | Partial: returns user defined default or 0x00
ASRASPC (data-area) | Validated
ASRASTG (data-area) | Validated
BRIDGE (data-area) | Partial: returns user defined default or spaces
BTRANS (data-area) | Partial: returns user defined default or 0x00
CHANNEL (data-area) | Full
CMDSEC (data-area) | Partial: returns user defined default or spaces
COLOR (data-area) | Partial: returns user defined default or 0x00
CWALENG (data-area) | Full
DEFSCRNHT (data-area) | Partial returns 24
DEFSCRNWD (data-area) | Partial returns 80
DELIMITER (data-area) | Partial: returns user defined default or 0x30
DESTCOUNT (data-area) | Partial: returns user defined default or 0
DESTID (data-area) | Partial: INVREQ occurs
DESTIDLENG (data-area) | Partial: INVREQ occurs
DS3270 (data-area) | Full
DSSCS (data-area) | Partial: returns user defined default or 0x00
EWASUPP (data-area) | Partial: returns user defined default or 0 if tte <=model 2
EXTDS (data-area) | Partial: returns user defined default or 0x00
FACILITY (data-area) | Full
FCI (data-area) | Full: Override via user configuration
GCHARS (data-area) | Partial: returns user defined default or 0
GCODES (data-area) | Partial: returns user defined default or 0
GMMI (data-area) | Partial: returns user defined default or 0x00
HILIGHT (data-area) | Partial: returns user defined default or 0x00
INITPARM (ptr-ref) | Partial: returns user defined default
INITPARMLEN (data-area) | Partial: returns user defined default or 0
INPARTN (data-area) | Partial: returns user defined default or spaces
INVOKINGPROG (data-area) | Full
KATAKANA (data-area) | Partial: returns user defined default or 0x00
LANGINUSE (data-area) | Validated
LDCMNEM (data-area) | Partial: returns user defined default or spaces
LDCNUM (data-area) | Partial: returns user defined default or 0x00
MAPCOLUMN (data-area) | Partial: returns user defined default or 0
MAPHEIGHT (data-area) | Partial: returns user defined default or 0
MAPLINE (data-area) | Partial: returns user defined default or 0
MAPWIDTH (data-area) | Partial: returns user defined default or 0
MSRCONTROL (data-area) | Partial: returns user defined default or 0x00
NATLANGINUSE (data-area) | Partial: returns user defined default or "E" meaning "English (US)"
NETNAME (data-area) | Full
NEXTTRANSID (data-area) | Full
NUMTAB (data-area) | Partial: returns user defined default or 0x00
OPCLASS (data-area) | Partial: returns user defined default or 0x00
OPERKEYS (data-area) | Partial: returns user defined default or 0x00
OPID (data-area) | Full
OPSECURITY (data-area) | Partial: returns user defined default or 0x00
ORGABCODE (data-area) | Full
OUTLINE (data-area) | Partial: returns user defined default or 0x00
PAGENUM (data-area) | Partial: returns user defined default or 0
PARTNPAGE (data-area) | Partial: returns user defined default or spaces
PARTNS (data-area) | Partial: returns user defined default or 0x00
PARTNSET (data-area) | Partial: returns user defined default or spaces meaning "No application partition set"
PRINSYSID (data-area) | Partial: returns user defined default or spaces
PROCESS (data-area) | Validated
PROCESSTYPE (data-area) | Validated
PROGRAM (data-area) | Full
PS (data-area) | Partial: returns user defined default or 0x00
QNAME (data-area) | Partial: returns user defined default or spaces
RESSEC (data-area) | Partial: returns user defined default or spaces
RESTART (data-area) | Partial: returns user defined default or x"00" meaning "Normal Start"
RETURNPROG (data-area) | Partial: returns user defined default or spaces
SCRNHT (data-area) | Full
SCRNWD (data-area) | Full
SIGDATA (data-area) | Partial: returns user defined default or spaces
SOSI (data-area) | Partial: returns user defined default or 0x00
STARTCODE (data-area) | Full
STATIONID (data-area) | Partial: returns user defined default or 0x00
SYSID (data-area) | Full
TASKPRIORITY (data-area) | Partial: returns user defined default or 0
TCTUALENG (data-area) | Partial: returns user defined default or 0
TELLERID (data-area) | Partial: returns user defined default or 0x00
TERMCODE (data-area) | Full
TERMPRIORITY (data-area) | Partial: returns user defined default or 0
TEXTKYBD (data-area) | Partial: returns user defined default or x"00" meaning "No"
TEXTPRINT (data-area) | Partial: returns user defined default or x"00" meaning "No"
TRANPRIORITY (data-area) | Partial: returns user defined default or 0
TWALENG (data-area) | Full
UNATTEND (data-area) | Partial: returns user defined default or 0x00
USERID (data-area) | Full
USERNAME (data-area) | Partial: returns user defined default or spaces
USERPRIORITY (data-area) | Full
VALIDATION (data-area) | Partial: returns user defined default or x"00" meaning "No"
Parent topic: Supported Base APIs.


BIF DEEDIT

The BIF DEEDIT function is supported.

Operand | Support
FIELD (data-area) | Full
LENGTH (data-value) | Full
Parent topic: Supported Base APIs.


CHANGE PASSWORD

The CHANGE PASSWORD function is supported.

Operand | Support
ESMREASON (data-area) | Validated
ESMRESP (data-area) | Validated
NEWPASSWORD (data-value) | Full
PASSWORD (data-value) | Full
USERID (data-value) | Full
Parent topic: Supported Base APIs.


Freemain

The FREEMAIN function is supported.

Operand | Support
DATA (data-area) | Full
DATAPOINTER (ptr-ref) | Full
Parent topic: Supported Base APIs.


Getmain

The GETMAIN function is supported.

Operand | Support
BELOW | Validated
CICSDATAKEY | Validated
FLENGTH (data-value) | Full
INITIMG (data-value) | Full
LENGTH (data-value) | Full
NOSUSPEND | Full
SET (ptr-ref) | Full
SHARED | Full
USERDATAKEY | Validated
Parent topic: Supported Base APIs.


HANDLE ABEND

The HANDLE ABEND function is supported.

Operand | Support
CANCEL | Full
LABEL (label) | Full
PROGRAM (data-value) | Full
RESET | Full
Parent topic: Supported Base APIs.


HANDLE AID

The HANDLE AID function is supported.

Parent topic: Supported Base APIs.


IGNORE CONDITION

The IGNORE CONDITION function is supported.

Parent topic: Supported Base APIs.


HANDLE CONDITION

The HANDLE CONDITION function is supported.

Parent topic: Supported Base APIs.


SIGNOFF

The SIGNOFF function is supported.

Parent topic: Supported Base APIs.


Signon

The SIGNON function is supported.

Note: The SIGNON API verifies the username and password using standard Microsoft Windows authentication, and sets the appropriate status (normal or an error code). It does not change the user account that the application runs under, nor change its permissions.
Operand | Support
ESMREASON (data-area) | Validated
ESMRESP (data-area) | Validated
GROUPID (data-value) | Full
LANGINUSE (data-area) | Validated
LANGUAGECODE (data-value) | Validated
NATLANG (data-value) | Validated
NATLANGINUSE (data-area) | Validated
NEWPASSWORD (data-value) | Full
OIDCARD (data-value) | Validated
PASSWORD (data-value) | Full
USERID (data-value) | Full
Parent topic: Supported Base APIs.


SYNCPOINT

The SYNCPOINT function is supported.

Operand | Support
ROLLBACK | Full
Parent topic: Supported Base APIs.


VERIFY PASSWORD

The VERIFY PASSWORD function is supported.

Operand | Support
CHANGETIME (data-area) | Full
DAYSLEFT (data-area) | Full
ESMREASON (data-area) | Validated
ESMRESP (data-area) | Validated
EXPIRYTIME (data-area) | Full
INVALIDCOUNT (data-area) | Full
LASTUSETIME (data-area) | Full
PASSWORD (data-value) | Full
USERID (data-value) | Full
Parent topic: Supported Base APIs.


WRITE OPERATOR

The WRITE OPERATOR function is supported.

Operand | Support
ACTION (data-value) | Validated
CRITICAL (cvda) | Validated
EVENTUAL (cvda) | Validated
IMMEDIATE (cvda) | Validated
MAXLENGTH (data-value) | Validated
NUMROUTES (data-area) | Validated
REPLY (data-area) | Validated
REPLYLENGTH (data-area) | Validated
ROUTECODES (data-value) | Validated
TEXT (data-value) | Full .
TEXTLENGTH (data-value) | Full .
TIMEOUT (data-value) | Validated
Parent topic: Supported Base APIs.


PUSH HANDLE

The PUSH HANDLE function is supported.

Parent topic: Supported Base APIs.


POP HANDLE

The POP HANDLE function is supported.

Parent topic: Supported Base APIs.


Supported BMS APIs

The following BMS APIs are supported:

  • PURGE MESSAGE
  • RECEIVE MAP
  • SEND CONTROL
  • SEND MAP
  • SEND PAGE
  • SEND TEXT
Parent topic: Application Programming CICS APIs


PURGE MESSAGE

The PURGE MESSAGE function is supported.

Parent topic: Supported BMS APIs


RECEIVE MAP

The RECEIVE MAP function is supported.

Operand | Support
ASIS | Full
FROM (data-area) | Full
INPARTN (data-value) | Validated
INTO (data-area) | Full
LENGTH (data-value) | Full
MAP (data-value) | Full
MAPSET (data-value) | Full
SET (ptr-ref) | Full
TERMINAL | Full
Parent topic: Supported BMS APIs


SEND CONTROL

The SEND CONTROL function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DEFAULT | Full
ERASE | Full
ERASEAUP | Full
FORMFEED | Full
FREEKB | Full
FRSET | Full
HONEOM | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LDC (data-value) | Validated
MSR (data-value) | Validated
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
SET (ptr-ref) | Full
TERMINAL | Full
WAIT | Full
Parent topic: Supported BMS APIs


SEND MAP

The SEND MAP function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DATAONLY | Full
DEFAULT | Full
ERASE | Full
ERASEAUP | Full
FMHPARM | Validated
FORMFEED | Full
FREEKB | Full
FROM (data-area) | Full
FRSET | Full
HONEOM | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LDC (data-value) | Validated
LENGTH (data-value) | Full
MAP (data-value) | Full
MAPONLY | Full
MAPSET (data-value) | Full
MSR (data-value) | Validated
NLEOM | Full
NOFLUSH | Validated
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
SET (ptr-ref) | Full
TERMINAL | Full
WAIT | Full
Parent topic: Supported BMS APIs


SEND PAGE

The SEND PAGE function is supported.

Operand | Support
ALL | Validated
AUTOPAGE | Full
CURRENT | Validated
FMHPARM (data-value) | Validated
LAST | Full
NOAUTOPAGE | Full
OPERPURGE | Full
RELEASE | Full
RETAIN | Full
SET (ptr-ref) | Full
TRAILER (data-area) | Full
TRANSID (data-value) | Full
Parent topic: Supported BMS APIs


SEND TEXT

The SEND TEXT function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DEFAULT | Full
ERASE | Full
FMHPARM (data-value) | Validated
FORMFEED | Full
FREEKB | Full
FROM (data-area) | Full
HEADER (data-area) | Full
HONEOM | Validated
JUSFIRST (cvda) | Full
JUSLAST (cvda) | Full
JUSTIFY (data-value) | Full
L40 | Validated
L64 | Validated
L80 | Validated
LAST | Full
LDC (data-value) | Validated
LENGTH (data-value) | Full
MSR (data-value) | Validated
NLEOM | Full
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Validated
REQID (data-value) | Full
SET (ptr-ref) | Full
TERMINAL | Full
TRAILER (data-area) | Full
WAIT | Full
Parent topic: Supported BMS APIs


Supported File Control APIs

The following File Control APIs are supported:

  • DELETE
  • ENDBR
  • READ
  • READNEXT
  • READPREV
  • STARTBR
  • RESETBR
  • REWRITE
  • UNLOCK
  • WRITE
Parent topic: Application Programming CICS APIs


DELETE

The DELETE function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
GENERIC | Full
KEYLENGTH (data-value) | Full
NUMREC (data-area) | Validated
RBA | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Validated
TOKEN (data-area) | Full
Parent topic: Supported File Control APIs


ENDBR

The ENDBR function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
REQID (data-value) | Full
SYSID (data-value) | Validated
Parent topic: Supported File Control APIs


READ

The READ function is supported.

Operand | Support
CONSISTENT | Validated
DATASET (data-value) | Full
DEBKEY | Validated
DEBREC | Validated
EQUAL | Full
FILE (data-value) | Full
GENERIC | Full
GTEQ | Full
INTO (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-area) | Full
NOSUSPEND | Full
RBA | Full
REPEATABLE | Validated
RIDFLD (data-area) | Full
RRN | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
UNCOMMITTED | Validated
UPDATE | Full
XRBA | Validated
Parent topic: Supported File Control APIs


READNEXT

The READNEXT function is supported.

Operand | Support
CONSISTENT | Validated
DATASET (data-value) | Full
FILE (data-value) | Full
INTO (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-area) | Full
RBA | Full
REPEATABLE | Validated
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SET (ptr-ref) | Full
SYSID (data-value) | Validated
TOKEN (data-area) | Full
UNCOMMITTED | Validated
UPDATE | Full
XRBA | Validated
Parent topic: Supported File Control APIs


READPREV

The READPREV function is supported.

Operand | Support
CONSISTENT | Validated
DATASET (data-value) | Full
FILE (data-value) | Full
INTO (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-area) | Full
RBA | Full
REPEATABLE | Validated
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SET (ptr-ref) | Full
SYSID (data-value) | Validated
TOKEN (data-area) | Full
UNCOMMITTED | Validated
UPDATE | Full
XRBA | Validated
Parent topic: Supported File Control APIs


STARTBR

The STARTBR function is supported.

Operand | Support
DATASET (data-value) | Full
DEBKEY | Validated
DEBREC | Validated
EQUAL | Full
FILE (data-value) | Full
GENERIC | Full
GTEQ | Full
KEYLENGTH (data-value) | Full
RBA | Full
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Validated
XRBA | Validated
Parent topic: Supported File Control APIs


RESETBR

The RESETBR function is supported.

Operand | Support
DATASET (data-value) | Full
EQUAL | Full
FILE (data-value) | Full
GENERIC | Full
GTEQ | Full
KEYLENGTH (data-value) | Full
RBA | Full
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Validated
XRBA | Validated
Parent topic: Supported File Control APIs


REWRITE

The REWRITE function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
FROM (data-area) | Full
LENGTH (data-value) | Full
SYSID (data-value) | Validated
TOKEN (data-area) | Full
Parent topic: Supported File Control APIs


UNLOCK

The UNLOCK function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
SYSID (data-value) | Validated
TOKEN (data-area) | Full
Parent topic: Supported File Control APIs


WRITE

The WRITE function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
FROM (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-value) | Full
MASSINSERT | Full
NOSUSPEND | Validated
RBA | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Validated
XRBA | Validated
Parent topic: Supported File Control APIs


Supported IntervalControl APIs

The following IntervalControl APIs are supported:

  • ASKTIME
  • CANCEL
  • DELAY
  • FORMATTIME
  • RETRIEVE
  • START
Parent topic: Application Programming CICS APIs


ASKTIME

The ASKTIME function is supported.

Operand | Support
ABSTIME (data-area) | Full
Parent topic: Supported IntervalControl APIs


CANCEL

The CANCEL function is supported.

Operand | Support
REQID (data-value) | Full
SYSID (data-value) | Full
TRANSID (data-value) | Full
Parent topic: Supported IntervalControl APIs


DELAY

The DELAY function is supported.

Operand | Support
FOR | Full
HOURS (data-value) | Full
INTERVAL (data-value) | Full
MINUTES (data-value) | Full
REQID (data-value) | Full
SECONDS (data-value) | Full
TIME (data-value) | Full
UNTIL | Full
Parent topic: Supported IntervalControl APIs


FORMATTIME

The FORMATTIME function is supported.

Operand | Support
ABSTIME (data-area) | Full
DATE (data-area) | Full
DATEFORM (data-area) | Full
DATESEP (data-value) | Full
DAYCOUNT (data-area) | Full
DAYOFMONTH (data-area) | Full
DAYOFWEEK (data-area) | Full
DDMMYY (data-area) | Full
DDMMYYYY (data-area) | Full
FULLDATE (data-area) | Full
MMDDYY (data-area) | Full
MMDDYYYY (data-area) | Full
MONTHOFYEAR (data-area) | Full
TIME (data-area) | Full
TIMESEP (data-value) | Full
YEAR (data-area) | Full
YYDDD (data-area) | Full
YYDDMM (data-area) | Full
YYMMDD (data-area) | Full
YYYYDDD (data-area) | Full
YYYYDDMM (data-area) | Full
YYYYMMDD (data-area) | Full
Parent topic: Supported IntervalControl APIs


RETRIEVE

The RETRIEVE function is supported.

Operand | Support
INTO (data-area) | Full
LENGTH (data-area) | Full
QUEUE (data-area) | Full
RTERMID (data-area) | Full
RTRANSID (data-area) | Full
SET (ptr-ref) | Full
WAIT | Validated
Parent topic: Supported IntervalControl APIs


START

The START function is supported.

Operand | Support
AFTER | Full
AT | Full
FMH | Validated
FROM (data-area) | Full
HOURS (data-value) | Full
INTERVAL (data-value) | Full
LENGTH (data-value) | Full
MINUTES (data-value) | Full
NOCHECK | Validated
PROTECT | Full
QUEUE (data-value) | Full
REQID (data-value) | Full
RTERMID (data-value) | Full
RTRANSID (data-value) | Full
SECONDS (data-value) | Full
SYSID (data-value) | Full
TERMID (data-value) | Full
TIME (data-value) | Full
TRANSID (data-value) | Full
USERID (data-value) | Full
Parent topic: Supported IntervalControl APIs


Supported TaskControl APIs

The following TaskControl APIs are supported:

  • DELETE CONTAINER
  • DEQ
  • ENDBROWSE CONTAINER
  • ENQ
  • GET CONTAINER
  • GETNEXT CONTAINER
  • LINK
  • LOAD
  • MOVE CONTAINER
  • PUT CONTAINER
  • RELEASE
  • RETURN
  • STARTBROWSE CONTAINER
  • XCTL
Parent topic: Application Programming CICS APIs


DELETE CONTAINER

The DELETE CONTAINER function is supported.

Operand | Support
CHANNEL (data-value) | Full
CONTAINER (data-value) | Full
SYSTEM (cvda) | Recognized
USER (cvda) | Recognized
Parent topic: Supported TaskControl APIs


DEQ

The DEQ function is supported.

Operand | Support
LENGTH (data-value) | Full
LUW (cvda) | Full
MAXLIFETIME (data-value) | Full
RESOURCE (data-value) | Full
TASK (cvda) | Full
Parent topic: Supported TaskControl APIs


ENDBROWSE CONTAINER

The ENDBROWSE CONTAINER function is supported.

Operand | Support
BROWSETOKEN (data-area) | Full
Parent topic: Supported TaskControl APIs


ENQ

The ENQ function is supported.

Operand | Support
LENGTH (data-value) | Full
LUW (cvda) | Full
MAXLIFETIME (data-value) | Full
NOSUSPEND | Full
RESOURCE (data-value) | Full
TASK (cvda) | Full
UOW (cvda) | Full
Parent topic: Supported TaskControl APIs


GET CONTAINER

The GET CONTAINER function is supported.

Operand | Support
ACQACTIVITY | Recognized
ACQPROCESS | Recognized
ACTIVITY (data-value) | Recognized
CHANNEL (data-value) | Full
CONTAINER (data-value) | Full
FLENGTH (data-area) | Full
INTO (data-area) | Full
INTOCCSID (data-area) | Full
NODATA | Full
PROCESS | Recognized
SET (ptr-ref) | Full
SYSTEM (cvda) | Recognized
USER (cvda) | Recognized
Parent topic: Supported TaskControl APIs


GETNEXT CONTAINER

The GETNEXT CONTAINER function is supported.

Operand | Support
BROWSETOKEN (data-area) | Full
CONTAINER (data-area) | Full
Parent topic: Supported TaskControl APIs


LINK

The LINK function is supported.

Operand | Support
CHANNEL (data-value) | Validated
COMMAREA (data-area) | Full
DATALENGTH (data-value) | Validated
INPUTMSG (data-area) | Full
INPUTMSGLEN (data-value) | Full
LENGTH (data-value) | Full
PROGRAM (data-value) | Full
SYNCONRETURN | Validated
SYSID (data-value) | Validated
TRANSID (data-value) | Validated
Parent topic: Supported TaskControl APIs


LOAD

The LOAD function is supported.

Operand | Support
ENTRY (ptr-ref) | Full
FLENGTH (data-area) | Full
FROM (data-area) | Full
HOLD | Full
LENGTH (data-area) | Full
PROGRAM (data-value) | Full
SET (ptr-ref) | Full
Parent topic: Supported TaskControl APIs


MOVE CONTAINER

The MOVE CONTAINER function is supported.

Operand | Support
AS (data-value) | Full
CHANNEL (data-value) | Full
CONTAINER (data-value) | Full
TOCHANNEL (data-value) | Full
Parent topic: Supported TaskControl APIs


PUT CONTAINER

The PUT CONTAINER function is supported.

Operand | Support
ACQACTIVITY | Recognized
ACQPROCESS | Recognized
ACTIVITY (data-value) | Recognized
BIT (cvda) | Full
CHANNEL (data-value) | Full
CHAR (cvda) | Full
CONTAINER (data-value) | Full
DATATYPE (data-value) | Full
FLENGTH (data-area) | Full
FROM (data-area) | Full
FROMCCSID (data-area) | Full
PROCESS | Recognized
SYSTEM (cvda) | Recognized
USER (cvda) | Recognized
Parent topic: Supported TaskControl APIs


RELEASE

The RELEASE function is supported.

Operand | Support
PROGRAM (data-value) | Full
Parent topic: Supported TaskControl APIs


RETURN

The RETURN function is supported.

Operand | Support
CHANNEL (data-value) | Validated
COMMAREA (data-area) | Full
ENDACTIVITY | Validated
IMMEDIATE | Full
INPUTMSG (data-area) | Full
INPUTMSGLEN (data-value) | Full
LENGTH (data-value) | Full
TRANSID (data-value) | Full
Parent topic: Supported TaskControl APIs


STARTBROWSE CONTAINER

The STARTBROWSE CONTAINER function is supported.

Operand | Support
ACTIVITYID (data-value) | Recognized
BROWSETOKEN (data-area) | Full
CHANNEL (data-value) | Full
PROCESS (data-value) | Recognized
PROCESSTYPE (data-value) | Recognized
Parent topic: Supported TaskControl APIs


XCTL

The XCTL function is supported.

Operand | Support
CHANNEL (data-value) | Validated
COMMAREA (data-area) | Full
INPUTMSG (data-area) | Full
INPUTMSGLEN (data-value) | Full
LENGTH (data-value) | Full
PROGRAM (data-value) | Full
Parent topic: Supported TaskControl APIs


Supported TerminalControl APIs

The following TerminalControl APIs are supported:

  • DISCONNECT
  • SEND
  • RECEIVE
Parent topic: Application Programming CICS APIs


DISCONNECT

The DISCONNECT function is supported.

Parent topic: Supported TerminalControl APIs


SEND

The SEND function is supported.

Operand | Support
ALTERNATE | Full
CTLCHAR (data-value) | Full
DEFAULT | Full
DEST (data-value) | Validated
ERASE | Full
FLENGTH (data-value) | Full
FROM (data-area) | Full
LENGTH (data-value) | Full
STRFIELD | Full
WAIT | Full
Parent topic: Supported TerminalControl APIs


RECEIVE

The RECEIVE function is supported.

Operand | Support
ASIS | Full
BUFFER | Full
FLENGTH (data-area) | Full
INTO (data-area) | Full
LENGTH (data-area) | Full
MAXFLENGTH (data-value) | Validated
MAXLENGTH (data-value) | Validated
NOTRUNCATE | Validated
SET (ptr-ref) | Full
Parent topic: Supported TerminalControl APIs


Supported TSTD APIs

The following TSTD APIs are supported:

  • DELETEQ TD
  • DELETEQ TS
  • READQ TD
  • READQ TS
  • WRITEQ TS
  • WRITEQ TD
Parent topic: Application Programming CICS APIs


DELETEQ TD

The DELETEQ TD function is supported.

Operand | Support
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: Supported TSTD APIs


DELETEQ TS

The DELETEQ TS function is supported.

Operand | Support
QNAME (data-value) | Full
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: Supported TSTD APIs


READQ TD

The READQ TD function is supported.

Operand | Support
INTO (data-area) | Full
LENGTH (data-area) | Full
NOSUSPEND | Full
QUEUE (data-value) | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
Parent topic: Supported TSTD APIs


READQ TS

The READQ TS function is supported.

Operand | Support
INTO (data-area) | Full
ITEM (data-area) | Full
LENGTH (data-area) | Full
NEXT | Full
NUMITEMS (data-area) | Full
QNAME (data-value) | Full
QUEUE (data-value) | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
Parent topic: Supported TSTD APIs


WRITEQ TS

The WRITEQ TS function is supported.

Operand | Support
AUXILIARY | Validated
FROM (data-area) | Full
ITEM (data-area) | Full
LENGTH (data-value) | Full
MAIN | Validated
NOSUSPEND | Validated
NUMITEMS (data-area) | Full
QNAME (data-value) | Full
QUEUE (data-value) | Full
REWRITE | Full
SYSID (data-value) | Full
Parent topic: Supported TSTD APIs


WRITEQ TD

The WRITEQ TD function is supported.

Operand | Support
FROM (data-area) | Full
LENGTH (data-value) | Full
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: Supported TSTD APIs


Supported CICS System Programming APIs

The following CICS System Programming APIs are supported:

  • INQUIRE FILE
  • INQUIRE PROGRAM
  • INQUIRE SYSTEM
  • INQUIRE TASK
  • INQUIRE TASK LIST
  • INQUIRE TCLASS
  • INQUIRE TERMINAL
  • INQUIRE TRANCLASS
  • INQUIRE TRANSACTION
  • SET FILE
  • SET PROGRAM
  • SET TRANSACTION
Parent topic: CICS APIs Supported


Overriding ASSIGN and INQUIRE Values

The implementation of the EXEC CICS ASSIGN, EXEC CICS INQUIRE FILE, and EXEC CICS INQUIRE PROGRAM APIs in this release does not fully support many of the options for those APIs. Some features of these APIs are not applicable, such as options regarding mainframe limitations with 24-bit addressing. Others refer to features not yet implemented. For these options, Enterprise Server for .NET returns a configurable default value.

Some applications depend on receiving a specific value for these options, and this can be different from the default returned value. For these applications, you can configure the return value. The value you configure applies to the region configuration, that is the configured value applies to only those programs running in the region.

  • Configuring ASSIGN and INQUIRE Override Values
  • EXEC CICS ASSIGN Override Values
  • EXEC CICS INQUIRE FILE Override Values
  • EXEC CICS INQUIRE PROGRAM Override Values
  • EXEC CICS INQUIRE TRANSACTION Override Values
Parent topic: CICS APIs Supported


Configuring ASSIGN and INQUIRE Override Values

Edit the region's startup file to configure an ASSIGN or INQUIRE override value. The default region startup file, Region_ESDEMO.config is installed to:

%ProgramData%\Micro Focus\Enterprise Developer\2.2\SEE\config.

You set override values using an XML add element. You set the override in a specific configuration section in the region's startup file depending on the type. The optional sections you can create are:

  • <cicsAssign>

    Use this section to configure ASSIGN override values.

  • <cicsInquireFile>

    Use this section to configure INQUIRE FILE override values.

  • <cicsInquireProgram>

    Use this section to configure INQUIRE PROGRAM override values.

You can add these sections anywhere in the region element of the region startup file.

Override Values

You can specify the override values to correspond to the type of data returned by the option. The available types are as follows:

Char-n
A value of 0 to n characters. The value is padded on the right with spaces if necessary. Values that are too long are truncated.
Example:

<add key="Abprogram" value="TESTCFG"/>

Hex-n

A string of pairs of hexadecimal digits, to represent n bytes. The string can be prefixed with x, X, h, or H and quoted with single or double-quote characters; or it can be unquoted and prefixed with 0x. There must be an even number of digits. If there are fewer than 2n digits, the value is padded with zeroes, and if there are more, the value is truncated.

Note: The double-quote character must be escaped in XML using the entity reference &quot, so single quotes are more convenient.
Examples:

<add key="Aplkybd" value="H'ff'"/>

<add key="ASRAINTRPT" value="x'0001020304050607'"/>

<add key="color" value="0xFF"/>

Int
An integer value in the appropriate range. See the IBM documents listed below for information on the ranges of integer-valued options. The value can be specified as a decimal number, or as a hexadecimal number using the same syntax as for a Hex-n item.
Examples:

<add key="MAPCOLUMN" value="12"/>

<add key="pagenum" value="0x2a"/>

CVDA (CICS Value Data Area)

CVDA items can be specified as an integer value, using the Int syntax, but it is usually more convenient to specify them using the CVDA value name detailed in the IBM documentation.

CVDA names are converted to their associated values and returned to the calling program. They are case-insensitive in the configuration file. Note that the implementation does not check that a CVDA value is appropriate for the option in question.

Examples:

<add key="AccessMethod" value="0x04"/> (corresponds to REMOTE)

<add key="BlockFormat" value="Unblocked"/>

<add key="exclusive" value="EXCTL"/>

See the current versions of the IBM documents SC34-6232, CICS Application Programming Reference, and SC34-6233, CICS System Programming Reference, for more information on options for ASSIGN, INQUIRE FILE, and INQUIRE PROGRAM. The System Programming Reference also has a complete listing of CVDA values.

Example

<microfocus.region>
   <region name="CVTEST" ...>
    <database>
      <server name="(local)" />
    </database>
    ...
    <!-- Optional overrides for CICS ASSIGN and INQUIRE API values -->
    <cicsAssign>
      <add key="AbDump" value="h'ab'"/>
      <add key="Btrans" value="X'ff'"/>
    </cicsAssign>
    <cicsInquireFile>
      <add key="disposition" value="old"/>
    </cicsInquireFile>
    <cicsInquireProgram>
      <add key="cedfstatus" value="cedf"/>
    </cicsInquireProgram>
  </region>
</microfocus.region>
Parent topic: Overriding ASSIGN and INQUIRE Values


EXEC CICS ASSIGN Override Values

The EXEC CICS ASSIGN values that you can override, along with the default values for each, are as follows:

Name | Type | Default
APLKYBD | Hex-1 | low-values
ASRAINTRPT | Hex-8 | low-values
ASRAPSW | Hex-8 | low-values
ASRAREGS | Hex-64 | low-values
BRIDGE | Char-4 | spaces
BTRANS | Hex-1 | low-values
CHANNEL | Char-16 | spaces
CMDSEC | Char-1 | spaces
COLOR | Hex-1 | low-values
DELIMITER | Hex-1 | h'30'
DESTCOUNT | Int | 0
DSSCS | Hex-1 | low-values
EWASUPP | Hex-1 | depends on terminal
EXTDS | Hex-1 | low-values
FCI | Hex-1 | depends on facility
GCHARS | Int | 0
GCODES | Int | 0
GMMI | Hex-1 | low-values
HILIGHT | Hex-1 | low-values
INITPARM | Hex-60 | low-values
INPARTN | Char-2 | spaces
KATAKANA | Hex-1 | low-values
LDCMNEM | Char-2 | spaces
LDCNUM | Hex-1 | low-values
MAPCOLUMN | Int | 0
MAPHEIGHT | Int | 0
MAPLINE | Int | 0
MAPWIDTH | Int | 0
MSRCONTROL | Hex-1 | low-values
NATLANGINUSE | Char-1 | "E"
NUMTAB | Hex-1 | low-values
OPCLASS | Hex-3 | low-values
OPID | Char-3 | spaces
OPSECURITY | Hex-3 | low-values
OPERKEYS | Hex-8 | low-values
ORGABCODE | Char-4 | spaces
OUTLINE | Hex-1 | low-values
PAGENUM | Int | 0
PARTNPAGE | Char-2 | spaces
PARTNS | Hex-1 | low-values
PARTNSET | Char-6 | spaces
PRINSYSID | Char-4 | spaces
PS | Hex-1 | low-values
QNAME | Char-4 | spaces
RESSEC | Char-1 | spaces
RESTART | Hex-1 | low-values
RETURNPROG | Char-8 | spaces
SIGDATA | Int | 0
SOSI | Hex-1 | low-values
STATIONID | Hex-1 | low-values
TASKPRIORITY | Int | 0
TCTUALENG | Int | 0
TELLERID | Char-1 | "0"
TERMCODE | Hex-2 | depends on terminal
TERMPRIORITY | Int | 0
TEXTKYBD | Hex-1 | low-values
TRANPRIORITY | Int | 0
TEXTPRINT | Hex-1 | low-values
TWALENG | Int | 0
UNATTEND | Hex-1 | low-values
USERPRIORITY | Int | 0
VALIDATION | Hex-1 | low-values
Parent topic: Overriding ASSIGN and INQUIRE Values


EXEC CICS INQUIRE FILE Override Values

The EXEC CICS INQUIRE FILE values that you can override, along with the default values for each, are as follows:

Name | Type | Default
ACCESSMETHOD | CVDA | VSAM
BLOCKFORMAT | CVDA | BLOCKED
BLOCKKEYLEN | Int | 0
BLOCKSIZE | Int | 0
DISPOSITION | CVDA | SHARE
EMPTYSTATUS | CVDA | NOEMPTYREQ
EXCLUSIVE | CVDA | NOTAPPLIC
FWDRECSTATUS | CVDA | NOTFWDRCVBLE
FWDRECSTATUS | CVDA | NOTFWDRCVBLE
JOURNALNUM | Int | 0
LSRPOOLID | Int | 0
MAXNUMRECS | Int | 0
OBJECT | CVDA | BASE
RELTYPE | CVDA | NOTAPPLIC
STRINGS | Int | 1
TABLE | CVDA | NOTTABLE
UPDATEMODEL | CVDA | NOTAPPLIC
Parent topic: Overriding ASSIGN and INQUIRE Values


EXEC CICS INQUIRE PROGRAM Override Values

The EXEC CICS INQUIRE PROGRAM values that you can override, along with the default values for each, are as follows:

Name | Type | Default
COBOLTYPE | CVDA | COBOLII *
EXECKEY | CVDA | CICSEXECKEY *
LANGUAGE | CVDA | depends on program
LPASTATUS | CVDA | NOTLPA
TRANSID | Char-4 | spaces
In the Default column above:
  • * = NOTAPPLIC for non-program modules.
Parent topic: Overriding ASSIGN and INQUIRE Values


EXEC CICS INQUIRE TRANSACTION Override Values

The EXEC CICS INQUIRE TRANSACTION values that you can override, along with the default values for each, are as follows:

Name | Type | Default
BREXIT | char-8 | spaces
CMDSEC | cvda | CMDSECNO
DTB | cvda | NOTSUPPORTED
FACILITYLIKE | char-4 | spaces
INDOUBTMINS | int | 0
INDOUBTWAIT | cvda | NOWAIT
ISOLATEST | cvda | NOISOLATE
PROFILE | char-8 | spaces
PURGEABLITY | cvda | NOTPURGEABLE
RESSEC | cvda | RESSECNO
ROUTING | cvda | STATIC
STORAGECLEAR | cvda | NOCLEAR
TASKDATAKEY | cvda | CICSDATAKEY
TASKDATALOC | cvda | ANY
TRACING | cvda | STANTRACE
TRPROF | cvda | spaces
Parent topic: Overriding ASSIGN and INQUIRE Values


CICS Supplied Transactions

The topics in this section detail the CICS transactions supplied with Enterprise Server for .NET.

  • CESF - Sign Off
    Signs off from a terminal
  • CEBR - Browse Temporary Storage
    Examines the contents of records in temporary storage or transient data queues.
  • CESN - Sign On
    Signs on to a terminal.
  • CFCR - Create a File
    Creates an empty file, if the file has previously been defined in the FCT.
  • CFMT - File Master Transaction
    Opens, closes, enables, disables or inquires on a file.
  • CINQ - Inquire On ASSIGN Values
    Displays a list of all the ASSIGN command values and their settings.
  • CINS - Install a Resource Group
    Installs a resource group.
  • CMAP - Display BMS Maps and Information
    Displays the contents of a BMS map and displays information about the map and mapset.
  • CPMT - Inquire and Set Program Attributes
    Displays the current attributes of the specified program for an inquire, and sets the specified program attribute.
  • CRUN - Generic Run Program
    Invokes the specified program.
  • EXIT - Sign Off Terminal Emulator
    Signs off and closes the terminal window.
Parent topic: Enterprise Server for .NET Reference Information


CESF - Sign Off

Signs off from a terminal

Syntax:

CESF

Notes:

When the terminal emulator session is closed down, the sign-on screen appears.

Parent topic: CICS Supplied Transactions


CEBR - Browse Temporary Storage

Examines the contents of records in temporary storage or transient data queues.

Syntax:

CEBR

Notes:

You do not enter any options on the command line. When you press Enter after CEBR, a screen is displayed showing the contents of the queue CEBRname, where name is your terminal identifier.

If you want to display a different queue, either:

Enter the subcommand QUEUE with the queue identifier.

or:

Enter the queue identifier in the CEBR command line.

CEBR Subcommands:

The CEBR transaction has the following subcommands (the acceptable abbreviation is shown in upper case):

Option | Topic
BOTtom | Displays the last records in the TS queue (as many as fill the screen)
COLumn nnnn | Displays TS queue records starting at column nnnn
Find /string | Searches TS queue records for the character string string
GET xxxx | Takes the contents of the transient data queue named xxxx and puts it at the end of the displayed TS queue, so that you can browse its contents
LINE nnnn | Alters the display so that record nnnn -1 is at the top of the screen and record nnnn is the current record.
PURGE | Deletes the TS queue that you are browsing
PUT xxxx | Copies the TS queue being browsed to the TD queue named xxxx
Queue xxxxxxxxxxxxxxxx | Displays the contents of the TS queue named xxxxxxxxxxxxxxxx
TERMinal xxxx | Displays the contents of the TS queue named term-idxxxx, where term-id is your terminal identifier
Top | Starts the display at the first record in the TS queue

Restrictions:

The CEBR transaction works as it does on a mainframe, with minor exceptions. In the QUEUE subcommand, you cannot supply a queue name in hexadecimal. There are no PF key equivalents for subcommands.

Parent topic: CICS Supplied Transactions


CESN - Sign On

Signs on to a terminal.

Syntax:

CESN

Notes:

You do not enter any options on the command line. A screen appears when you enter the command, prompting you for:

Userid (1 to 8 characters)

Password (1 to 8 characters). Your password is not displayed on the screen when you type it in.

New password (1 to 8 characters). This field appears only if you have the authority to change your password.

Parent topic: CICS Supplied Transactions


CFCR - Create a File

Creates an empty file, if the file has previously been defined in the FCT.

Syntax:

CFCR fct-file-entry

Notes:

fct-file-entry is the name specified in the file option in the FCT. The file can be either a base file or an alternate index. It is created with all the related indexes.

A confirmation message shows you the base file characteristics and all the alternate keys that you specified. An error message is displayed if the file has not been created.

Parent topic: CICS Supplied Transactions


CFMT - File Master Transaction

Opens, closes, enables, disables or inquires on a file.

Syntax:

CFMT [OPen|CLose|ENable|DIsable|INquire|NAme] filename

Notes:

You must enter at least the first two letters of the option you choose.

The filename may contain wild card characters. A question mark denotes any single character, while a single asterisk denotes any number of characters. An asterisk can appear only at the end of the filename. Question marks and an asterisk can be combined, for example:

CFMT CL A??PP*

closes all files that start with "A" and have "PP" in character positions 4 and 5.

You can use the CEBR transaction to view the results of a CFMT transaction that uses wild cards in the filename.

Parent topic: CICS Supplied Transactions


CINQ - Inquire On ASSIGN Values

Displays a list of all the ASSIGN command values and their settings.

Syntax:

CINQ

Notes:

The ASSIGN command values and settings are listed in alphabetic order.

Parent topic: CICS Supplied Transactions


CINS - Install a Resource Group

Installs a resource group.

Syntax:

CINS group-name

CINS resource-type(resource-id) Group(group-name)

Parameters:

resource-type | One of File, Program, TDqueue, Terminal, TRansaction, TYpeterm. You must supply at least the portion of the type shown in upper case
resource-id | The name of the resource
group-name | The name of the group the resource belongs to

Notes:

If the group is already installed, the existing definitions are replaced by those currently in the resource definition file (RDF). The group-name can be a maximum of eight characters. Group can be abbreviated to G.

Example:

CINS F(ACCTFIL) G(TEST)

This will install the file control table entry for ACCTFIL from the resource group TEST.

Parent topic: CICS Supplied Transactions


CMAP - Display BMS Maps and Information

Displays the contents of a BMS map and displays information about the map and mapset.

Syntax:

CMAP [mapset-name [map-name]]

Parameters:

[mapset-name [map-name]]

If a mapset-name is specified, then a list of maps within the mapset is displayed. If, in addition, a map-name is specified, then that map is displayed.

If map-name is not specified, you can use wildcard characters ("?" and "*") within mapset-name to reduce the number of mapsets displayed.

Notes:

If no parameters are specified, or the parameters specified are not found, a list of mapsets found in the mapset directories is displayed. If a mapset contains .MOD files, the mapset name is displayed in white.

MST files ( old mapfile format) files are not supported.

You can select an item in a list either by positioning the cursor, or by typing a slash "/" against the item, and pressing Enter. Selecting a mapset displays a list of the maps it contains. Selecting a map displays the map itself.

If a mapset appears more than once in the list, then CMAP always displays the first mapset.

Typing "i" against an item (mapset or map) and pressing Enter, displays information about the item.

Dates are shown in ISO format and are not configurable.

You can use F7-PgUp and F8-PgDn to page through lists that are more than one screen long.

Pressing Clear (or any attention key) returns to the previous higher level screen.

You can exit the transaction at any time by pressing F3.

Parent topic: CICS Supplied Transactions


CPMT - Inquire and Set Program Attributes

Displays the current attributes of the specified program for an inquire, and sets the specified program attribute.

Syntax

CPMT function program-name

Notes

The function is specified as one of:
  • NEwcopy
  • PHasein
  • DPlsubset
  • FUllapi
  • PRivate
  • SHared
  • ENabled
  • DIsabled
  • INquire
  • NAme-inquire

CEdf and NOCEdf are not supported.

For each function except INquire and NAme-inquire, CPMT issues an EXEC CICS SET PROGRAM command for the corresponding system programming API keyword.

For the INquire function, CPMT issues an EXEC CICS INQUIRE PROGRAM command, and displays the results.

For the NAme-inquire function, CPMT displays the fully qualified program name of the object loaded from disk for the associated program or table.

Parent topic: CICS Supplied Transactions


CRUN - Generic Run Program

Invokes the specified program.

Syntax:

CRUN program

Notes:

The program is invoked through XCTL. You can use CRUN to execute a program without having to define an explicit PCT entry for it. CRUN is useful for testing a program, or for invoking a PLT-type program on an as-required basis.

Parent topic: CICS Supplied Transactions


EXIT - Sign Off Terminal Emulator

Signs off and closes the terminal window.

Syntax:

EXIT

Notes:

When the terminal emulator closes down, the terminal is disconnected from Enterprise Server.

Parent topic: CICS Supplied Transactions


Resource Definitions Available in Enterprise Server for .NET

The resource definitions available in Enterprise Server for .NET are the same as those in native Enterprise Server, with the following exceptions:

  • The DFH$APCT group
  • The DFH$IMQS group
  • The DFHBMS group
  • The DFHBRDG group
  • The DFHCIVP group
  • The DFHCONS group
  • The DFHEDF group
  • The DFHELCG group transactions
  • The DFHEZA group
  • The DFHHARDC group
  • The DFHISC group
  • The DFHMQS group
  • The DFHSPI group
  • The DFHTYPE group
  • The IMSGRP group
  • The MCOASM group
  • The MCOGROUP group
  • CICS Resource Definitions
Parent topic: Enterprise Server for .NET Reference Information


CICS Resource Definitions

In Mainframe Subsytem Support you can define a subset of the resource types that you can define in mainframe CICS. You can use the same definition mechanism as mainframe CICS: DEFINE statements followed by keywords that specify various attributes of the resource. The keywords differ depending on the resource being defined. DEFINE statements are held in resource definition table (.rdt) files, which constitute a staging post in the process of exchanging resource definitions with the mainframe CICS System Definition (CSD) file.

In mainframe CICS you can define many more types of resource than you can in Mainframe Subsytem Support, for example LSRPOOL and SESSIONS. Mainframe Subsytem Support does not support these resource types because they are meaningless on the target environment.

Mainframe Subsytem Support provides Micro Focus extensions for some resource types. These are extra keywords that define attributes specific to Mainframe Subsytem Support on the target environment.

In the following specifications of the resource type definitions, each keyword and its parameters is shown in a mixture of upper case and lower case. You need to specify at least the letters in upper case. For example, in the Connection definition, DE and DESCRIPTION are synonyms. However, we recommend that you specify keywords and parameters in full, as shown in the examples. Defaults are shown in bold.

Mainframe Subsytem Support also accepts DEFINE MAPSET and all its keywords, but it does not store these definitions as mapset definitions in the resource definition file. Instead it stores them as data tables (DEFINE PROGRAM with _MOduletype set to Data).

  • DEFINE CONNECTION
    Defines a remote system with which ES communicates via inter-region communication (IRC).
  • DEFINE FILE
    Defines the attributes and characteristics of a file used by Enterprise Server.
  • DEFINE PROGRAM
    Defines a program used to process transactions in Enterprise Server.
  • DEFINE TERMINAL
    Defines the characteristics of display devices and printers used by Enterprise Server.
  • DEFINE TRANSACTION
    Defines the attributes of a transaction.
  • DEFINE TDQUEUE
    Defines the attributes of a transient data queue.
  • DEFINE TYPETERM
    Defines the attributes for a set of terminals that have similar characteristics.
  • DEFINE _SIGNON
    Defines user IDs and their level of access security to Enterprise Server resources.
Parent topic: Resource Definitions Available in Enterprise Server for .NET


DEFINE CONNECTION

Defines a remote system with which ES communicates via inter-region communication (IRC).
Keyword | Description
Connection(name) | Specifies the logical name of this connection. Mandatory. Must be unique across all connected systems. Can be up to four alphanumeric characters.
Group(groupname) | Names the group the connection definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the connection. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Connection Properties |
Netname(name) | Specifies the network name that identifies the APPLID of the remote system or region. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Required in most circumstances.
PRotocol(Appc|Cci) | Identifies the connection method to be used for the connection: Appc: a remote connection over an LU6.2 link Cci: a remote connection through a CCI gateway Mandatory
Operational Properties |
INSERVICE(Yes|No) | Indicates whether or not this connection is in service; that is, whether transactions can be initiated and messages sent.
Security |
SEcurityname(name) | The security name of the remote system. Required only if the connection method is APPC. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.
ATtachsec(Local|identify|Verify|Persistent|Mixedpe | The level of security required when a user attaches to this connection: Local: the authority of the user is taken to be that of the link Identify: Incoming attach requests must specify a user ID Verify: Incoming attach requests must specify both a user ID and a password Persistent: The first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID Mixedpe: Incoming attach requests may specify either Identify or Persistent
Micro Focus Extensions |
_OPERId(code) | Specifies an operator ID used for routing messages. Up to three alphanumeric characters. Optional.
_OPERPriority(number) | Specifies the operator priority for transactions initiated over this connection. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of: Terminal priority Transaction priority Operator priority (this field) The sum cannot be greater than 255.
_Userid(name) | Specifies a user ID to be associated with the connection. Mandatory if no sign-on takes place on the connection.
_Natlang(E|K) | Specifies the national language in which messages are sent over the connection: E: English K: Kanji
_Sessionmax(number) | Specifies the maximum number of concurrent sessions for the connection. Defaults to 0(zero).
_Lualias(name) | Specifies the LU name by which the connection is known in the APPC configuration. Mandatory only where the connection method is APPC.
_Partneralias(name) | Specifies the name used by local transactions to refer to this partner LU. Mandatory only where the connection method is APPC.
_Aliasapplid(code) | Specifies the APPLID used by the APPC link. Mandatory only where the connection method is APPC.
_Modetable(name) | Specifies the name of the APPC transmission service profile that describes the APPC link between the local and partner LUs. Mandatory only where the connection method is APPC. It can be up to eight characters in length. The first character must be from the set A through Z and $. Subsequent characters can be from the set A through Z, 0 through 9 and $.
_CCIProtocol(CCITCPIP) | For connections where the connection method is CCI, specifies which CCI protocol is to be used: CCITCPIP: TCP/IP Mandatory.
_CCIMachine(name) | Names the machine on which on which the CCITCP2 daemon is running. Required only where CCIProtocol is CCITCPIP.
_MFNode(name) | Names the machine on which the target region runs. This is its IP name or IP address. _MFNode and _MFPort together equate to the socket used by the TCP/IP server for the remote target region that this connection definition describes. These fields are mandatory only where CCIProtocol is CCITCPIP and when using a direct connection to the remote region with no CCITCP2 daemon present on the network.
_MFport(number) | Identifies the port number for _MFNode. _MFNode and _MFPort together equate to the socket used by the TCP/IP server for the remote target region that this connection definition describes. These fields are mandatory only where CCIProtocol is CCITCPIP and when using a direct connection to the remote region with no CCITCP2 daemon present on the network..
  • Examples
Parent topic: CICS Resource Definitions


Examples

DEFINE CONNECTION(L001) GROUP(SAMPGRP)
DESCRIPTION(Sample APPC connection)
       NETNAME(NET081) INSERVICE(YES) SECURITYNAME(SESS1)
       ATTACHSEC(LOCAL) PROTOCOL(APPC)

DEFINE CONNECTION(C002) GROUP(SAMPGRP)
DESCRIPTION(Sample CCI connection)
       INSERVICE(YES) ATTACHSEC(LOCAL) PROTOCOL(CCI) _OPERPRTY(0)
       _NATLANG(E) _SESSIONMAX(0) _CCIPROTOCOL(CCITCP)
       _CCIMACHINE(cvimtb09)

DEFINE CONNECTION(L001) GROUP(SAMPGRP)
DESCRIPTION(Sample APPC connection with MF extensions)
       NETNAME(NET081) INSERVICE(YES) SECURITYNAME(SESS1)
       ATTACHSEC(LOCAL) PROTOCOL(APPC) _OPERPRTY(0) _USERID(U555)
       _NATLANG(E) _SESSIONMAX(4) _LUALIAS(MTB9AFG)
       _PARTNRALIAS(ASL8KKK) _ALIASAPPLID(MPAPP)
Parent topic: DEFINE CONNECTION
Related information
Resource Definitions


DEFINE FILE

Defines the attributes and characteristics of a file used by Enterprise Server.
Keyword | Description
File(name) | Names the file. Mandatory. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the file belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the file. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
VSAM
DSName(name) | Specifies the name of the physical file. This is a mainframe-style data set name of up to 44 characters.
Remote
REMOTESystem(name) Applicable only for remote files. Specifies the ID of the remote system that holds the file. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote files. Names the remote file. Necessary only if it differs from the local file name.
RECORDSize(number) | Applicable only for remote files. Specifies the maximum length in bytes of records in a remote file, in the range 1 through 32767.
Keylength(number) | Applicable only for remote files. Specifies the length in bytes of the key for a remote file, in the range 1 through 32767.
Initial Status
STAtus(Enabled|Disabled|Unenabled) Effective only for files owned by the local region. Specifies whether this file is accessible to transactions when the region is started.

Enabled: accessible at region startup

Disabled: not accessible at region startup

Unenabled: can be opened only by a SET FILE OPEN command. You cannot specify Unenabled for files of type Altindex

Opentime(Firstref|Startup) Indicates when the file is opened.

Firstref: the first time the file is referenced in the program being executed

Startup: when the region starts up

Note that this keyword controls only when the file is opened, not whether or not it is accessible; accessibility is controlled by the STAtus keyword.

Operations
Add(No|Yes) | Indicates whether users can add records to the file.
Browse(No|Yes) | Indicates whether users can browse the file.
DELete(No|Yes) | Indicates whether users can delete records from the file.
REAd(Yes|No | Indicates whether users can read records in the file.
Update(No|Yes) | Indicates whether users can update records in the file.
Recovery Parameters
RECOVery(None|Backoutonly|All) Specifies the recovery options for this file:

None: the file is not recoverable

Backoutonly; the file is a protected resource and changes can be backed out. You must also define the file as being held on a Fileshare server, as Fileshare is required for backward recovery.

All: the file is a protected resource and has both forward and backward recovery capability. For forward recovery journals are used to record changes to the file. You must also define the file as being held on a Fileshare server, as Fileshare is required for forward and backward recovery.

Security
RESsecnum(keys) | Specifies one or more indicators, each corresponding to one of the 24 resource keys for this file. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RESSECNUM(1-5,10).
Micro Focus Extensions
_MAxreclen(number) | Specifies the maximum logical record length of the file in bytes, in the range 1 through 32767. The value must be greater than or equal to the value of _Minreclen. Specify a value if _FILEType is one of the following: KSDS, RRDS, ESDS or the file is remote (you specified a value in Remotesystem(name)).
_MInreclen(number) | Specifies the minimum logical record length of the file in bytes , in the range 1 through 32767. The value must be less than or equal to the value of _Maxreclen. Specify a value if _FILEType is one of the following: KSDS, RRDS or ESDS.
_KEYPosition(number)

The key position is the offset, relative to zero, of the key from the beginning of the data record, in the range 0 through 32767. When set to 0, the key begins in the first position of the record. Specify a value if _FILEType is one of the following: KSDS or Altindex.

_KEYLength(number) Specifies the length of the record key in bytes, in the range 1 through 32767. The value of the following expression must not exceed the minimum record length:

key position + key length - 1

_FILEType(type) Specifies what type of file this is:

KSDS: key sequenced data set

ESDS; entry sequence data set

RRDS: relative record data set

Altindex: Alternate index for a KSDS file.

May be omitted if the file is defined as remote (you specified a value in Remotesystem(name)).

_Basefile(fileid) | For a file of type Altindex, specifies the base data file for which this is an alternate index. fileid must correspond to the file name of another file definition of type KSDS.
_Startempty(No|Yes) Indicates whether the current contents of the file are deleted when the region starts up:

No: the file contents are not deleted

Yes: the file contents are deleted

_Dupkey(No|Yes) | For an alternate index, indicates whether duplicate keys are allowed
_Path(string) | Specifies the path of the physical file if you want to override the default path. Do not include the filename or the file extension. Mandatory if the file is held on a Fileshare server, in which case _FILEShareid must be present too.
_FILEShareid(name) | Specifies the Fileshare server on which the file resides. name can be up to 16 characters in length.
_FILEFormat(Microfocus|IDXFMT4|IDXFMT8|IDXFMT9) | Specifies the format for files that are to be created by Mainframe Transaction Option. We recommend that you use the default, IDXFMT8.
_FILEName(name) | Specifies the name of the physical PC file if you want to override the default filename, which is the name given by File(name). Do not include the file extension.
_FILEExt(value) | Specifies the file extension of the physical file if you want to override the default, which is .dat
_Collseq(Ebcdic|Ascii) | Specifies the collating sequence used in the file.
  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE FILE(SAMPLEA) GROUP(SAMPGRP)
DESCRIPTION(Sample KSDS FCT entry)
       STATUS(ENABLED) OPENTIME(STARTUP) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(KSDS) _MAXRECLEN(200)
       _MINRECLEN(200) _KEYPOSITION(1) _KEYLENGTH(6) _STARTEMPTY(YES)
       _DUPKEY(NO) _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
DEFINE FILE(SAMPLEA1) GROUP(SAMPGRP)
DESCRIPTION(Index for SAMPLEA)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(ALTINDEX) _BASEFILE(SAMPLEA)
       _KEYPOSITION(8) _KEYLENGTH(4) _STARTEMPTY(NO) _DUPKEY(NO)
       _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
DEFINE FILE(SAMPLEB) GROUP(SAMPGRP)
DESCRIPTION(Sample RRDS entry)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(RRDS) _MAXRECLEN(500)
       _MINRECLEN(500) _STARTEMPTY(NO) _DUPKEY(NO) _PATH(x:\cics\fshr)
       _FILESHAREID(FSHRCIC2) _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
       RESSECNUM(01-08,17-22,24)
DEFINE FILE(SAMPLEC) GROUP(SAMPGRP)
DESCRIPTION(Example of an ESDS)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(NO) READ(YES) UPDATE(NO)
       RECOVERY(BACKOUTONLY) _FILETYPE(ESDS) _MAXRECLEN(1000)
       _MINRECLEN(120) _STARTEMPTY(NO) _DUPKEY(NO) _FILEEXT(DAT)
       _FILEFORMAT(MICROFOCUS) _FILENAME(TESTC) _USECATALOG(NO)
Parent topic: DEFINE FILE


DEFINE PROGRAM

Defines a program used to process transactions in Enterprise Server.
Keyword | Description
PROGram(name) | Names the program. Mandatory. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a program name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system programs.
Group(groupname) | Names the group the program belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as MSS uses that prefix for system groups.
DEscription(text) | Describes the program. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Language(Cobol|Assembler|Pli) | Specifies the programming language that the program is written in.
RESident(No|Yes) Specifies whether the program is permanently resident in memory:

No: The program is removed from memory when the tasks using it have completed

Yes: The program remains in memory throughout the session

Status(Enabled|Disabled) Specifies whether the program is accessible when the region starts up:

Enabled: the program is accessible when the region starts up.

Disabled: The program cannot be used until it is specifically enabled using the transaction CPMT.

RSl(keys) | (RSl stands for Resource Security Level.) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this program. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RSl(1-5,10).
Remote Attributes
REMOTESystem(name) Applicable only for remote programs. Specifies the ID of the remote system that holds the file. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote programs. Names the remote file. Necessary only if it differs from the local program name.
Transid(name) | Applicable only for remote programs. Specifies the name of the transaction that the remote system is to attach and under which it is to run the remote program. If not specified, the remote system executes the program under one of the supplied mirror transactions CSMI and CVMI. If supplied, name must be up to four characters in length
Micro Focus Extensions
_MOduletype(Program|Data) Specifies whether the resource being defined is an executable program or a data table:

Program: Resource is an executable program

Data: Resource is a data table. It can be loaded via an EXEC CICS LOAD PROGRAM command. Any attempt to use EXEC PROGRAM LINK or EXEC PROGRAM XCTL will fail with a PGMIDERR condition

_Wssavestate(No|Yes) | Specifies whether or not a program's working storage should be saved in its initial state so that it can be restored if the same program is called again at a lower level
_MAxcommarea(size) | Specifies the amount of storage to be allocated to the communications area (COMMAREA) to allow CICS Option to behave like mainframe CICS. The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space. This overrides the COMMAREA override value held in the SIT.
  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE PROGRAM(TEST001) GROUP(TESTGRP)
LANGUAGE(COBOL) RESIDENT(NO) STATUS(ENABLED)
RSL(01,03,06,08-14,16,19-21)
DEFINE PROGRAM(TEST002) GROUP(TESTGRP)
DESCRIPTION(Sample PPT program)
LANGUAGE(ASSEMBLER) RESIDENT(NO) STATUS(DISABLED)
DEFINE PROGRAM(SAMP001) GROUP(SAMPGRP)
DESCRIPTION(Sample PPT with MF extensions)
LANGUAGE(COBOL) RESIDENT(NO) STATUS(ENABLED)
_MODULETYPE(PROGRAM) _WSSAVESTATE(NO) _MAXCOMMAREA(0)
DEFINE PROGRAM(DATA001) GROUP(SAMPGRP)
DESCRIPTION(Sample PPT for data table)
LANGUAGE(ASSEMBLER) RESIDENT(NO) STATUS(ENABLED)
_MODULETYPE(DATA) _WSSAVESTATE(NO) _MAXCOMMAREA(0)
Parent topic: DEFINE PROGRAM
Related information
Resource Definitions


DEFINE TERMINAL

Defines the characteristics of display devices and printers used by Enterprise Server.
Keyword | Description
TErminal(name) | Specifies the logical name of this terminal. Mandatory. Must be unique across all connected systems. Up to four alphanumeric characters.
Group(groupname) | Names the group the terminal definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the terminal. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
AUTINSTModel(No|Yes|Only) Specifies whether or not this terminal definition can be used as a model terminal definition for autoinstall:

Yes: can be used as a model for autoinstall, as well as for a specific device that is not autoinstalled

No: can be used only for a specific device that is not autoinstalled

Only: can be used only as a model for autoinstall

AUTINSTName(name) | Applicable only if AUTINSTModel is Yes or Only. Specifies the name by which the definition is known to the Autoinstall Control Program. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Defaults to the value given by Terminal(name).
Terminal Identifiers
Typeterm(name) | Names the associated Typerterm definition, which must exist. Mandatory.
Netname(name) | Identifies the terminal to the network. Mandatory if AUTOINSTModel is Yes or No. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. The first character must be a letter.
REMOTESYSTem(name) Applicable only for remote terminals. Specifies the ID of the remote system that holds the terminal definition. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote terminals. Names the remote terminal. Necessary only if it differs from the local terminal name.
Associated Printers
PRINTER(name) | Identifies the printer used for handling print requests. This printer must be owned by the system that owns the terminal. name can be up to four characters in length.
PRINTERCopy(No|Yes) | Indicates whether or not the hardware copy feature (using the printer defined for this terminal) is used for print requests issued from this terminal.
ALTPRINTEr(name) | Identifies the printer used for handling print requests if the printer specified in PRINTER(name) is unavailable. This printer must be owned by the system that owns the terminal. name can be up to four characters in length.
ALTPRINTCopy(No|Yes) | Indicates whether or not the hardware copy feature (using the alternate printer defined for this terminal) is used for print requests issued from this terminal.
Operator Defaults
OPERId(code) | Specifies an operator ID used for routing messages. Specify this for a terminal that cannot be signed on, such as a printer. If you specify an operator ID for a terminal that can be signed on, it is overridden by the operator ID specified in the user's sign-on table entry. Up to three alphanumeric characters.
OPERPriority(number) Specifies the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

Terminal priority

Transaction priority

Operator priority (this field)

The sum cannot be greater than 255.

Preset Security
Userid(name) | Specifies a user ID to be associated with the terminal. Mandatory if no sign-on takes place on the connection.
Natlang(E|K) Specifies the national language in which messages are sent over the connection:

E: English

K: Kanji

Terminal Usages
Transaction(name) | Names the only transaction that users can run from this terminal, apart form print and paging requests. Optional. If not specified, users can run any transaction from this terminal.
Termpriority(number) Specifies the priority for transactions run from this terminal. Defaults to 0(zero). Terminal priority is one factor in determining a transaction's execution priority, which is the sum of:

Terminal priority (this field)

Transaction priority

Operator priority

The sum cannot be greater than 255.

Inservice(Yes|No) | Indicates whether or not this terminal is in service; that is, whether transactions can be initiated and messages sent.
Session Security
Securityname(name) | The security name of the terminal. Required only if the terminal is owned by a remote system and the connection method is APPC. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.
ATtachsec(Local|Identify|Verify|Persistent|Mixedpe) The level of security required when a user issues an attach request from this terminal:

Local: the authority of the user is taken to be that of the link

Identify: Incoming attach requests must specify a user ID

Verify: Incoming attach requests must specify both a user ID and a password

Persistent: The first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID

Mixedpe: Incoming attach requests may specify either Identify or Persistent

  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE TERMINAL(T001) GROUP(SAMPGRP)
DESCRIPTION(Sample terminal definition)
       AUTINSTMODEL(NO) TYPETERM(3270) NETNAME(NET0001) PRINTER(PRN2)
       PRINTERCOPY(YES) ALTPRINTER(PRN3) ALTPRINTCOPY(YES)
       OPERPRIORITY(0) USERID(P901) NATLANG(E) TERMPRIORITY(68)
       INSERVICE(YES) ATTACHSEC(LOCAL)
Parent topic: DEFINE TERMINAL
Related information
Resource Definitions


DEFINE TRANSACTION

Defines the attributes of a transaction.

General

Keyword (default values in bold) | Description
TRANSaction(name) | Names the transaction. Mandatory. name can be up to four alphanumeric characters in length. Do not specify a transaction name starting with C, as Mainframe Subsystem Support uses that prefix for system transactions.
Group(groupname) | Names the group the transaction definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support uses that prefix for system groups
DEscription(text) | Describes the file. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
PROGram(name) | Program driven by this transaction.
TWasize(number) | Size of transaction work area, between 0 and 32767.
STAtus(Enabled|Disabled) Indicates whether or not the transaction is accessible when the region is started:
Enabled
The transaction is accessible when the region starts up
Disabled
The transaction cannot be used until it is specifically enabled using the transaction CPMT.

Remote Attributes

Keyword (default values in bold) | Description
DYnamic(No|Yes) Indicates whether or not the transaction can be dynamically routed to a remote region:
Yes
The transaction can be dynamically routed to a remote region
No
Creates a remote definition if REMOTESystem(name) is present; creates a local definition if it is not
REMOTESystem(name) Applicable only for remote transactions. Specifies the ID of the remote system that runs the transaction. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote Mainframe Subsystem Support region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote transactions. Names the remote transaction. Necessary only if it differs from the local transaction name.

Scheduling

Keyword | Description
PRIOrity(number) | Specifies the priority for this transaction. Defaults to 0(zero). Transaction priority is one factor in determining a transaction's execution priority, which is the sum of: Terminal priority Transaction priority (this field) Operator priority The sum cannot be greater than 255.
TRANClass(DFHTCL00|tranclass) | Specifies the name of the transaction class to which the transaction belongs. The reserved name DFHTCL00 is used to indicate that the transaction does not belong to any transaction class.

Recovery

Keyword (default values in bold) | Description
DTimout(No|0|hundredthsOfASecond) Specifies the deadlock timeout, that is, the period after which the transaction is terminated if it has been suspended.
NO
No deadlock timeout
0
Use system (SIT) deadlock timeout value
hundredthsOfASecond
The length of the timeout in hundredths of a second. The maximum value is 408000.
DUmp(No|Yes) | Indicates whether or not Mainframe Subsystem Support produces a program dump if this transaction abends.
Runaway(SYSTEM|0|hundredthsOfASecond) The time to allow a task to control the processor before it is assumed to be looping and therefore purged.
SYSTEM
Use system (SIT) value
0
No deadlock timeout
hundredthsOfASecond
On this system, must be a value between 100 and 270000. If less than 100 (one second), changes are ignored.
Note: That the mainframe allows 50 hundredths of a second.
TRACe(Yes|No|Special) Indicates tracing options for this transaction:
Yes
The transaction is traced
No
The transaction is not traced
Special
Not currently supported

Indoubt Attribute

Keyword (default value in bold) Description
INdoubt(Backout|Commit|Wait) Indicates the action to be taken if this transaction abends during syncpoint or abend processing:
Backout
The effects of the transaction are backed out using SYNCPOINT ROLLBACK (For this to work, you must also set backwards recovery on for any file used by the transaction.)
Commit
Any changes are committed
Wait
Critical resources are locked until the session has recovered and are then backed out or committed in step with the remote system

Security

Keyword (default values in bold) | Description
CMDSEC(No|Yes) | Indicates whether or not security checking is enabled for CICS command operations.
RESSec(No|Yes) | Indicates whether or not the transaction program performs resource security checking by comparing a user's resource keys (defined in the user's entry in the sign-on-table) with the keys enabled for a particular resource.
TRANSec(keys) Specifies one or more indicators, each corresponding to one of the 64 security keys for this transaction.

A user has access to a particular transaction only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off.

You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code TRANsec(1-5,10).

RSL(keys) (RSL stands for Resource Security Level.) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this transaction.

A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off.

You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RSl(1-5,10).

Micro Focus Extensions

Keyword (default values in bold) | Description
_CATEGORY(No|0|3) | A value of “3” specifies an IBM Category 3 Transaction. These transactions have no security checking. Therefore, transactions in this category are allowed for all users, and no authorization calls are made. An example of this type of transaction is CESN.
_Inboundtp(No|Yes) | Indicates whether or not registry entries to allow inbound transactions are created.
_Screen(Default|Alternate) | Indicates the screen size is used by the transaction. Both sizes are defined in the Typeterm definition for the terminal in use at the time.
_Uctran(Yes|No) | Indicates whether or not any data received by the transaction is automatically folded to upper case
_Timethold(SYSTEM|0|seconds) The time to wait for a transaction to complete before triggering a monitoring event.
SYSTEM
Use system (SIT) value.
0
No monitoring event.
seconds
Maximum time is 65333 seconds.
_Rtimeout(SYSTEM|0|seconds) The time to wait for input, after which the terminal will automatically sign off the user.
SYSTEM
Use system (SIT) value.
0
No timeout.
seconds
Maximum time is 4080 seconds.
  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE TRANSACTION(TRNX) GROUP(SAMPGRP)
DESCRIPTION(Sample PCT entry)
       PROGRAM(ABP0001A) TWASIZE(1024) STATUS(ENABLED) DYNAMIC(YES)
       PRIORITY(100) DTIMOUT(NO) INDOUBT(COMMIT) DUMP(YES) TRACE(YES)
       RESSEC(NO) TRANSEC(01,09-10,15-20,25,30,53-59)
       RSL(02,07-10,15,24)

DEFINE TRANSACTION(TRNX) GROUP(SAMPGRP)
DESCRIPTION(Sample PCT entry)
       PROGRAM(ABP0001A) TWASIZE(1024) STATUS(ENABLED) DYNAMIC(YES)
       PRIORITY(100) DTIMOUT(NO) INDOUBT(COMMIT) DUMP(YES) TRACE(YES)
       RESSEC(NO) TRANSEC(01,09-10,15-20,25,30,53-59)
       RSL(02,07-10,15,24) _SCREEN(DEFAULT) _UCTRAN(YES) _INBOUNDTP(NO)
Parent topic: DEFINE TRANSACTION
Related information
Resource Definitions


DEFINE TDQUEUE

Defines the attributes of a transient data queue.
Keyword | Description
TDqueue(name) | Names this queue. Mandatory. name can be up to four alphanumeric characters, the first of which must be aletter other than C.
Group(groupname) | Names the group the queue belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
DESCription(text) | Describes the transient data queue. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
TYPE(INTra | Extra | INDirect | INTRDR) Specifies the type of this queue:

Intra: The contents of the queue are accessible only to transactions and are temporary

Extra: The contents of the queue are made available to non-CICS programs, or data is made available from non-CICS programs

INDirect: An alias that points to another queue, which may be of any type

INTRDR: Specifies the internal reader to which CICS applications can direct a JCL job stream for execution by the JCL engine.

Intrapartition Queue Parameters
Atifacility(Terminal|blank)) (Intrapartition queues). Indicates the type of destination the queue represents:

Terminal: the transient data queue is associated with a terminal, which is specified in Facilityid(name).

RECOVstatus(No|Physical|Logical) | (Intrapartition queues). Indicates whether or not the queue is recoverable. If you specify that the queue is recoverable (physical and logical are synonymous), you must also specify _FILESHAREID. This is because MSS recovery is handled by Fileshare.
Facilityid(name) | (Intrapartition queues). Specifies the terminal ID if Atifacility is set to Terminal. If unspecified defaults to the queue name. A terminal definition must exist.
TRAnsid(name) | (Intrapartition queues). Specifies the name of the transaction to be run when the queue reaches the level specified in Triggerlevel(number)
TRIggerlevel(number) | (Intrapartition queues). Specifies the number of data records to be accumulated in the queue before the transaction specified in Transid(name) is run. A value of 0 means that the transaction is never run.
Extrapartition Queue Parameters
DSName(name) | (Extrapartition queues). Not used..
Opentime(Initial|Deferred) (Extrapartition queues). Indicates the initial status of the queue:

Initial: the queue is opened when the region starts up

Deferred: the queue is closed until it is required

TypeFile(Output|Input|Rdback) | (Extrapartition queues). Specifies whether the queue is for input, output, or may be read backwards.
RECORDSize(number) | (Extrapartition queues). Specifies the maximum length of records in this queue, in the range 0 through 32767
RECORDFormat(Fixed|Variable) (Extrapartition queues). Specifies the record format:

Fixed: the minimum record size is set to the same value as the maximum record size

Variable: the minimum record size is set to 1

Printcontrol(Asa|Machine) | (Extrapartition queues). Specifies the type of print control characters to be used. Optional.
Indirect Parameters
Indirectname(name) | Specifies the name of another transient data queue, which must be defined
Remote Parameters
REMOTEName(name) | Applicable only for remote transient data queues. Names the remote queue. Necessary only if it differs from the local file name. The queue must be defined on the remote system.
REMOTESystem(name) | Applicable only for remote transient data queues. Specifies the ID of the remote system that holds the file. This must correspond to the Local SYSID field in the SIT used to run the related remote region.
Micro Focus Extensions
_Status(Enabled|Disabled) Effective only for queues owned by the local region. Specifies whether this queue is accessible when the region is started.

Enabled: accessible when the region starts up

Disabled: not accessible when the region starts up

_Minrecsize(number) | (Extrapartition queues). Specifies the minimum length of records in this queue. Must be less than or equal to RECORDSize. If this is not specified, MSS deduces it from RECORDFormat.
_FILEShareid(name) | Specifies the Fileshare server on which this queue resides
_PCfiletype(Normal|Lineseq) | Indicates the type of PC file to be created to hold the queue. Choose Lineseq if you want to edit the file.
_FILEName(name) | (Extrapartition queues). Specifies the name of the file that holds this queue. Do not include the file extension. Defaults to dfhxdddd.tdq where dddd is the four-character name of the queue as specified in Tdqueue(name).
_PAth(path) | (Extrapartition queues). Specifies the path of the file that holds the queue if you want to override the default.
_FILEExt(extension) | Specifies the extension of the file that that holds the queue if you want to override the default, which is .tdq
_Rsl(keys) | Specifies one or more indicators, each corresponding to one of the 24 resource keys for this queue. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code Rsl(1-5,10).
  • Examples
Parent topic: CICS Resource Definitions


Examples

DEFINE TDQUEUE(A042) GROUP(SAMPGRP)
DESCRIPTION(Sample extrapartition DCT)
       TYPE(EXTRA) DDNAME(A042) OPENTIME(INITIAL) TYPEFILE(OUTPUT)
       RECORDFORMAT(VARIABLE) RECORDSIZE(500) BLOCKFORMAT(UNBLOCKED)
       REMOTENAME(P908) REMOTESYSTEM(SYSB)
DEFINE TDQUEUE(D010) GROUP(SAMPGRP)
DESCRIPTION(Sample intrapartition DCT)
       TYPE(INTRA) RECOVSTATUS(NO) TRANSID(TTAB) TRIGGERLEVEL(25)
DEFINE TDQUEUE(K022) GROUP(SAMPGRP)
DESCRIPTION(Sample extrapartition DCT)
       TYPE(EXTRA) DDNAME(K022) OPENTIME(INITIAL) TYPEFILE(OUTPUT)
       RECORDFORMAT(FIXED) RECORDSIZE(100) BLOCKFORMAT(UNBLOCKED)
DEFINE TDQUEUE(S030) GROUP(SAMPGRP)
DESCRIPTION(Sample indirect Q)
       TYPE(INDIRECT) INDIRECTNAME(D025)

DEFINE TDQUEUE(A042) GROUP(SAMPGRP)
DESCRIPTION(Sample extrapartition DCT with MF extensions)
       TYPE(EXTRA) DDNAME(A042) OPENTIME(INITIAL) TYPEFILE(OUTPUT)
       RECORDFORMAT(VARIABLE) RECORDSIZE(500) BLOCKFORMAT(UNBLOCKED)
       REMOTENAME(P908) REMOTESYSTEM(SYSB) _STATUS(ENABLED)
       _MINRECSIZE(26) _FILESHAREID(CICFSHRA) _PCFILETYPE(NORMAL)
       _FILENAME(ac116bx) _PATH(x:\frp\cicsa\) _FILEEXT(dct)
       _RSL(01,03,05,09-15)
DEFINE TDQUEUE(D010) GROUP(SAMPGRP)
DESCRIPTION(Sample intrapartition DCT with MF extensions)
       TYPE(INTRA) RECOVSTATUS(NO) TRANSID(TTAB) TRIGGERLEVEL(25)
       _STATUS(ENABLED)
DEFINE TDQUEUE(S030) GROUP(SAMPGRP)
DESCRIPTION(Sample indirect Q with MF extensions)
       TYPE(INDIRECT) INDIRECTNAME(D025) _STATUS(ENABLED)
Parent topic: DEFINE TDQUEUE
Related information
Resource Definitions


DEFINE TYPETERM

Defines the attributes for a set of terminals that have similar characteristics.
Keyword | Description
TYpeterm(name) | Names this terminal type. Mandatory. name can be up to four alphanumeric characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the terminal type definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
DEScription(text) | Describes the terminal type. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Resource Type
DEVice(3270|3270P) Specifies the device type:

3270: display

3270P: printer

SHippable(No|Yes) Indicates whether or not this definition can be shipped to a remote system if a device of this type attempts to initiate a remote transaction.

Yes: the terminal definition can be shipped. It is not necessary for the terminal definition to be installed on the remote system.

No: the terminal definition cannot be shipped. You must ensure that the terminal definition is installed on the remote system.

Mapping Properties
PAGesize(rows,columns) | Specifies the page size for the terminal type being defined. Page size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80.
ALTPage(rows,columns) | Specifies the page size for the terminal type being defined, if you have specified an alternate screen size (none-default values for ALTSCreen). Alternate page size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80. Unexpected results may occur if the number of columns is not the same as the number of columns you specify for alternate screen size. Defaults to the values specified in PAGesize
OBOperid(No|Yes) | Indicates whether or not MSS uses the outbound operator identifiers to support the BMS routing facilities required by this terminal type definition.
Device Properties
DEFscreen(rows,columns) | Specifies the default screen size for the 3270 terminal type being defined. This is the screen size that is used when a transaction definition specifies a default screen. Screen size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80. There is no validity checking; incorrect sizes may lead to unpredictable behavior.
ALTSCReen(rows,columns) | Specifies the alternate screen size for the 3270 terminal type being defined. This is the screen size that is used when a transaction definition specifies an alternate screen. Screen size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80. There is no validity checking; incorrect sizes may lead to unpredictable behavior.
APLKybd(No|Yes) | Indicates whether or not the terminal type has the APL keyboard feature
AUDiblealarm(No|Yes) | Indicates whether or not the terminal type has the audible alarm feature
COLor(Yes|No) | Indicates whether or not the terminal type has the color feature, allowing colors to be selected for individual fields
COPy(No|Yes) | Indicates whether or not the terminal type has the copy feature
DUalcasekybd(No|Yes) Indicates which type of keyboard the terminal type has:

Yes: the terminal has a typewriter keyboard

No: the terminal has an operator console keyboard

Both types of keyboard transmit both upper-case and lower-case data.

EXtendedds(Yes|No) Indicates whether or not the terminal type supports extensions to the 3270 data stream:

Yes: extensions are supported. You must specify Yes if you also specify yes for Color or Hilight.

No: extensions are not supported.

HIlight(Yes|No) | Indicates whether or not the terminal type has the extended highlight feature, allowing individual fields or characters to be displayed in bold, reverse video, or blinking
Katakana(No|Yes) | Indicates whether or not the this terminal type is a Katakana terminal type. Katakana terminals do not support mixed case output. Upper-case characters appear as upper-case English, but lower-case characters appear as Katakana characters.
Lightpen(No|Yes) | Indicates whether or not the terminal type has the light pen selector feature. MSS emulates this feature using mouse clicks.
PRIntadapter(Yes|No) | Indicates whether or not output BMS screens with the PRINT option set on are to be copied automatically to an attached printer.
PROgsymbols(No|Yes) | Indicates whether or not the terminal type supports the programmed symbol facility. This facility allows you to use a maximum of six sets of 191 characters.
OUtline(No|Yes) | Indicates whether or not the terminal type supports field outlining
SOsi(No|Yes) | Indicates whether or not the terminal type supports mixed EBCDIC and DBCS fields
CGcsgid(num1,num2) | Specifies the coded graphic character set global identifier (CGCSGID) that enables transaction programs to determine what character set is supported by this terminal. Defaults to 0,0, which means that the terminal type does not support this feature. num1 is the graphic character set global identifier (GCSGID) and num2 is the code page global identifier (CPGID).
Session Properties
AScii(No|7|8) Specifies whether or not this terminal type has an ASCII feature:

No: the terminal type does not have an ASCII feature

7: Terminals of this type are ASCII-7 terminals. All outbound data is translated to 7-bit ASCII, and all inbound data is translated to EBCDIC

8: Terminals of this type are ASCII-8 terminals. All outbound data is translated to 8-bit ASCII, and all inbound data is translated to EBCDIC

SENdsize(number) | Specifies the size, in bytes, of the receive buffer of a terminal of this type. This represents the maximum amount of data that the terminal can receive, and depends on the capability of the device. Considerations of line quality may lead you to specify a buffer size that is less than the terminal type's maximum buffer size. A message longer than the receive buffer is broken into as many request units as are necessary. Defaults to 0 (zero). If you specify a zero buffer size, the message is not broken up; the whole message is presented.
RECEivesize(number) | Specifies the maximum size, in bytes, of a request unit that can satisfy a receive request. The value you specify may be rounded down.
Diagnostic Display
ERRLastline(No|Yes) Indicates whether or not error messages are displayed at the bottom of the screen:

Yes: an error message is displayed at the bottom of the screen, starting at a position that allows the entire message to be shown at once. If messages are received in quick succession, an earlier message may be overwritten before the user has time to read it. Messages displayed in this way may have the additional attributes specified in ERRIntensity, ERRColor and ERRHilight.

No: an error message is displayed at the current cursor position, and without any additional attributes.

ERRIntensify(No|Yes) | Indicates whether or not an error message is displayed in an intensified field (bold). A setting of Yes takes effect only if ERRLastline is set to Yes.
ERRColor(NO|Blue|Red|Pink|Green|

Turquoise|Yellow|Neutral)

Specifies the color in which error messages are to be displayed on a terminal of this type. A setting other than NO takes effect only if ERRLastline is set to Yes.
ERRHilight(No|Blink|Reverse|

Underline)

Specifies the type of highlighting to be used for error messages displayed on a terminal of this type. A setting other than No takes effect only if ERRLastline is set to Yes.
Operational Properties
AUTOConnect(No|Yes) Indicates whether or not a session with the terminal is established when the region starts up:

Yes: a session is established when the region starts up

No: a session is established when the user signs on at the terminal

ATi(No|Yes) | Indicates whether or not a transaction can be automatically initiated on this terminal. If you specify ATi(No), you should specify TTi(Yes) to allow users to initiate transactions.
TTi(Yes|No) | Indicates whether or not users can initiate transactions at this terminal. If you specify TTi(No), you should specify ATi (Yes) to allow transactions to be automatically initiated.
CReatesess(No|Yes) Indicates whether or not a session can be initiated from a terminal of this type:

Yes: EXEC START requests and Automatic Transaction Initiation (ATI) requests are allowed to create sessions automatically

No: EXEC START requests and Automatic Transaction Initiation (ATI) requests are not allowed to create sessions automatically. Such requests are queued or rejected if a session has not been established.

Nepclass(number) | Specifies the transaction class of the node error program. Defaults to 0 (zero), which indicates that the default node error program is to be used.
Signoff(No|Yes) Indicates whether or not a terminal of this type is to be automatically signed off in the absence of user input:

Yes: the terminal is to be automatically signed off after a period of no user input; the length of this period is specified in the Timeout field of the user's entry in the sign-on table.

No: the terminal is not automatically signed of in the absence of user input.

Message Receiving Properties
ROutedmsgs(No|Yes) Indicates whether or not messages are routed to a terminal of this type by the EXEC CICS ROUTE command:

Yes: BMS routes to this terminal messages that are destined for all terminals, as well as messages destined for this terminal

No: no messages are routed to this terminal, even if they are specifically destined for this terminal

LOGOnmsg(No|Yes) Indicates whether or not the transaction that displays the logon message will be initiated when this terminal is connected:

Yes: the logon transaction is initiated when a session is established and displays the logon message on the terminal. Automatic Transaction Initiation (ATI) is used to start the transaction, so you must specify ATi(Yes). The transaction competes with any other ATI transactions for use of the terminal. If you specified ErrLastline(Yes), the logon message does not overwrite any error message currently displayed.

No: the logon transaction is not initiated when a session is established.

Application Features
BUildchain(No|Yes) Indicates whether or not MSS is to reassemble request units into complete messages before passing data from a terminal of this type to a transaction program:

Yes: MSS reassembles request units into a complete message before passing it to a transaction program.

No: messages are received by the transaction program in individual request units.

USerarealen(number) | Specifies the size, in bytes, of the user area of a terminal of this type. Defaults to 0 (zero).
Ioarealen(min,max) Specifies the minimum and maximum sizes, in bytes, of the terminal I/O area to be passed to a transaction program when it issues a RECEIVE. If you specify min, a terminal I/O area of at least that size is passed to the transaction program. If you specify both values and a message longer than min but shorter than max is received, then a terminal I/O area of the maximum size is passed to the transaction program. A message longer than max causes the node abnormal condition program to send an exception response to the terminal. Defaults to 0,0.

If you specify ATi(Yes), you must specify a terminal I/O area of at least one byte.

UCtran(No|Yes|Tranid) Indicates whether or not data entered in lower case is to be translated to upper case:

Yes: data input in lower case is translated to upper case

No: data input in lower case is not translated to upper case

Tranid: transaction identifiers input in lower case are translated to upper case; not other input data is translated

Recovery
RECOVOption(Sysdefault|Clearconv|

Releasesess|Uncondrel|None)

Specifies how MSS recovers the session and returns the terminal to normal service:

Sysdefault: MSS selects the best recovery strategy based on session activity and the characteristics of the terminal

Clearconv: MSS sends a CLEAR request to reset the conversation state, or an UNBIND request if the session does not support the CLEAR request. MSS sends the CLEAR or UNBIND request only if the session was busy.

Releasesess: MSS sends an UNBIND request to clear the active session, if the session was busy.

Uncondrel: MSS sends an UNBIND request to clear the active session, whether or not the session was busy

None: the terminal session is not automatically recovered. If you specified AUTOConnect(Yes), the terminal is automatically reconnected

RECOVNotify(None|Message|

Transaction)

Specifies how the user is notified of system recovery:

None: the user is not notified

Message: a message is displayed on the terminal. The terminal must be capable of displaying BMS maps, and you must have specified ATi(Yes)

Micro Focus Extensions
_Featurebuff(No|Yes) Indicates whether or not BMS buffers formatted data streams that are sent to a terminal of this type:

Yes: When an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal only when it is full

No: When an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal for every command issued, filling up the page by appending blank lines if necessary

  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE TYPETERM(TT01AA01) GROUP(SAMPGRP)
DESCRIPTION(Sample terminal type definition)
       DEVICE(3270) SHIPPABLE(NO) PAGESIZE(24,80) ALTPAGE(24,80)
       OBOPERID(NO) DEFSCREEN(24,80) ALTSCREEN(24,80) APLKYBD(NO)
       APLTEXT(NO) AUDIBLEALARM(NO) COLOR(YES) COPY(NO)
       DUALCASEKYBD(NO) EXTENDEDDS(YES) HILIGHT(YES) KATAKANA(NO)
       LIGHTPEN(NO) PROGSYMBOLS(NO) FORMFEED(NO) OUTLINE(NO) SOSI(NO)
       CGCSGID(0,0) ASCII(NO) SENDSIZE(0) RECEIVESIZE(0)
       ERRLASTLINE(NO) ERRINTENSIFY(NO) ERRCOLOR(NO) ERRHILIGHT(NO)
       AUTOCONNECT(NO) ATI(NO) TTI(YES) CREATESESS(YES) NEPCLASS(0)
       SIGNOFF(NO) ROUTEDMSGS(NONE) LOGONMSG(NO) BUILDCHAIN(NO)
       USERAREALEN(0) IOAREALEN(0,0) UCTRAN(NO) RECOVOPTION(SYSDEFAULT)
       RECOVNOTIFY(NONE)
Parent topic: DEFINE TYPETERM
Related information
Resource Definitions


DEFINE _SIGNON

Defines user IDs and their level of access security to Enterprise Server resources.
Keyword | Description
Description(text) | Describes the sign-on record. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
_Password(password) The password that the user must supply to sign on to an enterprise server session.

Format: up to eight characters.

_OPIdent(name) An ID associated with the terminal.

Format: up to three alphanumeric characters.

_RSlkey(key,key1-key2) Specifies the resource keys owned by the user. A comma-separated list, each item in which may be any of the following:
nn
Toggle the specified resource key (nn is in the range 1 to 24).
mm-nn
Toggle resource keys in the range mm to nn inclusive (mm and nn are in the range 1 to 24).
_SCtykey(key,key1-key2) Specifies the security keys owned by the user. A comma-separated list, each item in which may be any of the following:
nn
Toggle the specified security key (nn is in the range 1 to 64).
mm-nn
Toggle security keys in the range mm to nn inclusive (mm and nn are in the range 1 to 64).
_USerkey(key,key1-key2) Specifies the surrogate keys owned by the user. A comma-separated list, each item in which may be any of the following:
nn
Toggle the specified surrogate key (nn is in the range 1 to 24).
mm-nn
Toggle surrogate keys in the range mm to nn inclusive (mm and nn are in the range 1 to 24).
_Timeout(minutes) Specifies the time, in minutes, for which the user will remain logged on to theTransaction System without initiating a transaction. A value of 0 means that the user will remain logged on indefinitely.

Format: 0 to 60.

_OPPrty(value) Specifies the priority of transaction programs started by this user. 0 is the highest priority, and 255 is the lowest. The priority of a transaction is the sum of:
  • The terminal priority
  • The transaction priority
  • The operator priority (this field)

This sum must not be greater than 255.

Format: 0 to 255.

_GRPPrefix(value) Controls this user's access to private group definitions. The user can only access groups whose names begin with the characters specified here.

You cannot specify a prefix that begins with "DFH".

If you do not specify a group prefix, the user cannot access any private group definitions.

Format: up to eight characters.

_GRPAccess(Update|Read|None) Specifies the type of access this user will be granted to group definitions.

The permissions specified here do not apply to groups whose name begins with "DFH".

In the case of private groups, the access granted here applies only to those groups whose name begins with the user's group prefix.

_PCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to PCT definitions.
_FCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to FCT definitions.
_PPtaccess(Update|Read|None) | Specifies the type of access this user will be granted to PPT definitions.
_DCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to transient data queue/destination control table (DCT) definitions.
_SItaccess(Update|Read|None) | Specifies the type of access this user will be granted to SIT definitions.
_SNtaccess(Update|Read|None) | Specifies the type of access this user will be granted to sign-on table (SNT) definitions.
_TStaccess(Update|Read|None) | Specifies the type of access this user will be granted to temporary storage (TST) definitions.
_JCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to journal control table (JCT) definitions.
_TTyaccess(Update|ReRead|None) | Specifies the type of access this user will be granted to terminal type (TTY) definitions.
_TRmaccess(Update|Read|None) | Specifies the type of access this user will be granted to terminal definitions.
_PLtaccess(Update|Read|None) | Specifies the type of access this user will be granted to program list table (PLT) definitions.
_SUpaccess(Update|Read|None) | Specifies the type of access this user will be granted to start-up list definitions.
_XLtaccess(Update|Read|None) | Specifies the type of access this user will be granted to XLT definitions.
_BAtaccess(Update|Read|None) | Specifies the type of access this user will be granted to batch processing.
_XAtaccess(Update|Read|None) | Specifies the type of access this user will be granted to XAT definitions.
_Imsaccess(Update|Read|None) | Specifies the type of access this user will be granted to IMS processing.
_JCLsubauth(Yes|No) | Specifies whether or not this user will be granted authority to submit JCL.

Example

DEFINE _SIGNON(FRED)
           DESCRIPTION(Fred’s system access)
       _PASSWORD(GUEST) _OPIDENT(SYS) _OPPRTY(255) _TIMEOUT(0)
       _RSLKEY(01-24) _SCTYKEY(01-64)
       _JCLSUBAUTH(NO) _GRPACCESS(UPDATE) _PCTACCESS(UPDATE)
       _FCTACCESS(UPDATE) _PPTACCESS(UPDATE) _DCTACCESS(UPDATE)
       _SITACCESS(UPDATE) _SNTACCESS(UPDATE) _TSTACCESS(UPDATE)
       _JCTACCESS(UPDATE) _TTYACCESS(UPDATE) _TRMACCESS(UPDATE)
       _PLTACCESS(UPDATE) _SUPACCESS(UPDATE) _XLTACCESS(UPDATE)
       _XATACCESS(UPDATE) _BATACCESS(UPDATE) _IMSACCESS(NONE)
Parent topic: CICS Resource Definitions


Abend Codes in CICS Transactions

Unhandled transaction program abends are reported through the TXKC0001E system message. Generally these abends are caused by a standard CICS error condition. The abend codes (and descriptions) in these cases are the same as the abend codes issued for those conditions in the mainframe environment.

In addition to these errors, the emulator can encounter conditions that do not match a standard CICS error condition but where the transaction cannot proceed successfully and so must be abended. These abend codes are:

  • ASSA
  • EXIF
  • FUNC
  • IRST
  • LANG
  • MATP
  • MBLL
  • MCOM
  • MUSR
  • RECU
Parent topic: Enterprise Server for .NET Reference Information
Related information
IBM CICS/ESA Messages and Codes


ASSA

Your development system issues the ASSA abend code if it encounters either of the following:

  • an invalid resource name
  • a lack of storage

when it is dynamically creating a resource entry (for example, a PPT entry).

Use the diagnostic tools and log files to determine the cause of the error.

Parent topic: Abend Codes in CICS Transactions


EXIF

Your development system issues the EXIF abend code if your program calls the CICS API with parameters that do not conform to the specifications. The most likely cause is that the transaction program was compiled from a translated source file that has been modified incorrectly.

Parent topic: Abend Codes in CICS Transactions


FUNC

The FUNC abend code is issued when an unsupported CICS API function is requested. It is caused by the execution of an EXEC CICS command that was identified by the preprocessor as unsupported and the /CICSECM(FUNCTION=ABEND) preprocessor directive (abend at execution) was specified.

Parent topic: Abend Codes in CICS Transactions


IRST

The IRST abend code is issued when the program control functions for saving and restoring Working Storage have encountered an illogical condition; generally a system error.

Parent topic: Abend Codes in CICS Transactions


LANG

The LANG abend code is issued when different dialects of COBOL are mixed in a run unit, for example, a program written in VS COBOL II calls a program written in OS/VS COBOL.

Parent topic: Abend Codes in CICS Transactions


MATP

The MATP abend code is issued when there is insufficient memory for the API Emulation server to allocate the control block needed for the target program of a LINK, XCTL, or VS COBOL II CALL.

Parent topic: Abend Codes in CICS Transactions


MBLL

The MBLL abend code is issued when there is insufficient memory for the API Emulation server to allocate the BLL Cell List area for an OS/VS COBOL transaction program.

Parent topic: Abend Codes in CICS Transactions


MCOM

The MCOM abend code is issued when there is insufficient memory for the API Emulation server to allocate a COMMAREA to be passed to a user transaction program invoked through XCTL.

Parent topic: Abend Codes in CICS Transactions


MUSR

The MUSR abend code is issued when there is insufficient memory for the API Emulation server to allocate the file or terminal buffer for data to be returned to the user transaction program.

Parent topic: Abend Codes in CICS Transactions


RECU

The RECU abend code is issued when an attempt is made to CALL (using DFHEIBLK) a user transaction program that is already active in the current CICS LINK level.

Parent topic: Abend Codes in CICS Transactions


Developing Mainframe Managed Subsystem Applications

The topics in this section describe how to develop and debug Enterprise Server for .NET applications.

  • About Developing Enterprise Server for .NET Applications
  • Creating a Managed Code Project
  • Configuring Project Properties
  • Project Properties Reference
  • Compiling a Project
  • Configuring and Running the Debugger
  • REST Web Services and EXCI
Parent topic: Development Role


About Developing Enterprise Server for .NET Applications

You can develop and maintain CICS batch applications in the Enterprise Server for .NET environment. These can be migrated applications that currently operate in the native Enterprise Server environment, or new CICS and batch applications.

  • Working with Programs
  • Working with BMS Maps
  • Working with VSAM Data
Parent topic: Developing Mainframe Managed Subsystem Applications


Working with Programs

Mainframe Managed Subsystem Application projects are used for building the executable artifacts for deployment to a managed-code CICS or batch execution environment.

As with other Enterprise Developer programs, use the Visual Studio IDE to edit the source and compile these projects.

Parent topic: About Developing Enterprise Server for .NET Applications
Related tasks
To Import Existing Project Components


Working with BMS Maps

You can include native Enterprise Server BMS maps with your Enterprise Server for .NET projects, and include them in the compile process. You can edit a BMS map from within Visual Studio by right-clicking the BMS file and selecting BMS Painter or by opening the BMS file normally and editing it as code.

BMS maps added to a Mainframe Managed Subsystem Application project are compiled when the project is built.

Parent topic: About Developing Enterprise Server for .NET Applications


Working with VSAM Data

You can configure and deploy VSAM data files as data stores, so that they are available to the applications running in regions.

There are three configuration options for configuring a VSAM data store:

  • Import a VSAM files as an Enterprise Server for .NET Data Store.
  • Access VSAM files on a native Enterprise Server Fileshare server.
  • Store the file on disk, and configure the location, so that the region can access it.
Note: You configure and administer the VSAM data using the Enterprise Server for .NET configuration and administration user interface that runs in the Microsoft Management Console ( MMC).
Parent topic: About Developing Enterprise Server for .NET Applications
Related tasks
To Configure a Resource Definition for a VSAM File On Disk
To Add a Data File using MMC


Creating a Managed Code Project

You can create an empty project in the Visual Studio IDE, then create the programs and the other components that it uses.

You can create a managed code project based on an existing mainframe application or an existing native Enterprise Server project.

When importing existing COBOL source files into a project, the import process scans the source file. For each imported file, this scan determines the COBOL dialect, and whether or not it needs to be compiled with the CICS ECM. It then sets the file-level properties accordingly.

  • To Create a Managed Project
  • To Import Existing Project Components
Parent topic: Developing Mainframe Managed Subsystem Applications


To Create a Managed Project

Use this procedure to create a new managed code project.
  1. Open Enterprise Developer from the Windows Start menu to display Microsoft Visual Studio.
  2. From the File menu, choose New > Project. The New Project dialog box appears.
  3. In the .NET Framework list, select .NET Framework 4.
  4. In the Installed Templates list, select COBOL, Managed, and in the right pane, select Mainframe Managed Subsystem Application.
  5. At the bottom of the New Project dialog box, type the Name, Location, and Solution Name details.
  6. Click OK to create the project. The project is created.
Parent topic: Creating a Managed Code Project


To Import Existing Project Components

Use this procedure to import existing application components into your Enterprise Server for .NET project.
  1. From the Project menu, choose Add Existing Item.
  2. Use the Browse dialog box to locate and select the source files to add. Use the Ctrl key to select multiple files, and the Shift key to select ranges of files.
  3. From the Add button list, select how you want to add the files:
    • Select Add to create copies of the files in your project folder.
    • Select Add As Link to create links to the files in your project folder.

      If source files are added as links to a native Enterprise Server project location, any changes made to the files apply to both the native and managed code projects. If the source files are copied into the managed code MSS project folder, changes apply only to the managed code MSS project.

  4. Click Add to add the files to your project. The files are added to your project and are ready for use. The process scans each file, and determines characteristics such as the COBOL dialect. The properties the scan process detects are set as the file-level properties.
Parent topic: Creating a Managed Code Project
Related concepts
Working with Programs


Configuring Project Properties

You can configure project properties at either the project or the component level.
  • Properties configured at the project level apply to all related project components.
  • Properties configured at the component level apply only to that particular component.

An n Enterprise Server for .NET project contains the following properties specific to Enterprise Server for .NET:

  • Application

    This includes the Compile to multiple assemblies property, which must be selected. Selecting this property ensures the compile process produces a DLL file for each assembly, rather than a single DLL that contains all assemblies in the project.

  • SQL

    This includes properties for configuring the ESQL preprocessor type and the directives to use.

  • Copybook paths

    This property configures the paths for any copybooks that the project contains. Set this property to allow for copybooks not located in the default project folder.

  • COBOL
    This includes properties for configuring COBOL language-related properties, including:
    • Whether or not debugging is activated
    • The COBOL dialect to use
    • Compiler options
    • Warning levels
  • Debug
    This includes properties to configure:
    • The database server instance hosting the debug session
    • The region in which the application to be debugged operates
    • CICS transaction details
  • To Configure the Project Properties
  • To Configure the Properties for a Source File
Parent topic: Developing Mainframe Managed Subsystem Applications


To Configure the Project Properties

  1. From the Solution Explorer pane at the right of the screen, double-click the Properties item.

    The project's Properties view displays.

  2. In the left pane, select the project area to configure.

    The areas specific to Enterprise Server for .NET projects are:

    • Application
    • SQL
    • Copybook Paths
    • BMS
    • COBOL
    • Debug
  3. Configure the required project settings, then save and compile the project to apply the settings.

The Output path on the COBOL settings tab and the Load module output path on the BMS settings tab must have corresponding locations in the region startup file for the CICS execution environment to locate the files.

Parent topic: Configuring Project Properties


To Configure the Properties for a Source File

In addition to configuring project-wide properties, you can also configure properties at the source file level. Properties set at the source file level override any applicable project-level properties.
Note: You can set the same properties for multiple source files by selecting more than one file.

Use this procedure to configure source file properties.

  1. In the Solution Explorer in the right pane, right-click a source file or files and choose Properties. A dialog box appears with the available properties for the selected file or files.
  2. Set the properties as required, and click OK. The selected file or files' properties are set.
Parent topic: Configuring Project Properties


Project Properties Reference

This section details properties specific to Enterprise Server for .NET projects.

  • Application Project Properties
  • COBOL Project Properties
  • Debug Project Properties
  • Copybook Paths Project Properties
  • SQL Project Properties
Parent topic: Developing Mainframe Managed Subsystem Applications
Related concepts
To Configure the Project Properties


Application Project Properties

There is one Application project property for Enterprise Server for .NET. The Compile to multiple assemblies property must be selected. Selecting this property ensures the compile process produces a DLL file for each assembly, rather than a single DLL that contains all assemblies in the project. This property is selected by default.

Parent topic: Project Properties Reference


COBOL Project Properties

The COBOL properties that can be set are:

General section

Platform target
The platform on which the application runs.
Note: Managed-code MSS programs must be compiled with the Any CPU option to allow them to be deployed to both x86 and x64 operating systems. It is recommend that you do not use the x86 or x64 options.
Source Format
Can be set to one of the following:
  • Variable
  • Fixed
  • Free
Compile for debugging
Select this checkbox to compile the program for debugging.
Generate 64-bit pointers
this should never be checked for MSS type projects.
Advanced - Additional copybook paths
Enter any additional paths that contain copybooks. The application searches these paths if it cannot find the specified copybook in the paths set at the project level. Click this button to configure commands that execute before the build process commences, and after the build process completes.
Advanced - Generate directives file
Select this checkbox to generate a .DIR file that lists the directives used by the compiler.
Advanced - Build Events
Click this button to configure commands that execute before the build process commences, and after the build process completes.

Mainframe section

Exec CICS
Select this checkbox to set the CICSECM options. You can configure:
  • How the application handles unsupported functions
  • How the application handles unsupported options
  • Additional CICSECM options

Errors and warnings section

Set the warning level to use, and how to handle errors and warnings that the application generates.

Additional directives section

Add additional COBOL compiler directives specific to your CICS application here.

The charset(ascii) directive is inserted by default when you create a project. The current release of Enterprise Server for .NET does not support EBCDIC.

Output

Configures the location where the build process creates the output. This is the location that you configure for components in a region's startup file. You can also configure the following:

Parent topic: Project Properties Reference
Related concepts
Copybook Paths Project Properties
SQL Project Properties
To Define a New Region With an Existing Region Startup File


Debug Project Properties

The debug properties that you can set are:
Database Server Instance
The database server instance for the region that hosts the application to debug.
Region Name
The name of the region that hosts the application to debug.
CICS User
You can restrict the debugger to debug only transactions from a specific user. If you leave this field empty, the debugger debugs transactions from any user.
Terminal
You can restrict the debugger to debug only transactions from a specific terminal ID. If you leave this field empty, the debugger debugs transactions from any terminal.
Transaction
You can restrict the debugger to debug only specific transactions. If you leave this field empty, the debugger debugs all transactions.
Parent topic: Project Properties Reference


Copybook Paths Project Properties

You can set the path or paths that the project searches to find copybooks that the application uses. You can define a single path or multiple paths. If you define multiple paths, the application searches the paths in the order listed, and uses the first copybook it finds.

Parent topic: Project Properties Reference
Related concepts
SQL Project Properties
COBOL Project Properties
To Define a New Region With an Existing Region Startup File


SQL Project Properties

The SQL properties that you can configure for a project are:
ESQL Preprocessor
This defines the preprocessor to use. The only option available for Enterprise Server for .NET projects is OpenESQL.
Directives
You can configure the ESQL directives that the project uses. For each directive, you can configure the directive value.
Note: You can also set these properties at the project component level.
Parent topic: Project Properties Reference
Related concepts
Copybook Paths Project Properties
COBOL Project Properties
To Define a New Region With an Existing Region Startup File


Compiling a Project

An Enterprise Server for .NET project must be compiled as multiple assemblies. The compile process produces a DLL file for each assembly rather than a single DLL that contains all assemblies in the project.

The project's Application properties includwe the Compile to multiple assemblies property. This property is selected by default. This property ensures that the compile process produces a DLL for each component rather than a DLL that contains all components.

  • To Compile a Project
Parent topic: Developing Mainframe Managed Subsystem Applications


To Compile a Project

When compiling an Enterprise Server for .NET project:

  • Choose Build > Build Solution to recompile all programs in all projects in the solution.

  • Choose Build > Rebuild Solution to recompile all programs with sources or dependencies that have changed in all projects in your solution.

When compiling a project:

  • Choose Build > Build <Project> to recompile all programs in the selected project.

  • Choose Build > Rebuild <Project> to recompile all programs with sources or dependencies that have changed in the selected project.

The application is compiled to a .NET assembly, packaged as .DLL files for each program.

Parent topic: Compiling a Project


Configuring and Running the Debugger

Use this procedure to configure and run the debugger.

  1. In Visual Studio, create a debug-enabled version of the project.

    To do this, enable debugging for the project, then configure the output paths for the compiled debug version.

  2. Compile the debug version of the project.

    This creates the mapsets and programs that the region uses during debugging.

  3. Configure the region.

    To do this, configure the region startup file to use the debug-enabled versions of the programs that you created.

    Tip:

    As an alternative, once a region is running, you can enable the region for dynamic debugging.

  4. Start the region, create a terminal connection, and log on to the region.
  5. In Visual Studio, start a debug session and set breakpoints as needed.

    Visual Studio must be started with administrator permissions ( right click Visual Studio and run as administrator).

    Failing to do so will cause the debug session to fail with the debug sep.exe process reporting access denied errors to the net.tcp port sharing service.

  6. In your terminal session, generate transactions that trigger the breakpoints that you set
  7. In Visual Studio, use the tools available to step through your code and set and clear breakpoints as required.
  • To Configure a Project for Debugging
  • To Configure a Region for Debugging
  • To Enable Dynamic Debugging
  • To Start and Run the Debug Session
  • Debugging Tutorial
Parent topic: Developing Mainframe Managed Subsystem Applications


To Configure a Project for Debugging

You must configure the project within Visual Studio to enable debugging.

  1. Use the Microsoft Visual Studio File, Open, Project Solution option to browse to, and open the project file to debug.
  2. From the Project menu, select Properties, and on the left of the screen, select the COBOL tab.
  3. In the General area, select the Compile for Debugging checkbox.
  4. On the left of the screen, select the Debug tab, and configure the screen as follows:
    Database Server Instance
    The database server instance for the region that hosts the application to debug.
    Region Name
    The name of the region that hosts the application to debug.
    CICS User
    You can restrict the debugger to debug only transactions from a specific user. If you leave this field empty, the debugger debugs transactions from any user.
    Terminal
    You can restrict the debugger to debug only transactions from a specific terminal ID. If you leave this field empty, the debugger debugs transactions from any terminal.
    Transaction
    You can restrict the debugger to debug only specific transactions. If you leave this field empty, the debugger debugs all transactions.
Parent topic: Configuring and Running the Debugger
Related concepts
To Configure a Region for Debugging
To Start and Run the Debug Session
Related tasks
Debugging Tutorial


To Configure a Region for Debugging

You can configure a region startup definition to enable debugging, and to use the locations that contain the debug-enabled components.

Note:

As an alternative, once a region is running, you can enable the region for dynamic debugging.

  1. In the SEE Administration snap-in, select the region to debug, and edit the region's startup file.
  2. In the Region Startup File Editor's left pane, select Region.
  3. In the right pane under Debug, set Allow Dynamic Debugging to True.
  4. In the left pane, select Locations.
  5. For both the Map Files and Programs items, right-click and select Add, Folder Location.
  6. Add the output folder that contains the debug Map and Program locations.
  7. Save the startup file, stop, then cold-start the region.
Parent topic: Configuring and Running the Debugger
Related concepts
To Configure a Project for Debugging
To Start and Run the Debug Session
To Enable Dynamic Debugging
Related tasks
Debugging Tutorial


To Enable Dynamic Debugging

The project that you use must be configured for debugging, and the region must be started and running.

As an alternative to configuring a region's definition file for debugging, you can enable a running region dynamically for debugging.
  1. Ensure that the region is running.
  2. In the Enterprise Server for .NET user interface, choose SEE Administration > Regions.
  3. In the regions list, select the region for which you want to enable dynamic debugging, then select Dynamic Debugging in the Actions pane.

    The Dynamic Debugging status displays in the Results pane. The display lists any active debugging sessions operating for the region.

  4. In the Results pane, click Enable.

    Dynamic debugging is enabled for the region, and the button caption changes to Disable.

To disable dynamic debugging for the region, click Disable.
Parent topic: Configuring and Running the Debugger
Related concepts
To Configure a Region for Debugging
Related tasks
Configure the Region for Debugging


To Start and Run the Debug Session

You must have a listener configured to connect to the debug region.

Use a terminal session to connect to the debug region and start the process to be debugged.

  1. In the Visual Studio IDE, set breakpoints in the source code where you want the debugging to stop.
  2. In the Visual Studio IDE, press F5, or from the menu, choose Debug > Start debugging .
  3. Start a 3270 terminal and connect to the debug-configured region.

    The Sign on to CICS login screen appears.

  4. Clear the screen, and enter the transaction to debug.

    In Visual Studio, the code breaks at the set breakpoint.

  5. Use the debug actions to step through the code as needed.
  6. To stop debugging, choose Debug > Stop debugging from the Visual Studio menu.
Parent topic: Configuring and Running the Debugger
Related concepts
To Configure a Project for Debugging
To Configure a Region for Debugging
Related tasks
Debugging Tutorial


Debugging Tutorial

This tutorial steps through debugging a program. It uses the ACCT transaction in the ESDEMO sample region included in the installation software.

By default, the demonstration region software is installed to %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\ACCT.

Note: This tutorial assumes that you have run the installation verification procedure outlined in the Configuration and Administration help. The tutorial uses the ESDEMO region configuration used to verify the installation, and the listener configured for the verification procedure.
  • Configure the ACCT Transaction Program
    In this stage, you configure the ACCT program to enable debugging, and build the program.
  • Build the Debug Transaction
    In this stage, you build the debug-enabled version of the program.
  • Configure the Region for Debugging
    In this stage, you configure the ESDEMO region to enable debugging, and to use the debug-enabled ACCT transaction that you created.
  • Start Debugging
    In this stage, you start a terminal session to connect to the debug region and start the debug process in Visual Studio.
Parent topic: Configuring and Running the Debugger


Configure the ACCT Transaction Program

Note: You can change the default output location for the debugging version, and use the modified location when you configure the region.
  1. From the Windows Start menu, select Start > All Programs > Micro Focus Enterprise Developer > Enterprise Developer for Visual Studio 2010 to open Visual Studio.
  2. Choose File > Open > Project Solution to navigate to and open the ACCT.sln project file.

    The default location for this file is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet \ACCT.

  3. From the Microsoft Visual Studio Project menu, choose Properties, then select the COBOL tab.

  4. In the General area, select the Compile for debugging checkbox.
  5. Scroll to the Output area, and check the Output path value.

    This is where the compiled debug-enabled ACCT program is created. The default location is the bin\debug folder located under the project folder. Note of this location. You need it to configure the region that the debug process uses.

  6. Select the Debug tab, and set the following fields:
    Database Server Instance
    Your database server instance.
    Region Name
    ESDEMO, the region in which ACCT runs.
    CICS User, Terminal, and Transaction
    You can restrict the debugger to debug only transactions from a specific user, terminal or transaction. For this tutorial, type AC* in the Transaction field to filter all transactions beginning with AC, to trap the ACCT transaction.
Parent topic: Debugging Tutorial


Build the Debug Transaction

  1. In Microsoft Visual Studio, open ACCT00.CBL in the editor, and configure program debugging.
  2. Save the project and build the solution.

    The build process displays messages in the Output area to show the build progress.

  3. Use Windows Explorer to navigate to the output folder that you configured and check that the output is created.
Parent topic: Debugging Tutorial


Configure the Region for Debugging

As an alternative to configuring the region definition file, you can enable dynamic debugging once the region starts.

  1. Open the MMC and load the SEE Administration snap-in.
  2. Select the ESDEMO region and edit the region's startup file.
  3. In the Region startup file editor, select Region.
  4. In the right pane under Debug, set Allow Dynamic Debugging to True.
  5. In the left pane, select Locations.
  6. Right-click Map Files and choose Add > Folder Location. Add the configured debug output folder. If multiple locations are listed, ensure that the folder you add is at the top of the list. This ensures that the region uses the debug version of the ACCT transaction rather than the non-debug version.
  7. Repeat the previous step to configure the location for Programs.
  8. Save the region startup file, then stop and cold-start the region.
Parent topic: Debugging Tutorial
Related concepts
To Enable Dynamic Debugging


Start Debugging

For this stage, use the listener that you configured in the installation verification procedure. See To Configure and Start the ESDEMO listener in the online help for instructions.

  1. In the Visual Studio IDE, press F5, or choose Debug > Start debugging from the menu to start debugging.
  2. In the code, scroll down to the Procedure division, and set a breakpoint on the first line: EXEC CICS HANDLE CONDITION MAPFAIL(NO-MAP)
  3. Set any other breakpoints that you would like.
  4. Start a 3270 terminal and connect to the region.

    The Sign on to CICS login screen appears.

  5. Clear the screen, and enter acct to start the transaction.

    In Visual Studio, the code breaks at the set breakpoint.

  6. Use the debug actions to step through the code as required, and to set additional breakpoints as required.
  7. To stop debugging, choose Debug > Stop debugging from the Visual Studio menu.
Parent topic: Debugging Tutorial


REST Web Services and EXCI

This section discusses creating transaction and client programs for CICS REST web services and EXCI (External Call Interface).

  • About CICS REST Web Services
  • About CICS External Call Interface
  • The REST Interface
    The REST web service interface, from the development perspective.
  • REST Client APIs
  • Server Program Considerations for REST Services
  • The EXCI Interface
    The EXCI interface, from the development perspective.
  • EXCI Client APIs
  • The EXCI User Exit
  • Server Program Considerations for EXCI
Parent topic: Developing Mainframe Managed Subsystem Applications


The REST Interface

CICS REST web services are a feature of Enterprise Server for .NET for invoking CICS transaction programs from outside the CICS region, using HTTP. They are described in more detail in About CICS REST Web Services.

Since REST web services use HTTP, the interface is composed of HTTP methods, URLs, headers, message bodies, and response codes.

Methods

REST web services use the method of the HTTP request message to indicate to the server what sort of action to perform. Enterprise Server for .NET CICS REST services currently support the GET and POST methods. The only difference between these two methods is how the client program's application data, if any, is passed to the CICS region. The method does not affect how the application transaction program receives the data — in either case it is passed as a CICS commarea.

With the GET method, the request data is sent as a query string appended to the Request-URI. This is the part of the URL path after the "?" character. The request data must be in string form, must be encoded using the HTTP URL-encoding rules, and must be specified as the value of the commarea parameter. An example of the beginning of a GET request:
GET /rest/default/TRAN?commarea=Test%20data HTTP/1.1

A request using the POST method passes the application data in the message body, after the HTTP header block. In this case it is encoded as a JSON (Javascript Object Notation) object, containing the commarea data as either a string or an array of bytes, as described in more detail below.

If the client application does not need to pass any data to the service, the GET method should be used.

URLs

A client invokes a REST service by specifying a URL (Universal Resource Locator), which specifies the protocol or scheme ("http"), the host and port to connect to, a resource path, and optionally a query string (as described under "Methods" above). The path and query parts of the URL become the Request-URI of the request message sent to the server. (URI, for Universal Request Identifier, is a technical term for a class of strings that includes URLs.)

Enterprise Server for .NET CICS uses the path part of the Request-URI to determine which REST service configuration applies to the request, and which CICS transaction program to invoke. The last element of the path is the name of the transaction program: it should match a CICS PCT definition in the region (either configured at region startup, or installed dynamically while the region is running). The other path elements are matched against REST service configurations specified in the region startup file, which can contain wildcards; see Configuring REST Web Services. A REST service configuration can specify various optional parameters that affect how the service works. If there is no matching configuration, the request is rejected.

In the example given above in the "Methods" section, the transaction program that will be invoked is named TRAN, and the configuration that will be used is the one that best matches /rest/default. The "best match" is determined by the smallest number of substitutions that have to be made to replace wildcard characters in the configuration path with characters from the Request-URI. For example, this path would match /rest/d* more closely than it would match /rest/*.

Note: URLs are case sensitive.

Headers

HTTP messages include a series of headers describing the message, and the REST web services feature makes use of some of them.

Some headers are required by the HTTP protocol itself, as described in the IETF standard RFC 2616 (available from rfc-editor.org and various other sources). These will generally be applied automatically by a client framework or library for the request, and handled automatically when processing the response: the application usually does not have to deal with them. There are a few headers which are significant for CICS REST web services:

  • CICS REST web services use JSON encoding for message bodies, as described in the next section, so when a request or response message includes a body, it should also include the header Content-Type: application/json.
  • If a message body is present in a request, the request also needs to indicate the length of the body, either with the Content-Length header, or by including the Transfer-Encoding: chunked header and using the "chunked" protocol (see RFC 2616 for more information).
  • Enterprise Server for .NET currently sends Server: Micro Focus Enterprise Server for .NET to identify itself in its responses.
  • Enterprise Server for .NET does not currently support HTTP persistent conversations, so it always sets the Connection: close header in its responses.

Message bodies

As described above, a REST web service request that uses the POST method to send application data in a request will put the data in the HTTP message body. Similarly, if there is any application data in the response to a REST web service (that is, if the transaction program puts data in its commarea before returning to CICS), that will be sent back to the client as the message body of the HTTP response.

In either case, the message body is encoded using JSON, the Javascript Object Notation, a standard plain-text encoding that is specified by the IETF standard RFC 4627. The JSON object represents the commarea in one of two forms, as an object with one member. The member can either be a string named commarea, or an array of bytes named binaryCommarea. (If both members are present in a request, binaryCommarea takes precedence and commarea is ignored.) The binaryCommarea version can be used for any commarea and is most useful when the application's commarea is defined in a way that is not convenient to represent as a string, such as a COBOL group item or an object that is serialized in binary form. commarea is a useful alternative when the commarea only contains text, since it's easy to generate and to read in traces.

An example of a string commarea:

{ "commarea": "text commarea data" }

An example of a binary commarea:

{ "binaryCommarea": [98, 105, 110, 97, 114, 121] }

In a Microsoft.NET managed program, you can use the JsonSerializer class to convert to and from JSON. The RestClient convenience class provided with Enterprise Server for .NET will automatically perform the conversion for client programs.

Response codes

Enterprise Server for .NET CICS REST web services use standard HTTP response codes, which are described in full in RFC 2616. Response codes, which appear on the first line of the HTTP response message, indicate the success or failure of the request, or other information about its status. A code in the range 200-299 indicates success; codes 400 and above are errors. The server currently uses the following codes:

  • 200 indicates the request was processed successfully.
  • 400 indicates the server did not understand the request, for example because it could not find a valid transaction ID in the Request-URI.
  • 403 is returned when the server does not have a REST service configuration that matches the Request-URI.
  • 500 signals an internal server error, such as an exception.

Usually server errors are handled by the client API and signalled to the client program by an error return code or an exception, but it is often useful to examine the response code and the body of the message (which will be a plain-text document with additional information about the error) to determine why the request failed.

Parent topic: REST Web Services and EXCI


REST Client APIs

You can use various APIs in a client program to invoke Enterprise Server for .NET CICS REST web services.

  • RestClient Class
  • Javascript AJAX APIs
  • Other REST Client APIs
Parent topic: REST Web Services and EXCI


RestClient Class

Micro Focus supplies a public class, MicroFocus.SEE.Comms.RestClient in the MicroFocus.SEE.Comms.Public.dll assembly, which can be used to make REST requests. It provides a simple interface for invoking the type of web service exposed by the CICS REST web service feature.

To use the RestClient class, construct a RestClient object using one of the new overloads. You can call new with a string containing the service URL, a .NET Framework Uri object representing the service URL, or with the host, port, and transaction ID as separate strings.

After creating the object, use either the MakeRequest or MakeBinaryRequest method of the object to make one or more requests. MakeRequest takes a string (which can be null) containing request data, and returns a string with the response data. MakeBinaryRequest takes a byte array (declared as binary-char unsigned occurs any in managed COBOL) for request data, which can be null, and returns a byte array with the response data. Both methods use the .NET Framework's WebRequest and JsonSerializer classes, which will raise exceptions if errors occur.

Parent topic: REST Client APIs


Javascript AJAX APIs

Most web browsers provide a Javascript API for invoking web services named XMLHttpRequest. You can use it along with other Javascript features to invoke Enterprise Server for .NET CICS REST web services from scripts on web pages and dynamically update the page content based on the response. Using this approach in web pages is often known as AJAX (Asynchronous Javascript and XML).

There are numerous online and print tutorials and references for XMLHttpRequest and AJAX.

Some additional configuration is required for CICS REST web services that will be invoked from a web page. See Configuring REST Web Services for AJAX.

Parent topic: REST Client APIs


Other REST Client APIs

Since Enterprise Server for .NET CICS REST web services use standard protocols, they can be invoked by clients using various framework and third-party APIs, with no Micro Focus libraries or licenses required on the client system (unless the client program is COBOL).

Managed-code .NET applications in any language can use framework classes such as WebRequest and JsonSerializer to make requests to CICS REST services, serialize application request data to JSON, and deserialize the JSON response. Refer to the framework documentation and MSDN for more information.

JVM applications, such as Java and COBOL for JVM programs, have a number of options for invoking REST services. The Java runtime includes HTTP client classes such as java.net.URL, and there are several open-source third-party implementations of REST client classes, JSON serializers, and so on.

There are also third-party libraries for native-code applications. Microsoft Windows includes the WinINet and WinHTTP APIs. The open-source cURL library has been used with native-code COBOL programs to communicate with REST web services.

Note: Micro Focus does not endorse or support these third-party APIs. This topic is for information purposes only and does not imply these APIs are suitable for any purpose.
Parent topic: REST Client APIs


Server Program Considerations for REST Services

Enterprise Server for .NET CICS REST web services invoke CICS transaction programs. There are some considerations when writing these programs.

Since a REST server program is a CICS transaction program, the top-level program specified in the PCT definition for the transaction should be a procedural managed-code COBOL program compiled with the CICSECM directive, just as with a program associated with a transaction you would initiate from a terminal session. (While the top-level program must be procedural, it can instantiate classes and invoke methods defined in managed-code OO COBOL assemblies, of course.)

REST server programs do not have a CICS primary facility (terminal session), and so they are not allowed to use certain CICS APIs, including any API dealing with terminal I/O or BMS such as EXEC CICS SEND MAP. REST server programs are limited to the DPL subset of the CICS API as defined by IBM, though this restriction may not be enforced in all cases.

For the same reason, REST server programs do not receive any terminal input. Application data supplied by the client is passed to the server program as a CICS commarea, and the server program uses the commarea for its response. The maximum size of the commarea is determined before the server program is executed, based on the size of the request data and the REST service configuration, so if the server needs to send a response that is larger than the client's request, the service configuration must specify the minimum commarea size. See Configuring REST Web Services. See the REST server sample program included with the product for an example of using the commarea.

REST services are non-conversational. No program state is maintained by the server between requests. Usually, if the application needs to maintain state, it is kept by the client and passed in each request (this is the REST design philosophy). Server programs can also use CICS facilities such as temporary storage to retain state between invocations, but be aware of potential complications such as performance costs.

Parent topic: REST Web Services and EXCI


The EXCI Interface

EXCI (External CICS Interface) is an IBM-defined API for non-CICS applications to execute programs under CICS, much as if they had been called from a CICS program using EXEC CICS LINK. For an introduction to EXCI see About CICS External Call Interface. For more information on the design of EXCI, see the IBM CICS documentation.

EXCI in Enterprise Server for .NET is implemented using a REST web service that invokes the system transaction CPMI. The standard CICS resource definition set supplied with the product includes a PCT definition for CPMI, but for security reasons the corresponding REST web service is not defined by default. Instructions for defining it can be found in Configuring a REST Web Service for EXCI.

In the native-code Enterprise Server, EXCI is implemented using IBM's CTG protocol. The EXCI client APIs support both REST and CTG, so you can invoke CICS programs running under both managed and native Enterprise Server.

To make an EXCI request, the client program invokes one of the EXCI client APIs (see EXCI Client APIs) with the appropriate parameters and options. The EXCI client layer uses the APPLID string supplied by the client application to find the URL for the EXCI REST service or CTG listener for the target CICS region. If the target is anEnterprise Server for .NET CICS region, the client constructs a request object and serializes it, then passes it to the REST service as the commarea for the CPMI transaction. The request object includes the name of the program that the client wants to invoke. CPMI invokes the program, passing the application request data. When the application program returns, CPMI constructs a response object which includes the application response (if any), as well as error codes and abend information. That is returned to the EXCI client layer, which deserializes the response and makes the information available to the client program. With native Enterprise Server, the process is somewhat different, but the results are essentially identical from the application's point of view.

To derive the service URL from the APPLID supplied by the caller, the EXCI client layer looks in the application configuration or web configuration for the client program. The URL may use the http scheme, to connect to Enterprise Server for .NET, or the ctg scheme for native Enterprise Server. It can also make use of an optional user exit routine to convert one APPLID to another. See Configuring EXCI for the client.

Parent topic: REST Web Services and EXCI


EXCI Client APIs

You can use various APIs in a client program to invoke Enterprise Server for .NET CICS programs using EXCI (External CICS Interface).

All of the APIs make use of parameter values and return codes that are specified by the IBM EXCI interface. See the IBM CICS documentation for more details.

Micro Focus supplies the copybooks DFHXCPLO.CPY and DFHXCURM.CPY for use with COBOL programs that use EXCI. The MicroFocus.SEE.Comms.Public namespace, in the assembly of the same name, contains enumerations ExciResponse and ExciReason for EXCI response and reason (error) codes.

  • EXEC CICS LINK for EXCI
  • DFHXCIS API
  • ExciClient Class
Parent topic: REST Web Services and EXCI


EXEC CICS LINK for EXCI

The simplest way to use EXCI from a procedural managed-code COBOL program is the EXEC CICS LINK macro. You can code an EXEC CICS LINK statement in a non-CICS COBOL program, then compile the program with the CICS preprocessor and the EXCI option, and the preprocessor will convert the LINK statement into an EXCI call. The LINK statement is similar to one in a CICS program, except that it also includes the APPLID parameter, which tells EXCI what region to contact. (To see how the APPLID is translated into a request URL for a specific region, see Configuring EXCI for the client.)

To compile a program for EXCI using EXEC CICS LINK, add CICSECM(EXCI=YES) to the compiler directives for the project.

When an EXCI LINK returns, it will populate a group item provided by the caller with any RESP and RESP2 codes and ABEND code from the server or called program, and possibly with an explanatory message. The format of this item is described in the IBM EXCI documentation, and is also shown in the example below.

An example of EXCI with an EXEC CICS LINK macro:
01  my-data         pic x(100) value "something".
01  my-data-len     pic 9(8) comp value 100.
01  exci-return.
  03  exci-resp     pic 9(8) comp.
  03  exci-resp2    pic 9(8) comp.
  03  exci-abcode   pic x(4).
  03  exci-msg-len  pic 9(8) comp.
  03  exci-msg-ptr  pointer.
...
exec cics link
    applid("ESDEMO")
    program("MYPROG")
    commarea(my-data)
    length(my-data-len)
    retcode(exci-return)
end-exec
Parent topic: EXCI Client APIs


DFHXCIS API

Enterprise Server for .NET includes an implementation of IBM's DFHXCIS API for making EXCI requests. (Not all DFHXCIS features are supported at this time.) DFHXCIS is a procedural API which client applications call to define EXCI connections and make requests.

DFHXCIS is more complicated than the EXEC CICS LINK interface, but it gives the application more control, and can be invoked from any managed-code program, not just a COBOL one compiled with the CICS ECM. DFHXCIS is also more efficient if the application will be making multiple EXCI requests to the same region.

Note: Because DFHXCIS uses mainframe-format ("big-endian", computational) integers, some additional work is required to invoke it from non-COBOL languages. For EXCI from a non-COBOL .NET language it may be more convenient to use the ExciClient Class.

The DFHXCIS API is in the MicroFocus.SEE.Comms.Public namespace, in the assembly of the same name.

DFHXCIS uses a single entry point, DFHXCIS, which takes a series of fixed parameters (version, return information, token, and call type) followed by one or more additional parameters, depending on the function being used.

The complete DFHXCIS reference is available in the IBM CICS documentation.

Parent topic: EXCI Client APIs


ExciClient Class

The MicroFocus.SEE.Comms.Public.ExciClient class, included with Enterprise Server for .NET in the MicroFocus.SEE.Comms.Public.dll assembly. This class is another API for EXCI clients which is more-suited to object-oriented and non-COBOL managed-code programs.

A client program can instantiate an ExciClient object using the static InitializeUser factory method, then invoke that object's AllocatePipe, OpenPipe, DPLRequest, ClosePipe, and DeallocatePipe methods to set up and make EXCI requests. These methods have the same functionality as the equivalent DFHXCIS API functions. There are also some convenience methods and properties. An ExciClient object uses standard .NET types for its parameters, and keeps track of the EXCI request state, including any error information from the most recent EXCI request.

An ExciClient demo that uses a WinForms client is included in the Enterprise Server for .NET samples.

Parent topic: EXCI Client APIs


The EXCI User Exit

The EXCI client supports an optional user exit named DFHXCURM, as defined by the IBM EXCI documentation. You can write a module that implements this exit and configure the EXCI client layer to load and call it. (The exit program can be written in any .NET language, but because the interface is defined as a COBOL group item, additional work is required to implement it in any language other than COBOL.)

The EXCI user exit receives certain parameters regarding each client request, and has the option of changing the APPLID that identifies the target region before the request is made. This has two main uses:

  1. The exit can be used to change the APPLID in order to change the request destination without changing the client application source code. This may be useful to temporarily redirect a client, or to switch between test and production regions, for example.
  2. The exit can change the APPLID when an EXCI request fails because the target region is not available. This can be used as a form of failover processing.

A sample DFHXCURM user exit is included with Enterprise Server for .NET.

Parent topic: REST Web Services and EXCI


Server Program Considerations for EXCI

In the target CICS region, EXCI invokes the server program specified by the client using an EXEC CICS LINK operation. The server program runs under the system program dfhzcpmi, which is the top-level program for the system transaction CPMI.

The application server program is a CICS program, and can use most CICS functions. EXCI server programs are restricted to the DPL subset of the CICS API as defined by IBM, though this restriction may not be enforced in all cases. Because the application server program does not run at the top link-level, it cannot use certain other options of some CICS APIs, such as the IMMEDIATE or COMMAREA options of EXEC CICS RETURN. It does not need a PCT entry. If you need to change the PCT attributes for an EXCI server program, you will have to copy the CPMI entry to a user resource group and modify it.

The server program will be called with a CICS commarea containing any application data supplied by the EXCI client program. The size of the commarea (EIBCALEN) will be the larger of the size of the data from the client and the minimum commarea size specified in the EXCI service configuration, unless that is larger than the maximum commarea size specified in the service configuration, or larger than the maximum commarea supported by the system. (The minimum and maximum commarea size attributes for the service are optional: if they are not set, the commarea will be as large as the data sent by the client.) The server program can change the commarea contents in place to create the response message for the client. It cannot change the size of the commarea, or move or reallocate it.

The dfhzcpmi program will intercept any abends not handled by the EXCI application server program, or any abends or errors that occur while trying to execute the server program (for example if the LINK operation fails because the program could not be loaded). It sends information about these errors back to the EXCI client, which makes them available to the client program.

Parent topic: REST Web Services and EXCI


Windows Azure Support

  • Introduction
  • What is Windows Azure
  • Overview
  • Configuring the Enterprise Server for .NET System
  • Deploying Enterprise Server for .NET Applications into Azure
  • Using Azure Drives with Enterprise Server for .NET
  • SQL Azure
  • System Center Monitoring Pack for Windows Azure Applications
  • Users in Windows Azure
  • Sample - BankDemo in Azure
  • References
Parent topic: Micro Focus Enterprise Server for .NET


Introduction

This document outlines current support for the Windows Azure Platform (http://msdn.microsoft.com/en-us/library/dd163896.aspx) for the Enterprise Developer - Enterprise Server for .NET and Enterprise Server for .NET. This document uses Enterprise Option as a generic name that can be used interchangeably unless otherwise stated.

This support requires Azure Platform account access. MSDN subscribers can take advantage of Microsoft's special introductory offer for MSDN subscribers. See Windows Azure Offers at http://www.microsoft.com/windowsazure/offers/ for details.

Parent topic: Windows Azure Support


What is Windows Azure

Extract taken from What is Windows Azure? (http://msdn.microsoft.com/en-us/library/dd179367.aspx):

"Windows Azure is an operating system that serves as the development, service hosting, and service management environment for the Windows Azure platform. The Windows Azure platform consists of an infrastructure of hardware, software, network, and storage resources. Windows Azure handles load balancing and resource management and automatically manages the life cycle of a hosted service based on defined requirements. Developers can build and deploy applications as a hosted service for Windows Azure by using the .NET Framework, un-managed code, or other approaches.

A Windows Azure hosted service can contain web role, worker role, and VM role instances. As its name suggests, a web role instance can accept incoming HTTP or HTTPS requests and can support web application programming hosted in IIS. Worker role instances are similar to, but not quite the same as a web role. The main difference is that a worker role instances is not hosted by IIS. Instead, they are executable in their own right. A VM role differs from a web role and a worker role, because with these roles, you focus on creating and running your code in an operating system that is managed by Windows Azure; for the VM role, you provide a pre-configured operating system image.

Applications can consist of solely web role instances, only worker role instances, only VM role instances, or a combination of all three. When the load increases for your application, you can request more instances of any of the defined roles. By running multiple instances of a role, Windows Azure helps the application scale. Scalability is achieved through virtualization. As you need to scale capacity, you can spin up new virtual machines to handle the added traffic and when the extra capacity is no longer needed you can release them. "
Parent topic: Windows Azure Support


Overview

Micro Focus recommends running CICS applications and batch programs in Windows Azure under an Enterprise Server for .NET system hosted as a set of distinct worker roles.

Using the Enterprise Server for .NET VS2010 template solution lets you quickly configure and easily deploy a worker role based Enterprise Server for .NET system to Windows Azure.

The remainder of this section describes how to configure and deploy your Enterprise Server for .NET system as a set of worker roles.

Each of the four key components of Enterprise Server for .NET is represented as a worker role in Windows Azure.

  • Listener - The worker role MicroFocus.SEE.Listener.Azure provides a communication channel for TN3270 clients.
  • Dispatcher - The worker role MicroFocus.SEE.Dispatch.Azure queues and dispatches CICS transaction requests and batch requests.
  • SEP - The worker role MicroFocus.SEE.SEP.Azure executes client transaction requests and batch requests.
  • Event monitor - The worker role MicroFocus.SEE.Monitor.Azure - provides an interface for remote administration (e.g. starting/stopping regions, querying SEP statuses, etc) and monitors the health of the system.

See the Enterprise Server for .NET product documentation for details about each of these components.

Note: It is not currently possible to perform dynamic debugging in an azure deployment . Debugging is limited to CTF tracing and event logs. The recommended practice is to deploy and debug to an on premise Enterprise Server for .NET and debug there. Once you are happy with the application then deploy into Azure.
Parent topic: Windows Azure Support


Configuring the Enterprise Server for .NET System

To configure an Enterprise Server for .NET system to run in Windows Azure:

  • Prerequisites
  • Creating A New Deployment Project
    Creating a new deployment project
  • Editing A Deployment Project
    Describes the editing environment for Azure deployment configuration
  • Publishing And Control of a Deployment
    How to publish a deployment, and control it.
Parent topic: Windows Azure Support


Prerequisites

The following are Windows Azure support prerequisites:

  • Azure Platform account. You can start with a free trial at http://www.windowsazure.com/en-us/pricing/free-trial/ for details on setting up an Azure Platform account.

  • SQL Azure server. See Getting Started with SQL Azure Database using the Windows Azure Management Portal at http://www.windowsazure.com/en-us/manage/services/sql-databases/getting-started-w-sql-databases/ for details on setting up and accessing SQL Azure databases.

  • Azure storage account. See http://www.windowsazure.com/en-us/manage/services/storage/ for details of how to set up an Azure storage account.

  • Windows Azure Tools for Visual Studio v1.8 . Download this SDK from http://www.windowsazure.com/en-us/downloads/archive-net-downloads/. The SDK is required on any system that deploys Enterprise Server for .NET roles to Azure.

Parent topic: Configuring the Enterprise Server for .NET System


Creating A New Deployment Project

This procedure creates a new deployment project which can be published / deployed into Azure.

  1. Open the Enterprise Server for .NET Administration tool.

  2. Right-click the Azure Deployment node (1) and select Add. A wizard will guide you through the basic deployment configuration.

  3. Enter the service name you want to give this deployment ( see 1 above). When the project is deployed, the service will be created if it is not present.

    If you want to copy a configuration from a previously defined deployment, click Copy Configuration (see 2 above).

  4. Click Next to continue.

    The next panel configures the management certificate.

  5. Click Generate (1 above). A browser window will open, which will take you to the azure portal to generate and download the certificate.

    Once you have downloaded a certificate, you need to import it by clicking Import (2 above) and navigating to the stored certificate and selecting it. Once imported, you will be presented with the following panel:

  6. Click Next to continue.

  7. Select the location in which you want the service deployment to reside. If you click the ellipsis (1 above) you will be presented with the available regions for your deployment.

    It makes good sense to deploy to the same location as your database. If you choose a different location, a great deal of lag could be introduced into the system.

  8. Click Next to continue.

  9. Enter the database instance ID of the SQL server you want to use for the deployment (1 above). This ID is the ID as provided by the SQL azure setup process, e.g. wzi3vhmgv1. You can also click the ellipsis (2 above) to get a list of database servers associated with the subscription. If you have not created a database server to use, you must do so, as it is a prerequisite.
  10. Enter the user id associated with the SQL server (3 above). This would have been set up during the database server creation.
  11. Enter the password associated with the SQL server (4 above).

    If you are using an SQL Azure server, and it exists, you can test the connection by clicking Test Connection (5 above).

  12. Click Next to continue.

    The system uses Azure storage accounts to store the deployment package, diagnostic data as well as information stored on Azure storage drives. The storage accounts do not have to belong to the subscription used for the deployment.

  13. Enter the Storage Account Name to be used for deployment and azure drive storage (1 above).You can click the ellipsis (2 above) to get a list of storage accounts associated with the subscription.
  14. Enter the Storage Account Key associated with storage account. If you selected the storage account using the ellipsis button, this is populated automatically.

  15. Click Next to continue.

    This storage account is used to store the diagnostic information emitted by the system. CTF traces and windows event log.

    The Storage account defaults to the same details as on the previous panel, but can be changed if you need the information to be kept separate for some reason.

  16. Amend as required and click Next to continue.

  17. If you want to access the Virtual machines hosting the worker roles in Azure using remote desktop, for example to check deployment, enable the checkbox.
  18. Enter the account user name (1 above).
  19. Select the certificate to use to secure the connection to the remote desktop (2 above).
  20. Enter a password to use to secure the connection (3 above), and confirm it (4 above).
  21. Choose an account expiration date. By default this is set far in the future.
  22. Click Next to continue.

    On this panel you can insert a region that will be associated with the deployment.

    By default, the wizard will insert two demo regions for you, designed to work with the demonstration regions definitions shipped with the product. You can delete these using the administration tool if you want, once the wizard is complete.

  23. Click Add Region (1 above) to add a new region. A new row will be inserted.
  24. Enter the Region Name and select the Region Type from the dropdown (2 above).

    The wizard is now at a point where it can complete.

  25. Click Finish to commit the new deployment configuration.
Parent topic: Configuring the Enterprise Server for .NET System


Editing A Deployment Project

This topic describes the editing interface, and how to edit Azure deployment configuration.

Not all fields will be described in this topic because context-sensitive help is available on all the configuration screens. For the context sensitive help, select the page to edit and click the blue Help button.

  1. Open the Enterprise Server for .NET Administration tool.

  2. Expand the Azure System Deployment node in the left pane (1 above). You will be presented with a list of configured deployments to select from. Select a deployment to work on.

    When a deployment is selected, the configuration editor is displayed in the middle panel.

    By default, the editor is used in simple mode. Most advanced configuration that normally need not be changed is hidden.

  3. To activate advanced mode, click the Options menu item (2 above) and select Advance Edit Mode.

    There is a configuration group for each of the worker roles, and a global configuration group that pertains to all roles.

    You can expand each of the nodes, and navigate to the configuration elements that need to be modified.

  4. If you want to invoke the wizard to take you through the basic configuration process, click Wizard (4 above).

    Changes do not persist until you either click Save (3 above), or use the File > Save menu.

Parent topic: Configuring the Enterprise Server for .NET System


Publishing And Control of a Deployment

Once a deployment project is configured, it needs to be published to Azure.

  • Open the Enterprise Server for .NET Administration tool and select the deployment you want to publish.

  • Click Publish in the Action pane (1 above). The view will change to publish/control mode.

  • To publish and start the deployment, click the blue arrow icon (1 above)

  • The system will package and deploy the project to Azure. An informational panel (1 above) will display the latest status of the deployment which is refreshed every few seconds.

  • A deployment is ready when each Worker role instance is in the ReadyRole state (1 above).
  • To delete a deployment, click Delete (2 above). This stops and deletes the deployment.
  • To stop a deployment, click Stop (3 above).
  • You can increase and decrease the number of instances of each worker role dynamically by using the increase and decrease icons next to each role (4 above). When increasing the number of instances, the Azure fabric will start a new VM and deploy the package to it. Once the new role is ready, it will accept work for the role from the Azure load balancers.

    Once you are happy with the new number of instances, click the green check icon which will appear when the instances are modified.

    Note: When decreasing the number of roles, a random instance will be stopped and deleted. At the moment, the role only receives notification of its demise a short time before it is destroyed. This is an Azure limitation that we cannot code around. This means that it might not be possible for the role to finish any work it is currently busy with. Use this functionality with caution.

Once the deployment is in a ready state, you can use the region control functionality of the administration tool to configure and control the regions.

Parent topic: Configuring the Enterprise Server for .NET System


Deploying Enterprise Server for .NET Applications into Azure

To deploy CICS applications, you deploy the region startup file, resource definition file, programs (.NET assemblies), BMS maps, and data files to SQL Azure databases or to an Azure drive ( as described in the confiuration section)

To deploy batch applications, you deploy the region startup file, programs( .NET assemblies) and data files to the SQL Azure database or to an Azure drive ( as described in the configuration section)

Enterprise Server for .NET provides a script that deploys the files required for running the ACCT application under a CICS region. Use this script as an example for how to deploy other applications.

Before deploying the files to the SQL Azure database (or subsequently administer these files using the Enterprise Server for .NET user interface), you must add the same database connection strings that you added to the see.azure.config file to your local machine's machine.config file. See SQL Azure Connection Strings for details.

  • Defining an Azure Region
  • Starting a Region in Azure
    Enter a short description of your topic here (optional).
  • Connecting Terminals to the Azure Region
  • Deploying the ACCT Sample Application into Azure
Parent topic: Windows Azure Support


Defining an Azure Region

  • Defining an Azure CICS Region
  • Defining an Azure Batch Region
Parent topic: Deploying Enterprise Server for .NET Applications into Azure


Defining an Azure CICS Region

  1. From the Windows Start menu, click Micro Focus Enterprise Developer > Enterprise Server for .NET > SEE Administration option to open the Microsoft Management Console (MMC).
  2. Right-click the SEE Administration > Regions > CICS node in the left-hand tree pane and select Define Region to display the Define Region dialog box.

  3. In the Database server instance field of the Define Region dialog box, Type the name of your SQL Azure database instance. Click Next.

  4. In the Region name field of the Define Region dialog box, type ESDEMO. Click Next.

  5. Select the Cross-region database radio button and click Browse.

    The Select Region Startup File dialog box appears.

  6. Select region_esdemodb.config from the Available region startup files list. This is the name of the region startup file deployed by seedeploy.cmd. Click OK to return to the Define Region dialog box.

    The Region startup file location is set to region_esdemodb.config.

  7. Click Finish to close the Define Region dialog box.

Parent topic: Defining an Azure Region


Defining an Azure Batch Region

  1. From the Windows Start menu, click Micro Focus Enterprise Developer > Enterprise Server for .NET > SEE Administration option to open the Microsoft Management Console (MMC).
  2. Right-click the SEE Administration > Regions > JES node in the left-hand tree pane and select Define Region to display the Define Region dialog box.

  3. In the Database server instance field of the Define Region dialog box, Type the name of your SQL Azure database instance. Click Next.

  4. In the Region name field of the Define Region dialog box, type ESDEMO. Click Next.

  5. Select the Cross-region database radio button and click Browse.

    The Select Region Startup File dialog box appears.

  6. Select region_jcldemo.config from the Available region startup files list. This is the name of the region startup file deployed by seedeploy.cmd. Click OK to return to the Define Region dialog box.

    The Region startup file location is set to region_jcldemo.config.

  7. Click Finish to close the Define Region dialog box.

Parent topic: Defining an Azure Region


Starting a Region in Azure

  • Starting a CICS Region in Azure
  • Starting a Batch Region in Azure
Parent topic: Deploying Enterprise Server for .NET Applications into Azure


Starting a CICS Region in Azure

  1. Expand the Regions >CICS node in the left-hand tree pane and select the ESDEMO node.
  2. Change the value in the Start/stop server name field in the middle pane to the DNS name of your hosted service (see 1 in the diagram). This is the name of the server used to start and stop your CICS region.
  3. Click Start/Stop Region in the right-hand action pane (see 2 in the diagram).

  4. Click Start at the bottom of the middle pane to start the region.

    Messages indicating the progress of the region startup appear in the middle pane.

    The Start button changes to Stop. To stop the region, return to this view by clicking Start/Stop Region in the right-hand action pane clicking Stop.

Parent topic: Starting a Region in Azure


Starting a Batch Region in Azure

  1. Expand the Regions >JES node in the left-hand tree pane and select the JCLDEMO node.
  2. Change the value in the Start/stop server name field in the middle pane to the DNS name of your hosted service (see 1 in the diagram). This is the name of the server used to start and stop your CICS region.
  3. Click Start/Stop Region in the right-hand action pane (see 2 in the diagram).

  4. Click the Cold Start radio button at the bottom of the middle pane and then click Startto start the region.

    Messages indicating the progress of the region startup appear in the middle pane.

    The Start button changes to Stop. To stop the region, return to this view by clicking Start/Stop Region in the right-hand action pane clicking Stop.

Parent topic: Starting a Region in Azure


Connecting Terminals to the Azure Region

To connect a 3270 terminal to the region:

  • Use the DNS name of your hosted service as the name of the machine you want to connect to, such as mycics.cloudapp.net.
  • Use the port specified in the listener worker-role's app.config file for the 3270 channel, such as 9023.
Parent topic: Deploying Enterprise Server for .NET Applications into Azure


Deploying the ACCT Sample Application into Azure

The ACCT sample application shoes how a CICS application runs under Enterprise Server for .NET in Azure.

Use this procedure to deploy the sample ACCT application to run under a CICS region.

  1. Open an Enterprise Developer command prompt.
  2. Run the following command:
    seedbdeploy [servername]

    where [servername] is the name of your SQL Azure database server instance (such as iwek9v4j6a) configured for the listener role in your CICS system. This script deploys the following files to the server instance's cross-region database:

    • All of the system transactions (for example, CPMT, CINS and CFCR) required by a CICS system.
    • A resource definition file named ResourceDefinitionsDB.config. This file includes FCT definitions for the ACCTFIL and ACCTIX files used by the ACCT application. The FCT definitions specify that these files reside in a database. By default they reside in the database named MicroFocus$SEE$Files$VSAM.
    • A region startup file named Region_ESDEMODB.config that uses the ResourceDefinitionsDB.config resource definition file.
    • The ACCT00.dll, ACCT01.dll, ACCT02.dll, ACCT03.dll, ACCT04.dll and ACCTMENU.dll assemblies that are used by the ACCT sample.
    • The ACCTSET.mod BMS mapset used by the ACCT sample.

Note that the file ACCTFIL used by the ACCT application is not deployed. Instead, this file must be created using the CFCR ACCTFIL transaction before running the ACCT transaction.

Parent topic: Deploying Enterprise Server for .NET Applications into Azure


Using Azure Drives with Enterprise Server for .NET

A windows Azure drive is a Virtual Hard Drive (.vhd) image that is stored in Azure Blob Storage and mounted by Enterprise Server for .NET within a monitor role, and shared to the other worker roles ( Listener, Dispatcher and SEP) using a custom drive letter.

A Windows Azure drive acts as a local NTFS volume that is mounted on the server’s file system and that is accessible to code running in a role. The data written to a Windows Azure drive is stored in a page blob defined within the Windows Azure Blob service, and cached on the local file system. Because data written to the drive is stored in a page blob, the data is maintained even if the role instance is recycled. For this reason, a Windows Azure drive can be used to run an application that needs to use information that will persist between recycles.

In the Enterprise Server for .NET context, an Azure drive provides an alternative deployment to deploying in SQL Azure database instances. The main benefit in using an Azure drive over a database deployment is speed.

  • Configuring an Azure Drive
  • Deploy Artifacts to an Azure Drive.
  • Using an Azure Drive From Within a Running Region
Parent topic: Windows Azure Support


Configuring an Azure Drive

You can configure an Azure drive for a region to use by using the administration tool .

Parent topic: Using Azure Drives with Enterprise Server for .NET


Deploy Artifacts to an Azure Drive.

Deploying artifacts ( programs, mapsets etc) to an azure drive running under a Enterprise Server for .NET Azure instance is done using the seedeploy tool as discussed in cmd seedeploy using the cdrv:// url syntax.

Parent topic: Using Azure Drives with Enterprise Server for .NET


Using an Azure Drive From Within a Running Region

Once an Azure drive has been configured, and is available to the worker roles, the region can be configured to use it, in a similar way to an on premise deployment.

For example, to use the drive to store the transaction dll's, maps etc, and configure the region to load them, do the following:

  • Deploy the region startup file, and, if you are configuring a CICS region, the resource definition file into SQL Azure. An example of how to do this can be found in the ACCT sample deployment example.
  • Once the region startup file is deployed, define the region as described in the Defining an Azure Region section.
  • Edit the Region Startup configuration, as described in the Configuring Regions and Resources.
  • Set the path names to the deployed objects on the azure drive and save the configuration.

For example, If you configured the Azure drive to have a drive letter M: you might configure the Application Program Paths node to contain "m:\programs".

Parent topic: Using Azure Drives with Enterprise Server for .NET


SQL Azure

  • What is SQL Azure?
  • Using SQL Azure with Enterprise Server for .NET
  • SQL Azure Firewall
  • SQL Azure Connection Strings
Parent topic: Windows Azure Support


What is SQL Azure?

This extract is from SQL Azure Database Overview at http://social.technet.microsoft.com/wiki/contents/articles/sql-azure-database-guide.aspx:

"Microsoft SQL Azure Database is a database service provided as part of the Windows Azure Platform. It is based on Microsoft SQL Server, and provides many of the same features. Unlike SQL Server, which is provided as a software package that you install and maintain, SQL Azure Database is provided as a service that is hosted on hardware in Microsoft datacenters. SQL Azure takes care of maintaining the hardware and software layer, freeing you to concentrate on database design. Since SQL Azure maintains the hardware and software for your database, provisioning a new database is very straightforward and easy; you request a new database and Microsoft provisions one automatically for you. Data stored in SQL Azure Database is also highly available, as each database hosted in the Microsoft data center has three copies: one primary and two secondary replicas. All reads and writes go through the primary, and any changes are replicated to the secondary replicas asynchronously."

See Getting Started with Windows Azure SQL Database at http://www.windowsazure.com/en-us/manage/services/sql-databases/getting-started-w-sql-databases for details about how to set up and access SQL Azure databases. The documentation in this section assumes availability of a SQL Azure database server.

Parent topic: SQL Azure


Using SQL Azure with Enterprise Server for .NET

SQL Azure databases can host both CICS regions and VSAM data files. A CICS system deployed either on-premise by an Enterprise Option product installation, or off-premise by an Azure Hosted Service can access a SQL Azure region and VSAM file databases. Performance when accessing SQL Azure on-premise is significantly slower than accessing it directly from an Azure Hosted Service where the Azure Hosted Service and SQL Azure database(s) are hosted in the same data center.

By default, Enterprise Option uses Windows authentication (SSPI), using the logged in user's credentials to access SQL Server databases. However, connecting to a SQL Azure database requires a specially formatted connection string that includes your SQL Azure database server name, user name and password. Do the following to determine the connection string for your master database.

By default, the administration tool wizard will create connection strings automatically, but if you want to override the defaults, follow these steps to obtain the database connection strings:

  1. Login to the Azure Management portal and click Db icon in the left-hand pane.

    The SQL databases screen will be displayed.

  2. Select the database of interest.
  3. Under the quick glance section is an information button "Show connection strings. Click this.
  4. The Connection Strings dialog box appears.
  5. Copy the connection string displayed under ADO.Net and then click Close to close the dialog box.

    The connection string is similar to the following:

    Server=tcp:[servername].database.windows.net;
                Database=master;
                User ID=[username]@[servername];
                Password=[userpassword];
                Trusted_Connection=False;
                 Encrypt=True;
    where:
    • [servername] is the name of your SQL Azure database server (for example iwek9v4j6a)
    • [username] is your SQL Azure user name and [userpassword] is your SQL Azure password

    The connection string for each of your SQL Azure databases has the same format except with master replaced by the appropriate database name.

Parent topic: SQL Azure


SQL Azure Firewall

The SQL Azure Firewall initially blocks all access to the SQL Azure server instance. Firewall rules must be defined before access is allowed. See the firewall section of the howto at SQL Azure Firewall at http://www.windowsazure.com/en-us/manage/services/sql-databases/how-to-configure-a-sqldb/ for more information about defining firewall rules.

Parent topic: SQL Azure


SQL Azure Connection Strings

Note: When using the deployment wizard in the administration tool to deploy a worker role-based deployment, these strings are auto configured. This section still contains valuable information for connection strings if you build your own deployment packages, or use virtual machine deployments.
  1. To configure SQL Azure connections for CICS systems deployed as worker roles, open the see.azure.config file in an editor.
    Tip: You may already have this file open in an editor if you are following the instructions for Configuring the CICS System.

Configuring SQL Azure Connections for a Local Machine or Virtual Machine Role

  1. Open machine.config in an editor as Administrator. The machine.config file is in %windir%\Microsoft.NET\Framework\v4.0.30319\Config for Windows 32-bit, and in %windir%\Microsoft.NET\Framework64\v4.0.30319\Config for Windows 64-bit.
  2. If the MicroFocus.SEE section is not defined in the file, add the following <section> element just before the </configSections> closing tag.
    <!-- Added for Micro Focus SEE for .NET -->
<section name="MicroFocus.SEE"
               type="MicroFocus.SEE.Utils.GlobalConfigurationSection,
               MicroFocus.SEE.Utils,Version=4.0.0.0,
               Culture=neutral,PublicKeyToken=0412c5e0b2aaa8f0" />
  3. At the end of the file, just before the closing tag, add the MicroFocus.SEE section.
    <!-- Added for Micro Focus SEE for .NET -->
<MicroFocus.SEE>
</MicroFocus.SEE>

Adding Connection String Entries

  1. Define a connection string for each SQL Azure database accessed by the CICS system. Add each connection string as a child element of the MicroFocus.SEE element. For example:
    <MicroFocus.SEE>
  <add key="SQL.ConnectionString.[servername]/master"
       value="Server=tcp:[servername].database.windows.net;
              Database=master;
              User ID=[username]@[servername];
              Password=[userpassword];
              Trusted_Connection=False;
              Encrypt=True;"
  />
  <add key="SQL.ConnectionString.[servername]/MicroFocus$SEE$CrossRegion"
       value="Server=tcp:[servername].database.windows.net;
              Database=MicroFocus$SEE$CrossRegion;
              User ID=[username]@[servername];
              Password=[userpassword];
              Trusted_Connection=False;
              Encrypt=True;"
  />
  <add key="SQL.ConnectionString.[servername]/MicroFocus$SEE$Region$ESDEMO"
       value="Server=tcp:[servername].database.windows.net;
              Database=MicroFocus$SEE$Region$ESDEMO;
              User ID=[username]@[servername];
              Password=[userpassword];
              Trusted_Connection=False;
              Encrypt=True;"/>
  <add key="SQL.ConnectionString.[servername]/MicroFocus$SEE$Region$TESTDB"
       value="Server=tcp:[servername].database.windows.net;
              Database=MicroFocus$SEE$Region$TESTDB;
              User ID=[username]@[servername];
              Password=[userpassword];
              Trusted_Connection=False;
              Encrypt=True;"/>
  <add key="SQL.ConnectionString.[servername]/MicroFocus$SEE$Files$VSAM"
       value="Server=tcp:[servername].database.windows.net;
              Database=MicroFocus$SEE$Files$VSAM;
              User ID=[username]@[servername];
              Password=[userpassword];
              Trusted_Connection=False;
              Encrypt=True;"/>
</MicroFocus.SEE>
  2. Define as a minimum a connection string for the master database, cross-region database, and one CICS region database. Enterprise Server for .NET implicitly creates the cross-region and CICS region databases, so connection strings are required even though they may not currently exist. In the example above, connection strings have been specified for the following:
    • Master database. The master database always has the name master
    • Cross-region database. The cross-region database always has the name MicroFocus$SEE$CrossRegion
    • ESDEMO and TESTDB region databases. A region database name is always of the form MicroFocus$SEE$Region$region name
    • Default VSAM file datastore. A VSAM file datastore database name is always of the form MicroFocus$SEE$Files$VSAM datastore name
  3. Define a connection string for each VSAM file datastore hosted in SQL Azure. The following is a connection string for the MyVsamFiles datastore:
    <add key="SQL.ConnectionString.[servername]/MicroFocus$SEE$Files$MyVsamFiles"
     value="Server=tcp:[servername].database.windows.net;
     Database=MicroFocus$SEE$Files$MyVsamFiles;
     User ID=[username]@[servername];
     Password=[userpassword];
     Trusted_Connection=False;
     Encrypt=True;"
/>
Parent topic: SQL Azure


System Center Monitoring Pack for Windows Azure Applications

An example management pack to monitor an Enterprise Server for .NET deployment in Azure is included in the product.

It enables a SCOM server to monitor performance counters on the worker Role instances.

These help topics assume that you already have a working region deployed with performance counters enabled.

They also assume that you have extensive Systems Center Operations Manager knowledge.

  • Setting the Agent Proxy
    Set up the SCOM agent proxy.
  • Installing the Management Pack
    Install the SCOM Azure management Pack.
  • Adding Other Performance Counters
    Adding other performance counters
Parent topic: Windows Azure Support


Setting the Agent Proxy

The Enterprise Server for .NET Azure management pack is run through a proxy machine.

The proxy machine can be any machine that is managed by a SCOM server, including the SCOM server itself.

  • Open the SCOM administration tool, and select the machine to act as the agent.

  • Right-click, click Security and check the box to allow the agent to act as a proxy.

  • On the proxy machine create a folder called c:\SEE_Azure_MP and copy the following items to it.
    • From the products etc\SEE\SCOM\Azure directory:
      • AzureBrowser.exe
      • AzureDeployment.xml
    • From the Azure sdk:
      • Microsoft.WindowsAzure.StorageClient.dll
      • Microsoft.WindowsAzure.StorageClient.xml
    • Import the management certificate associated with the Windows subscription into the machine's certificate cache.
    • Modify the AzureDeployment.XML file to include your Azure subscription ID, the slot, the certificate thumbprint and the subscription name.
Parent topic: System Center Monitoring Pack for Windows Azure Applications


Installing the Management Pack

  1. Copy the Microfocus.SEE.Azure.xml management pack file from the products etc\SEE\SCOM\Azure directory to a local folder.
  2. In System Center Operations Manager, click Administration - Management Packs.
  3. From the menu bar, click Actions > Action-Import Management Packs.
  4. Click Add > Add from Disk and browse to the location of the MicroFocus.SEE.Azure.mp file.

  5. Click Monitoring in SCOM.
  6. Under Monitoring, click Discovered Inventory.
  7. From the menu, click Actions > State Actions > Change Target Type.

  8. Click View all Targets and Azure Deployment and click OK.

  9. Right-click the resulting Discovered Inventory item and click Open - diagram view.
  10. From the diagram, select any node and from the right Actions pane click Performance View.
Parent topic: System Center Monitoring Pack for Windows Azure Applications


Adding Other Performance Counters

The management pack contains rules for gathering all Micro Focus performance counters. However, we can add Windows default performance counters as well.

To add other performance counters, we need to add a rule to gather them.

  1. Open Microfocus.SEE.Azure.mp in SCOM 2007 R2 Authoring console.
  2. Under the Health model, select rules.

    There are already a few rules there for gathering Enterprise Server for .NET performance counters.

  3. Right-click in the middle view and select New - Custom Rule.

  4. Give it a name and optionally a description. In the target, you can select only these four classes:
    • 1. Azure Dispatcher Instances
    • 2. Azure Listener Instances
    • 3. Azure Monitor Instances
    • 4. Azure SEP Instances
  5. Select Modules.
  6. Under Data Sources, select Create. In the resulting dialog, look for Azure Performance Counter Data Source.

    Give it a name and click OK.
  7. Under Condition Detection, select Create and look for System.Performance.DataGenericMapper.

    Select it, give it a name and click OK.
  8. Under Actions select Create and look for Performance Data Write Action, give it a name and hit OK.
  9. Again hit Create and look for Performance data publisher, give it a name and hit OK.

    The Rule Dialog should look as follows:

  10. Under the Data Source, click Edit.
  11. Fill in all the parameters:
    • Timegap is the duration of data to retrieve in minutes
    • Counterspecifier is the name of the counter to retrieve.
  12. Select Edit under Condition Detection.
  13. Fill in the parameters. In Value however, use the same name as was specified in the CounterSpecifier. In the given example it's SEPTransactionPerSec.

Parent topic: System Center Monitoring Pack for Windows Azure Applications


Users in Windows Azure

Applications running in Enterprise Server for .NET can be affected in various ways by the identity of the user executing the application. APIs such as EXEC CICS SIGNON, the CESN system transaction, and the USER card in a JCL deck can establish the user's identity. EXEC CICS ASSIGN USERID and similar APIs can retrieve the user's identity.

User impersonation lets Enterprise Server for .NET run application code under the operating system account for the default or current user.

In a conventional Windows deployment, Enterprise Server for .NET uses the Windows operating system to authenticate users and supply the user tokens for impersonation. A Windows Azure deployment, however, may not have access to the same collection of Windows user accounts, since it runs in the Azure cloud rather than as part of your corporate network. There are various options for handling users in Windows Azure.

Predefined Users in Azure Virtual Machine Roles

An Azure VM role is a self-contained Windows Server installation that you set up before deploying it to Azure. That means you can add required user accounts to the role during the setup process. You can automate this task using VBScript, PowerShell, or another scripting language.

Predefined Users in Azure Worker Roles

Setting up users for Azure worker roles is more complex, because the Windows environment for these roles is created automatically by Azure. The worker role deployment solution can create users as part of its setup process.

The startup.cmd script supplied with the Enterprise Server for .NET Azure deployment solution creates a temporary user account using the Windows net user command as part of its processing. If you are only creating a few users, you could do something similar in your deployment process.

Other options include writing a program to create the necessary user accounts and having that run as part of role setup or even Enterprise Server for .NET region startup, and creating accounts manually in a Remote Desktop session connected to your worker role instance.

The Service Bus Logon Provider

The Service Bus Logon Provider is an optional Enterprise Server for .NET component that changes how regions validate user credentials and perform other user-related tasks. By default, another logon provider component called the Windows Logon Provider handles those functions. The Service Bus Logon Provider lets an Enterprise Server for .NET Azure role instance check usernames and passwords by sending them to the seesvcbuslogon service running on another system, typically a system in your Windows domain. The Service Bus Logon Provider lets you avoid predefining Enterprise Server for .NET user accounts. Users simply sign on to regions using their normal Windows credentials.

The Service Bus Logon Provider does not support impersonation, so while it can validate usernames and passwords, it doesn't provide the run-time security of executing application code with the user's authority.

Azure Connect

Azure Connect is an additional Azure feature provided by Microsoft. It lets you join Azure role instances to your domain as if they were part of your private network. See the MSDN topic "Overview of Windows Azure Connect" at http://msdn.microsoft.com/en-us/library/windowsazure/gg432997.aspx for more information.

In principle, Azure Connect should let you use the default Windows Logon Provider in your Enterprise Server for .NET Azure role instances, allowing users to sign on to regions using their normal Windows credentials. Micro Focus has not tested this configuration.

User Impersonation in Azure

User impersonation is currently only available in Azure VM roles because it requires that the Event Monitor and SEP be running under the same OS instance. It also requires the Windows Logon Provider, as the Service Bus Logon Provider cannot create impersonation tokens.

Parent topic: Windows Azure Support
Related concepts
Logon Providers in ES.NET
About User Impersonation


Sample - BankDemo in Azure

The BankDemo application is a more advanced application than the ACCT example. It has more programs and maps, and more interestingly, can be configured to use HCOSS to access the samples database.

Note: This sample assumes that you have already successfully configured and deployed the ESDEMO sample as described in the previous topics in this section and you have successfully started and run the ACCT example in Azure.

This walkthrough will take you through the steps required to build and deploy the BankDemo application into a SQL Azure database hosted deployment using a local machine architecture. It will use HCOSS to access the applications database.

If you do not want to use HCOSS to access the database, ignore the HCOSS configuration steps.

The BankDemo sample is in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo
  1. Create the BANKDEMO database.
    1. Open and log in to the Azure management portal.
    2. Connect to the database where you would like to host the region and BANKDEMO database.
    3. Create a database called BANKDEMO in your chosen SQL Azure server.
    4. Select the BANKDEMO database and click the MANAGE link at the bottom of the page.
    5. Log in to the SQL Azure database, and use the New Query link to open a new SQL query.
    6. Open the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo\SQL\BankDemoCreateAzure.SQL file and copy the contents into your clipboard
    7. Copy the contents of the clipboard into the SQL query window you just opened. ( Hint: Use the Ctrl+V key to copy the contents of your clipboard into this query window.)
    8. Execute the SQL by clicking Run at the top of the page.
    9. Click Design on the bottom left of the page and check that the tables have been created. It should look similar to the following:

  2. Build the application in Enterprise Developer for Visual Studio.
    1. Open Enterprise Developer for Visual Studio.
    2. Open the bankdemo.sln.
    3. Select the relevant project to build:
      1. If using HCOSS, make BankDemo the startup project.
        1. Open the project properties

          1. Select the COBOL properties (1)
          2. Click build events button (2)
          3. Enter the DSN name configured in the HCOSS tool below, e.g. BANKDEMO (3).
        2. Open the HCO for SQL Server Tools.

        3. Select the Manage Connections activity from the list, click the SQL Azure radio button and click New SQL Server Connection in the connection list dialog.

        4. Configure the connection data.
          1. Enter BANKDEMO as Data Source Name.
          2. You can only use SQL Server Login. Enter the correct username and password to access the SQL Azure instance.
          3. Enter the TCP address of the SQL Azure instance. E.g. tcp:sfcgreio.database.windows.net.
          4. Check Use a database other than the default database.
          5. Select BANKDEMO from the database dropdown list.

          6. Click the CICS region radio button and configure the displayed dialog.
            1. You can only use SQL Server Login. Enter the correct username and password to access the SQL Azure instance.
            2. Enter the TCP address of the SQL Azure instance. E.g. tcp:sfcgreio.database.windows.net.
            3. Enter BANKDEMO as the CICS region.

          7. Click Save.
      2. If not using HCOSS, make BankDemo2 the startup project.
    4. Build the project.

      The project should build with no errors or warnings. For the HCOSS version the post build event will perform the bind to the configured database

    5. This step is optional and is presented to show how to manually perform the bind step. The bind is normally done by the post build event during the project build for the HCOSS project. .
      1. Select the Manage Packages and Plans activity from the Activities list in the left pane.
        1. Make sure that the Bind Scripts tab is selected.
        2. In the Bind Script File Actions, click Open and open %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\DotNet\BankDemo\BankDemo.hcodsn.
        3. Select BANKDEMO from the SQL Server Connection dropdown.
      2. Click Execute All.

        This will bind the binaries generated when you built the project to the SQL Azure hosted BANKDEMO database.

  3. Package and deploy the ES for .NET system to Azure.
    1. Open theEnterprise Server for .NET Administration UI and configure a deployment project for BANKDEMO as per the instructions found at Creating A New Deployment Project.
    2. Make sure that the listener endpoints etc are correct.
    3. Make sure that there is a connection string for the user BANKDEMO database as well. It is sufficient to just add BANKDEMO in simple editing mode, the tool will generate the advanced connection strings for you. If you wish to edit or change the connection strings themselves, enable advanced editing mode.

    Save and publish the deployment to Azure (Publishing And Control of a Deployment.).

  4. Deploy the system transactions and the BANKDEMO application into the cross region database.
    1. Open an Enterprise developer command prompt as Administrator.
    2. Navigate to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\DotNet\BankDemo directory.
    3. Deploy the bankdemo application into the cross region database.
      • Make sure that your deployment configuration contains database connection strings for the master and cross region database similar to those supplied in the ESDEMO deployment example.
        1. If you wish to change the database connection string default, make sure that the Advanced edit mode is activated in the Options menu of the Azure service configuration panel.
      • bankdemodbdeploy <SQLAzureDatabaseName >, e.g. bankdemodbdeploy wai3yvmxx1.

      It is well worth looking at these two batch files to understand how files are uploaded to the database. This knowledge is invaluable to deployment when developing your own deployment scripts.

  5. Configure an XA resource definition for the bankdemo database as described in Configuring XA resources .
    1. An XA resource definition will be used to define how the region is to connect to the database.
    2. Ensure that the application plan field in the XA resource definition is set correctly ( BANKDEMO in this case).

      There is no need to set the application plan in the region definition file.

  6. Create the BANKDEMO region.

    These steps are not detailed, as most of the process has been previously described in other tutorials.

    1. Open the Enterprise Server for .NET Administration UI.
      1. Create a new CICS Region called BANKDEMO, hosted in the SQL Azure database.
      2. Select the region definition file from the cross region database. It was deployed in the previous step.
        • It is called region_bankdemo_db.config.
        • If using HCOSS , edit the region definition or PCT entry and set the XA resource name to the name of the XA resource you created above.
    2. Start the region, making sure that the start/stop server name points to xxx.cloudapp.net, where xxx is the service name to which you deployed the Azure project.
    3. Check to see that the system picks up the XA resource definition correctly and that the DFHPLT transaction was loaded from the database, and not disk.

  7. Run Bankdemo.
    1. Connect a TN3270 terminal to the listener port in Azure you configured to be associated with BANKDEMO.
      • e.g. mycics.cloudapp.net port 9123.

      You should be presented with a blank screen, with a flashing cursor.

    2. Type 'bank' and click Enter.

      You will be presented with the initial login screen.

    3. Enter an account, in the format B000xx, e.g. B0001 and anything in the password field.

      You will be presented with the first screen (BANK20) in the demonstration application.

    4. Tab to a field, enter a character and click Enter.
    5. Look at the console view in the administration tool, and notice that the transactions are being loaded from the SQL Azure database as opposed to disk.
Parent topic: Windows Azure Support


References

Connecting Local Computers to Windows Azure Roles | http://msdn.microsoft.com/en-us/library/gg433122.aspx
Creating and Deploying a Virtual Machine Role in Windows Azure | http://msdn.microsoft.com/en-us/wazplatformtrainingcourse_vmrolelab_topic2#_Toc279616583
Download Windows Azure SDK | http://www.microsoft.com/windowsazure/sdk/
Getting Started with SQL Azure using the Windows Azure Management Portal | http://social.technet.microsoft.com/wiki/contents/articles/getting-started-with-sql-azure-using-the-windows-azure-platform-management-portal.aspx
How to Create a Storage Account | http://msdn.microsoft.com/en-us/library/gg433066.aspx
Introduction to the VM Role Development Process | http://msdn.microsoft.com/en-us/library/gg466229.aspx
Setting Up Named Authentication Credentials | http://msdn.microsoft.com/en-us/library/ff683676.aspx
SQL Azure | http://www.microsoft.com/windowsazure/learn/
SQL Azure Database Overview | http://social.technet.microsoft.com/wiki/contents/articles/sql-azure-database-guide.aspx
SQL Azure Firewall | http://msdn.microsoft.com/en-us/library/ee621782.aspx
Troubleshooting with Remote Desktop | http://msdn.microsoft.com/en-us/wazplatformtrainingcourse_vmrolelab_topic3#_Toc279616590
Using Remote Desktop with Windows Azure Roles | http://msdn.microsoft.com/en-us/library/gg443832.aspx
What is Windows Azure? | http://msdn.microsoft.com/en-us/library/dd179367.aspx
Windows Azure Offers | http://www.microsoft.com/windowsazure/offers/
Windows Azure Platform | http://msdn.microsoft.com/en-us/library/dd163896.aspx
Parent topic: Windows Azure Support


Enterprise Server for .NET Glossary

The following is a list of glossary terms related to Enterprise Server for .NET:

  • Glossary terms A to M
  • Glossary terms N to Z
Parent topic: Micro Focus Enterprise Server for .NET


Glossary terms A to M

  • ACB
  • Access method services (AMS)
  • BMS Map
  • CICS Region
  • CICS resource
  • Cross-Region Database
  • DCT - Destination Control Table
  • Dispatcher
  • Endpoint
  • Event Monitor
  • FCT - File Control Table
  • IMS - Information Management System
  • ISC - Inter-system communication
  • IVP - Installation Verification Procedure
  • JES - Job Entry Subsystem
  • Listener
  • LU6.2
  • MMC - Microsoft Management Console
  • MSS - Mainframe Subsystem Support
Parent topic: Enterprise Server for .NET Glossary


ACB

Mainframe VSAM control block information.
Parent topic: Glossary terms A to M


Access method services (AMS)

A utility program used to define and manage VSAM data sets.
Parent topic: Glossary terms A to M


BMS Map

BMS (Basic mapping support) maps provide an interface between the CICS environment and application programs. BMS mapping controls input and output display data format and routes multiple-page output messages to terminals.
  • In native Enterprise Server, use the BMS Screen Painter to format output.
  • In Enterprise Server for .NET, the BMS Screen Painter is not available. Edit the definition file to modify the map.
Parent topic: Glossary terms A to M


CICS Region

A named collection of resources controlled by CICS as a unit. In Enterprise Server for .NET, a region's operating records are maintained in a SQL Server database.
Parent topic: Glossary terms A to M


CICS resource

Any facility or component of a CICS system that is required to perform a task. The resources in a region include programs, Basic Mapping Support (BMS) map sets, transactions, terminals, files, transient data queues, temporary storage queues, and journals.
Parent topic: Glossary terms A to M


Cross-Region Database

The database that coordinates processes running between regions.
Parent topic: Glossary terms A to M


DCT - Destination Control Table

Destination Control Table
Parent topic: Glossary terms A to M


Dispatcher

Service responsible for queuing client requests received from a listener, and dispatching requests to available SEPs. A dispatcher service is either self-hosted within an seedispatch.exe process, or WAS-hosted within a w3wp.exe process.
Parent topic: Glossary terms A to M


Endpoint

See Service Endpoint:

The Windows Communication Foundation ( WCF) location of an Enterprise Server for .NET component, that the other components use to communicate with the component. This can be either a port on the local machine, or it can be defined as a URL, for services operating on machines in a cluster for example. The URL defines the endpoint's protocol, hostname, port, and path.

Parent topic: Glossary terms A to M


Event Monitor

Windows service process (seemonitor.exe) installed on machines required to run dispatcher and/or SEP services. An event monitor is responsible for providing administration and management functionality for the SEP and dispatcher services that run on the same machine as the monitor. Event monitors on different machines communicate with each other to perform certain tasks, such as region shutdown or internal transaction request (ITR) invocation. These require coordination with all SEPs in the enterprise that are running, or have run, tasks for a given CICS region.
Parent topic: Glossary terms A to M


FCT - File Control Table

The FCT maintains control information of all files used under CICS. For each file used, the FCT contains:
  • The file name and type, such as KSDS, ESDS, or RRDS.
  • A list of the valid file control operations.
  • Information on the records, such as minimum and maximum length, whether they are read sequentially or randomly, and if they can be deleted or modified.
Parent topic: Glossary terms A to M


IMS - Information Management System

IBM Information Management System (IMS) is a joint hierarchical database and information management system with extensive transaction processing capabilities. IMS was is also called DB1 and is the precursor to DB2.
Parent topic: Glossary terms A to M


ISC - Inter-system communication

Enterprise Server for .NET provides some support for communication with other Enterprise Server regions.
  • A CICS region can be configured to connect to a native Enterprise Server region configured for JES, in order to submit JCL through the CICS internal reader. The native Enterprise Server region must have a listener for the CICS Transaction Gateway (CTG) protocol. Configure the hostname and port of the CTG listener in the Enterprise Server for .NET CICS region startup file.
  • Enterprise Server for .NET includes an assembly, MicroFocus.SEE.Comms.Public, that allows managed applications to invoke CICS transactions in a native Enterprise Server region using CTG. See the The EXCI Interface for more information.
Parent topic: Glossary terms A to M


IVP - Installation Verification Procedure

A supplied procedure to check that the installation is correct.
Parent topic: Glossary terms A to M


JES - Job Entry Subsystem

Job scheduling and input-output spooling subsystems found on IBM's MVS, OS/390 and z/OS operating systems.
Parent topic: Glossary terms A to M


Listener

The listener resides on a 3270 channel machine. A listener is configured with a port and a region, and can communicate with the configured region only. When logging on to a 3270 machine, the listener forwards information to the dispatcher to establish contact with the configured region.

The listener listens for input from both the 3270 channel machine, and the SEP to which it is connected. It also:
  • Forwards input from the 3270 machine to the region for processing.
  • Displays the data that it receives from the region, for example status data and prompts.
Parent topic: Glossary terms A to M


LU6.2

A part of the SNA protocol for inter-computer communications. LU6.2 fills a similar role to TCP/IP.
Parent topic: Glossary terms A to M


MMC - Microsoft Management Console

A Microsoft component that hosts user interfaces that you add as snap-ins. Enterprise Server for .NET provides an MMC snap-in for the system configuration and administration functionality.
Parent topic: Glossary terms A to M


MSS - Mainframe Subsystem Support

A facility available with Enterprise Developer and Enterprise Server that enables CICS, IMS and JCL applications migrated from the mainframe to be maintained, developed and deployed on Windows or UNIX platforms.
Parent topic: Glossary terms A to M


Glossary terms N to Z

  • NLB - Network Load Balancing
  • Native Enterprise Server
  • OLTP - Online Transaction Processing
  • Package
  • PCT - Program Control Table
  • Region
  • Region database
  • SEE - Server Enterprise Edition
  • Self-hosted
  • SEP - Service Execution Processes
  • SEP Pool
  • Service Endpoint
  • SNA
  • SOA - Service-Oriented Architecture
  • Startup List
  • SIT - System Initialization Table
  • WAS/WPAS - Windows Process Activation Service
  • WCF - Windows Communication Foundation
  • Web Service
  • WPF - Windows Presentation Foundation
Parent topic: Enterprise Server for .NET Glossary


NLB - Network Load Balancing

A facility that balances network component loads so processing is shared evenly between components.
Parent topic: Glossary terms N to Z


Native Enterprise Server

The Micro Focus native-code mainframe emulation production environment. Also known as the Micro Focus Enterprise Server with the Mainframe Subsystem option.
Parent topic: Glossary terms N to Z


OLTP - Online Transaction Processing

Online Transaction Processing
Parent topic: Glossary terms N to Z


Package

Packages are not currently applicable to Enterprise Server for .NET. An implementation package defines the application that provides the business functionality.
Parent topic: Glossary terms N to Z


PCT - Program Control Table

A control table that maintains control information of all CICS transactions. The PCT contains a list of each transaction ID and the corresponding program that CICS loads when the transaction initiates. Control information includes the priority and security level (RSLC) of each transaction.
Parent topic: Glossary terms N to Z


Region

In Enterprise Server for .NET, CICS and JCL regions are represented by SQL Server databases. A region database contains configuration and state information. Unlike native Enterprise Server where an enterprise server instance can run both CICS transactions and batch jobs, in Enterprise Server for .NET CICS transactions can only be run within CICS regions and batch jobs can only be run within JES regions.
Parent topic: Glossary terms N to Z


Region database

A region database contains the configuration and state information representing a CICS or JES region.
Parent topic: Glossary terms N to Z


SEE - Server Enterprise Edition

Server Enterprise Edition
Parent topic: Glossary terms N to Z


Self-hosted

The ability to run WCF services within a non-WAS/IIS process such as a Windows console application. seedispatch.exe and seesep.exe are provided to self-host dispatcher and SEP WCF services respectively.
Parent topic: Glossary terms N to Z


SEP - Service Execution Processes

Service execution process. The name is taken from native Enterprise Server. In Enterprise Server for .NET, a SEP is an AppDomain running within a w3wp.exe or seesep.exe process. Multiple SEPs will exist within these processes. A CICS transaction or batch job runs within a SEP.
A SEP provides:
  • A COBOL execution environment
  • State/Session management
  • Transactional control (resource management)
  • Infrastructure for RTS and Request Handlers
Parent topic: Glossary terms N to Z


SEP Pool

A w3wp.exe or seesep.exe process hosting one or more SEPs. Each SEP pool registers itself with the event monitor service to allow the event monitor to administer and manage SEP execution.
Parent topic: Glossary terms N to Z


Service Endpoint

See Endpoint.

The Windows Communication Foundation ( WCF) location of an Enterprise Server for .NET component, that the other components use to communicate with the component. This can be either a port on the local machine, or it can be defined as a URL, for services operating on machines in a cluster for example. The URL defines the endpoint's protocol, hostname, port, and path.

Parent topic: Glossary terms N to Z


SNA

Systems Network Architecture (SNA) is IBM's proprietary networking architecture, created in 1974.
Parent topic: Glossary terms N to Z


SOA - Service-Oriented Architecture

Provides a set of principles of governing concepts used during phases of systems development and integration. Such an architecture packages functionality as interoperable services: software modules provided as services can be integrated or used by several organizations, even if their respective client systems are substantially different. It is an attempt to develop yet another means for software module integration. Rather than defining an API, SOA defines the interface in terms of protocols and functionality. An endpoint is the entry point to an SOA implementation.

Parent topic: Glossary terms N to Z


Startup List

The Startup List contains the list of the groups of resources to be used by a CICS region. Enterprise Server for .NET loads all the groups in the startup list into the region database when cold starting a CICS region.. The base startup list dfhlist contains recommended system groups that you should include in all your user-defined startup lists.

Parent topic: Glossary terms N to Z


SIT - System Initialization Table

The SIT defines initialization parameters used when cold starting a CICS region.

Parent topic: Glossary terms N to Z


WAS/WPAS - Windows Process Activation Service

Windows Process Activation Service. Auto-activation of WCF services within a w3wp.exe process. Within Enterprise Server for .NET, WAS activates dispatcher and SEP services.
Parent topic: Glossary terms N to Z


WCF - Windows Communication Foundation

A framework for sending data as asynchronous messages from one service endpoint to another. Enterprise Server for .NET uses WCF to communicate between listener, dispatcher, SEP and event monitor processes.

Parent topic: Glossary terms N to Z


Web Service

A Web Service is a software system identified by a URI, whose public interfaces and bindings are defined and described using XML. The Web Service definition can be discovered by other software systems. These can then interact with the Web service in a manner prescribed by its definition, using XML based messages conveyed by Internet protocols. SOAP messages are transported using HTTP.
Parent topic: Glossary terms N to Z


WPF - Windows Presentation Foundation

A graphical subsystem for rendering user interfaces in Windows-based applications.
Parent topic: Glossary terms N to Z


DB2 Call Attach Facility

You use the DB2 Call Attach Facility (CAF) to access DB2 subsystems and the data they manage. You do this by calling DSNALI with the appropriate series of functions. The MSS emulation of this facility behaves exactly as on the mainframe, with the following exceptions:

  • CONNECT function.
    • The subsystem parameter (parameter number 2) must be present but is otherwise ignored.
    • The termination Event Control Block (ECB) parameter (parameter number 3) must be present but is otherwise ignored. This ECB is never posted.
    • The starting ECB parameter (parameter number 4) must be present but is otherwise ignored. This ECB is never posted.
    • The Release Information Block (RIB) pointer (parameter 5) must be present and is set to point to a constant value which contains items such as an eye-catcher "RIB" and the DB2 subsystem release number of 710 (for DB2 V7.1.0).
  • OPEN function.
    • The subsystem parameter (parameter number 2) must be present but is otherwise ignored.
  • TRANSLATE function.
    • No translation is performed. In the SQLCA, SQLCODE is always set to -924, and SQLSTATE is always set to 58006.
Related information
About XA Resources


VSE JCL Configuration Files

At system start-up, VSE can set a number of values that are available to any job run on the system until shut down. MSS emulates this behavior with the use of a configuraiton file. You can use the configuration file to specify information about the following:

  • Devices. These can be designated as Printers, Punches, Tapes, Readers or Disks.
  • Logical Units. SYSxxx (where xxx is a 3 digit number) or one of the standard logical devices SYSIPT, SYSLST etc.
  • Standard labels. Commonly-used file names and the associated data sets can be set so that no DLBL statement for this filename/data set name is necessary in the JCL decks; the file is automatically allocated.

MSS reads the configuration file at the start of each job, so if you run a job then modify the configuration file, running the job again will pick up the modified configuration file.

Related tasks
To Configure VSE Job Execution
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region